openapi: 3.0.1
info:
  title: P2ACH 광고분석 API
  description: P2ACH 광고분석 연동 API 문서입니다
  contact:
    email: support@p2ach.ai
  license:
    name: CC BY-NC
  version: v1
servers:
  - url: https://admin.dev.p2ach.io/customer
security:
  - Bearer: []
paths:
  /authorize:
    post:
      tags:
        - 인증
      summary: API 키 인증 api
      description: |-
        발급/전달 받은 access_key와 secret_access_key를 사용하여 인증합니다.
        반환 된 access token을 헤더에 `Bearer {access_token}` 형식으로 담아 요청합니다.
      operationId: authorize_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIAuthorize'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIAuthorizeResponse'
      x-codegen-request-body-name: data
  /advertisements:
    post:
      tags:
        - 송출 기록
      summary: 광고 송출 기록 저장 API
      description: |-
        피치에이아이 분석 데이터와 연동하기 위해 광고 송출 기록을 저장합니다.

        광고의 캠페인 ID, 송출 시작/종료시간과 광고가 송출된 매체(display) id를 리스트 형태로 요청합니다.

        광고 송출 기록을 해당 api 로 저장한 다음날 피치에이아이 내부에서 성과분석 데이터와 송출 기록 데이터를 연동합니다.

        start_date와 end_date는 UTC 기준입니다.
      operationId: advertising_record
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkAdvertisingRecord'
        required: true
      responses:
        '201':
          description: Success
        '400':
          description: Invalid request
      x-codegen-request-body-name: data
  /measurements:
    get:
      tags:
        - 성과분석
      summary: 배치용 광고 성과 분석 조회 api
      description: >-
        지정한 날짜의 광고 성과 측정 데이터를 조회합니다. campaign_ids, display_ids 파라미터를 통해 특정 캠페인들과
        매체들의 데이터만 조회하도록 지정할 수 있습니다. 한번에 모든 데이터를 가져오기 떄문에 배치성 작업에 적합합니다.
      operationId: measurements
      parameters:
        - name: campaign_ids
          in: query
          description: 광고 캠페인 id 리스트
          required: false
          schema:
            type: array
            items:
              type: string
        - name: display_ids
          in: query
          description: 디스플레이 id 리스트
          required: false
          schema:
            type: array
            items:
              type: string
        - name: datetime__gte
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: datetime__lte
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: combine_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - display
              - campaign
              - date
              - time
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Measurement'
  /measurements/v2:
    get:
      tags:
        - 성과분석
      summary: 웹용 광고 성과 분석 조회 api v2
      description: >-
        지정한 날짜 외 추가 세부 파라미터를 사용하여 광고 성과 측정 데이터를 조회합니다. api 응답이 빠르고 응답 데이터가 비대하지
        않아 웹에 보여주는 용도에 적합합니다.
      operationId: measurementsV2
      parameters:
        - name: branch_ids
          in: query
          description: 지점 id 리스트
          required: false
          schema:
            type: array
            items:
              type: string
        - name: display_ids
          in: query
          description: 디스플레이 id 리스트
          required: false
          schema:
            type: array
            items:
              type: string
        - name: campaign_ids
          in: query
          description: 광고 캠페인 id 리스트
          required: false
          schema:
            type: array
            items:
              type: string
        - name: datetime__gte
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: datetime__lte
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: combine_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - branch
              - display
              - campaign
              - date
              - time
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MeasurementCombineBy'
  /measurements/check:
    get:
      tags:
        - 성과분석
      summary: 성과분석 데이터 연동 확인 API
      description: 매체 별로 광고 성과 데이터와 송출기록 데이터 연동 여부를 확인하는 API
      operationId: measurements_measurements_check
      parameters:
        - name: date
          in: query
          description: 조회 날짜 (YYYY-MM-DD)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  < * >:
                    type: boolean
              example:
                display1: true
                display2: false
  /settopbox:
    get:
      tags:
        - 기기
      summary: 피치에이아이 셋탑박스 - 고객사 매체 조회
      description: |-
        피치에이아이에 등록되어 있는 셋탑박스와 연결된 매체(디스플레이) 정보를 조회합니다.
        각 항목에는 셋탑박스의 시리얼 번호, 설치 위치, 하드웨어 스펙, 카메라 유효 거리 등의 정보가 포함되어 있습니다.
      operationId: settopbox_read
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DisplayRegister'
    post:
      tags:
        - 기기
      summary: 셋탑박스-매체 등록 API
      description: |-
        초기 장비 셋업시, 사용자가 피치에이아이의 셋탑박스와 매체(디스플레이)를 연동할 수 있도록 등록하는 API입니다.
        이미 등록된 셋탑박스나 중복되는 매체 ID가 있는 경우 오류를 반환합니다.
      operationId: settopbox_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettopboxCreateRegister'
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayRegister'
      x-codegen-request-body-name: data
