เอกสารอ้างอิง API คำสั่งซื้อ

สรุป

หน้านี้รวบรวมสถานะ, endpoint, พารามิเตอร์ และรหัสข้อผิดพลาดของโมดูลคำสั่งซื้อ สำหรับขั้นตอนแบบครบวงจร ดู คู่มือการสั่งซื้อและชำระเงินคำสั่งซื้อ Taobao/1688 วิธีรับอัปเดตคำสั่งซื้อผ่าน webhook มี หน้าอ้างอิงแยกต่างหาก

ขอบเขต: รองรับหลายตลาดแล้ว การชำระเงินถูกรวมเป็น VND, USD หรือ RMB (CNY) — กระเป๋าเงินสำหรับสั่งซื้อเติมเงินด้วยหนึ่งในสามสกุลเงินนี้ ยอดคงเหลือและมูลค่าคำสั่งซื้อใน API ถูกปรับให้เป็นหน่วยกลาง (*_cny)

Elim เป็น แพลตฟอร์มเทคโนโลยี ที่ดูแลการดำเนินการคำสั่งซื้อและการชำระเงิน — ไม่ได้ขายปลีกและไม่รับลูกค้าปลายทางโดยตรง ระบบของคุณชำระเงินให้ Elim ผ่าน กระเป๋าเงินสำหรับสั่งซื้อ แล้ว Elim จึงชำระเงินต่อให้ผู้ขายบนแพลตฟอร์ม ด้วยเหตุนี้ทุกคำสั่งซื้อจึงมี สองสถานะที่เป็นอิสระต่อกัน — สถานะแพลตฟอร์ม (status) และสถานะการชำระเงินกับ Elim (payment_status) — บวกกับตัวบ่งชี้ผลการชำระเงินฝั่งแพลตฟอร์มอีกหนึ่งตัว (platform_payment_status)

ทุก endpoint ต้องมีการยืนยันตัวตน JWT (Authorization: Bearer <token>) หรือ API Key (x-api-key) ดู การยืนยันตัวตนคำขอ API

สถานะแพลตฟอร์ม (status)

ความคืบหน้าในการประมวลผลคำสั่งซื้อฝั่ง Taobao / 1688

creating → pending_payment → paid → shipped → completed
                                            ↘ cancelled

สถานะการชำระเงิน Elim (payment_status)

ความคืบหน้าการชำระเงินระหว่างผู้ใช้กับ Elim เป็นอิสระ จาก status

unpaid → requested → approved → paid → refunded
   ↑         ↓
   └──── rejected

จาก requested ผู้ใช้สามารถถอนคำขอของตนเองเพื่อกลับสู่ unpaid ได้ (ดู cancel-payment-request) หลังจาก approved แล้ว ย้อนกลับได้ด้วยการคืนเงินเท่านั้น

ผลการชำระเงินแพลตฟอร์ม (platform_payment_status)

มีค่าเฉพาะหลังจาก Elim ดำเนินการชำระเงินกับแพลตฟอร์มแล้วเท่านั้น

แสดงทั้ง status และ payment_status ในอินเทอร์เฟซเสมอ platform_payment_status ใช้เพื่อวินิจฉัยเมื่อเกิดปัญหาเป็นหลัก

Endpoint คำสั่งซื้อ

Prefix /v1/orders Rate limit นับตามกรอบเวลาวินาที

ดูตัวอย่างและสร้างคำสั่งซื้อ — body

{
  "platform": "alibaba",
  "receiver_address": {
    "name": "Nguyen Van A",
    "phone": "02812345678",
    "mobile": "13800138000",
    "address": "广州市天河区体育西路123号",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区",
    "town": "天河南街道"
  },
  "line_items": [
    { "product_ref": "734467086498", "sku_ref": "5578084256927", "quantity": 2, "price": 15.5 }
  ],
  "preview_token": "c5f75ec1-9f8d-4bf6-9de2-048d50fef349",
  "idempotency_key": "checkout-2026-08-25-001",
  "remark": "หมายเหตุถึงผู้ขาย",
  "promotion_id": "PROMO123"
}

