创建供应商询单

两个写接口：一个开启会话，一个继续会话。两者使用相同的 questions 数组，也都支持 Idempotency-Key。

创建询单

POST /v1/supplier-inquiries，需要 supplier_inquiry:write scope。

请求体

字段必填说明
product_url是1688 或淘宝商品绝对链接，最长 2048 字符
questions是1–10 个问题，见问题类型
sku否{ "id": "...", "label": "..." }，各最长 200 字符，用于把问题限定到某个规格
attachments否最多 5 个文件引用，见附件
POST /v1/supplier-inquiries
Authorization: Bearer hio_live_...
Idempotency-Key: inq-2026-05-20-001
 
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "sku": { "id": "3245:12345", "label": "黑色 / XL" },
  "questions": [
    { "type": "packed_weight", "note": "含彩盒的重量" },
    { "type": "carton_info" },
    { "type": "neutral_packaging" }
  ]
}

响应

201 Created；若 Idempotency-Key 命中此前的请求则返回 200 OK。

{
  "id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "product": {
    "channel": "1688",
    "source_product_id": "554456348334",
    "product_url": "https://detail.1688.com/offer/554456348334.html",
    "canonical_product_url": "https://detail.1688.com/offer/554456348334.html",
    "title": "...",
    "image": "...",
    "shop_id": "...",
    "shop_name": "..."
  },
  "sku": {
    "id": "3245:12345",
    "label": "黑色 / XL"
  },
  "message_count": 1,
  "last_message_at": "2026-05-20T08:31:12.000Z",
  "created_at": "2026-05-20T08:31:11.000Z",
  "updated_at": "2026-05-20T08:31:12.000Z",
  "message": {
    "id": "smsg_1a4b...",
    "type": "initial",
    "status": "waiting_supplier"
  },
  "request_id": "req_..."
}

title、image、shop_id、shop_name 为尽力而为填充：补全依赖商品详情接口，而该接口需要你的应用持有对应渠道授权。拿不到时这些字段保持 null，不影响询单正常进行。

同一商品只允许一个活跃询单

若该商品已有活跃询单，创建会失败：

409 Conflict
{
  "error": {
    "code": "ACTIVE_INQUIRY_EXISTS",
    "message": "An active supplier inquiry already exists for this product.",
    "details": { "inquiry_id": "sinq_9f2c...", "next_action": "add_message" }
  }
}

请用返回的 inquiry_id 追加消息。如果上一个会话是 completed 或 failed，创建请求不会报错，而是重开该会话，新消息记为 follow_up。

追加提问

POST /v1/supplier-inquiries/{inquiry_id}/messages，需要 supplier_inquiry:write scope。

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "按 500 件计算" },
    { "type": "moq" }
  ],
  "attachments": [
    {
      "type": "image",
      "url": "https://cdn.example.com/packaging-example.jpg",
      "filename": "packaging-example.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}
201 Created
{
  "inquiry_id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "message": {
    "id": "smsg_77de...",
    "type": "follow_up",
    "status": "waiting_supplier",
    "questions": [
      { "id": "sqst_...", "type": "lead_time", "note": "按 500 件计算", "question": null, "status": "pending", "answer": null }
    ],
    "attachments": [
      {
        "id": "satt_...",
        "type": "image",
        "url": "https://cdn.example.com/packaging-example.jpg",
        "filename": "packaging-example.jpg",
        "mime_type": "image/jpeg",
        "source": "developer",
        "expires_at": null,
        "created_at": "2026-05-20T10:02:00.000Z"
      }
    ],
    "provider_note": null,
    "created_at": "2026-05-20T10:02:00.000Z",
    "answered_at": null
  },
  "request_id": "req_..."
}

cancelled 的询单会以 409 INQUIRY_NOT_ACTIVE 拒绝新消息；completed 或 failed 的会被重开。

附件

两个写接口都支持可选的 attachments 数组：参考图、SKU 截图、尺寸图纸、规格 PDF 等。附件归属于发送它的那条消息，因此每一轮沟通各带各的附件。

字段必填说明
url是只接受 https://，最长 2048 字符；http:、file:、data:、javascript:、ftp: 一律返回 INVALID_ATTACHMENT_URL
type否image / document / other，缺省为 other
filename否最长 255 字符
mime_type否最长 128 字符，按你声明的值原样保存

单条消息最多 5 个附件，超出返回 400 TOO_MANY_ATTACHMENTS。

HIOBuy 只保存元数据和 URL，不保存文件：不上传、不下载、不复制、不代理附件内容，也不会去访问你提交的 URL。文件请自行托管，并确保在会话进行期间询单服务能够访问该地址。

幂等

两个写接口都支持 Idempotency-Key（或 X-Idempotency-Key，最长 200 字符）。同一应用重复使用相同 key，会返回首次创建的那条消息，状态为 200 而非 201，且不会重复打扰供应商。

创建请求超时后请务必带同一个 key 重试；不带 key 重试可能开出第二个会话，或直接撞上 ACTIVE_INQUIRY_EXISTS。

获取支持

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

发送邮件