คู่มือ Order API

ขณะนี้ฟีเจอร์นี้รองรับเฉพาะตลาดเวียดนามเท่านั้น เราจะเพิ่มการรองรับตลาดอื่นๆ ในอนาคต โปรดติดตามข่าวสารอัปเดต

Order API ช่วยให้คุณสร้างและจัดการคำสั่งซื้อแทนบน Taobao และ 1688 (Alibaba) คำสั่งซื้อแต่ละรายการมี สถานะสองแบบที่เป็นอิสระ: สถานะแพลตฟอร์ม (status) ที่ Taobao/1688 ส่งกลับมา และสถานะการชำระเงิน Elim (payment_status) ที่ระบบกระเป๋าสินค้าจัดการ

ทุก endpoint ต้องการการยืนยันตัวตน JWT ผ่าน header Authorization: Bearer <token> หรือ API Key (X-API-KEY)

คู่มือการยืนยันตัวตน: Authentication

สถานะคำสั่งซื้อ

ก่อนใช้ API โปรดทำความเข้าใจสถานะสองมิติของคำสั่งซื้อเพื่อหลีกเลี่ยงความสับสนเมื่อแสดงผลต่อผู้ใช้งานปลายทาง

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

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

ค่า	คำอธิบาย	แพลตฟอร์ม
`creating`	สร้างคำสั่งซื้อแล้ว รอการยืนยันจากแพลตฟอร์ม	✅ Taobao ✅ 1688
`pending_payment`	แพลตฟอร์มสร้างคำสั่งซื้อแล้ว รอการชำระเงิน	✅ Taobao ✅ 1688
`paid`	ชำระเงินแล้วบนแพลตฟอร์ม	✅ Taobao ✅ 1688
`shipped`	สินค้าออกจากคลัง อยู่ระหว่างจัดส่ง	✅ Taobao ✅ 1688
`completed`	คำสั่งซื้อเสร็จสมบูรณ์ ผู้ซื้อยืนยันรับสินค้า	✅ Taobao ✅ 1688
`cancelled`	คำสั่งซื้อถูกยกเลิก	✅ Taobao ✅ 1688
`unknown`	ไม่สามารถแปลงสถานะจากแพลตฟอร์มได้	✅ Taobao ✅ 1688

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

สะท้อนถึงว่าคำสั่งซื้อได้ชำระเงินให้ Elim แล้วหรือไม่ สถานะนี้ เป็นอิสระ จาก status — คำสั่งซื้ออาจอยู่ที่ status=shipped แต่ยังเป็น payment_status=unpaid หากมีปัญหาเกิดขึ้น

ค่า	คำอธิบาย
`unpaid`	ยังไม่ชำระเงิน — ค่าเริ่มต้นเมื่อสร้างคำสั่งซื้อ
`paid`	หักจากกระเป๋าสินค้าสำเร็จแล้ว
`refunded`	คืนเงินเข้ากระเป๋าหลังจากยกเลิกคำสั่งซื้อ

แสดงทั้งฟิลด์ `status` และ `payment_status` ในอินเทอร์เฟซของคุณเสมอ อย่ารวมเป็นสถานะเดียว — ผู้ใช้ต้องรู้ทั้งความคืบหน้าของคำสั่งซื้อและสถานะการชำระเงิน

ดูตัวอย่างคำสั่งซื้อ

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

ก่อนสร้างคำสั่งซื้อจริง ให้เรียก endpoint ดูตัวอย่างเพื่อรับยอดรวมโดยประมาณและตรวจสอบความพร้อมของสินค้า ขั้นตอนนี้ไม่สร้างคำสั่งซื้อหรือหักเงิน — ส่งคืนเฉพาะข้อมูลเพื่อให้ผู้ใช้ยืนยันก่อนชำระเงิน

Rate limit: 20 ครั้ง / 60 วินาที

POST /v1/orders/preview

Request body:

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

ข้อมูลที่อยู่ผู้รับสินค้าต้องเป็นที่อยู่ที่ถูกต้องในประเทศจีน

คำอธิบายฟิลด์ `line_items`

ฟิลด์	ประเภท	จำเป็น	คำอธิบาย
`mp_id`	string	ใช่	รหัสสินค้า — `mp_id` (Taobao) / `offerId` (1688)
`id`	string	ใช่	รหัส SKU — `mp_skuid` (Taobao) / `spec_id` (1688)
`quantity`	number	ใช่	จำนวนที่ต้องการซื้อ
`price`	number	ไม่	ราคาต่อหน่วย (CNY) — จำเป็นสำหรับการดูตัวอย่างที่แม่นยำ

การจัดการ `unavailable_items`

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

{
  "unavailable_items": [{ "mp_id": "123456", "id": "sku_789", "reason": "out_of_stock" }]
}

