响应格式

HIOBuy 公开 API 的部分 POST 路由支持两种响应形态。可在 JSON 请求体中传入可选字段 response_format。

一句话理解

默认是 standard。 不传 response_format，或传 "response_format": "standard" 即可。

	`standard`（推荐）	`upstream`
返回内容	HIOBuy 统一模型 — 跨渠道相同 JSON 结构	上游服务商的原始 JSON（1688 Open API、淘宝 IOP 等）
字段映射	由 HIOBuy Gateway 完成（字段名、嵌套、单位换算）	不做映射 — 字段与上游官方文档一致
1688 vs 淘宝	同一接口 → 同一结构；切换 `channel` 无需重写解析逻辑	各渠道返回完全不同的上游 JSON
适用场景	生产集成、多 channel 共用一套代码、业务/UI 层	对照官方文档调试、旧系统迁移、临时排查
如何指定	默认，无需额外字段	显式传 `"response_format": "upstream"`

建议： 正常接入请使用 standard。HIOBuy 会在统一模型中维护跨渠道兼容（如 StandardProductDetail、StandardOrderPreviewResult）。仅在需要上游原生 payload 时使用 upstream。

两种模式的鉴权、渠道 OAuth、配额与限流规则相同。

模式

值	说明
`standard`（默认）	HIOBuy 规范化类型 — `StandardProductDetail`、`StandardProductList`、`StandardOrderPreviewResult`、`StandardOrderCreateResult` 等。无论 `channel` 为 `1688` 或 `taobao`，同一接口返回相同结构。
`upstream`	上游透传 — 1688 / 淘宝官方 JSON 放在 `upstream` 中，不做 HIOBuy 字段映射。结构随上游 API 与版本变化。

Upstream 信封

显式设置 "response_format": "upstream" 时，HTTP 响应会包装上游服务商的原始 JSON：

{
  "channel": "1688",
  "response_format": "upstream",
  "upstream_api": "com.alibaba.fenxiao.crossborder/product.search.keywordQuery",
  "upstream": {
    "result": {
      "success": true
    }
  },
  "upstream_steps": [],
  "request_id": "req_abc123"
}

upstream_api — 主上游 API 标识（1688 路径或淘宝 IOP 路由）
upstream — 该上游返回的原始 HTTP JSON 正文（与官方文档一致）
upstream_steps — 可选的前置调用（例如以图搜索前的图片上传）

上游变更 API 时，HIOBuy 不承诺 upstream 内层结构的长期稳定。生产环境请优先使用 standard。

Standard 示例（默认）

不传 response_format — 大多数集成应解析这种响应：

POST /v1/products/search
{
  "channel": "1688",
  "keyword": "phone case",
  "page": 1,
  "page_size": 10
}

响应为 StandardProductList（见商品响应模型）。将 "channel" 改为 "taobao" 时，顶层字段结构不变，仅数据来源不同。

标准预览响应 {#standard-preview}

POST /v1/orders/preview（1688 与淘宝）在 standard 模式下返回 StandardOrderPreviewResult。金额单位为分（CNY 分）。字段参考：采购订单。

{
  "channel": "taobao",
  "success": true,
  "total": {
    "payment": {
      "amount": 12900,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 0,
      "currency": "CNY"
    }
  },
  "unavailable_lines": [],
  "sellers": [
    {
      "seller_id": "...",
      "lines": [
        {
          "offer_id": "...",
          "spec_id": "...",
          "quantity": 5
        }
      ]
    }
  ],
  "request_id": "req_..."
}

1688 额外返回 trade_types、pay_channels 与 promotions。传 "response_format": "upstream" 时，预览返回原始上游 JSON，需自行按 1688 / 淘宝字段解析。

商品路由

Endpoint	Channels	Upstream API（示例）
`POST /v1/products/detail`	1688, taobao	`queryProductDetail` / `/traffic/item/get`
`POST /v1/products/search`	1688, taobao	`keywordQuery` / `/traffic/item/search`
`POST /v1/products/search-by-image`	1688, taobao	upload + `imageQuery` / upload + `/traffic/item/imgsearch`

POST /v1/products/parse 始终仅返回 standard。POST /v1/products/freight/estimate 请求体与订单预览相同，仅返回运费。

订单路由（1688 与淘宝）

Endpoint	Standard	Upstream API（示例）
`POST /v1/orders/list`	✓	`alibaba.trade.getBuyerOrderList`
`POST /v1/orders/1688/preview`	✓	`alibaba.createOrder.preview`
`POST /v1/orders/1688/create`	✓	`alibaba.trade.createCrossOrder`
`POST /v1/orders/preview`	✓	按 `channel` 分发（1688 / taobao）
`POST /v1/orders/create`	✓	按 `channel` 分发
`POST /v1/orders/taobao/preview`	✓	`/purchase/order/render`
`POST /v1/orders/taobao/create`	✓	`/purchase/order/create`
`POST /v1/orders/cancel`	✓	`alibaba.trade.cancel`
`POST /v1/orders/pay`	✓	按 `channel` 分发
`POST /v1/orders/detail`	✓	按 `order_id` 查询订单详情
`POST /v1/orders/logistics/trace`	✓	国内物流轨迹
`POST /v1/orders/purchase/query`	✓	淘宝采购单列表

示例 — upstream 搜索

curl https://api.hiobuy.com/v1/products/search \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "response_format": "upstream",
    "channel": "1688",
    "keyword": "phone case",
    "page": 1,
    "page_size": 10,
    "language": "en"
  }'

校验

无效值（例如 vendor_raw）返回 HTTP 400 且 VALIDATION_ERROR。见错误。

OpenAPI

机器可读规范：openapi.json （schema：UpstreamApiResponse、UpstreamStep）。

获取支持

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

发送邮件