下单预览 API

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

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

请求体

快捷路径：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 请从 商品详情 现取，不要用长期缓存。

同时传 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 示例见 响应格式。

金额单位为 人民币分。total 固定包含 merchandise、shipping 和 payment。已知零金额返回 amount:0 的 Money 对象；只有金额确实未知时才返回 null。

创单前必须确认 success === true。Gateway 还会校验应付金额大于零、卖家分组、全部请求行、不可购行，以及 1688 是否存在 op_support:true 的交易方式。可解析但不完整的结果返回 HTTP 200、success:false，并带 LINE_UNAVAILABLE、UNSUPPORTED_TRADE_MODE 或 PREVIEW_INCOMPLETE 等 code。

为保持兼容，1688 上游明确返回的 SKU、库存、MOQ 和市场限制错误仍使用 HTTP 502 标准错误信封。response_format:"upstream" 保留原始语义，HTTP 200 中也可能包含上游业务失败，请检查 upstream payload。

订单预览是只读操作。在自行采购和仓库代采模式下，Gateway 都使用 App 对应的渠道 token 直接调用平台 preview/render API。仓库模式的 token 来自 warehouse_channel_tokens，preview 不再转发至仓库 /procurement/preview；create、detail、pay、cancel 和 logistics 等有状态操作仍由仓库处理。