파트너 API

API를 통한 주문 데이터 동기화

백엔드를 통한 주문 데이터 동기화(권장)

주문 데이터를 CitrusAd에 전송하려면 아래 명령과 유사한 명령을 사용합니다. 아래 orders 필드의 데이터는 더미 데이터이며 여기에서 예시로만 제공됩니다. 이러한 예는 모두 표준 통합을 표시합니다.

📘

마켓플레이스 sellerId를 통합하시겠습니까?

아래 마켓플레이스 sellerId를 반드시 읽으십시오.

단일 항목 주문

다음은 단일 항목을 구매한 고객의 컨텍스트입니다.

POST $BASE_URL/v1/orders HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "orders": [
       {
        "customerId": "npc-s243-ir",
        "catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
        "sessionId": "5cat7-9964-4f",
        "orderDate": "2021-12-02T15:00:00Z",
        "id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
        "orderItems": [
            {
                  "gtin": "9891998566P",
                  "quantity": 3,
                  "regularUnitPrice": "1.00",
                  "totalOrderItemPriceAfterDiscounts": "3.00"              
                }
              ]
            }
    ]
}

성공하면 다음 오브젝트가 반환됩니다.

HTTP/2 200
{
    "orders": [
        {
            "adIds": null,
            "teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
            "customerId": "npc-s243-ir",
            "catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
            "sessionId": "5cat7-9964-4f",
            "id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
            "orderItems": [
                {
                    "regularUnitPrice": 1.00,
                    "citrusDiscountAmount": null,
                    "gtin": "9891998566P",
                    "adId": "",
                    "quantity": 3,
                    "substitutedFor": null,
                    "totalOrderItemPriceAfterDiscounts": 3.00
                }
            ],
            "orderDate": "2021-12-02T15:00:00Z",
        }
    ]
}

🚧

OrderDate 형식

위 형식의 OrderDate는 UTC 시간으로 읽습니다. UTC로 동기화해야 합니다.

