レスポンス形式

HIOBuy Public API の一部 POST ルートは 2 種類のレスポンス形態をサポートします。

要点

デフォルトは standard です。 response_format を省略するか、"response_format": "standard" を指定してください。

standard（推奨）upstream
返却内容HIOBuy 統一モデル — チャネル横断で同じ JSON 構造上流プロバイダの生 JSON
フィールドマッピングHIOBuy Gateway が実施なし — ベンダー公式ドキュメントと同じ
用途本番統合（推奨）デバッグ・移行

推奨: 通常は standard で統合してください。

モード

値説明
standard (デフォルト)HIOBuy 正規化型 — channel が 1688 でも taobao でも 同じ構造。
upstream上流透過 — 1688 / Taobao の公式 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 パスまたは Taobao IOP ルート)
  • upstream — その呼び出しの生の HTTP JSON 本文
  • upstream_steps — 任意の事前呼び出し (例: 画像検索前の画像アップロード)

標準プレビューレスポンス {#standard-preview}

POST /v1/orders/preview (1688 と Taobao) は、standard モードで StandardOrderPreviewResult を返します。金額は fen (CNY cents) です。フィールド一覧: Procurement orders。

{
  "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" の場合、preview は生のベンダー 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 & Taobao)

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✓Taobao 購入一覧

例 — upstream search

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 を返します。Errors を参照してください。

OpenAPI

機械判読可能な仕様: openapi.json  (スキーマ UpstreamApiResponse, UpstreamStep)。

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support