响应格式

支持的 POST 路由可在 JSON 请求体中传入可选字段 response_format。省略或使用 standard 即为默认的 HIOBuy 统一模型。

模式

值说明
standard（默认）规范化类型——StandardProductDetail、StandardProductList、StandardOrderPreviewResult 等
upstream上游透传——1688 官方 Open API 或淘宝 IOP JSON 置于 upstream，不做字段映射

Upstream 信封

当 response_format 为 upstream 时：

{
  "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 — 可选的前置调用（例如以图搜索前的图片上传）

标准预览响应 {#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。

商品路由

EndpointChannelsUpstream API（示例）
POST /v1/products/detail1688, taobaoqueryProductDetail / /traffic/item/get
POST /v1/products/search1688, taobaokeywordQuery / /traffic/item/search
POST /v1/products/search-by-image1688, taobaoupload + imageQuery / upload + /traffic/item/imgsearch

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

订单路由（1688 与淘宝）

EndpointStandardUpstream 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）。