人工采购 API

一个渠道、一个卖家、一笔采购订单

每笔采购订单可以包含多个商品或 SKU，但所有商品必须属于同一个渠道和同一个卖家。

如果顾客购买了不同卖家或不同渠道的商品，你的应用必须先按渠道和卖家拆成独立的采购订单，再调用 HIOBuy 订单 API。

HIOBuy 不会自动拆分采购订单，也未提供此流程的批量下单 API。

如何识别渠道和卖家

使用订单级 channel；渠道快捷路径、请求体和商品行中的渠道必须一致。不得在 lines[] 或 items[] 中混合渠道。
客户端分组时，可使用商品 API 返回的真实 seller.id：1688 来源为 sellerOpenId，淘宝详情来源为 shop_id。自动生成的 seller_1688_*／seller_taobao_* 回退值、缺失的 ID、商品标题或店铺名称均不能证明卖家身份。淘宝店铺 ID 与下单渲染返回的卖家 ID 属于不同标识体系，不能直接比较。
标准创建请求不新增必填的卖家字段。self 模式下，Gateway 在正式下单前，通过原始商品详情核验 1688 的卖家归属；淘宝则使用 render_item_list[].seller_id，并核对请求中的全部商品和 SKU。证据缺失或归属不明确时拒绝创建。
Warehouse 采购模式（包括人工采购）由仓库负责卖家校验，必须在创建订单、启动采购、钱包扣款或返回部分成功之前完成。Gateway 检查原始请求中的渠道冲突并透传仓库的校验错误，不重复查询电商平台。仓库须单独完成验收；Gateway 已上线不代表外部仓库已实现此校验。
人工采购使用 channel=manual，所有商品还必须属于同一个 source_platform。seller_name 仅为展示用声明。仓库必须核验每个商品的真实平台卖家归属，无法核验时返回 SELLER_ID_UNAVAILABLE；调用方填写的名称或 ID 不能代替真实归属校验。仓库契约验收通过前，不应开启人工采购创建能力。

错误码与处理建议

以下三类错误均返回 HTTP 400，分类为 VALIDATION_ERROR：

错误码	处理建议
`MULTIPLE_CHANNELS_NOT_ALLOWED`	按渠道拆分商品，并确保快捷路径、请求体和商品行中的渠道一致。
`MULTIPLE_SELLERS_NOT_ALLOWED`	在每个渠道内按真实卖家拆分，再分别创建采购订单。
`SELLER_ID_UNAVAILABLE`	获取有效的商品／SKU 标识，或接入可信的仓库卖家解析能力。不要原样重试，也不要按名称猜测。

混合下单时，API 返回的英文提示原文为：

A purchase order must contain products from the same channel and seller. Please split the items into separate orders by channel and seller.

卖家归属校验失败时，不得创建采购订单或采购任务，不得扣款，也不得产生部分成功订单。现有幂等规则继续有效。主动拆分后的每笔采购应使用独立的业务单号／幂等键；重试同一笔未修改的采购时，应复用原键。

采购订单与仓库合箱发货

采购订单对应向单个卖家发起的国内采购。不同采购订单的商品可分别入库，并在满足仓库与物流条件后合并为一个国际发货单。合箱不会合并原采购单号、国内运费、付款、取消或退款状态。

正确请求：同一已核验卖家的多个 SKU

仓库必须独立确认两个商品链接均属于同一个稳定的平台卖家。示例链接仅用于说明请求结构，不能作为卖家身份证据或生产验收结果。

{
  "channel": "manual",
  "external_order_id": "MANUAL-SELLER-A-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 41",
      "unit_price": 5000,
      "quantity": 1
    }
  ]
}

错误示例：商品的实际卖家不同

若 items[0].product_url 归属于卖家 A，items[1].product_url 归属于卖家 B，即使请求声明 seller_name: "Seller A"，仓库也必须返回 MULTIPLE_SELLERS_NOT_ALLOWED。无法核实归属时，应返回 SELLER_ID_UNAVAILABLE，不能仅凭声明的名称接受请求。

{
  "channel": "manual",
  "external_order_id": "INVALID-MIXED-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-B/shirt",
      "product_name": "Shirt",
      "specification": "M",
      "unit_price": 3000,
      "quantity": 1
    }
  ]
}

仓库返回的卖家校验拒绝结果应按现有业务单号／幂等契约重放，且不得创建订单或扣款。已创建订单的重放、详情、支付及取消行为保持兼容。

POST /v1/orders/manual

一次请求创建一张订单，每单仅一个平台和一个卖家，可包含该卖家的多个商品。首期只开放 jd、pinduoduo、poizon，seller_name 必填。不同平台或卖家必须拆成独立请求并使用不同业务单号。

需要 Production API Key、order:create 权限、warehouse 履约模式及有效仓库绑定。无需电商 OAuth 或商品 API。Sandbox 暂不支持人工采购；使用前须完成仓库人工接口接入和联调。

