配送チャネル API

GET /v1/fulfillment/shipping/channels は、アプリに接続された倉庫経由で利用できる、有効かつ料金設定済みの国際配送チャネルを一覧します。

チャネルセレクターの構築や対応能力の確認に使います。仕向地ごとの可否と金額は送料見積もりを呼び出してください。ここにある料金表は課金モデルの説明のみであり、価格を確定しません。

GEThttps://open.hiobuy.com/v1/fulfillment/shipping/channels

倉庫フルフィルメントが必要です。hio_test_* キーのサンドボックスアプリは決定的なモックデータを受け取ります。

見積もりは予算であり、確定価格ではありません。倉庫での計量、容積測定、再梱包、サービス確認により最終金額は変わり得ます。

金額と単位 {#units}

金額の amount はすべて整数の CNY fen（補助単位）です。1000 は ¥10.00 を意味します。
トップレベルの monetary_unit は常に CNY_minor です。
金額オブジェクトは次の形です:

{
  "amount": 1000,
  "currency": "CNY"
}

KG = キログラム、CM = センチメートル、M3 = 立方メートル、KG_PER_M3 = キログラム毎立方メートル。
チャネル、地域、サービスは name ではなく安定した code で識別してください。
Public API は倉庫データベース ID、開発者コード、サプライヤー URL を公開しません。

リクエスト {#request}

GET /v1/fulfillment/shipping/channels?country_code=US&include=regions,services,rate_cards&page=1&page_size=20
Authorization: Bearer hio_live_xxx
Language: en

表示言語は Language ヘッダーのみです。対応値: en（デフォルト）、en-US、zh、zh-CN、zh-TW、cn、hk。クエリ文字列や JSON 本文に language を入れないでください。

クエリパラメータ

パラメータ	必須	デフォルト	説明
`channel_code`	いいえ	—	安定したチャネルコードの完全一致（最大 64 文字）
`country_code`	いいえ	—	ISO 3166-1 alpha-2 の仕向国
`include`	いいえ	—	カンマ区切りの展開: `regions`、`services`、`rate_cards`
`page`	いいえ	`1`	ページ番号。1 から開始
`page_size`	いいえ	`20`	1 ページあたりの件数。最大 50

`include` 展開

include を省略すると軽量なチャネル概要になります。

`include` の値	レスポンスフィールド	用途
`regions`	`regions`	カバー範囲、マッチ種別、参考輸送日数
`services`	`value_added_services`	見積もり用のチャネル付加価値サービス
`rate_cards`	`rate_cards`	課金モデルを説明する参考料金行

値は組み合わせ可能です。例: include=regions,services,rate_cards。未知の値は 400 VALIDATION_ERROR を返します。

rate_cards は reference_only です。POST /v1/fulfillment/shipping/quotes の代替にしてはいけません。料金行を倉庫に問い合わせるのは include=rate_cards のときだけです。

有効かつ有効な料金設定があるチャネルだけが返ります。items が空配列のときは、現在のフィルタに一致するカタログチャネルがありません。

レスポンス {#response}

{
  "items": [
    {
      "code": "US-SEA",
      "name": "US Ocean",
      "description": "General cargo line",
      "status": "ACTIVE",
      "tags": [
        "GREAT_VALUE"
      ],
      "warehouse": {
        "code": "SZ",
        "name": "Shenzhen Warehouse"
      },
      "capabilities": {
        "delivery_methods": [
          "DOOR_DELIVERY"
        ],
        "multi_package_supported": true,
        "tracking_supported": true,
        "shipping_label_supported": false
      },
      "requirements": {
        "weight": "REQUIRED",
        "dimensions": "CONDITIONAL",
        "postal_code": "OPTIONAL",
        "declared_value": "OPTIONAL",
        "customs_code": "OPTIONAL",
        "personal_customs_code": "OPTIONAL",
        "recipient_identity": "OPTIONAL"
      },
      "attribute_matching": {
        "mode": "ANY_OF",
        "accepted_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ]
      },
      "billing": {
        "basis": "WEIGHT",
        "calculation_model": "FIRST_NEXT_WEIGHT",
        "quantity_unit": "KG",
        "supported_range": {
          "minimum": {
            "value": 0.5,
            "unit": "KG"
          },
          "maximum": {
            "value": 30,
            "unit": "KG"
          },
          "out_of_range_behavior": "UNAVAILABLE"
        },
        "minimum": {
          "value": 0.5,
          "unit": "KG",
          "ceil_to_minimum": true
        },
        "rounding": {
          "single_package_step": {
            "value": 0.5,
            "unit": "KG"
          },
          "multi_package_step": {
            "value": 0.5,
            "unit": "KG"
          },
          "ignore_below": {
            "value": 0.05,
            "unit": "KG"
          }
        },
        "multi_package": {
          "mode": "PER_BOX",
          "calculation_scope": "PER_PACKAGE",
          "aggregation": "SUM_PACKAGE_CHARGES",
          "minimum_per_package": {
            "value": 0.5,
            "unit": "KG"
          },
          "minimum_total": {
            "value": 0,
            "unit": "KG"
          }
        },
        "volumetric_weight": {
          "enabled": true,
          "divisor": 6000,
          "average_with_actual": false,
          "exemption": null
        },
        "overweight_warning": {
          "enabled": false,
          "threshold": {
            "value": 0,
            "unit": "KG"
          },
          "notice": null
        }
      },
      "rule_summary": {
        "fee_aggregation": "SUM_ALL",
        "maximum_charge": {
          "amount": 0,
          "currency": "CNY"
        },
        "has_surcharges": true,
        "has_order_restrictions": false,
        "has_dispatch_restrictions": true,
        "evaluated_by_quote": true
      },
      "regions": [
        {
          "code": "US-WEST",
          "name": "US West",
          "status": "ACTIVE",
          "match_type": "COUNTRY_REGION",
          "countries": [
            "US"
          ],
          "postal_code_required": false,
          "reference_transit_time": {
            "text": "15-18 business days",
            "min_business_days": 15,
            "max_business_days": 18
          },
          "areas": []
        }
      ],
      "value_added_services": [
        {
          "code": "LINE_FUEL",
          "name": "Fuel surcharge",
          "request_mode": "MANDATORY",
          "pricing_type": "CALCULATED",
          "pricing_scope": "REGION",
          "pricing_basis": "BASE_FREIGHT_PERCENT",
          "region_prices": [
            {
              "region_code": "US-WEST",
              "value": 500,
              "value_unit": "BASIS_POINT",
              "fixed_charge": {
                "amount": 200,
                "currency": "CNY"
              }
            }
          ],
          "final_quote_required": true,
          "may_be_adjusted": true
        }
      ],
      "rate_cards": [
        {
          "region_code": "US-WEST",
          "billing_basis": "WEIGHT",
          "calculation_model": "FIRST_NEXT_WEIGHT",
          "quantity_unit": "KG",
          "currency": "CNY",
          "reference_only": true,
          "price_rows": [
            {
              "type": "FIRST_WEIGHT",
              "pricing_basis": "WEIGHT",
              "range": {
                "minimum": 0.5,
                "maximum": 0.5,
                "unit": "KG",
                "minimum_inclusive": true,
                "maximum_inclusive": false
              },
              "first_quantity": {
                "value": 0,
                "unit": "KG"
              },
              "step": {
                "value": 0,
                "unit": "KG"
              },
              "charge": {
                "amount": 8000,
                "currency": "CNY"
              }
            }
          ]
        }
      ],
      "service_policy": {
        "warehouse_may_add_services": true,
        "warehouse_may_remove_services": true,
        "prices_may_change_after_inspection": true
      },
      "final_quote_required": true,
      "config_updated_at": "2026-09-07T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "has_more": false
  },
  "monetary_unit": "CNY_minor",
  "generated_at": "2026-09-07T09:00:00Z",
  "request_id": "req_xxx"
}

regions、value_added_services、rate_cards は、対応する include 値を送ったときだけ現れます。

レスポンスフィールド {#fields}

フィールド	説明
`items[]`	一致したチャネル。フィルタに一致するカタログチャネルがないときは空です。
`items[].code`	安定したチャネルコード。見積もりの `channel_codes` と出荷作成で使います。
`items[].name`	ローカライズされた表示名（`Language` ヘッダー）。
`items[].description`	ローカライズされた説明。
`items[].status`	カタログステータス。返却されるチャネルは `ACTIVE` です。
`items[].tags`	`GREAT_VALUE` などの安定タグ。
`items[].warehouse`	紐づく倉庫 `{ code, name }`。データベース ID ではありません。
`items[].capabilities`	配送方法、複数梱包、追跡、ラベル対応。
`items[].requirements`	入力の充足ヒント: `REQUIRED` · `OPTIONAL` · `CONDITIONAL` · `NOT_SUPPORTED`。
`items[].attribute_matching`	`ANY_OF` または `ALL_REQUIRED` と `accepted_attributes[].code`。
`items[].billing`	チャネルが貨物を課金する方式。下記を参照。
`items[].rule_summary`	追加料金や制限の有無。ルールは見積もりで評価されます。
`items[].regions`	`include=regions` のときに存在します。
`items[].value_added_services`	`include=services` のときに存在します。
`items[].rate_cards`	`include=rate_cards` のときに存在します。常に `reference_only` です。
`items[].service_policy`	倉庫が検品後にサービスを追加・削除し、価格を変更する場合があります。
`items[].final_quote_required`	出荷固有の見積もりがまだ必要なときは `true`。
`items[].config_updated_at`	このチャネルのカタログ改訂時刻。
`pagination`	`page`、`page_size`、`total`、`has_more`。
`monetary_unit`	常に `CNY_minor`。
`generated_at`	レスポンス時刻（ISO 8601）。
`request_id`	`x-request-id` と突き合わせます。

課金 {#billing}

フィールド	意味
`basis`	`WEIGHT`、`VOLUME`、または `DENSITY`
`calculation_model`	料金行が使う課金モデル
`quantity_unit`	`KG`、`M3`、または `KG_PER_M3`
`supported_range`	課金可能な数量の最小・最大
`supported_range.out_of_range_behavior`	`UNAVAILABLE` — 範囲外の荷物はこのチャネルで運べません。外挿しないでください。
`minimum`	最小課金数量と、それ未満を切り上げるか（`ceil_to_minimum`）
`rounding`	単梱包および複数梱包の丸めステップ
`volumetric_weight`	容積重量の除数と免除ルール
`multi_package`	梱包単位か合算課金か、および集計方法
`overweight_warning`	任意の過重量通知

課金モデルには FIRST_NEXT_WEIGHT、TIERED_PRICE、UNIT_PRICE_PLUS_GRADE、MULTI_LEVEL_NEXT_WEIGHT、RANGE_FIRST_NEXT_WEIGHT が含まれます。これらの行から倉庫の料金エンジンを再実装しないでください。

地域 {#regions}

フィールド	意味
`code` / `name`	安定した地域コードとローカライズ名
`match_type`	`COUNTRY_REGION` または `POSTAL_CODE`
`countries`	この地域がカバーする ISO 国コード
`postal_code_required`	`true` のときは見積もりに `postal_code` を送ってください
`reference_transit_time`	表示テキストと任意の最短・最長営業日
`areas`	任意のより細かいエリア一覧。カタログは郵便ルールの全データベースを公開しません。

付加価値サービス {#value-added-services}

送料見積もりの services.channel[] では value_added_services[].code を使います。

フィールド	意味
`code`	安定したサービスコード
`request_mode`	`MANDATORY`（常に適用）または `OPTIONAL`（開発者が選択）
`pricing_type`	定額か算出か（例: `CALCULATED`）
`pricing_scope`	価格の適用範囲（例: `REGION`）
`pricing_basis`	料金の算出方法

BASIS_POINT はパーセントのベーシスポイントです。500 は 5% を意味します。処理中に倉庫がサービスを追加・削除・調整する場合があります — service_policy と may_be_adjusted を参照してください。

料金表 {#rate-cards}

フィールド	意味
`region_code`	この料金表が属する地域
`billing_basis`	`billing.basis` と同じ語彙
`calculation_model`	`billing.calculation_model` と同じ語彙
`quantity_unit`	`KG`、`M3`、または `KG_PER_M3`
`price_rows`	モデル説明用の参考帯
`reference_only`	常に `true` — ライブ見積もりではありません

キャッシュ {#caching}

config_updated_at は、チャネル詳細、地域、料金表、ルール、サービスが変わると更新されます。軽量カタログは短時間キャッシュし、このタイムスタンプが変わったら展開を再取得し、出荷作成前には必ず送料見積もりを呼び出してください。確定済みの料金バージョンはありません。

エラー {#errors}

チャネル固有の対象外は HTTP エラーではありません。空の items 配列はカタログ不一致の成功レスポンスです。

HTTP	`error.code`	発生条件
400	`VALIDATION_ERROR`	ページング、国コード構文、または `include` 値が不正
401	`INVALID_API_KEY`	Bearer トークンがない、または無効
400	`INVALID_SHIPPING_CHANNEL`	未知のチャネルを指定する見積もり / 出荷呼び出し向けに予約。この一覧は空の `items` 配列を返すだけです。
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	アプリが自社フルフィルメント
403	`WAREHOUSE_AUTH_INVALID`	倉庫認可がない、拒否された、または期限切れ
422	`INVALID_COUNTRY_CODE`	仕向国が無効または非対応
502	`WAREHOUSE_UPSTREAM_ERROR`	倉庫サービス失敗。バックオフして再試行

公開の独立コード AUTHENTICATION_ERROR、WAREHOUSE_AUTH_REQUIRED、WAREHOUSE_SERVICE_UNAVAILABLE はありません。認証失敗は 401 INVALID_API_KEY、倉庫未バインドは 403 WAREHOUSE_AUTH_INVALID、倉庫障害は 502 WAREHOUSE_UPSTREAM_ERROR です。

エラーと認証を参照してください。

例 {#examples}

軽量カタログ:

curl "https://api.hiobuy.com/v1/fulfillment/shipping/channels?page=1&page_size=20" \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Language: en"

米国向けに配送できるチャネル（参考料金を含む）:

curl "https://api.hiobuy.com/v1/fulfillment/shipping/channels?country_code=US&include=regions,services,rate_cards" \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Language: zh-CN"

次へ: 仕向地固有の送料見積もりをリクエスト。

Get Support

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

Email support