components:
  schemas:
    APIAuthorize:
      required:
        - access_key
        - secret_access_key
      type: object
      properties:
        access_key:
          title: Access key
          minLength: 1
          type: string
        secret_access_key:
          title: Secret access key
          minLength: 1
          type: string
    APIAuthorizeResponse:
      required:
        - access
        - refresh
      type: object
      properties:
        refresh:
          title: Refresh
          minLength: 1
          type: string
        access:
          title: Access
          minLength: 1
          type: string
    AdvertisingRecord:
      required:
        - campaign_id
        - end_date
        - display_id
        - start_date
      type: object
      properties:
        campaign_id:
          title: Campaign id
          minLength: 1
          type: string
          description: 광고 캠페인에 대한 ID
        display_id:
          title: Display id
          minLength: 1
          type: string
          description: 매체 ID
        start_date:
          title: Start date
          type: string
          description: 플레이 시작 시간, UTC 시간
          format: date-time
        end_date:
          title: End date
          type: string
          description: 플레이 종료 시간, UTC 시간
          format: date-time
    BulkAdvertisingRecord:
      required:
        - records
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/AdvertisingRecord'
    FootTraffic:
      required:
        - m_20
        - m_30
        - m_40
        - m_50
        - m_60
        - w_20
        - w_30
        - w_40
        - w_50
        - w_60
      type: object
      properties:
        m_20:
          title: M 20
          type: integer
          description: 20대 이하
        m_30:
          title: M 30
          type: integer
          description: 30대
        m_40:
          title: M 40
          type: integer
          description: 40대
        m_50:
          title: M 50
          type: integer
          description: 50대
        m_60:
          title: M 60
          type: integer
          description: 60대 이상
        w_20:
          title: W 20
          type: integer
          description: 20대 이하
        w_30:
          title: W 30
          type: integer
          description: 30대
        w_40:
          title: W 40
          type: integer
          description: 40대
        w_50:
          title: W 50
          type: integer
          description: 50대
        w_60:
          title: W 60
          type: integer
          description: 60대 이상
      description: 성별, 연령별 유동인구 숫자
    Focus:
      required:
        - m_20
        - m_30
        - m_40
        - m_50
        - m_60
        - w_20
        - w_30
        - w_40
        - w_50
        - w_60
      type: object
      properties:
        m_20:
          title: M 20
          type: integer
          description: 20대 이하
        m_30:
          title: M 30
          type: integer
          description: 30대
        m_40:
          title: M 40
          type: integer
          description: 40대
        m_50:
          title: M 50
          type: integer
          description: 50대
        m_60:
          title: M 60
          type: integer
          description: 60대 이상
        w_20:
          title: W 20
          type: integer
          description: 20대 이하
        w_30:
          title: W 30
          type: integer
          description: 30대
        w_40:
          title: W 40
          type: integer
          description: 40대
        w_50:
          title: W 50
          type: integer
          description: 50대
        w_60:
          title: W 60
          type: integer
          description: 60대 이상
      description: 성별, 연령별 주목한 유동인구 숫자
    Interested:
      required:
        - m_20
        - m_30
        - m_40
        - m_50
        - m_60
        - w_20
        - w_30
        - w_40
        - w_50
        - w_60
      type: object
      properties:
        m_20:
          title: M 20
          type: integer
          description: 20대 이하
        m_30:
          title: M 30
          type: integer
          description: 30대
        m_40:
          title: M 40
          type: integer
          description: 40대
        m_50:
          title: M 50
          type: integer
          description: 50대
        m_60:
          title: M 60
          type: integer
          description: 60대 이상
        w_20:
          title: W 20
          type: integer
          description: 20대 이하
        w_30:
          title: W 30
          type: integer
          description: 30대
        w_40:
          title: W 40
          type: integer
          description: 40대
        w_50:
          title: W 50
          type: integer
          description: 50대
        w_60:
          title: W 60
          type: integer
          description: 60대 이상
      description: 성별, 연령별 관심을 보인 유동인구 숫자
    MeasurementBase:
      required:
        - count
        - focus
        - foot_traffic
        - interested
      type: object
      properties:
        count:
          title: Count
          type: integer
          description: 총 유동인구 숫자
        foot_traffic:
          $ref: '#/components/schemas/FootTraffic'
        focus:
          $ref: '#/components/schemas/Focus'
        interested:
          $ref: '#/components/schemas/Interested'
      description: 일별 유동인구 숫자
    MeasurementByHour:
      required:
        - hour_0
        - hour_1
        - hour_10
        - hour_11
        - hour_12
        - hour_13
        - hour_14
        - hour_15
        - hour_16
        - hour_17
        - hour_18
        - hour_19
        - hour_2
        - hour_20
        - hour_21
        - hour_22
        - hour_23
        - hour_3
        - hour_4
        - hour_5
        - hour_6
        - hour_7
        - hour_8
        - hour_9
      type: object
      properties:
        hour_0:
          $ref: '#/components/schemas/MeasurementBase'
        hour_1:
          $ref: '#/components/schemas/MeasurementBase'
        hour_2:
          $ref: '#/components/schemas/MeasurementBase'
        hour_3:
          $ref: '#/components/schemas/MeasurementBase'
        hour_4:
          $ref: '#/components/schemas/MeasurementBase'
        hour_5:
          $ref: '#/components/schemas/MeasurementBase'
        hour_6:
          $ref: '#/components/schemas/MeasurementBase'
        hour_7:
          $ref: '#/components/schemas/MeasurementBase'
        hour_8:
          $ref: '#/components/schemas/MeasurementBase'
        hour_9:
          $ref: '#/components/schemas/MeasurementBase'
        hour_10:
          $ref: '#/components/schemas/MeasurementBase'
        hour_11:
          $ref: '#/components/schemas/MeasurementBase'
        hour_12:
          $ref: '#/components/schemas/MeasurementBase'
        hour_13:
          $ref: '#/components/schemas/MeasurementBase'
        hour_14:
          $ref: '#/components/schemas/MeasurementBase'
        hour_15:
          $ref: '#/components/schemas/MeasurementBase'
        hour_16:
          $ref: '#/components/schemas/MeasurementBase'
        hour_17:
          $ref: '#/components/schemas/MeasurementBase'
        hour_18:
          $ref: '#/components/schemas/MeasurementBase'
        hour_19:
          $ref: '#/components/schemas/MeasurementBase'
        hour_20:
          $ref: '#/components/schemas/MeasurementBase'
        hour_21:
          $ref: '#/components/schemas/MeasurementBase'
        hour_22:
          $ref: '#/components/schemas/MeasurementBase'
        hour_23:
          $ref: '#/components/schemas/MeasurementBase'
      description: 시간별 유동인구 숫자
    Measurement:
      required:
        - by_day
        - by_hour
        - campaign_id
        - date
        - settopbox_serial_number
      type: object
      properties:
        campaign_id:
          title: Campaign id
          minLength: 1
          type: string
          description: 광고 캠페인에 대한 ID
        display_id:
          title: Display id
          minLength: 1
          type: string
          description: 매체 ID
        date:
          title: Date
          type: string
          description: 조회 날짜
          format: date
        by_day:
          $ref: '#/components/schemas/MeasurementBase'
        by_hour:
          $ref: '#/components/schemas/MeasurementByHour'
    MeasurementCombineBy:
      required:
        - combine_by
        - measurements
      type: object
      properties:
        combine_by:
          title: combine_by paramter
          minLength: 1
          type: string
          description: combine_by 파라미터로 설정한 값의 ID
        measurements:
          $ref: '#/components/schemas/MeasurementBase'
    MeasurementDisplay:
      required:
        - display_id
        - measurements
      type: object
      properties:
        display_id:
          title: Display id
          minLength: 1
          type: string
          description: 매체 ID
        measurements:
          $ref: '#/components/schemas/MeasurementBase'
    MeasurementCampaign:
      required:
        - campaign_id
        - measurements
      type: object
      properties:
        campaign_id:
          title: Campaign id
          minLength: 1
          type: string
          description: 광고 캠페인에 대한 ID
        measurements:
          $ref: '#/components/schemas/MeasurementBase'
    DisplayRegister:
      required:
        - display_id
      type: object
      properties:
        settopbox_serial_number:
          title: Settopbox serial number
          type: string
          description: 셋탑박스 serial number
          readOnly: true
        detail:
          title: Detail
          type: string
          description: 설치 위치
          readOnly: true
        hardware_spec:
          title: Hardware spec
          type: string
          description: 하드웨어 주요 스펙
          readOnly: true
        effective_range:
          title: Effective range
          type: string
          description: 카메라 설정 (비전) 유효 거리
          readOnly: true
        display_id:
          title: Display id
          type: string
          description: 매체 ID
    SettopboxCreateRegister:
      required:
        - display_id
        - settopbox_serial_number
      type: object
      properties:
        display_id:
          title: Display id
          minLength: 1
          type: string
          description: 매체 ID
        settopbox_serial_number:
          title: Settopbox serial number
          minLength: 1
          type: string
          description: 셋탑박스 serial number
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header
    Token:
      type: apiKey
      name: Authorization
      in: header
x-original-swagger-version: '2.0'