พารามิเตอร์ที่ไม่บังคับ

พารามิเตอร์	คำอธิบาย	แพลตฟอร์ม
`remark`	หมายเหตุแนบกับคำสั่งซื้อ	✅ Taobao ✅ 1688
`promotion_id`	รหัสโปรโมชั่น	✅ Taobao ✅ 1688

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

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

สร้างคำสั่งซื้อจริงบนแพลตฟอร์ม Request body เหมือนกับการดูตัวอย่าง — ควรใช้ข้อมูลที่ผ่านการตรวจสอบแล้วจากขั้นตอนดูตัวอย่างเพื่อสร้างคำสั่งซื้อและหลีกเลี่ยงความไม่สอดคล้อง

Rate limit: 10 ครั้ง / 60 วินาที

POST /v1/orders

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

การจัดการ Response

ฟิลด์	คำอธิบาย
`data.id`	รหัสภายในรูปแบบ `ORD0000000001` — ใช้สำหรับการดำเนินการต่อๆ ไปทั้งหมด
`status`	`pending_payment` หากสำเร็จ; `unknown` หากเกิดข้อผิดพลาด
`data.order_list[]`	รายละเอียดร้านค้า + สินค้าจากแพลตฟอร์ม — ใช้แสดงใบเสร็จ

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

รูปแบบรหัส: Elim ID จะเป็นรูปแบบ ORD + 10 หลักเสมอ (เช่น ORD0000000123) คำสั่งซื้อที่สร้างสำเร็จจะมี order_id ของแพลตฟอร์มด้วย

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

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

ส่งคืนรายการคำสั่งซื้อของผู้ใช้ปัจจุบัน (ระบุตัวตนผ่าน JWT) ผลลัพธ์แบ่งหน้า

Rate limit: 30 ครั้ง / 60 วินาที

GET /v1/orders

พารามิเตอร์กรอง

พารามิเตอร์	ประเภท	คำอธิบาย
`page`	number	หน้าปัจจุบัน — ค่าเริ่มต้น 1
`size`	number	จำนวนรายการต่อหน้า — ค่าเริ่มต้น 20
`platform`	string	`taobao` หรือ `alibaba` — ละว่างเพื่อดูทั้งคู่
`status`	OrderStatus	กรองตามสถานะแพลตฟอร์ม
`created_from`	ISO date	กรองตั้งแต่วันที่
`created_to`	ISO date	กรองถึงวันที่

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

ฟิลด์ `line_items` ในรายการเป็น snapshot เมื่อสร้างคำสั่งซื้อ หากต้องการข้อมูลคำสั่งซื้อที่เป็นปัจจุบันและถูกต้อง ให้เรียก `GET /v1/orders/:id`

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

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

ส่งคืนข้อมูลที่ครบถ้วนและเป็นปัจจุบันที่สุดของคำสั่งซื้อ

Rate limit: 30 ครั้ง / 60 วินาที

GET /v1/orders/:id

ส่งรหัสในรูปแบบ ORD...

ความแตกต่างของ Response ระหว่าง Taobao และ 1688

แพลตฟอร์มทั้งสองส่งคืนโครงสร้างข้อมูลที่แตกต่างกัน — ต้องจัดการแยกกัน:

แพลตฟอร์ม	สินค้า	โลจิสติกส์
1688	`products[]`	`logistics.logistics_info[]` — ฝังอยู่ใน response แล้ว
Taobao	`line_items[]`	ต้องเรียก `GET /v1/orders/:packageId/logistic-detail` แยก

ฟิลด์ platform มีอยู่ใน response รายการ — แคชจาก list view เพื่อรู้ว่าต้องเรนเดอร์ component ไหนก่อนเรียก detail

ยกเลิกคำสั่งซื้อ

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

ยกเลิกคำสั่งซื้อที่อยู่ในสถานะที่สามารถยกเลิกได้ หลังจากระบบยกเลิกสำเร็จ ให้เรียก GET /v1/orders/:id อีกครั้งเพื่อรับสถานะล่าสุด

Rate limit: 10 ครั้ง / 60 วินาที

POST /v1/orders/:id/cancel

เงื่อนไข: สามารถยกเลิกได้เฉพาะเมื่อ status เป็น creating หรือ pending_payment เท่านั้น ปิดการใช้งานปุ่มยกเลิกสำหรับสถานะอื่นๆ

หากคำสั่งซื้อยังไม่มีรหัสคำสั่งซื้อของแพลตฟอร์ม (แพลตฟอร์มยังไม่ประมวลผล) ระบบจะส่งคืน `{ success: true, message: 'Internal order cancelled, no external order to cancel' }` — คำสั่งซื้อถูกยกเลิกใน Elim API แล้ว แต่ไม่มีการดำเนินการใดๆ บน Taobao/1688

