HIOBuy 开放平台

HIOBuy 是 淘宝、1688 与 微店的 官方授权技术合作方。我们用一套统一的 API，把中国制造与供应链接到你的平台上——不止是商品「读」数据，更覆盖从品类同步到自动采购、再到（可选）跨境配送的整条链路。

HIOBuy 能提供什么

和仅有站点抓取器或「只读数据管道」的方案不同，HIOBuy 从设计之初就为 端到端履约而生。接入方应能通过你的 storefront 与我们的代购 API 驱动真实成交。

示意图（HIOBuy 在中间：商品同步 → 接单 → 自动代购 → 状态回传）

HIOBuy 位于电商平台与你的业务之间：同步商品、接收订单、完成自动采购，并把进度推回你的运营后台。

能力	对你的意义
商品同步	经 /v1/products/* 从 1688、淘宝、微店拉取检索、详情、以图搜、SKU/库存/标价
订单接入	用户在你站内下单后，你的后端把订单发送到 HIOBuy
自动代购	HIOBuy 在源卖场替你完成对应买单，链路见 /v1/orders/*
状态同步	采购与国内物流进度、（仓配模式下）干线/末端追踪回传到你的系统——见 Webhooks
国际履约（可选）	小包入仓出库、跨境配送经 /v1/fulfillment/*（仅仓库/仓配模式）

与其它接口方案的差异

• 合规官方通道：基于授权与合作集成，而非非官方爬虫。
• 面向成交：商品域 API 服务于选品结账；代购 API 闭环买单。
• 统一字段模型：面向 1688 / 淘宝 / 微店的统一 schema，参见 响应结构。
• 可选全栈履约：自履约（自备仓与链路）vs 仓库模式（由 HIOBuy 仓备货并跨境发运）。

合规使用与额度 {#acceptable-use}

调用 不设「无限配额」。速率和并发与商务协议以及平台预期 **成交金额（GMV）**绑定。

本平台面向：发现商品后能形成真实代购单的场景——消费者在贵站买单，后端调用 /v1/orders/* 完成采购。若仅大量使用搜索/详情、却几乎不产生采购成交量，或使用目录 API 却把采购链路旁路由其它通道完成，则可能 不予受理或后续暂停。

技术层面的节流响应头与错误码见 限流；商务 SLA 在开通过程中另行约定，不在单篇接口正文重复。

集成拓扑 {#integration-flows}

在应用授权时请选定履约模式（见 仓库绑定与门户授权）。商品侧路径大体一致；代购与国际段会因模式不同。

自履约——你自持店铺凭证与链路

更合适：你已在卖场侧拥有账号与国内仓自主权。

1. 商品同步 — 1688 / 淘宝 / 微店 ↔ HIOBuy 网关：搜索、详情、图片、SKU、库存
2. 展示上架 — 网关 ↔ 自有 storefront
3. 用户下单 — 消费者 ↔ 你的网站
4. 代购链路 — 你的后端 ↔ 网关：POST /v1/orders/preview → create → pay
5. 自动采购 — 网关 ↔ 卖场（用你的 OAuth）
6. 卖场回执 — 卖场 ↔ 网关：履约与国内物流轨迹
7. 运营回写 — 网关 ↔ 你的看板/OMS

/v1/fulfillment/* 国际出库在 自履约模式不可用，跨境最后一公里由你自行安排。

HIOBuy 仓库模式——端到端

单仓授权码可同时绑定多渠道；代购、入库与国际发运可走 HIOBuy 履约网络。

1. 商品 API — 仍可直连卖场（兼顾低时延刷新）
2. 商品上架 — 同步到你面向消费者的站点
3. 用户下单 — 你的网站
4. 代购 — POST /v1/orders/*（网关转发仓库侧采购）
5. 自动代购 — 仓库侧使用托管凭证替你完成买单
6. 国内入库 — 包裹入仓，parcel_nos 等参见订单详情
7. 国际段 — 运费试算 → 批次预览 → 创建 → 支付
8. 末端追踪 — /v1/fulfillment/shipments/logistics/trace

代购与国际段 API 经 HIOBuy 路由；商品域仍可对卖场直连，保证刷新吞吐。

两种模式对照

	自履约	HIOBuy 仓库
渠道令牌	你维护各渠道的 OAuth	单仓绑定码统一管理
/v1/products/*	网关转发卖场（直连卖场）	网关转发卖场（直连低时延）
/v1/orders/*	网关用 你的令牌代购	网关 → HIOBuy 履约仓代购
/v1/fulfillment/*	不可用	国际出库 + 余额/结算

如何成为开发者 {#become-a-developer}

1. 用你的公司主页、站内场景等信息 注册账号（示例：海淘代购、跨境电商独立站）。
2. 完成邮箱验证。
3. 登录后在开发者门户 创建 App——描述集成用途与预期量级。
4. 等待 HIOBuy 审核。我们优先考虑「以成交为导向」的集成；通过后分配额度与卖场通道。
5. 获批后：绑定渠道（自履约 OAuth 或 仓库绑定码），并在 API Keys 面板创建密钥。
6. 开发顺序可参考：详情/搜索 → preview/create/pay → Webhooks。仓库模式再接国际出库。

若你需要 仓库侧开发者绑定码：在获准开通仓配后与运营同学申请。

API 速查

基地址：https://api.hiobuy.com/v1

模块	Prefix	文档入口
商品	/v1/products/*	商品
代购	/v1/orders/*	代购订单
履约	/v1/fulfillment/*	出库与余额

两类「订单」不要混用：/v1/orders/* 是在国内卖家侧 完成采购；/v1/fulfillment/shipments/* 是把已入库包裹 跨境发运。

建议阅读顺序 {#reading-order}

1. 成为开发者 — 注册、审核、密钥
2. 鉴权 + 门户授权
3. 商品 → 代购订单
4. 可选：履约（仓库模式）
5. 上线加固：错误 与 限流

公开文档范围 {#public-api-scope}

本站描述的是当前 支持的 Public HTTP 曲面。若在 openapi.json  中看到未在站内列出的路由（示例：历史 /v1/shipments、退款类内部路径），一律视为 不承诺对外：请 不要在未获书面确认前投产。

技术约定 {#technical-conventions}

• 认证：Authorization: Bearer YOUR_API_KEY —— 鉴权
• 请求体商品 language —— 多语言
• 金额：商品侧常用 CNY 元，订单与国际段常用 分（fen）
• response_format: "standard"（默认）或 "upstream" —— 响应结构

OpenAPI 机器可读：api.hiobuy.com/openapi.json 

在线文档：hiobuy.com/api-docs