Hướng dẫn API đơn hàng

API đơn hàng cho phép bạn tạo và quản lý đơn mua hộ trên Taobao và 1688 (Alibaba). Mỗi đơn hàng duy trì hai trạng thái độc lập: trạng thái nền tảng (status) do Taobao/1688 trả về và trạng thái thanh toán Elim (payment_status) do hệ thống ví mua hàng quản lý.

Tất cả endpoint yêu cầu xác thực JWT qua header Authorization: Bearer <token> hoặc API Key (X-API-KEY)

Hướng dẫn authentication: Authentication

Trạng thái đơn hàng

Trước khi sử dụng API, hãy nắm rõ hai chiều trạng thái của một đơn hàng để tránh nhầm lẫn khi hiển thị cho người dùng cuối.

Trạng thái nền tảng (status)

Trạng thái phản ánh tiến trình xử lý đơn phía Taobao hoặc 1688.

Trạng thái thanh toán Elim (payment_status)

Trạng thái phản ánh việc đơn hàng đã được thanh toán cho Elim hay chưa. Đây là trạng thái độc lập với status — một đơn có thể ở status=shipped nhưng vẫn payment_status=unpaid nếu có sự cố.

Xem trước đơn hàng

Xem chi tiết: Preview đơn hàng

Trước khi tạo đơn thật, gọi endpoint preview để lấy tổng tiền ước tính và kiểm tra tình trạng hàng hóa. Bước này không tạo đơn, không trừ tiền — chỉ trả về thông tin để người dùng xác nhận trước khi checkout.

Rate limit: 20 request / 60 giây

POST /v1/orders/preview

Body:

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

Giải thích các trường line_items

Xử lý unavailable_items

Response trả về mảng unavailable_items chứa các sản phẩm không thể đặt (hết hàng, SKU sai, ngừng bán). Không cho phép tạo đơn nếu mảng này khác rỗng — hỏi người dùng xử lý các item lỗi trước.

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

Tham số tùy chọn

Tạo đơn hàng

Xem chi tiết: Tạo đơn hàng

Tạo đơn thật trên nền tảng. Body giống hệt preview — nên dùng dữ liệu đã validate từ bước preview để tạo đơn, tránh sai lệch.

Rate limit: 10 request / 60 giây

POST /v1/orders

Sau khi tạo thành công, redirect người dùng sang trang chi tiết đơn (/orders/ORD...). Đừng giữ người dùng ở giỏ hàng vì đơn đã được gửi lên nền tảng.

Xử lý response

Quy ước ID: Elim ID luôn có dạng ORD + 10 chữ số (ví dụ: ORD0000000123). Đơn hàng tạo mới thành công mới có ID của nền tảng order_id.

Danh sách đơn hàng

Xem chi tiết: Danh sách đơn hàng

Lấy danh sách đơn của người dùng hiện tại (xác định qua JWT). Kết quả được phân trang.

Rate limit: 30 request / 60 giây

GET /v1/orders

Tham số lọc

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

Chi tiết đơn hàng

Xem chi tiết: Chi tiết đơn hàng

Lấy thông tin đầy đủ và cập nhật nhất của một đơn.

Rate limit: 30 request / 60 giây

GET /v1/orders/:id

Truyền ID dạng ORD....

Khác biệt response giữa Taobao và 1688

Hai nền tảng trả về cấu trúc dữ liệu khác nhau — cần xử lý riêng:

Trường platform có sẵn trong response danh sách — cache lại từ list view để biết render component nào trước khi gọi detail.

Hủy đơn hàng

Xem chi tiết: Hủy đơn hàng

Hủy một đơn đang ở trạng thái có thể hủy được. Sau khi hệ thống hủy thành công, gọi lại GET /v1/orders/:id để lấy trạng thái mới nhất.

Rate limit: 10 request / 60 giây

POST /v1/orders/:id/cancel

Điều kiện: Chỉ hủy được khi status là creating hoặc pending_payment. Disable nút hủy ở các trạng thái khác.

Theo dõi vận chuyển

Xem chi tiết: Logistic detail

Lấy thông tin tracking vận chuyển nội địa Trung Quốc. Chỉ áp dụng cho Taobao — đơn 1688 đã có logistics.logistics_info[] nhúng sẵn trong response chi tiết đơn.

Rate limit: 20 request / 60 giây

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

packageId là số nguyên, lấy từ response chi tiết đơn Taobao — không phải ID dạng ORD....

Thanh toán đơn hàng

Elim đóng vai trò đại lý mua hộ: người dùng thanh toán cho Elim qua ví mua hàng (đơn vị CNY), Elim thanh toán lại với nền tảng ngoài hệ thống. Quy trình đầy đủ:

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

Xem số dư ví

GET /v1/purchasing/wallet

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

Xác nhận thanh toán

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

Hệ thống kiểm tra ví → trừ tiền → cập nhật payment_status = paid.

Response thành công (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
}

Dùng balance_after để cập nhật số dư ví mới nhất mà không cần gọi thêm GET /v1/purchasing/wallet.

Xử lý lỗi không đủ số dư

Khi ví không đủ tiền, hệ thống trả 400 với body:

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

Hiển thị modal thông báo thiếu bao nhiêu CNY và hướng dẫn nạp thêm. Quy trình nạp tiền thực hiện ngoài hệ thống (chuyển khoản) — admin xác nhận và cộng ví thủ công.

Phí dịch vụ

Phí dịch vụ tính theo công thức: max(tổng_đơn × fee_percent, min_fee). Phần trăm và mức tối thiểu do admin cấu hình.

Lịch sử giao dịch ví

GET /v1/purchasing/wallet/transactions

Tỷ giá

GET /v1/purchasing/exchange-rates

Trả về tỷ giá hiện hành VND → CNY và USD → CNY do Elim cấu hình. Hiển thị tỷ giá này cho người dùng biết trước khi nạp tiền.

Xử lý lỗi

Tất cả response lỗi theo shape { statusCode, message, error }. Message đôi khi là tiếng Việt — có thể hiển thị trực tiếp cho người dùng.