送料見積もり API

POST /v1/fulfillment/shipping/quotes は、仕向地、重量、寸法、商品属性、サービスから国際送料を見積もります。

倉庫での分割が不明なときは 単梱包ショートハンド を使います。梱包数と梱包ごとの計測値が既知のときは packages[] を使います。

このエンドポイントは配送チャネル API と同じチャネル、地域、サービス、課金、金額の用語を使います。

POSThttps://api.hiobuy.com/v1/fulfillment/shipping/quotes

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

互換エイリアス: POST /v1/fulfillment/shipments/freight/estimate（同じ動作）。/v1/fulfillment/shipping/quotes を優先してください。

金額と単位 {#units}

金額の amount はすべて整数の CNY fen です。5000 は ¥50.00 を意味します。
トップレベルの monetary_unit は常に CNY_minor です。
金額オブジェクトは { "amount": 5000, "currency": "CNY" } です。
リクエストの重量は常に KG。梱包寸法は常に CM。
チャネルとサービスは name ではなく安定した code で識別してください。

リクエストヘッダー {#request}

POST /v1/fulfillment/shipping/quotes
Authorization: Bearer hio_live_xxx
Content-Type: application/json
Language: en

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

2 つのリクエスト形式 {#request-formats}

単梱包ショートハンドのフィールド（weight_kg、length_cm、width_cm、height_cm）と packages[] を混ぜないでください。混在リクエストは 400 VALIDATION_ERROR で拒否されます。

形式 A — 単梱包ショートハンド {#format-a}

仕向地と推定の合計重量は分かるが、倉庫が箱をどう分割するかは分からないときに使います。

最小リクエスト:

{
  "destination": {
    "country_code": "KR"
  },
  "weight_kg": 2.05
}

寸法付きの単梱包:

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "weight_kg": 2.05,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10,
  "attributes": []
}

weight_kg は推定の出荷重量（KG）です。
length_cm、width_cm、height_cm は CM です。3 つすべてを送るか、3 つとも省略してください。
最終的な倉庫分割が不明なときはこの形式を優先します。寸法欠落は、容積課金チャネルで PARTIAL または REVIEW_REQUIRED になることがあります。

形式 B — 既知の梱包 {#format-b}

箱数と各箱のデータが既知のときは packages[] を使います。

申告済み単梱包:

{
  "destination": {
    "country_code": "KR"
  },
  "packages": [
    {
      "reference": "box-1",
      "weight": {
        "value": 2.05,
        "unit": "KG"
      },
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10,
        "unit": "CM"
      }
    }
  ]
}

複数梱包:

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "packages": [
    {
      "reference": "box-1",
      "weight": {
        "value": 1.25,
        "unit": "KG"
      },
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10,
        "unit": "CM"
      }
    },
    {
      "reference": "box-2",
      "weight": {
        "value": 0.8,
        "unit": "KG"
      },
      "dimensions": {
        "length": 20,
        "width": 15,
        "height": 8,
        "unit": "CM"
      }
    }
  ]
}

packages[] のルール（OpenAPI）:

1〜200 梱包。
要素 1 つは明示的な単梱包。複数要素は明示的な複数梱包出荷です。
reference は任意ですが、リクエスト内で一意である必要があります。
packages[].weight は必須です。packages[].weight.unit は KG である必要があります。
packages[].dimensions は任意です。指定する場合、length、width、height、unit がすべて必須です。unit は CM である必要があります。

Gateway は形式 A を倉庫の単梱包にマップします。形式 B は申告どおり検証・マップされます。最終的な分割と実測寸法は、倉庫処理後に決まります。

共通リクエストフィールド {#shared-fields}

どちらの形式でも次を含められます。

`destination`

フィールド	必須	説明
`country_code`	はい	ISO 3166-1 alpha-2、2 文字
`subdivision_code`	いいえ	例: `US-CA`。国プレフィックスは `country_code` と一致する必要があります。
`region`	いいえ	行政区の表示名。有効な `subdivision_code` が優先されます。
`postal_code`	いいえ	文字列。先頭のゼロを保持してください。

`declared_value`

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

出荷レベルの申告価格。整数の CNY fen。不明なときはフィールドを省略してください。不明の意味で 0 を送らないでください。

`attributes`

GET /v1/fulfillment/shipments/item-attributes の安定した商品属性コードの配列。一意な文字列、最大 100。

見積もり対象はまず destination.country_code に適用できるチャネルだけに絞られ、他国向けチャネルは除外されます。残った各チャネルが申告属性を個別に判定します。非対応属性があるチャネルは ATTRIBUTE_NOT_SUPPORTED を伴う UNAVAILABLE になりますが、他の適用可能なチャネルは引き続き見積もりを返せます。

`services`

{
  "services": {
    "channel": [
      {
        "code": "LINE_INSURANCE",
        "quantity": 1
      }
    ],
    "outbound": [
      {
        "code": "VACUUM_PACKING",
        "quantity": 1
      }
    ],
    "inbound": [
      {
        "code": "PHOTO",
        "quantity": 3
      }
    ]
  }
}

グループ	意味
`channel`	チャネル付加価値サービス。コードはチャネルの `value_added_services[].code` です。
`outbound`	出庫倉庫処理
`inbound`	入庫倉庫処理

各項目に code と quantity が必要です。OpenAPI: quantity は 1〜999 の整数です。コードは各グループ内で一意である必要があります。

`channel_codes`

見積もり対象を絞り込む安定したチャネルコード。省略すると候補チャネルすべてを見積もります。空配列は 送らないでください。未知またはアクセスできないコードは、リクエスト全体に対して 400 INVALID_SHIPPING_CHANNEL を返します。

完全なリクエスト例 {#complete-request}

形式 A。仕向地、寸法、申告価格、属性、サービス、チャネルフィルタ付き:

{
  "destination": {
    "country_code": "US",
    "subdivision_code": "US-CA",
    "region": "California",
    "postal_code": "90001"
  },
  "weight_kg": 2.05,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10,
  "declared_value": {
    "amount": 5000,
    "currency": "CNY"
  },
  "attributes": [
    "GENERAL_CARGO"
  ],
  "services": {
    "channel": [
      {
        "code": "LINE_INSURANCE",
        "quantity": 1
      }
    ],
    "outbound": [
      {
        "code": "VACUUM_PACKING",
        "quantity": 1
      }
    ],
    "inbound": [
      {
        "code": "PHOTO",
        "quantity": 3
      }
    ]
  },
  "channel_codes": [
    "US-SEA"
  ]
}

レスポンス {#response}

{
  "success": true,
  "estimate_type": "DECLARED",
  "completeness": {
    "level": "HIGH",
    "destination": "COMPLETE",
    "package_dimensions": "COMPLETE",
    "package_split": "DECLARED",
    "declared_value": "PROVIDED",
    "attributes": "DECLARED",
    "services": "REQUESTED_ONLY"
  },
  "warnings": [
    {
      "code": "WAREHOUSE_REVIEW_REQUIRED",
      "message": "Final charges require warehouse measurement, packing and service review.",
      "affects": [
        "FINAL_CHARGES"
      ]
    }
  ],
  "quotes": [
    {
      "channel": {
        "code": "US-SEA",
        "name": "US Ocean",
        "description": "General cargo line",
        "tags": [
          "GREAT_VALUE"
        ],
        "capabilities": {
          "delivery_methods": [
            "DOOR_DELIVERY",
            "PICKUP"
          ]
        }
      },
      "available": true,
      "quote_status": "COMPLETE",
      "unavailable_reason": null,
      "attribute_evaluation": {
        "status": "SUPPORTED",
        "declared_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ],
        "accepted_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ],
        "unsupported_attributes": []
      },
      "matched_region": {
        "code": "US-WEST",
        "name": "US West",
        "match_type": "COUNTRY_REGION"
      },
      "packages": [
        {
          "reference": "box-1",
          "weight": {
            "value": 2.05,
            "unit": "KG"
          },
          "dimensions": {
            "length": 30,
            "width": 20,
            "height": 10,
            "unit": "CM"
          },
          "weights": {
            "actual": {
              "value": 2.05,
              "unit": "KG"
            },
            "volumetric": {
              "value": 1,
              "unit": "KG"
            },
            "chargeable": {
              "value": 2.5,
              "unit": "KG"
            }
          }
        }
      ],
      "weights": {
        "actual": {
          "value": 2.05,
          "unit": "KG"
        },
        "volumetric": {
          "value": 1,
          "unit": "KG"
        },
        "chargeable": {
          "value": 2.5,
          "unit": "KG"
        }
      },
      "billing_quantity": {
        "value": 2.5,
        "unit": "KG"
      },
      "pricing_selector": {
        "type": "WEIGHT",
        "value": 2.5,
        "unit": "KG",
        "scope": "SHIPMENT"
      },
      "transit_time": {
        "text": "15-18 business days",
        "min_business_days": 15,
        "max_business_days": 18
      },
      "charges": {
        "base_freight": {
          "amount": 10000,
          "currency": "CNY"
        },
        "channel_services": {
          "amount": 550,
          "currency": "CNY",
          "known_amount": 550,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "channel_rules": {
          "amount": 0,
          "currency": "CNY",
          "known_amount": 0,
          "calculation_status": "CALCULATED",
          "items": [],
          "aggregation": "SUM_ALL",
          "cap": null
        },
        "outbound_services": {
          "amount": 800,
          "currency": "CNY",
          "known_amount": 800,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "inbound_services": {
          "amount": 300,
          "currency": "CNY",
          "known_amount": 300,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "adjustments": {
          "amount": 0,
          "currency": "CNY",
          "known_amount": 0,
          "calculation_status": "CALCULATED",
          "items": []
        }
      },
      "display_charges": {
        "addition": {
          "amount": 0,
          "currency": "CNY",
          "included_in_total": false
        },
        "floor": {
          "amount": 0,
          "currency": "CNY",
          "included_in_total": false
        }
      },
      "total": {
        "amount": 11650,
        "currency": "CNY"
      },
      "known_total": {
        "amount": 11650,
        "currency": "CNY"
      },
      "warnings": [],
      "service_adjustment_possible": true
    }
  ],
  "monetary_unit": "CNY_minor",
  "generated_at": "2026-09-07T08:00:00Z",
  "request_id": "req_xxx",
  "disclaimer": "Estimated charges based on declared data."
}

トップレベルフィールド

フィールド	説明
`success`	一部の見積もりが `UNAVAILABLE` でも、見積もり成功時は `true`。
`estimate_type`	`DECLARED` — 申告データに基づき、倉庫実測ではありません。
`completeness`	入力の充足度。配送可否の保証ではありません。
`warnings`	出荷レベルの警告。
`quotes`	チャネルごとの結果: 完全、部分 / 確認待ち、利用不可の順。
`monetary_unit`	常に `CNY_minor`。
`generated_at`	レスポンス時刻。
`request_id`	`x-request-id` と突き合わせます。
`disclaimer`	人が読める見積もり免責。

`completeness`

フィールド	意味
`level`	入力全体の充足度。例: `HIGH`。
`destination`	仕向地の充足度（国があれば `COMPLETE`）。
`package_dimensions`	縦 / 横 / 高さが提供されたか。
`package_split`	`packages[]` を送ったときは `DECLARED`。ショートハンドは単梱包とみなします。
`declared_value`	`PROVIDED`、または省略 / 不明。
`attributes`	商品属性が申告されたか。
`services`	選択サービスを送ったときは `REQUESTED_ONLY`。倉庫がさらに追加する場合があります。

見積もりステータス {#quote-status}

available だけで判断しないでください。必ず quote_status を読んでください。

`quote_status`	`available`	`total`	意味
`COMPLETE`	`true`	金額オブジェクト	表示してよい完全な予算。それでも確定ではありません。
`PARTIAL`	`true`	通常 `null`	入力不足。警告を読み、寸法、郵便番号、申告価格を追加してください。
`REVIEW_REQUIRED`	`true`	通常 `null`	倉庫実測または人手確認が必要です。
`UNAVAILABLE`	`false`	`null`	このチャネルは見積もりできません。HTTP リクエスト自体は成功しています。

total は判明しているときの完全な予算です。
known_total は現時点で算出できる料金の合計です。
total が null のとき、known_total を完全な見積もりとして扱わないでください。
unavailable_reason.code はプログラム処理用です。
unavailable_reason.message は表示専用です。

1 件の見積もりが UNAVAILABLE でも HTTP エラーではありません。

見積もりオブジェクト {#quotes}

フィールド	説明
`channel`	`{ code, name, description, tags, capabilities }` — チャネルカタログと同じ識別子。
`channel.capabilities.delivery_methods`	後方互換のオプション配列。安定コードは `DOOR_DELIVERY`、`PICKUP`、`POST_OFFICE_PICKUP`。すべての見積ステータスで返る可能性があり、既存クライアントは無視できます。
`available`	このチャネルが利用可能な見積もりを出したか。`quote_status` と合わせて見てください。
`quote_status`	`COMPLETE` · `PARTIAL` · `REVIEW_REQUIRED` · `UNAVAILABLE`。
`unavailable_reason`	`{ code, message }` または `null`。
`attribute_evaluation`	チャネルごとの任意の判定結果。`SUPPORTED`、`UNSUPPORTED`、`NOT_DECLARED` と、申告済み・受入可能・非対応属性の一覧。
`matched_region`	`{ code, name, match_type }` または `null`。
`packages`	申告またはマップされた梱包と梱包ごとの重量。
`weights`	出荷レベルの `actual` / `volumetric` / `chargeable`（`KG`）。
`billing_quantity`	チャネルが実際に課金する数量。単位は `KG`、`M3`、または `KG_PER_M3`。
`pricing_selector`	その数量が料金表のどの帯に当たったか（`type`、`value`、`unit`、`scope`）。
`transit_time`	参考輸送日数。
`charges`	料金グループ。下記を参照。
`display_charges`	任意の UI 専用行。`included_in_total` が `false` なら `total` に加算しないでください。
`total` / `known_total`	完全な予算と、現時点で判明している料金。
`warnings`	チャネルレベルの警告。
`service_adjustment_possible`	倉庫処理でサービスと料金がまだ変わり得る場合は `true`。

重量と課金数量 {#weights}

actual — 申告または実測重量。
volumetric — 容積重量。
chargeable — 運賃計算に使う重量。
billing_quantity — チャネルが課金する数量（重量、容積、密度の場合があります）。
pricing_selector — その数量が料金行をどう選んだか。種別はカタログの WEIGHT / VOLUME / DENSITY と一致します。
複数梱包チャネルは 箱ごと に丸めてから合計する場合があります。pricing_selector.scope が PER_PACKAGE のときは、各 packages[].pricing_selector を読んでください。

料金 {#charges}

グループ	意味
`base_freight`	基本国際運賃
`channel_services`	必須および開発者選択のチャネルサービス
`channel_rules`	過大、過重、申告価格、その他の路線ルール
`outbound_services`	出荷準備 / 出庫処理時に実施する付加価値サービス
`inbound_services`	倉庫での受領 / 入庫処理時に実施する付加価値サービス
`adjustments`	調整

入庫サービスと出庫サービス

inbound_services と outbound_services は、倉庫付加価値サービスの異なる工程です。入庫サービスは倉庫受領時に行われ、荷物写真、動画撮影、検品などが含まれます。出庫サービスは出荷準備時に行われ、荷物補強、真空梱包、木枠・木箱梱包などが含まれます。同じ荷物や配送に対して両工程の異なるサービスが実施され、両方が正当に請求される場合があります。

Shipping Quote の金額は適用サービスの見積もりにすぎず、見積もりの取得自体が追加料金を発生させることはありません。実際の請求額は、実施されたサービスとその最終料金・精算によって決まります。総履行コストの見積もりには両グループを使用し、各見積もりを対応する最終実費と照合してください。同一サービスの見積額を最終料金に再度加算しないでください。

CNY の最小単位による例：荷物写真 50 fen（¥0.50）、検品 100 fen（¥1.00）、真空梱包 150 fen（¥1.50）、荷物補強 200 fen（¥2.00）。異なる工程で行う別々のサービスなので、4 項目すべてが同時に存在できます。

各グループには通常次が含まれます:

フィールド	意味
`amount`	グループ合計（fen）。不明なら `null`
`currency`	`CNY`
`known_amount`	現時点で算出できる明細の合計
`calculation_status`	例: `CALCULATED`
`items`	明細行

channel_rules には aggregation と cap も含まれる場合があります。グループ小計を使ってください。生のルール明細を合計して置き換えないでください。

SUM_ALL は命中した全料金を合算します。HIGHEST_ONLY は金額降順の最高額 1 件だけを採用し、同額ルールは同等です。cap=null は上限なしです。ルール明細の reason は表示専用です。プログラムでは condition_match、matched_conditions、rule_type、charge_mode、charge_value、outcome、missing_fields を使用してください。PENDING_INPUT、REVIEW_REQUIRED その他の未計算ルールは既知合計に含まれません。amount=null はゼロではなく、設定済みの charge_value は実際の請求額ではありません。

料金明細

フィールド	意味
`code`	安定した料金またはサービスコード
`name`	ローカライズされた表示名
`category`	料金カテゴリ
`source`	`MANDATORY` · `DEVELOPER_SELECTED` · `RULE_ENGINE`
`pricing_basis`	行の課金方法
`quantity`	行の課金数量
`unit_price`	判明しているときの単価（fen）
`amount`	行合計。`null` は不明であり、ゼロではありません。
`estimated`	行がまだ見積もり段階か
`calculation_status`	算出状態
`affected_by_packages`	梱包数 / サイズがこの行を変え得るか
`included_in_total`	`false` なら `total` に再度加算しないでください

display_charges はフロントエンド表示専用で存在する場合があります。

利用不可理由 {#unavailable-reasons}

よくある unavailable_reason.code の値:

OUTSIDE_PRICING_RANGE
POSTAL_CODE_REQUIRED
POSTAL_CODE_NOT_SUPPORTED
DESTINATION_NOT_SUPPORTED
ATTRIBUTE_NOT_SUPPORTED
SERVICE_NOT_SUPPORTED
DIMENSIONS_REQUIRED
DECLARED_VALUE_REQUIRED
MULTI_PACKAGE_NOT_SUPPORTED
PRICING_MODE_UNSUPPORTED
CHANNEL_RULE_REJECTED
CHANNEL_PRICING_ERROR

利用不可のチャネルは quotes[] に残り、却下理由を説明できます。

カタログ用語 {#catalog-terminology}

配送チャネル	この API	意味
`items[].code/name/description/tags`	`quotes[].channel.*`	同じチャネル
`regions[].code/name/match_type`	`quotes[].matched_region.*`	見積もりが選んだ地域
`value_added_services[].code`	`services.channel[].code` および料金の `code`	安定したサービスコード
`billing.quantity_unit`	`billing_quantity.unit` / `pricing_selector.unit`	課金単位
`rule_summary.aggregation`	`charges.channel_rules.aggregation`	ルール集計
`rule_summary.cap`	`charges.channel_rules.cap`	集計後の上限。`null` は上限なし

商品属性 {#item-attributes}

GET /v1/fulfillment/shipments/item-attributes は、見積もりで有効な attributes[] コードを返します。

エラー {#errors}

HTTP	`error.code`	発生条件
400	`VALIDATION_ERROR`	構造不正、リクエスト形式の混在、KG/CM 単位、重複コード、または空の `channel_codes`
400	`INVALID_SHIPPING_CHANNEL`	リクエストした `channel_codes` が未知、またはアプリから見えない
401	`INVALID_API_KEY`	Bearer トークンがない、または無効
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	アプリが自社フルフィルメント
403	`WAREHOUSE_AUTH_INVALID`	倉庫認可がない、拒否された、または期限切れ
422	`INVALID_COUNTRY_CODE`	仕向国が無効
422	`INVALID_ITEM_ATTRIBUTE`	属性コードが無効
502	`WAREHOUSE_UPSTREAM_ERROR`	倉庫サービス失敗。バックオフして再試行

公開の独立コード AUTHENTICATION_ERROR、WAREHOUSE_AUTH_REQUIRED、WAREHOUSE_SERVICE_UNAVAILABLE はありません。401 INVALID_API_KEY、403 WAREHOUSE_AUTH_INVALID、502 WAREHOUSE_UPSTREAM_ERROR を使います。

この出荷を運べないチャネルは HTTP 失敗ではなく、UNAVAILABLE 見積もりです。

配送チャネル — 対応能力、カバー範囲、サービスコード
出荷 — 荷物が入庫したあとに出荷を作成
フルフィルメント概要

Get Support

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

Email support