วิธีสร้างและการจัดการคำสั่งซื้อบน Taobao/1688

เมื่อใดควรใช้คู่มือนี้

ใช้เมื่อคุณต้องให้ผู้ใช้สั่งซื้อรับฝากสินค้าจาก Taobao/1688 ผ่าน Elimapi — ตั้งแต่การดูตัวอย่างคำสั่งซื้อ การสร้างคำสั่งซื้อ การติดตาม ไปจนถึงการชำระเงินด้วยกระเป๋าเงินซื้อสินค้า

หมายเหตุ: ฟังก์ชันนี้ในปัจจุบันรองรับเฉพาะตลาดเวียดนามเท่านั้น ตลาดอื่นๆ จะถูกเพิ่มในภายหลัง

เอกสารอ้างอิงฉบับเต็ม (สถานะ, endpoints, พารามิเตอร์, รหัสข้อผิดพลาด): เอกสารอ้างอิง API คำสั่งซื้อ

ข้อกำหนดก่อนเริ่ม

• ข้อมูลยืนยันตัวตน API (JWT หรือคีย์ API) — ดู การยืนยันตัวตน API requests
• รหัสสินค้า (Product ID) และรหัส SKU — รับจาก การค้นหาสินค้า
• ที่อยู่จัดส่งที่ถูกต้องในจีน

ภาพรวมกระบวนการ

Preview → Tạo đơn (payment_status=unpaid) → Xác nhận thanh toán ví → payment_status=paid

แต่ละคำสั่งซื้อมี สองสถานะอิสระ: status (แพลตฟอร์ม) และ payment_status (กระเป๋าเงิน Elim) แสดงทั้งสองสถานะในอินเทอร์เฟซเสมอ — อย่ารวมเป็นสถานะเดียว

ขั้นตอนที่ 1 — ดูตัวอย่างคำสั่งซื้อ

เรียก preview เพื่อรับยอดรวมโดยประมาณและตรวจสอบสถานะสินค้า ขั้นตอนนี้ ไม่สร้างคำสั่งซื้อและไม่หักเงิน

POST /v1/orders/preview

{
  "platform": "alibaba",
  "receiver_address": {
    "name": "Nguyễn Văn A",
    "phone": "02812345678",
    "mobile": "13800138000",
    "address": "广州市天河区体育西路123号",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区"
  },
  "line_items": [
    {
      "mp_id": "734467086498",
      "id": "5578084256927",
      "quantity": 2,
      "price": 15.5
    }
  ]
}

ต้องตรวจสอบ unavailable_items เสมอ: หากอาร์เรย์นี้ไม่ว่าง ห้ามสร้างคำสั่งซื้อ — ให้ถามผู้ใช้เพื่อจัดการรายการที่มีปัญหา (สินค้าหมด, SKU ผิด, หยุดจำหน่าย) ก่อน

ที่อยู่จัดส่งต้องเป็นที่อยู่ที่ถูกต้องในจีน

ขั้นตอนที่ 2 — สร้างคำสั่งซื้อ

ใช้ข้อมูลที่ผ่านการตรวจสอบแล้วจากขั้นตอน preview (body เหมือนเดิม) เพื่อสร้างคำสั่งซื้อจริง:

POST /v1/orders

หลังจากสร้างสำเร็จ ให้ redirect ผู้ใช้ไปยังหน้าข้อมูลคำสั่งซื้อ (/orders/ORD...) — คำสั่งซื้อถูกส่งไปยังแพลตฟอร์มแล้ว อย่าค้างผู้ใช้ไว้ในตะกร้าสินค้า

จัดการ response:

[!WARNING] หาก response คืนค่า status: "unknown" ให้แสดงคำเตือน “คำสั่งซื้ออาจยังไม่ถูกสร้าง — โปรดติดต่อฝ่ายสนับสนุน” อย่าดำเนินการต่อในขั้นตอนการชำระเงิน

ขั้นตอนที่ 3 — ค้นหาคำสั่งซื้อ

รายการคำสั่งซื้อ (แบ่งหน้า, ระบุผู้ใช้ผ่าน JWT):

GET /v1/orders?page=1&size=20&platform=taobao&status=paid

พารามิเตอร์กรอง: page, size, platform (taobao/alibaba), status, created_from, created_to

line_items ในรายการเป็น snapshot ตอนสร้างคำสั่งซื้อ หากต้องการข้อมูลล่าสุด ให้เรียกข้อมูลคำสั่งซื้อโดยตรง

รายละเอียดคำสั่งซื้อ:

GET /v1/orders/:id

หมายเหตุความแตกต่างระหว่างสองแพลตฟอร์ม:

แคชฟิลด์ platform จาก response ของรายการ เพื่อ render component ที่ถูกต้องก่อนเรียกดูรายละเอียด

ขั้นตอนที่ 4 — ยกเลิกคำสั่งซื้อ (หากจำเป็น)

POST /v1/orders/:id/cancel

เงื่อนไข: ยกเลิกได้เฉพาะเมื่อ status เป็น creating หรือ pending_payment ปิดใช้งานปุ่มยกเลิกในสถานะอื่น หลังจากยกเลิกแล้ว ให้เรียก GET /v1/orders/:id อีกครั้งเพื่อรับสถานะล่าสุด

หากคำสั่งซื้อยังไม่มี platform order ID ระบบจะคืนค่า { success: true, message: 'Internal order cancelled, no external order to cancel' } — คำสั่งซื้อถูกยกเลิกที่ Elim แต่ไม่มีการดำเนินการบน Taobao/1688

ขั้นตอนที่ 5 — ชำระเงินคำสั่งซื้อ

Elim ทำหน้าที่เป็นตัวแทนซื้อสินค้า: ผู้ใช้ชำระเงินให้ Elim ผ่าน กระเป๋าเงินซื้อสินค้า (หน่วยเป็น CNY) จากนั้น Elim ชำระเงินกับแพลตฟอร์ม

1. ดูยอดเงินในกระเป๋า: GET /v1/purchasing/wallet → { balance, frozen_balance, available }
2. ยืนยันการชำระเงิน: POST /v1/purchasing/orders/:id/confirm → ระบบตรวจสอบกระเป๋าเงิน หักเงิน และอัปเดต payment_status = paid
3. ใช้ balance_after ใน response เพื่ออัปเดตยอดเงินในกระเป๋าโดยไม่ต้องเรียกซ้ำ
4. หากยอดเงินในกระเป๋าไม่เพียงพอ ระบบจะคืนค่า 400 พร้อม { error: "insufficient_balance", deficit, current_balance, required } — แสดง modal แจ้งว่าเงินขาดกี่ CNY และแนะนำวิธีการเติมเงิน

ตรวจสอบผลลัพธ์

• Preview คืนยอดรวมตรงกับที่คาดไว้ และ unavailable_items ว่างเปล่า
• การสร้างคำสั่งซื้อคืน data.id รูปแบบ ORD... และ status = pending_payment
• การยืนยันการชำระเงินคืน payment_status = paid พร้อม balance_after
• ข้อมูลคำสั่งซื้อแสดง status และ payment_status ถูกต้อง

จัดการข้อผิดพลาดทั่วไป

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

• เอกสารอ้างอิง: เอกสารอ้างอิง API คำสั่งซื้อ — สถานะ, พารามิเตอร์, รหัสข้อผิดพลาดฉบับเต็ม
• การยืนยันตัวตน: การยืนยันตัวตน API requests