下单预览 API

POST /v1/orders/preview — 在创建订单前校验行项、价格与国内运费。同一套 receiver + lines 也用于 创建订单 和 运费预估。

相关文档：创建订单 · 响应模型

请求体

字段必填说明
channel是1688 | taobao
receiver是国内入库地址：name、mobile、province、city、address；1688 未传 address_id 时还需 district
lines[]是推荐 id + spec_id + quantity。原来的 offer_id、mi_id 仍可用
response_format否standard（默认，推荐）或 upstream — 见 响应格式

快捷路径：POST /v1/orders/1688/preview、POST /v1/orders/taobao/preview（可省略 channel）。

lines[].id 从哪里来 {#line-mapping}

  1. 调用 POST /v1/products/detail（或使用 搜索 结果）。
  2. 将响应中的 id 填入 lines[].id（字段名相同 — 淘宝不要用 source_product_id）。
  3. 将所选 SKU 的 variants[].sku_id 填入 lines[].spec_id。
  4. preview 成功后，创单 使用相同的 lines[]。

id 请从 商品详情 现取，不要用长期缓存。

lines[] 字段1688淘宝
id（推荐）搜索/详情 id（offerId）搜索/详情 id（mi_id）— 不要用 source_product_id
offer_idid 的兼容别名id 的兼容别名
mi_id—淘宝兼容别名，等同 id
spec_idvariants[].sku_id（specId）variants[].sku_id（流量 sku）。也接受已撞库的 mpSkuId

同时传 id 和 offer_id 时，以 offer_id 为准。只传 id（或淘宝 mi_id）时会自动转成 offer_id。

淘宝：Gateway 自动批量校验 id/mi_id + 流量 sku_id → mpId / mpSkuId，再调用上游 /purchase/order/render。无需先调 /v1/products/batch-check。若值为纯数字 mpId，则跳过撞库。

淘宝 id / mi_id 会周期性变化。 请勿长期缓存。过期 id 会导致预览、创单和相似推荐失败。下单前请重新搜索或拉详情。

1688 示例

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

淘宝示例

把搜索/详情的 id 传给 lines[].id。已有接入可继续传 offer_id 或 mi_id。

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

响应

StandardOrderPreviewResult — 见 订单响应模型。JSON 示例见 响应格式。

金额单位为 人民币分。创单前请检查 success 与 unavailable_lines[]。

获取支持

需要集成帮助？请联系开发者支持 support@hiobuy.com · 预计 1–2 个工作日内回复

发送邮件