openapi: 3.0.0
info:
  title: 피치에이아이 광고 송출 데이터 연동 API
  description: >
    본 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:
  - url: https://{customer-domain}/api/v1
    description: 고객사 프로덕션 서버
    variables:
      customer-domain:
        description: 고객사에서 제공하는 도메인
        default: api.customer.com
paths:
  /api/v1/branches:
    get:
      summary: 지점 목록 제공 API
      description: |
        고객사가 보유한 매장 지점에 대한 목록을 제공하는 API입니다.
        피치에이아이 시스템은 이 API를 통해 연동 대상 지점 정보를 수집합니다.

        구현 시 주의사항:
        - 페이지네이션 없이 전체 매체 목록을 한 번에 응답해야 합니다.
        - 지점 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.
      responses:
        '200':
          description: 지점 목록 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  branchs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Branch'
  /api/v1/displays:
    get:
      summary: 광고 매체 목록 제공 API
      description: >
        고객사가 보유한 전체 광고 매체의 목록을 제공하는 API입니다.


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


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


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


        구현 시 주의사항:

        - 페이지네이션 없이 전체 매체 목록을 한 번에 응답해야 합니다.

        - 매체 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.
      responses:
        '200':
          description: 매체 목록 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  displays:
                    type: array
                    items:
                      $ref: '#/components/schemas/Display'
  /api/v1/campaigns:
    get:
      summary: 캠페인 목록 제공 API
      description: |
        고객사가 보유한 전체 광고 캠페인 목록을 제공하는 API입니다.
        피치에이아이 시스템은 이 API를 통해 연동 대상 캠페인 정보를 수집합니다.

        구현 시 주의사항:
        - 페이지네이션 없이 전체 캠페인 목록을 한 번에 응답해야 합니다.
        - 캠페인 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.
      responses:
        '200':
          description: 캠페인 목록 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
  /api/v1/ad_contents:
    get:
      summary: 캠페인 컨텐츠 목록 제공 API
      description: |
        고객사가 보유한 전체 광고 캠페인 컨텐츠 목록을 제공하는 API입니다.
        피치에이아이 시스템은 이 API를 통해 연동 대상 캠페인 컨텐츠 정보를 수집합니다.

        구현 시 주의사항:
        - 페이지네이션 없이 전체 캠페인 컨텐츠 목록을 한 번에 응답해야 합니다.
        - 캠페인 컨텐츠 정보가 변경될 때마다 최신 정보가 응답되어야 합니다.
      responses:
        '200':
          description: 캠페인 컨텐츠 목록 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  ad_contents:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdContent'
  /api/v1/displays/{display_id}/ready:
    post:
      summary: 데이터 동기화 완료 수신 API
      description: |
        피치에이아이 시스템이 특정 매체의 특정 일자 데이터 동기화를 완료했음을 통지받는 API입니다.
        고객사는 이 통지를 수신하여 데이터 정합성 검증 등 후속 처리를 수행할 수 있습니다.

        구현 시 주의사항:
        - 통지 수신 시 즉시 응답해야 합니다.
        - 동일한 통지가 중복 수신될 수 있으며, 멱등성을 보장해야 합니다.
      parameters:
        - name: display_id
          in: path
          description: 동기화가 완료된 매체의 고유 식별자
          required: true
          schema:
            type: string
        - name: date
          in: query
          description: 동기화가 완료된 데이터의 기준일자 (YYYY-MM-DD 형식)
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: 동기화 완료 통지 수신 성공
        '400':
          description: 잘못된 요청 파라미터
        '404':
          description: 존재하지 않는 매체 식별자
components:
  schemas:
    Error:
      type: object
      description: 에러 응답 스키마
      properties:
        code:
          type: integer
          format: int32
          description: |
            시스템 정의 에러 코드
            - 400: 잘못된 요청
            - 401: 인증 실패
            - 403: 권한 없음
            - 404: 리소스 없음
            - 500: 서버 오류
        message:
          type: string
          description: 에러에 대한 상세 설명
      required:
        - code
        - message
    AdPlay:
      type: object
      description: 광고 송출 이력 데이터 스키마
      properties:
        id:
          type: string
          description: 고객사에서 발급한 송출 이력의 고유 식별자
          example: PLAY_1234
        campaign_id:
          type: string
          description: 고객사의 광고 캠페인 고유 식별자
          example: CAMPAIGN_1234
        start_time:
          type: string
          format: date-time
          description: 광고 송출 시작 시간 (ISO 8601 형식, UTC 기준)
          example: '2025-01-01T00:00:00Z'
        end_time:
          type: string
          format: date-time
          description: 광고 송출 종료 시간 (ISO 8601 형식, UTC 기준)
          example: '2025-01-01T00:00:30Z'
      required:
        - id
        - campaign_id
        - start_time
        - end_time
    Branch:
      type: object
      description: 지점 정보 스키마
      properties:
        id:
          type: string
          description: 고객사에서 발급한 지점의 고유 식별자 (영문, 숫자 조합)
          example: BRANCH_001
        name:
          type: string
          description: 지점의 식별 가능한 표시명
          example: 역삼 사거리점
      required:
        - id
        - name
    Display:
      type: object
      description: 광고 매체 정보 스키마
      properties:
        id:
          type: string
          description: 고객사에서 발급한 매체의 고유 식별자 (영문, 숫자 조합)
          example: DISPLAY_001
        name:
          type: string
          description: 매체의 식별 가능한 표시명
          example: 메인 로비 디스플레이
        branch:
          type: string
          description: 매체가 속한 지점의 이름
          example: 역삼 사거리점
        zone:
          type: string
          description: 매장내 매체가 속한 구역의 이름
          example: 농산물 코너
        section:
          type: string
          description: 매장내 매체가 속한 섹션의 이름
          example: 농산물 코너 상단 진열대
      required:
        - id
        - name
    Campaign:
      type: object
      description: 캠페인 정보 스키마
      properties:
        id:
          type: string
          description: 고객사에서 발급한 캠페인의 고유 식별자 (영문, 숫자 조합)
          example: campaign_001
        name:
          type: string
          description: 캠페인의 식별 가능한 표시명
          example: 컴포즈 커피
      required:
        - id
        - name
    AdContent:
      type: object
      description: 캠페인 컨텐츠 정보 스키마
      properties:
        id:
          type: string
          description: 고객사에서 발급한 캠페인 컴텐츠의 고유 식별자 (영문, 숫자 조합)
          example: ad_content_001
        name:
          type: string
          description: 캠페인 컨텐츠의 식별 가능한 표시명
          example: 컴포즈 커피 1920x900
      required:
        - id
        - name
