国際フルフィルメント概要

/v1/fulfillment/* は、貨物が HIOBuy 倉庫に入庫した後の国際物流を扱います。国内調達は 代行購入注文 を参照してください。

アプリで倉庫フルフィルメントが必要です（ポータル認可）。自己フルフィルメントのアプリは 403 FULFILLMENT_MODE_NOT_SUPPORTED を受け取ります。

金額単位 {#monetary-unit}

金額を含むフルフィルメント経路の標準 JSON 応答には、トップレベルで monetary_unit: "CNY_minor" が含まれます。すべての { amount, currency } の amount は CNY fen（1 元 = 100 fen）です。フルフィルメント応答モデル を参照してください。

API の可用性 {#availability}

パス状態
/v1/fulfillment/inbounds/create倉庫モードでは Live（倉庫 simple-store）；サンドボックスは mock
/v1/fulfillment/packages倉庫モードでは Live（packages/index）；サンドボックスは mock
/v1/fulfillment/packages/{package_id}倉庫モードでは Live（packages/detail/{id}）；サンドボックスは mock
/v1/fulfillment/packages/{package_id}/tracking倉庫モードでは Live（packages/logs/{id}）；サンドボックスは mock
/v1/fulfillment/unclaimed-packages倉庫モードでは Live（一覧 + 引き取り）；サンドボックスは mock
/v1/fulfillment/returnsMock — 返送の作成 / 一覧 / 確認 / キャンセル
/v1/fulfillment/locations倉庫モードでは Live（warehouse）；サンドボックスは mock
/v1/fulfillment/value-added-services倉庫モードでは Live（services）；サンドボックスは mock
/v1/fulfillment/service-requestsMock — 作成 / 一覧 / 詳細 / 確認
/v1/fulfillment/shipments/{id}/intercept倉庫モードでは Live（shipments/set-exceptional）；サンドボックスは mock
/v1/fulfillment/shipments倉庫モードでは Live（shipments/index）；サンドボックスは mock
/v1/fulfillment/shipping/channels倉庫モードではチャネルカタログが Live；サンドボックスは mock
/v1/fulfillment/shipping/quotes倉庫モードでは見積もりが Live；サンドボックスは mock
/v1/fulfillment/shipments/*利用可能（設定済みなら倉庫 HTTP、それ以外は mock）
/v1/fulfillment/balance利用可能
/v1/shipments（旧版）非推奨

エンドツーエンドの流れ {#end-to-end-flow}

  1. 代行購入注文を作成 → 出品者が倉庫へ発送
    または すでに管理している荷物の 入庫予告
  2. 荷物詳細 / 追跡 → 倉庫計測 / 例外 / VAS / 履行タイムライン
    または 注文詳細 → 代行購入入庫後の tracking_numbers[]
  3. 配送チャネル で能力を確認し、送料見積もり → quotes[].channel.code を選択
  4. 出荷を作成 → id / order_sn（PENDING）
  5. 倉庫梱包と最終計測 → boxes[]、最終重量 / 寸法、最終運賃
  6. 出荷が支払い可能（WAIT_PAYMENT）→ 詳細 を参照。早すぎる支払いは 409 SHIPMENT_NOT_READY_FOR_PAYMENT
  7. 出荷を支払う → ウォレットから控除
  8. 一覧 / 詳細 → 軽量行、または箱 / 梱包ファイル / timeline / ファーストマイル・ラストマイル番号
    任意：インターセプト（WAIT_SHIP / SHIPPED を保留する場合）
  9. 国際トラッキング → スキャンイベント

倉庫フルフィルメントが初めてですか？ WH-DEV テストガイドに従い、倉庫梱包と精算を含む一連の流れを確認してください。

WH-DEV テストを開始 →

エンドポイント案内

トピックパスドキュメント
入庫予告POST .../inbounds/create入庫予告
荷物詳細 / 追跡 / 未引き取りGET .../packages/* · unclaimed-packages荷物
返送POST/GET .../returns · confirm/cancel返送
拠点GET .../locations拠点
付加価値サービスGET .../value-added-servicesVAS
サービス申請POST/GET .../service-requests · confirmサービス申請
配送チャネルGET .../shipping/channels配送チャネル
送料見積もりPOST .../shipping/quotes送料見積もり
作成 / 支払い / キャンセル / インターセプトPOST .../shipments/create · {id}/pay · {id}/cancel · {id}/intercept出荷
出荷一覧GET .../shipments出荷 · 一覧
出荷詳細GET .../shipments/{id}出荷 · 詳細
国際トラッキングGET .../shipments/{id}/tracking追跡
ウォレット残高GET /v1/fulfillment/balance残高
応答フィールド—フルフィルメント応答モデル
商品属性GET .../item-attributes送料見積もり

倉庫モードの調達

/v1/orders/* のパスは変わりません。Gateway が HIOBuy へ転送します。商品 API は引き続き各マーケットプレイスを直接呼び出します。

国内追跡：注文物流追跡（倉庫モードでは Gateway がプロキシ）。

ライフサイクル状態図 {#lifecycle}

状態遷移は 荷物、出荷、返送 を参照してください。

エラー

FULFILLMENT_MODE_NOT_SUPPORTED、SHIPMENT_CREATE_EXCEPTION、SHIPMENT_CREATE_FAILED、PARCEL_NOT_FOUND、EXTERNAL_ORDER_ID_ALREADY_EXISTS、SHIPMENT_NOT_READY_FOR_PAYMENT、SHIPMENT_ALREADY_PAID、INSUFFICIENT_BALANCE、NOT_FOUND（SHIPMENT_NOT_EXISTS）、インターセプト関連（SHIPMENT_NOT_FOUND、SHIPMENT_NOT_INTERCEPTABLE、SHIPMENT_INTERCEPTION_ALREADY_REQUESTED）— エラー と 出荷 を参照してください。

Get Support

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

Email support