创建代购订单 API

POST /v1/orders/create 与 下单预览 使用相同的 receiver + lines 请求体。本页补充创单专用字段与完整示例。

相关文档：下单预览 · 响应模型

行项映射（与 preview 相同）

字段名与 商品 API 保持一致，便于从详情直接复制到下单。

步骤商品 API订单 lines[]
1POST /v1/products/detail 或搜索结果—
2响应中的 idlines[].id（推荐）
3所选 SKU 的 variants[].sku_idlines[].spec_id
4购买数量lines[].quantity
lines[] 字段1688淘宝
id（推荐）搜索/详情 id搜索/详情 id（mi_id）— 不要用 source_product_id
spec_idvariants[].sku_idvariants[].sku_id（流量 sku）
offer_id / mi_idid 的兼容别名id 的兼容别名

同时传 id 和 offer_id 时，以 offer_id 为准。完整规则见 preview 行项映射。

淘宝： 创单前请重新 search/detail 获取最新 id，勿长期缓存。纯数字会被当作已撞库的 mpId 并跳过 batch-check — 若误传淘宝链接里的商品数字 id，容易导致创单失败。

追加字段（相对 preview）

字段说明
external_order_id你的幂等 / 外部订单号
buyer_message买家留言（1688 message / 淘宝 order_remark）

淘宝可选： outer_purchase_id（省略则自动生成）、purchase_amount（省略则从内部 preview 取）、channel_order_type（默认 PANAMA_DG）。

1688 可选： trade_type（来自 preview 的 trade_types[]）、flow、use_red_envelope。

推荐流程

1. POST /v1/products/detail  →  取 id + variants[].sku_id
2. POST /v1/orders/preview   →  可选；检查 success / unavailable_lines
3. POST /v1/orders/create    →  与 preview 相同的 lines[] + external_order_id
4. POST /v1/orders/detail    →  支付前确认最终金额

1688 创单示例

POST /v1/orders/create
{
  "channel": "1688",
  "flow": "general",
  "receiver": {
    "name": "张三",
    "mobile": "15251667788",
    "province": "浙江省",
    "city": "杭州市",
    "district": "滨江区",
    "address": "网商路699号"
  },
  "lines": [
    {
      "id": "554456348334",
      "spec_id": "b266e0726506185beaf205cbae88530d",
      "quantity": 5
    }
  ],
  "external_order_id": "MY-ORDER-20260101",
  "buyer_message": "请尽快发货",
  "trade_type": "assureTrade"
}

已有接入仍可传 offer_id 代替 id，只传其一即可。

淘宝创单示例

请使用与 preview 相同 的 id 和 spec_id（或创单前重新拉详情）：

POST /v1/orders/create
{
  "channel": "taobao",
  "receiver": {
    "name": "张三",
    "mobile": "15251667788",
    "province": "浙江省",
    "city": "杭州市",
    "district": "滨江区",
    "address": "网商路699号"
  },
  "lines": [
    {
      "id": "0000iIpSgysC-ca00kbG-Y-LXZu7WojtOJ5cnKTyzoID9UM",
      "spec_id": "6079564221554",
      "quantity": 1
    }
  ],
  "external_order_id": "MY-TB-ORDER-001",
  "buyer_message": "请尽快发货"
}

outer_purchase_id 与 purchase_amount 均可省略 — Gateway 会自动生成幂等键，并通过内部 preview 计算计划采购金额。

响应

默认返回 StandardOrderCreateResult（response_format: "standard"，推荐）。standard 与 upstream 的区别见 响应格式。字段说明见 订单响应模型。

成功落单后请持久化 order_id（淘宝还可保存 outer_purchase_id），用于 支付、详情/列表、国内物流。

创单返回金额为参考值，淘宝尤甚；支付或对账前请调用 订单详情。

获取支持

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

发送邮件