line_items[]

แต่ละรายการระบุสินค้าด้วยคู่ product_ref + sku_ref ซึ่งนำมาจาก การค้นหา / รายละเอียดสินค้า โดยตรง

คู่ mp_id + mp_skuid (marketplace ID) ยังคงรองรับเพื่อความเข้ากันได้ย้อนหลัง

receiver_address

Response การดูตัวอย่าง

{
  "success": true,
  "preview_token": "c5f75ec1-9f8d-4bf6-9de2-048d50fef349",
  "currency": "CNY",
  "total_product_amount": 31.0,
  "total_post_fee": 8.0,
  "total_amount": 39.0,
  "shops": [
    {
      "seller_id": "b2b-2201234567",
      "seller_name": "广州某某贸易有限公司",
      "post_fee": 8.0,
      "shop_amount": 31.0,
      "items": [
        { "product_id": "734467086498", "sku_id": "5578084256927", "quantity": 2, "unit_price": 15.5, "total_price": 31.0 }
      ]
    }
  ],
  "unavailable_items": []
}

Response การสร้างคำสั่งซื้อ

{
  "status": "pending_payment",
  "data": {
    "id": "ORD0000000123",
    "order_list": [
      {
        "success": true,
        "amount": 39.0,
        "post_fee": 8.0,
        "lines": [
          { "sub_id": "E2101234567890", "product_id": "734467086498", "sku_id": "5578084256927", "quantity": 2, "amount": 31.0 }
        ]
      }
    ]
  }
}

คำสั่งซื้อใหม่จะอยู่ที่ payment_status = unpaid เสมอ

รายการคำสั่งซื้อ — พารามิเตอร์กรอง

GET /v1/orders

Response: { total, page, size, items: OrderListItem[] }

{
  "total": 1, "page": 1, "size": 20,
  "items": [
    {
      "id": "ORD0000000123",
      "platform": "alibaba",
      "status": "paid",
      "payment_status": "paid",
      "total_amount_cny": 39.0,
      "total_amount": 39.0,
      "products": [
        { "id": "734467086498", "name": "某某商品", "price": 15.5, "quantity": 2, "img_urls": ["https://..."] }
      ],
      "created_at": "2026-04-09T10:30:00.000Z"
    }
  ]
}

line_items / products ในรายการเป็นสแนปช็อตตอนสร้างคำสั่งซื้อ หากต้องการข้อมูลล่าสุด ให้เรียก GET /v1/orders/:id

รายละเอียดคำสั่งซื้อ — ความแตกต่างตามแพลตฟอร์ม

GET /v1/orders/:id — ซิงค์สถานะจากแพลตฟอร์มอัตโนมัติก่อนตอบกลับ

ฟิลด์ platform มีอยู่แล้วใน response รายการ — เก็บไว้เพื่อเลือกวิธีแสดงผลก่อนเรียกรายละเอียด

package_id เป็น จำนวนเต็ม ที่ได้จาก response รายละเอียดคำสั่งซื้อ Taobao ไม่ใช่ ID ORD...

ยกเลิกคำสั่งซื้อ — เงื่อนไข

POST /v1/orders/:id/cancel — เฉพาะเมื่อ status เป็น creating หรือ pending_payment

หากคำสั่งซื้อยังไม่มีรหัสคำสั่งซื้อของแพลตฟอร์ม: { "success": true, "message": "Internal order cancelled, no external order to cancel" }

Endpoint กระเป๋าเงินสำหรับสั่งซื้อ

Prefix /v1/purchasing

GET /v1/purchasing/wallet

{
  "balance": 1670.30,
  "frozen_balance": 286.50,
  "available_balance": 1383.80,
  "total_deposited": 5000.00,
  "total_spent": 3329.70,
  "updated_at": "2026-06-19T00:00:00.000Z"
}

GET /v1/purchasing/wallet/transactions