또는 귀하의 시간대에 해당하는 `+HH:MM을 Z 에 대해 +HH:MM 로 대체하여 시간대 오프셋을 설정할 수 있습니다. 예를 들어 "orderDate": “2021-12-02T15:00:00+10:00" 는 표준 시간대를 UTC+10으로 지정합니다.

여러 항목 주문

아래는 여러 항목을 구매한 고객의 컨텍스트입니다. orderItems 배열에 여러 항목이 있습니다.

POST $BASE_URL/v1/orders HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "orders": [
       {
       "customerId": "npc-s243-ir",
       "catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
        "sessionId": "5cat7-9964-4f",
        "orderDate": "2021-12-02T15:00:00Z",
        "id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
        "orderItems": [
            {
                  "gtin": "9891998566P",
                  "quantity": 3,
                  "regularUnitPrice": "1.00",
                  "totalOrderItemPriceAfterDiscounts": "3.00"              
                }
              ]
            },
          {
                  "gtin": "351998532P",
                  "quantity": 1,
                  "regularUnitPrice": "2.50",
                  "totalOrderItemPriceAfterDiscounts": "2.50"            
                }
              ]
            }
    ]
}

성공하면 다음 오브젝트가 반환됩니다.

HTTP/2 200
{
    "orders": [
        {
            "adIds": null,
            "teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
            "customerId": "npc-s243-ir",
            "catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
            "sessionId": "5cat7-9964-4f",
            "id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
            "orderItems": [
                {
                    "regularUnitPrice": 1.00,
                    "citrusDiscountAmount": null,
                    "gtin": "9891998566P",
                    "adId": "",
                    "quantity": 3,
                    "substitutedFor": null,
                    "totalOrderItemPriceAfterDiscounts": 3.00
                },
                {
                    "regularUnitPrice": 2.50,
                    "citrusDiscountAmount": null,
                    "gtin": "351998532P",
                    "adId": "",
                    "quantity": 1,
                    "substitutedFor": null,
                    "totalOrderItemPriceAfterDiscounts": 2.50
                }
            ],
            "orderDate": "2021-12-02T15:00:00Z",
        }
    ]
}

여러 주문 동기화

여러 주문을 동기화하는 경우 요청당 최대 100개 항목을 묶음으로 전송할 수 있습니다. 요청 횟수는 무제한입니다. 푸시된 페이로드 순서는 반환된 결과와 순서가 동일합니다. 이렇게 하면 데이터를 백엔드에서 주문 표시와 일치시킬 수 있습니다.

POST $BASE_URL/v1/orders HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "orders": [
        {
      		  "customerId": "npc-s243-ir",
            "catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
            "sessionId": "5cat7-9964-4f",
      		  "orderDate": "2021-12-02T15:00:00Z",
      		  "id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
      		  "orderItems": [
            {
                  "gtin": "9891998566P",
                  "quantity": 3,
                  "regularUnitPrice": "1.00",
                  "totalOrderItemPriceAfterDiscounts": "3.00"              
                }
              ]
            },
        {
      		  "customerId": "rw3-v3ag-ol0",
            "sessionId": "2m342-2dfe-0f",
      		  "orderDate": "2021-12-02T15:00:00Z",
      		  "id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
      		  "orderItems": [
            {
                  "gtin": "5431998566P",
                  "quantity": 2,
                  "regularUnitPrice": "2.00",
                  "totalOrderItemPriceAfterDiscounts": "4.00"              
                }
              ]
            }
    ]
}

성공하면 다음 오브젝트가 반환됩니다.

HTTP/2 200
{
    "orders": [
        {
            "adIds": null,
            "teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
      		  "customerId": "npc-s243-ir",
            "catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
            "sessionId": "5cat7-9964-4f",
            "id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
            "orderItems": [
                {
                    "regularUnitPrice": 1.00,
                    "citrusDiscountAmount": null,
                    "gtin": "9891998566P",
                    "adId": "",
                    "quantity": 3,
                    "substitutedFor": null,
                    "totalOrderItemPriceAfterDiscounts": 3.00
                }
            ],
            "orderDate": "2021-12-02T15:00:00Z"
        },
        {
            "adIds": null,
            "teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
            "customerId": "rw3-v3ag-ol0",
            "sessionId": "2m342-2dfe-0f",
            "id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
            "orderItems": [
                {
                    "regularUnitPrice": 2.00,
                    "citrusDiscountAmount": null,
                    "gtin": "5431998566P",
                    "adId": "",
                    "quantity": 2,
                    "substitutedFor": null,
                    "totalOrderItemPriceAfterDiscounts": 4.00
                }
            ],
            "orderDate": "2021-12-02T15:00:00Z"
        }
    ]
}

마켓플레이스 sellerId

마켓플레이스 판매자를 온보딩하는 경우 다음을 동기화해야 합니다. sellerId 를 동기화해야 합니다. 구매한 제품에 sellerId가 없는 경우 생략할 수 있습니다.

❗️

마켓플레이스 판매자를 온보딩하지 않은 경우에는 주문 보고서에 sellerId를 지정하지 않아도 됩니다.

다음은 하나는 마켓플레이스 판매자의 제품이고 다른 하나는 마켓플레이스 외 제품인 경우 주문의 예입니다.

POST $BASE_URL/v1/orders HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "orders": [
       {
        "customerId": "npc-s243-ir",
        "catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
        "sessionId": "5cat7-9964-4f",
        "orderDate": "2021-12-02T15:00:00Z",
        "id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
        "orderItems": [
            {
                  "gtin": "9891998566P",
                  "quantity": 3,
                  "regularUnitPrice": "1.00",
                  "totalOrderItemPriceAfterDiscounts": "3.00",
                  "sellerId": "10sa-3s33-j8e3"
                }
              ]
            },
          {
                  "gtin": "351998532P",
                  "quantity": 1,
                  "regularUnitPrice": "2.50",
                  "totalOrderItemPriceAfterDiscounts": "2.50"            
                }
              ]
            }
    ]
}

프론트엔드를 통한 주문 데이터 동기화(권장하지 않음)

백엔드를 통해 주문 데이터를 동기화할 수 없는 경우, CitrusAd는 아래에 명시된 대로 오픈 API를 지원합니다. 백엔드 통합 및 파일 동기화 기능을 사용할 수 없는 경우에만 이를 사용하는 것이 좋습니다.

🚧

프론트엔드를 통해 데이터를 보고하는 것은 표준 백엔드 통합보다 더 위험합니다.

통합자는 도메인 보고가 현재 광고 차단기에 의해 차단되지는 않았지만 향후 어느 시점에 CitrusAd가 손실된 데이터에 대한 책임을 지지 않을 수 있다는 위험을 인식해야 합니다.

오픈 API 사양:

openapi: 3.0.1
info:
  title: Citrus
  version: 1.0.0
paths:
  /v1/resource/third-o:
    get:
      tags:
      - resource
      summary: Report an order.
      operationId: resource-third-o
      parameters:
      - in: query
        name: key
        description: |
          (Publishable) API key.
        schema:
          type: string
        required: true
      - in: query
        name: teaid
        description: |
          Team id.
        schema:
          type: string
        required: false
      - in: query
        name: catid
        description: |
          Catalog id.
        schema:
          type: string
        required: true
      - in: query
        name: ordid
        description: |
          Order id.
        schema:
          type: string
        required: true
      - in: query
        name: ordts
        description: |
          Order timestamp as a string in RFC3339.
        schema:
          type: string
        required: true
      - in: query
        name: sesid
        description: |
          Session id.
        schema:
          type: string
        required: true
      - in: query
        name: cusid
        description: |
          Customer id.
        schema:
          type: string
      - in: query
        name: procods
        description: |
          Product codes. Related by index to pris and quas. The length must match pris and quas.
        schema:
          type: array
          items:
            type: string
        examples:
          uat:
            value: [ "procods=7913494","procods=6815686" ]
            summary: "product code list"
        required: true
      - in: query
        name: pris
        description: |
          Prices as strings. Related by index to itsids and quas. The length must match pris and quas.
        schema:
          type: array
          items:
            type: string
        examples:
          uat:
            value: [ "pris=7913494","pris=6815686" ]
            summary: "prices list"
        required: true
      - in: query
        name: quas
        description: |
          Quantities as strings. Related by index to itsids and pris. The length must match itsids and pris.
        schema:
          type: array
          items:
            type: string
        examples:
          uat:
            value: [ "quas=7913494","quas=6815686" ]
            summary: "quantity list"
        required: true
      responses:
        200:
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
        400:
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        401:
          description: Invalid credentails.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        403:
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - apiKey: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header

📘

이 섹션에 기술된 용어를 잘 모르는 경우 참조 페이지를 방문하십시오.

주문 정보 검색

CitrusAd 내에서 주문 정보를 확인하려는 경우 주문 ID로 /orders/ API에 대한 GET 요청을 생성해야 합니다.

GET $BASE_URL/v1/orders/<ORDER_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>

CitrusAd 시스템 내에 저장된 주문과 관련된 모든 정보를 검색합니다.
제품을 찾을 수 없는 경우 주문이 CitrusAd 시스템에 처리되지 않았을 수 있습니다.