ติดตามการจัดส่ง

ดูรายละเอียด: รายละเอียดโลจิสติกส์

ส่งคืนข้อมูลติดตามการจัดส่งภายในจีน สำหรับ Taobao เท่านั้น — คำสั่งซื้อ 1688 มี logistics.logistics_info[] ฝังอยู่ใน response รายละเอียดคำสั่งซื้อแล้ว

Rate limit: 20 ครั้ง / 60 วินาที

GET /v1/orders/:packageId/logistic-detail

packageId เป็น จำนวนเต็ม ได้จาก response รายละเอียดคำสั่งซื้อ Taobao — ไม่ใช่รหัสรูปแบบ ORD...

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

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

ดูตัวอย่าง → สร้างคำสั่งซื้อ (payment_status=unpaid) → ยืนยันการชำระเงินกระเป๋า → payment_status=paid

ดูยอดเงินในกระเป๋า

GET /v1/purchasing/wallet

Response: { balance, frozen_balance, available } — available = balance - frozen_balance

ยืนยันการชำระเงิน

POST /v1/purchasing/orders/:id/confirm

ระบบตรวจสอบกระเป๋า → หักเงิน → อัปเดต payment_status = paid

Response เมื่อสำเร็จ (200):

{
  "order_id": "ORD0000000001",
  "goods_amount_cny": 299.0,
  "shipping_fee_cny": 15.0,
  "service_fee_cny": 15.7,
  "total_amount_cny": 329.7,
  "paid_at": "2026-04-13T10:00:00.000Z",
  "balance_after": 1670.3
}

ใช้ balance_after เพื่ออัปเดตยอดเงินในกระเป๋าใน local state โดยไม่ต้องเรียก GET /v1/purchasing/wallet อีก

การจัดการยอดเงินไม่เพียงพอ

เมื่อกระเป๋ามีเงินไม่เพียงพอ ระบบจะส่งคืน 400 พร้อม body:

{
  "error": "insufficient_balance",
  "deficit": 50.3,
  "current_balance": 279.4,
  "required": 329.7
}

แสดง modal แจ้งว่าต้องเติมเงินอีกเท่าไร CNY และแนะนำให้ผู้ใช้เติมเงิน กระบวนการเติมเงินดำเนินการนอกระบบ (โอนเงิน) — admin ยืนยันและเติมเงินในกระเป๋าด้วยตนเอง

ค่าธรรมเนียมบริการ

สูตรค่าธรรมเนียมบริการ: max(ยอดรวมคำสั่งซื้อ × เปอร์เซ็นต์ค่าธรรมเนียม, ค่าธรรมเนียมขั้นต่ำ) เปอร์เซ็นต์และขั้นต่ำกำหนดโดย admin

ประวัติธุรกรรมกระเป๋า

GET /v1/purchasing/wallet/transactions

พารามิเตอร์	คำอธิบาย
`page`	หมายเลขหน้า
`size`	จำนวนรายการต่อหน้า
`type`	`deposit` / `order_deduction` / `order_refund` / `admin_adjustment`
`date_from`	วันที่เริ่มต้น (ISO date)
`date_to`	วันที่สิ้นสุด (ISO date)

อัตราแลกเปลี่ยน

GET /v1/purchasing/exchange-rates

ส่งคืนอัตราแลกเปลี่ยนปัจจุบัน VND → CNY และ USD → CNY ที่ Elim กำหนด แสดงให้ผู้ใช้เห็นก่อนเติมเงิน

การจัดการข้อผิดพลาด

HTTP	สถานการณ์	วิธีจัดการ
`400`	`insufficient_balance`	แจ้งผู้ใช้ว่ายอดเงินในกระเป๋าไม่เพียงพอ
`400`	รูปแบบ platform ID ไม่ถูกต้อง	แสดงข้อความตรวจสอบ validation
`401`	JWT หมดอายุ	แจ้ง session หมดอายุ ขอให้ผู้ใช้เข้าสู่ระบบอีกครั้ง
`404`	ไม่พบคำสั่งซื้อ	แสดงสถานะไม่พบคำสั่งซื้อ
`429`	Rate limit	แจ้งข้อผิดพลาด rate limit ขอให้ผู้ใช้ลองใหม่ภายหลัง
`502`	แพลตฟอร์ม Taobao/1688 ไม่ตอบสนอง	แสดงข้อความผิดพลาด ขอให้ผู้ใช้ลองใหม่

Error response ทั้งหมดตาม shape { statusCode, message, error } บางครั้ง message เป็นภาษาเวียดนาม — สามารถแสดงให้ผู้ใช้เห็นโดยตรง