# 피치에이아이 광고 송출 데이터 연동 API

본 api 명세서는 고객사가 피치에이아이 광고 성과 플랫폼과의 데이터 연동을 위해 구현해야 하는 API 명세서입니다.
고객사는 아래 명세된 엔드포인트들을 구현하여 피치에이아이 시스템과 데이터 연동할 수 있습니다.

구현 필수사항:
1. 모든 API는 RESTful 형식으로 구현되어야 합니다.
2. 응답은 JSON 형식으로 제공되어야 합니다.
3. 모든 시간 데이터는 ISO 8601 표준을 따라야 합니다.
4. 에러 응답은 명세된 Error 스키마를 준수해야 합니다.

연동 데이터 흐름:
1. 각 매체별로 일자별 송출 데이터를 피치에이아이로 전송합니다.
2. 피치에이아이 시스템은 지점, 매체, 캠페인, 광고 소재에 대한 정보를 매핑합니다.
3. 광고분석 데이터 처리가 완료되면 처리 완료 통지를 수행합니다.
4. 고객사는 준비된 광고 분석 데이터를 조회합니다.

보안 요구사항:
- 모든 API 통신은 HTTPS를 통해 이루어져야 합니다.
- API 인증 방식은 별도 협의 후 적용됩니다.

# 송출 기록 데이터 포맷
송출 기록 데이터는 S3 버킷을 통해 전달됩니다. S3 버킷에 저장할 데이터는 csv 형태로 저장하며 아래 디렉토리 포맷을 따라야 합니다.

`BUCKET/PREFIX/{year}/{month}/{day}`

csv 파일은 아래 포맷을 따라야 합니다.

`
장비ID,캠페인ID,캠페인 컨텐츠ID,시작일시,종료일시
`

저장 일시등은 별도 협의를 통해 정합니다.

![flow](../images/flow.jpg)


Version: 1.0.0

## Servers

고객사 프로덕션 서버
```
https://{customer-domain}/api/v1
```

Variables:
- `customer-domain`: 고객사에서 제공하는 도메인
Default: "api.customer.com"

## Download OpenAPI description

[피치에이아이 광고 송출 데이터 연동 API](https://docs.p2ach.ai/_bundle/apis/integration.yaml)

## Other

### 지점 목록 제공 API

 - [GET /api/v1/branches](https://docs.p2ach.ai/apis/integration/paths/~1api~1v1~1branches/get.md): 고객사가 보유한 매장 지점에 대한 목록을 제공하는 API입니다.
피치에이아이 시스템은 이 API를 통해 연동 대상 지점 정보를 수집합니다.

구현 시 주의사항:
- 페이지네이션 없이 전체 매체 목록을 한 번에 응답해야 합니다.
- 지점 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.

### 광고 매체 목록 제공 API

 - [GET /api/v1/displays](https://docs.p2ach.ai/apis/integration/paths/~1api~1v1~1displays/get.md): 고객사가 보유한 전체 광고 매체의 목록을 제공하는 API입니다.

지점, 구역, 섹션에 대한 정보가 있다면 같이 응답합니다.

지점은 실제 매장의 지점명을 뜻하고 구역은 매장내 농산물, 수산 코너와 같은 매장내 구역을 뜻합니다. 섹션은 구역의 하위 개념으로 한 구역내에 세부적인 섹션을 뜻합니다.

피치에이아이 시스템은 이 API를 통해 연동 대상 매체와 매체가 속한 지점, 구역, 섹션 정보를 수집합니다.

구현 시 주의사항:
- 페이지네이션 없이 전체 매체 목록을 한 번에 응답해야 합니다.
- 매체 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.

### 캠페인 목록 제공 API

 - [GET /api/v1/campaigns](https://docs.p2ach.ai/apis/integration/paths/~1api~1v1~1campaigns/get.md): 고객사가 보유한 전체 광고 캠페인 목록을 제공하는 API입니다.
피치에이아이 시스템은 이 API를 통해 연동 대상 캠페인 정보를 수집합니다.

구현 시 주의사항:
- 페이지네이션 없이 전체 캠페인 목록을 한 번에 응답해야 합니다.
- 캠페인 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.

### 캠페인 컨텐츠 목록 제공 API

 - [GET /api/v1/ad_contents](https://docs.p2ach.ai/apis/integration/paths/~1api~1v1~1ad_contents/get.md): 고객사가 보유한 전체 광고 캠페인 컨텐츠 목록을 제공하는 API입니다.
피치에이아이 시스템은 이 API를 통해 연동 대상 캠페인 컨텐츠 정보를 수집합니다.

구현 시 주의사항:
- 페이지네이션 없이 전체 캠페인 컨텐츠 목록을 한 번에 응답해야 합니다.
- 캠페인 컨텐츠 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.

### 데이터 동기화 완료 수신 API

 - [POST /api/v1/displays/{display_id}/ready](https://docs.p2ach.ai/apis/integration/paths/~1api~1v1~1displays~1%7Bdisplay_id%7D~1ready/post.md): 피치에이아이 시스템이 특정 매체의 특정 일자 데이터 동기화를 완료했음을 통지받는 API입니다.
고객사는 이 통지를 수신하여 데이터 정합성 검증 등 후속 처리를 수행할 수 있습니다.

구현 시 주의사항:
- 통지 수신 시 즉시 응답해야 합니다.
- 동일한 통지가 중복 수신될 수 있으며, 멱등성을 보장해야 합니다.