กำลังซิงค์ข้อมูลคำสั่งซื้อผ่าน API

การซิงค์ข้อมูลคำสั่งซื้อผ่านแบ็กเอนด์ (แนะนำ)

ในการส่งข้อมูลคำสั่งซื้อไปยัง CitrusAd ให้ใช้คำสั่งที่คล้ายกับคำสั่งด้านล่าง โปรดทราบว่าข้อมูลใน orders ฟิลด์ด้านล่างเป็นข้อมูลจำลอง และให้ไว้ที่นี่เพื่อเป็นตัวอย่างเท่านั้น ตัวอย่างเหล่านี้ทั้งหมดแสดง การรวมมาตรฐาน

📘

รวม 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

หรือคุณสามารถตั้งค่าออฟเซ็ตสำหรับเขตเวลาของคุณแทน Z สำหรับ +HH:MM ที่เกี่ยวข้องกับเขตเวลาของคุณ ตัวอย่างเช่น: “วันที่สั่งซื้อ”: “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ซึ่งสามารถละไว้ได้

❗️

หากคุณไม่ได้เริ่มต้นใช้งานผู้ขายในตลาดกลาง คุณไม่จำเป็นต้องระบุรหัสผู้ขายในรายงานคำสั่งซื้อ

ด้านล่างนี้เป็นตัวอย่างการสั่งซื้อผลิตภัณฑ์หนึ่งมาจากผู้ขายในตลาดและอีกรายการหนึ่งไม่ใช่ผลิตภัณฑ์ในตลาด:

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 แบบเปิดตามที่ระบุด้านล่าง ขอแนะนำให้ใช้เฉพาะเมื่อไม่สามารถผสานรวมแบ็กเอนด์และไม่สามารถซิงค์ไฟล์

🚧

การรายงานข้อมูลใดๆ ผ่านฟรอนท์เอนด์มีความเสี่ยงสูงกว่าการรวมแบ็กเอนด์มาตรฐาน

ผู้ประกอบควรตระหนักถึงความเสี่ยงที่แม้โดเมนรายงานไม่ได้ถูก Adblocker บล็อกตอนนี้ แต่อาจถูกบล็อกในอนาคต และเมื่อถึงตอนนั้น 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 คุณจะต้องส่งคำขอ GET ไปยัง /orders/ API ที่มีรหัสคําสั่งซื้อ

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

คุณจะดึงข้อมูลทั้งหมดที่เกี่ยวข้องกับคำสั่งซื้อที่จัดเก็บไว้ในระบบ CitrusAd
ในกรณีที่ไม่พบคำสั่งซื้อ มีแนวโน้มว่าคำสั่งซื้อยังไม่ถูกนำเข้าไปยังระบบ CitrusAd