Tham chiếu API đơn hàng

Tóm tắt

Trang này liệt kê trạng thái, endpoint, tham số và mã lỗi của module đơn hàng. Để đi theo quy trình đầy đủ, xem Hướng dẫn đặt & thanh toán đơn Taobao/1688. Cách nhận cập nhật đơn qua webhook có trang tham chiếu riêng.

Phạm vi: Đã hỗ trợ nhiều thị trường. Thanh toán được thống nhất bằng VNĐ, USD hoặc RMB (CNY) — ví mua hàng nạp bằng một trong ba đồng tiền này; số dư và giá trị đơn trong API quy về đơn vị chung (*_cny).

Elim là nền tảng công nghệ lo khâu thực thi đơn và thanh toán — không bán lẻ, không nhận khách trực tiếp. Hệ thống của bạn thanh toán cho Elim qua ví mua hàng, Elim thanh toán lại với người bán trên nền tảng. Vì vậy mỗi đơn có hai trạng thái độc lập — trạng thái nền tảng (status) và trạng thái thanh toán với Elim (payment_status) — cộng một chỉ báo kết quả thanh toán phía nền tảng (platform_payment_status).

Mọi endpoint yêu cầu xác thực JWT (Authorization: Bearer <token>) hoặc API Key (x-api-key). Xem Hướng dẫn xác thực.

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

Tiến trình xử lý đơn phía Taobao / 1688.

creating → pending_payment → paid → shipped → completed
                                            ↘ cancelled

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

Tiến trình thanh toán giữa người dùng và Elim. Độc lập với status.

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

Từ requested, người dùng có thể tự rút yêu cầu để quay lại unpaid (xem cancel-payment-request). Sau khi approved thì chỉ đảo ngược được bằng hoàn tiền.

Kết quả thanh toán nền tảng (platform_payment_status)

Chỉ có giá trị sau khi Elim thực hiện thanh toán với nền tảng.

Luôn hiển thị cả status và payment_status trong giao diện. platform_payment_status chủ yếu để chẩn đoán khi có sự cố.

Endpoint đơn hàng

Prefix /v1/orders. Rate limit tính theo giây.

Preview và tạo đơn — 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": "Ghi chú cho người bán",
  "promotion_id": "PROMO123"
}

line_items[]

Mỗi phần tử định danh mặt hàng bằng cặp product_ref + sku_ref, lấy trực tiếp từ tìm kiếm / chi tiết sản phẩm.

Cặp mp_id + mp_skuid (ID marketplace) vẫn được chấp nhận cho tương thích ngược.

receiver_address

Response preview

{
  "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 tạo đơn

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

Đơn mới luôn ở payment_status = unpaid.

Danh sách đơn — tham số lọc

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 trong danh sách là ảnh chụp lúc tạo đơn. Muốn dữ liệu mới nhất, gọi GET /v1/orders/:id.

Chi tiết đơn — khác biệt theo nền tảng

GET /v1/orders/:id — tự đồng bộ trạng thái từ nền tảng trước khi trả về.

Trường platform có sẵn trong response danh sách — lưu lại để chọn cách hiển thị trước khi gọi chi tiết.

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

Hủy đơn — điều kiện

POST /v1/orders/:id/cancel — chỉ khi status là creating hoặc pending_payment.

Nếu đơn chưa có mã đơn nền tảng: { "success": true, "message": "Internal order cancelled, no external order to cancel" }.

Endpoint ví mua hàng

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

Tham số: page, size, type, date_from, date_to. Response: { total, page, size, items }.

GET /v1/purchasing/exchange-rates

Mảng tỷ giá đang hoạt động cho từng cặp tiền tệ (VND→CNY, USD→CNY): source_currency, target_currency, rate (tỷ giá thị trường), markup_percent, effective_rate (tỷ giá Elim áp dụng sau markup).

Endpoint thanh toán đơn hàng

Prefix /v1/purchasing/orders/:id. :id nhận dạng 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
}

Lỗi ví không đủ — 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
}

Dùng wallet_balance_after để cập nhật số dư hiển thị mà không phải gọi lại GET /v1/purchasing/wallet.

Các chuyển trạng thái do Elim thực hiện

Người dùng không gọi các thao tác này. Chúng được liệt kê để giải thích payment_status sẽ đổi thế nào và khi nào bạn nhận payment.updated.

Nhận cập nhật đơn qua webhook

Đăng ký webhook để Elim gọi vào hệ thống của bạn mỗi khi status hoặc payment_status của đơn đổi — thay cho việc hỏi trạng thái liên tục. Hai sự kiện liên quan module đơn hàng:

Payload mang một ảnh chụp đơn: data.order.id, status, payment_status, platform_payment_status, total_amount_cny, updated_at. Xử lý xong thì trả HTTP 2xx.

Endpoint đăng ký, cấu trúc payload đầy đủ, header, xác minh chữ ký HMAC và chính sách thử lại: xem Tham chiếu Webhook.

Mã lỗi

Response lỗi theo dạng { statusCode, message, error }. message đôi khi là tiếng Việt và có thể hiển thị trực tiếp.

Quy ước ID

• ID đơn nội bộ: ORD + 10 chữ số, ví dụ ORD0000000123. Dùng cho mọi endpoint.
• Mã đơn nền tảng (order_id): do Taobao/1688 cấp, chỉ có sau khi tạo đơn thành công.
• package_id: số nguyên, dùng cho tracking vận chuyển Taobao.

Liên kết liên quan

• Hướng dẫn đặt & thanh toán đơn Taobao/1688 — quy trình từng bước
• Tham chiếu Webhook — nhận cập nhật order.updated / payment.updated
• Xác thực API requests
• API Reference đầy đủ