พารามิเตอร์: page, size, type, date_from, date_to Response: { total, page, size, items }

GET /v1/purchasing/exchange-rates

อาร์เรย์อัตราแลกเปลี่ยนที่ใช้งานอยู่ต่อคู่สกุลเงิน (VND→CNY, USD→CNY): source_currency, target_currency, rate (อัตราตลาด), markup_percent, effective_rate (อัตราที่ Elim ใช้จริงหลังบวก markup)

Endpoint การชำระเงินคำสั่งซื้อ

Prefix /v1/purchasing/orders/:id :id รับรูปแบบ ORD...

POST …/request-payment

{
  "success": true,
  "order_id": "ORD0000000123",
  "frozen_amount": 286.50,
  "goods_amount_cny": 281.50,
  "shipping_fee_cny": 0,
  "service_fee_cny": 5.00
}

ข้อผิดพลาดกระเป๋าเงินไม่พอ — 400:

{
  "error": "insufficient_balance",
  "current_balance": 120.00,
  "available_balance": 90.00,
  "required": 286.50,
  "deficit": 196.50
}

POST …/confirm

{
  "order_id": "ORD0000000123",
  "goods_amount_cny": 281.50,
  "shipping_fee_cny": 0,
  "service_fee_cny": 5.00,
  "total_amount_cny": 286.50,
  "payment_status": "paid",
  "wallet_balance_after": 1383.80
}

ใช้ wallet_balance_after เพื่ออัปเดตยอดคงเหลือที่แสดงโดยไม่ต้องเรียก GET /v1/purchasing/wallet อีกครั้ง

การเปลี่ยนสถานะที่ Elim ดำเนินการ

ผู้ใช้ ไม่ เรียกการดำเนินการเหล่านี้ รายการนี้มีไว้เพื่ออธิบายว่า payment_status จะเปลี่ยนอย่างไร และเมื่อใดที่คุณจะได้รับ payment.updated

รับอัปเดตคำสั่งซื้อผ่าน webhook

ลงทะเบียน webhook เพื่อให้ Elim เรียกเข้าระบบของคุณทุกครั้งที่ status หรือ payment_status ของคำสั่งซื้อเปลี่ยน — แทนการถามสถานะซ้ำ ๆ มีสองเหตุการณ์ที่เกี่ยวกับโมดูลคำสั่งซื้อ:

Payload บรรจุสแนปช็อตของคำสั่งซื้อ: data.order.id, status, payment_status, platform_payment_status, total_amount_cny, updated_at เมื่อประมวลผลเสร็จให้ตอบกลับ HTTP 2xx

endpoint การลงทะเบียน, โครงสร้าง payload ฉบับเต็ม, header, การตรวจสอบลายเซ็น HMAC และนโยบายลองใหม่: ดู เอกสารอ้างอิง Webhook

รหัสข้อผิดพลาด

Response ข้อผิดพลาดเป็นรูปแบบ { statusCode, message, error } message บางครั้งเป็นภาษาเวียดนามและแสดงต่อผู้ใช้ได้โดยตรง

ข้อกำหนดเรื่อง ID

• ID คำสั่งซื้อภายใน: ORD + ตัวเลข 10 หลัก เช่น ORD0000000123 ใช้กับทุก endpoint
• รหัสคำสั่งซื้อแพลตฟอร์ม (order_id): ออกโดย Taobao/1688 มีเฉพาะหลังสร้างคำสั่งซื้อสำเร็จ
• package_id: จำนวนเต็ม ใช้สำหรับติดตามการขนส่ง Taobao

ลิงก์ที่เกี่ยวข้อง

• คู่มือการสั่งซื้อและชำระเงินคำสั่งซื้อ Taobao/1688 — ขั้นตอนทีละขั้น
• เอกสารอ้างอิง Webhook — รับอัปเดต order.updated / payment.updated
• การยืนยันตัวตนคำขอ API
• เอกสารอ้างอิง API ฉบับเต็ม