供应商询单 API

在用户下单前，给出更接近真实的国际运费

一张沙发、一盏落地灯、一台跑步机、一个大号宠物笼——它们的国际运费几乎完全取决于实际打包之后的样子：打包重量、包装箱尺寸、拆成几个包裹发。

而这些数据在 1688 和淘宝的商品页上经常缺失或不可靠。于是你的用户面对一个非常现实的问题：

他知道这件商品卖多少钱，却完全不知道运到自己国家要多少钱。

供应商询单 API 补上的就是这一层。在用户下单之前，HIOBuy 的供应商沟通服务会联系真实供应商，确认打包重量、包装尺寸与装箱方式，并把结果以结构化数据返回给你的应用，直接用于运费试算。

为什么商品 API 不够用

商品接口能稳定地给你平台自己掌握的信息：标题、图片、价格、SKU、属性、店铺。但物流数据完全是另一回事：

• 页面根本没写重量；
• 写的是商品净重，不是打包后的重量；
• 有商品尺寸，但没有打包后的尺寸；
• 重量是卖家手填的，只能当参考；
• 不同 SKU 打包后的重量并不一样；
• 大件商品会拆成多个包裹发货；
• 外箱数量、外箱重量、外箱尺寸页面上根本没有。

商品 API 告诉你平台知道什么；供应商询单帮你拿到只有供应商能确认的东西。

示例：给一张沙发算国际运费

一位美国用户正在你的应用里看一张 1688 沙发，售价 ¥800。商品接口已经返回了商品、价格、图片、SKU 和属性——唯独没有可靠的打包重量和包装尺寸。

于是你的应用回答不了接下来唯一重要的问题：

商品价格   ¥800
国际运费   ？？？

在大件商品上，这个未知数很可能比商品本身还贵。

应用发起一次询单：

POST /v1/supplier-inquiries
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "questions": [
    { "type": "packed_weight" },
    { "type": "package_dimensions" },
    { "type": "carton_info" }
  ]
}

HIOBuy 把任务交给供应商沟通服务，由中国本地人员联系这个链接背后的真实供应商。供应商回复说这张沙发分两个包裹发：

包裹 1   32 kg   110 × 75 × 55 cm
包裹 2   18 kg    90 × 60 × 40 cm

这些答案以结构化 JSON 回到你的应用，整条链路是这样的：

1688 商品
      ↓  商品 API
价格：¥800
      ↓  缺少可靠的物流数据
供应商询单
      ↓  HIOBuy 联系真实供应商
供应商确认：2 个包裹，32 kg + 18 kg，各自尺寸
      ↓  结构化物流数据
国际运费预估（中国 → 美国）
      ↓
用户在下单前就看到大致的总成本

这才是整件事的意义：

商品成本
+ 预估国际运费
= 更接近真实的购买成本

它在 HIOBuy 接口体系中的位置

商品 API        「这是什么商品，卖多少钱？」
      ↓
供应商询单 API   「供应商实际会怎么打包？」
      ↓
运费试算        「运到国外大概要多少钱？」

供应商询单，就是商品数据与运费报价之间缺失的那一层。

不只是物流数据

用于运费预估的包装数据是这个接口最先落地、也最具体的场景，但同一条供应商沟通链路可以问任何只有供应商知道的事：

起订量 · 库存 · 货期 · 中性包装 · 定制 · 装箱信息 · 商品细节，以及通过 other 类型问的任何其他问题。

所以今天它解决的是包装数据 → 运费预估，同一次调用同样可以服务供应商信息 → 采购决策。十种类型及其答案结构见问题类型。

工作方式

1. 应用调用 POST /v1/supplier-inquiries，传入商品链接、可选的 SKU，以及一个或多个结构化问题。
2. HIOBuy 创建询单并交给供应商沟通服务。
3. 中国本地人员联系该链接对应的供应商。
4. 供应商回复。
5. 回复按每个问题类型的 schema 归一成结构化数据。
6. 你的回调地址收到 supplier_inquiry.message_answered，或者主动轮询 GET /v1/supplier-inquiries/{id}。

一个询单是一段会话，不是一次性请求。创建之后，追加问题都发到同一个会话里，而不是另开一单。

附件

有些问题配一张图会容易得多：包装参考图、SKU 截图、尺寸图纸、规格书；反过来，供应商也可能回一张实拍包装照、外箱照或一份报价 PDF。

每条消息（你发的和供应商回的）最多可带 5 个附件：

{
  "message": "请问供应商能否用类似这样的包装？",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/reference-packaging.jpg",
      "filename": "reference-packaging.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

type 取 image / document / other。URL 必须是 https://，其它协议一律返回 INVALID_ATTACHMENT_URL。

供应商的回复同样可能带附件，它们会出现在消息的 attachments 数组里，以及 supplier_inquiry.message_answered Webhook 中，与结构化答案一同送达。你只会看到询单服务标记为「可交付给开发者」的附件——客服工作文件、与供应商的聊天截图等始终留在服务内部，不会进入 API。

开通与权限

供应商询单默认关闭，需商务对接后由 HIOBuy 按应用开通，请联系 HIOBuy 支持申请。

未开通或被暂停时，所有接口返回 403 SUPPLIER_INQUIRY_NOT_ENABLED。

支持的渠道

其他渠道返回 UNSUPPORTED_MARKETPLACE。商品身份由 channel + source_product_id 确定，不使用原始 URL 字符串，因此同一商品的不同链接形态会归一到同一个商品。

询单状态

pending、processing、waiting_supplier、answered 视为活跃。同一应用对同一商品同时只允许一个活跃询单，以此保证每个商品只有一条供应商会话。若该商品的上一个询单是 completed 或 failed，创建请求会重开原会话，而不是新建。

Webhook

在开发者门户注册回调地址并订阅 supplier_inquiry 分类，签名与重试遵循标准 Webhook 规则。

所有 payload 都带 inquiry_id 与 product.{channel,source_product_id}。

错误码

SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE 刻意保持笼统：余额、账户状态等服务方内部原因不对外暴露。联系支持时请提供 request_id。

接口一览