API đối tác

Đồng bộ hóa dữ liệu đơn hàng thông qua API

Đồng bộ hóa dữ liệu đơn hàng qua backend (nên thực hiện)

Để gửi dữ liệu đơn hàng đến CitrusAd, hãy sử dụng lệnh tương tự như lệnh bên dưới. Lưu ý rằng dữ liệu trong orders trường bên dưới là dữ liệu để làm ví dụ và không có thật. Tất cả các ví dụ này đều hiển thị tích hợp tiêu chuẩn .

📘

Tích hợp sellerId trên sàn thương mại?

Hãy nhớ đọc phần sellerId trên Sàn thương mại bên dưới.

Đơn hàng gồm một mặt hàng

Dưới đây là ngữ cảnh dành cho khách hàng đã mua một mặt hàng:

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"              
                }
              ]
            }
    ]
}

Nếu thành công, đối tượng sau sẽ được trả về:

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",
        }
    ]
}

🚧

Định dạng OrderDate

OrderDate ở định dạng trên được đọc là giờ UTC. Bạn sẽ cần phải đồng bộ hóa trong UTC.

Ngoài ra, bạn có thể đặt độ lệch cho múi giờ của mình, thay Z dành cho +HH:MM có liên quan đến múi giờ của bạn. Ví dụ: “orderDate”: “2021-12-02T15:00:00+10:00" sẽ chỉ định múi giờ là UTC+10.

Đơn hàng gồm nhiều mặt hàng

Dưới đây là ngữ cảnh của một khách hàng đã mua nhiều mặt hàng - có nhiều mặt hàng trong mảng 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"            
                }
              ]
            }
    ]
}

Nếu thành công, đối tượng sau sẽ được trả về:

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",
        }
    ]
}

Đồng bộ hóa nhiều đơn hàng

Nếu đang đồng bộ hóa nhiều đơn hàng, bạn có thể gửi tối đa 100 mặt hàng dưới dạng lô mỗi lần yêu cầu. Không có giới hạn về số lượng yêu cầu bạn có thể gửi. Thứ tự tải trọng được đẩy giống như thứ tự kết quả trả về. Việc này giúp dữ liệu luôn phù hợp với hình thái của lệnh trong backend của bạn.

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"              
                }
              ]
            }
    ]
}

Nếu thành công, đối tượng sau sẽ được trả về:

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 cho sàn thương mại

Nếu bạn đang giới thiệu người bán trên sàn thương mại, bạn cần phải đồng bộ hóa sellerId khi thích hợp vào thời điểm báo cáo đơn hàng. Trong trường hợp sản phẩm đã mua không có sellerIdthì bỏ qua cũng được.

❗️

Nếu bạn đang không hỗ trợ người bán trên thị trường trong những bước đầu tiên, bạn không cần chỉ định sellerId trong báo cáo đơn hàng

Dưới đây là ví dụ về đơn hàng mà một sản phẩm đến từ người bán trên sàn thương mại và một sản phẩm khác không phải là sản phẩm của sàn thương mại:

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"            
                }
              ]
            }
    ]
}

Đồng bộ hóa dữ liệu đơn hàng qua giao diện người dùng (không nên thực hiện)

Nếu bạn không thể đồng bộ dữ liệu đơn hàng qua chương trình backend, CitrusAd sẽ hỗ trợ API mở như nêu ở bên dưới. Bạn chỉ nên sử dụng tính năng này khi không thể tích hợp chương trình backend và không thể đồng bộ tệp tin.

🚧

Báo cáo dữ liệu qua giao diện người dùng có rủi ro cao hơn so với tích hợp chương trình backend tiêu chuẩn.

Nhà cung cấp dịch vụ tích hợp cần hiểu rõ rủi ro rằng mặc dù miền báo cáo hiện không bị trình chặn quảng cáo chặn, nhưng tương lai là có thể, tại thời điểm đó CitrusAd sẽ không chịu trách nhiệm về dữ liệu bị mất.

Đặc điểm kỹ thuật của API mở:

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

📘

Nếu bạn cần biết thông tin về các điều khoản được nêu trong phần này, vui lòng truy cập trang danh sách tham chiếu chi tiết.

Truy xuất thông tin đơn hàng

Nếu bạn muốn xác minh thông tin đơn hàng trong CitrusAd, hãy tạo lệnh NHẬN rồi gửi đến API /orders/ kèm theo id đơn hàng.

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

Bạn sẽ truy xuất được mọi thông tin liên quan đến đơn hàng được lưu trữ trong hệ thống CitrusAd.
Trong trường hợp không tìm thấy đơn hàng thì đơn hàng đó có thể chưa được nhập vào hệ thống CitrusAd.