API preview đơn hàng

POST /v1/orders/preview — validate dòng hàng, giá và freight nội địa trước khi create.

Liên quan: Create order · Response model

Request body

Taobao: Gateway tự động batch-check mi_id + traffic sku_id, rồi gọi upstream render. Dùng id / mi_id mới làm lines[].id — nó thay đổi định kỳ.

Line mapping

Prefer lines[].id = search/detail id. offer_id and mi_id remain compatible.

If both id and offer_id are sent, offer_id wins. Otherwise id (then mi_id) is copied to offer_id. Do not pass Taobao source_product_id. Taobao id / mi_id rotates periodically.

Ví dụ

POST /v1/orders/preview
{
  "channel": "1688",
  "receiver": {
    "name": "张三",
    "mobile": "15251667788",
    "province": "浙江省",
    "city": "杭州市",
    "district": "滨江区",
    "address": "网商路699号"
  },
  "lines": [
    {
      "id": "554456348334",
      "spec_id": "b266e0726506185beaf205cbae88530d",
      "quantity": 5
    }
  ]
}

Taobao example

POST /v1/orders/preview
{
  "channel": "taobao",
  "receiver": {
    "name": "张三",
    "mobile": "15251667788",
    "province": "浙江省",
    "city": "杭州市",
    "district": "滨江区",
    "address": "网商路699号"
  },
  "lines": [
    {
      "id": "0000iIpSgysC-ca00kbG-Y-LXZu7WojtOJ5cnKTyzoID9UM",
      "spec_id": "6079564221554",
      "quantity": 5
    }
  ]
}

Response

StandardOrderPreviewResult — xem order response models. Ví dụ JSON: Response format.

Số tiền dùng đơn vị fen CNY. total luôn có merchandise, shipping và payment. Giá trị 0 đã biết được biểu diễn bằng đối tượng Money có amount:0; chỉ dùng null khi thực sự không biết số tiền.

Trước khi tạo đơn, phải kiểm tra success === true. Gateway xác minh tổng thanh toán dương, nhóm người bán, tất cả dòng đã yêu cầu, các dòng không khả dụng và, với 1688, phương thức giao dịch có op_support:true. Kết quả đọc được nhưng không đầy đủ trả HTTP 200 với success:false và code như LINE_UNAVAILABLE, UNSUPPORTED_TRADE_MODE hoặc PREVIEW_INCOMPLETE.

Để tương thích, lỗi SKU, tồn kho, MOQ hoặc hạn chế marketplace do 1688 trả rõ ràng vẫn dùng error envelope HTTP 502. response_format:"upstream" giữ nguyên ngữ nghĩa gốc và có thể trả HTTP 200 kèm lỗi nghiệp vụ upstream; hãy kiểm tra upstream payload.

Preview đơn hàng là thao tác chỉ đọc. Ở cả chế độ self và warehouse, Gateway dùng channel token tương ứng của App để gọi trực tiếp API preview/render của marketplace. Trong chế độ warehouse, token lấy từ warehouse_channel_tokens; preview không được chuyển tiếp tới /procurement/preview. Các thao tác create, detail, pay, cancel và logistics vẫn đi qua warehouse.