请求

Authorization: Bearer <PRODUCTION_API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16

{
  "channel": "manual",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "language": "zh",
  "remark": "Please ship together",
  "items": [
    {
      "item_ref": "I001",
      "product_url": "https://example.com/item1",
      "product_name": "Wireless Mouse",
      "specification": "Black",
      "unit_price": 3500,
      "quantity": 2,
      "product_image": null,
      "remark": ""
    }
  ]
}

external_order_id 必填，在当前应用的人工订单中唯一。同业务单号、同采购资料即使更换请求幂等键也返回原订单；修改资料返回 HTTP 409 IDEMPOTENCY_CONFLICT。新的采购使用新的业务单号。创建、付款和取消均必须提供 Idempotency-Key。order_sn 由 HIOBuy 生成，item_ref 可省略并自动生成。不接受 sellers 数组或商品级平台、卖家覆盖字段。

字段	必填值或限制
`channel`	`manual`
`external_order_id`	1–200
`source_platform`	`jd` / `pinduoduo` / `poizon`
`seller_name`	1–200
`currency` / `monetary_unit`	`CNY` / `CNY_minor`
`domestic_shipping_fee` / `items[].unit_price`	integer ≥ 0
`items` / `items[].quantity`	1–100 / 1–9999

仓库费用

请求和响应金额均为人民币分整数：3500 表示 ¥35.00。商品金额、国内运费、现有 5% 采购服务费及应付金额全部由仓库计算。示例服务费不定义计费基数、最低收费或舍入规则。HIOBuy 校验并保存仓库费用，不再叠加 5%。金额或商品映射缺失的订单不可付款。

{
  "channel": "manual",
  "success": true,
  "order_id": "WH10001",
  "order_sn": "HB202610160001",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "status": "wait_payment",
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "total": {
    "merchandise": {
      "amount": 7000,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 800,
      "currency": "CNY"
    },
    "procurement_fee": {
      "amount": 390,
      "currency": "CNY"
    },
    "payment": {
      "amount": 8190,
      "currency": "CNY"
    }
  },
  "order_list": [
    {
      "order_id": "WH10001",
      "shipping": {
        "amount": 800,
        "currency": "CNY"
      },
      "lines": [
        {
          "item_ref": "I001",
          "sub_order_id": "WI10001",
          "title": "Wireless Mouse",
          "spec_title": "Black",
          "quantity": 2,
          "unit_price": {
            "amount": 3500,
            "currency": "CNY"
          },
          "line_total": {
            "amount": 7000,
            "currency": "CNY"
          }
        }
      ]
    }
  ],
  "failed_offers": [],
  "request_id": "req_example"
}

复用现有订单操作

创建不会扣款或触发真实采购。使用返回的 order_id 和 channel=manual 调用原付款、取消、详情及国内物流接口。付款不得提交 pay_amount 或最终金额。HIOBuy 付款前核对仓库金额与已保存快照，仓库执行原钱包支付流程；确认付款后才可采购。取消遵循原规则，不代表退款已经到账。

{
  "channel": "manual",
  "order_id": "WH10001"
}

{
  "channel": "manual",
  "order_id": "WH10001",
  "cancel_reason": "buyer_request"
}

重试与限制

超时或结果未知时保留原业务单号和幂等键，查询订单详情；不能自动换键重新扣款。仓库详情包含 payment_status、平台卖家、商品引用及冻结费用。人工订单当前支持详情与国内物流，电商订单列表和电商退款 API 暂不支持 manual。每单 1–100 行商品，数量 1–9999；卖家名称 200 字符，商品名称与规格 500，备注 1000，HTTP/HTTPS URL 2048；金额字符串和小数均不接受。

400 VALIDATION_ERROR · 403 FULFILLMENT_MODE_NOT_SUPPORTED / WAREHOUSE_AUTH_INVALID · 409 IDEMPOTENCY_CONFLICT / ORDER_AMOUNT_CHANGED / ORDER_OPERATION_UNRESOLVED · 502 WAREHOUSE_INVALID_RESPONSE · 503 WAREHOUSE_UNAVAILABLE

Webhooks

procurement.failed / procurement.out_of_stock

{
  "type": "procurement.failed",
  "data": {
    "channel": "manual",
    "order_id": "WH10001",
    "order_sn": "HB202610160001",
    "external_order_id": "EXT-10001",
    "source_platform": "jd",
    "seller_name": "Seller A",
    "status": "partial_failure",
    "reason_code": "OUT_OF_STOCK",
    "items": [
      {
        "item_ref": "I001",
        "sub_order_id": "WI10001",
        "quantity": 1,
        "reason_code": "OUT_OF_STOCK"
      }
    ]
  }
}

获取支持

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

发送邮件