Skip to content

피치에이아이 광고 송출 데이터 연동 API (1.0.0)

본 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

Download OpenAPI description
Languages
Servers
Mock server
https://docs.p2ach.ai/_mock/apis/integration/
고객사 프로덕션 서버
https://{customer-domain}/api/v1/

지점 목록 제공 API

Request

고객사가 보유한 매장 지점에 대한 목록을 제공하는 API입니다. 피치에이아이 시스템은 이 API를 통해 연동 대상 지점 정보를 수집합니다.

구현 시 주의사항:

  • 페이지네이션 없이 전체 매체 목록을 한 번에 응답해야 합니다.
  • 지점 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.
curl -i -X GET \
  https://docs.p2ach.ai/_mock/apis/integration/api/v1/branches

Responses

지점 목록 조회 성공

Bodyapplication/json
branchsArray of objects(Branch)
Response
application/json
{ "branchs": [ {} ] }

광고 매체 목록 제공 API

Request

고객사가 보유한 전체 광고 매체의 목록을 제공하는 API입니다.

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

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

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

구현 시 주의사항:

  • 페이지네이션 없이 전체 매체 목록을 한 번에 응답해야 합니다.
  • 매체 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.
curl -i -X GET \
  https://docs.p2ach.ai/_mock/apis/integration/api/v1/displays

Responses

매체 목록 조회 성공

Bodyapplication/json
displaysArray of objects(Display)
Response
application/json
{ "displays": [ {} ] }

캠페인 목록 제공 API

Request

고객사가 보유한 전체 광고 캠페인 목록을 제공하는 API입니다. 피치에이아이 시스템은 이 API를 통해 연동 대상 캠페인 정보를 수집합니다.

구현 시 주의사항:

  • 페이지네이션 없이 전체 캠페인 목록을 한 번에 응답해야 합니다.
  • 캠페인 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.
curl -i -X GET \
  https://docs.p2ach.ai/_mock/apis/integration/api/v1/campaigns

Responses

캠페인 목록 조회 성공

Bodyapplication/json
campaignsArray of objects(Campaign)
Response
application/json
{ "campaigns": [ {} ] }

캠페인 컨텐츠 목록 제공 API

Request

고객사가 보유한 전체 광고 캠페인 컨텐츠 목록을 제공하는 API입니다. 피치에이아이 시스템은 이 API를 통해 연동 대상 캠페인 컨텐츠 정보를 수집합니다.

구현 시 주의사항:

  • 페이지네이션 없이 전체 캠페인 컨텐츠 목록을 한 번에 응답해야 합니다.
  • 캠페인 컨텐츠 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.
curl -i -X GET \
  https://docs.p2ach.ai/_mock/apis/integration/api/v1/ad_contents

Responses

캠페인 컨텐츠 목록 조회 성공

Bodyapplication/json
ad_contentsArray of objects(AdContent)
Response
application/json
{ "ad_contents": [ {} ] }

데이터 동기화 완료 수신 API

Request

피치에이아이 시스템이 특정 매체의 특정 일자 데이터 동기화를 완료했음을 통지받는 API입니다. 고객사는 이 통지를 수신하여 데이터 정합성 검증 등 후속 처리를 수행할 수 있습니다.

구현 시 주의사항:

  • 통지 수신 시 즉시 응답해야 합니다.
  • 동일한 통지가 중복 수신될 수 있으며, 멱등성을 보장해야 합니다.
Path
display_idstringrequired

동기화가 완료된 매체의 고유 식별자

Query
datestring(date)required

동기화가 완료된 데이터의 기준일자 (YYYY-MM-DD 형식)

curl -i -X POST \
  'https://docs.p2ach.ai/_mock/apis/integration/api/v1/displays/{display_id}/ready?date=2019-08-24'

Responses

동기화 완료 통지 수신 성공