単一出荷の作成

CreateDeclarationShipment は、6 つの *Workflow mutation を 1 つの GraphQL リクエストに連結します。各ステップは前のステップで提供されたデータを基に構築され、すべてがまとめて送信されることで、1 回のラウンドトリップで完全な出荷を作成できます。

partyCreateWorkflow            → describe origin + destination parties
itemCreateWorkflow             → describe the line items
cartonsCreateWorkflow          → describe the physical packaging
shipmentRatingCreateWorkflow   → record the carrier rate quote
landedCostCalculateWorkflow    → calculate duties / taxes / fees
shipmentCreateWorkflow         → create the shipment + label

Workflow mutation は 連鎖する ように設計されています。ステップ間で ID を受け渡す必要はなく、ステップごとに個別のリクエストを送信する必要もありません。ドキュメント全体を送信すれば、最終的な Shipment が返されます。

最終ステップの serviceLevel が Japan Post のサービスレベル（japan_post.*）である場合、Zonos はお客様の Verified Account の Later Pay Number を使用して代わりに Japan Post Label API（コード 52）を呼び出し、ラベルとトラッキング番号を生成し、Declaration ID を作成してそれらを紐付けます — これらはすべて最終の shipmentCreateWorkflow ステップ内で行われます。

なぜ 1 つの mutation にまとめるのか？ 各ステップは前のステップに依存しています（landed cost の計算には items と parties が必要、ラベルの生成にはすべてが必要です）。これらを 1 つの GraphQL ドキュメントにまとめることで、データの整合性を保ちながら、5 回分の追加のラウンドトリップを回避できます。

エンドポイントと認証 

このチェーンのリクエストはすべて同じエンドポイントを使用します。ヘッダーに渡す内容はセットアップによって異なります — 該当するタブを選択してください。

URL:

https://api.zonos.com/graphql

ヘッダー:

credentialToken: {{YOUR_API_TOKEN}}

リクエスト例 

コピーして調整できる、完全な CreateDeclarationShipment リクエストです — mutation、その variables、および response を、米国向けに DDP で発送する単一の Japan Post 荷物の例として示します。各入力の詳細は、以下のステップごとの解説セクションで説明します。

ステップごとの解説 

以下の各テーブルの Status 列では、次の用語を使用しています:

• 必須 — これがないとリクエストは失敗します。
• ラベルに必須 — GraphQL スキーマ上は任意ですが、有効な Japan Post 米国向けラベルを生成するには必要です。
• 条件付き — 他のフィールドに応じて必要になります（本文中に記載）。
• 推奨 — 任意ですが、正確な関税・税金の算出に影響します。
• 任意 — 不要です。

1. partyCreateWorkflow

出荷に関わる パーティ を作成します — 最低限、ORIGIN（出荷元）と DESTINATION（購入者 / consignee）が必要です。

ペイロードの例:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

レスポンスには、作成された Party の ID と解決済みの address フィールドが返されます。

2. itemCreateWorkflow

出荷を構成する line item（品目） を作成します。これらは commercial invoice に記載され、landed cost の計算に使用される SKU です。

HS code、country of origin、amount の 3 つが、ステップ 5 の関税・税金の算出結果に最も大きく影響するフィールドです。

3. cartonsCreateWorkflow

物理的な包装 — 品目を収める箱、ポリバッグ、または封筒を作成します。

各 carton は、ステップ 6 の配送業者ラベル上で 1 つの荷物になります。carton が複数ある場合 → carton ごとに 1 つのトラッキング番号を持つ複数個口の出荷になります。

4. shipmentRatingCreateWorkflow

マーチャントが購入者に請求する配送料の レート見積もり を記録します。

これは、チェックアウト時に購入者に提示されたレートです。この値は landed cost の計算における「shipping」小計として使用され、正しい CIF 価格に基づいて関税と税金が算出されます。

5. landedCostCalculateWorkflow

関税・税金・手数料の計算 を配送先の国に対して実行します。直前のステップで作成した items、parties、配送料を使用します。

レスポンスには amountSubtotals（duties、taxes、fees、shipping、landedCostTotal）が含まれます — これらはチェックアウト時に購入者へ表示し、commercial invoice に印刷する数値です。

6. shipmentCreateWorkflow

最終ステップです — Shipment エンティティを作成し、配送業者ラベル を生成し、（任意で）commercial invoice / packing slip も生成します。

Japan Post の Verified Account の場合、このステップで Zonos が代わりに Japan Post Label API（コード 52）を呼び出し、Later Pay Number を挿入し、Declaration ID を作成して、Japan Post から返されるトラッキング番号に Declaration ID を紐付けます。

主なフィールド:

contentsType については、Verified Account のトラフィックで最も一般的な値は ECOMMERCE_GOODS（消費者への販売、BtoC）と COMMERCIAL_GOODS（企業間の販売、BtoB）の 2 つです。これらは、Zonos が Japan Post のラベル呼び出しで送信する pkgType を決定するため、この選択はラベルだけでなく customs declaration に印刷される内容も変わります。

nonDelivery サブ入力

荷物を配達できない場合（consignee による受取拒否、国境での拒否、宛先不明による配達不能など）に Japan Post が取るべき対応を指定します。

option は、これら 4 つの値のみを受け付けます。RETURN という値は存在しません — 荷物が いつ 返送されるかは RETURN_AFTER_RETENTION または RETURN_IMMEDIATELY で指定します。

API では 2 つの return バリアントを個別に公開していますが、Dashboard の Return オプションは両方をカバーします。

transportMethod は AIR または MOST_ECONOMICAL を受け付け、返送される荷物の輸送方法を設定します。これは 2 つの RETURN_* オプションにのみ適用されます — Dashboard では、Return が選択されている場合にのみ対応する Return method フィールドが表示されます。

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

Dashboard の Create label ダイアログにある If undeliverable ピッカーも同じフィールドに書き込むため、Dashboard で作成したラベルと API 経由で作成したラベルは同じ挙動になります。

references サブ入力

これらのフィールドは、配送業者ラベルや commercial invoice に印刷されます。consignee や税関当局が確認する必要のある PO 番号、license 番号、自由記述の remarks を表示するために使用します。

レスポンス

返される Shipment の中で注目すべきフィールドは次のとおりです:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number は Japan Post のトラッキング番号です。

label オブジェクトは、ラベルを 2 つの方法で返すことができます — ワークフローに合う方（または両方）をリクエストしてください:

必要なフィールドのみを選択してください。url をリクエストするとレスポンスを小さく保てます。labelImage をリクエストすると、ラベル全体がインラインで返されるため、取得のための 2 回目のラウンドトリップが不要になります。上記の例では url をリクエストしています。

Japan Post サービスレベル 

これらのコードのいずれかを、shipmentRatingCreateWorkflow の serviceLevelCode として渡します。

サービスレベルコードはアンダースコアではなく ドット を使用します。エラーメッセージや内部的な参照ではアンダースコア形式（japan_post_air_parcel）を見かけることがありますが、これは有効な入力ではありません。

航空便

船便

類似サービスの選び方

小型包装物 と 国際航空パケット の比較。 どちらも上限は 2 kg です。japan_post.air.packet は Japan Post の追跡可能な小型包装物サービスです。japan_post.air.small_packet は追跡なしの同等サービスです。軽量な荷物で追跡が必要な場合は japan_post.air.packet を使用してください。

書留バリアント。 書状と印刷物については、書留（registered）版のサービスによって追跡機能が追加されます。japan_post.air.printed_matter と japan_post.air.letter は、それ自体には追跡機能を含みません。

非推奨のコード

japan_post.air.epacket_light は、以前の International e-Packet Light です。Japan Post は 2026 年 6 月 1 日に、このサービスを 国際航空パケット に改称し、対象を全ての国・地域に拡大しました。サービス自体に変更はありません。

旧コードは今も解決されるため、既存の連携はそのまま動作しますが、新規で実装する場合は japan_post.air.packet を使用してください。

輸送モードコード

japan_post.air、japan_post.surface、japan_post.economy_air、japan_post.custom も解決されますが、これらは特定の郵便プロダクトではなく、輸送モードやフォールバックを示すものです。通常の出荷では、上記のサービスコードのいずれかを使用してください。

送信するコードを検証する

認識されない serviceLevelCode は エラーになりません。リクエストは errors 配列を含まない HTTP 200 を返し、serviceLevel は null として返され、shipping が landed cost の合計から抜け落ちます — つまり、レスポンス自体は正しく見えても金額が誤っている状態になります。

合計金額を信頼する前に、必ず shipmentRatingCreateWorkflow.serviceLevel が null でないことを確認してください。

現在のリストは、いつでも次の方法で取得できます:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

このクエリは carrier の ID を受け取ります。carrier コード japan_post を渡すと、エラーなく空のリストが返されます。

エラー処理 

• Validation errors（必須フィールドの欠落、無効な国コードなど）は、標準の GraphQL errors 配列で返され、チェーンの残りの処理は中断されます。
• Japan Post errors（ラベル生成の失敗、無効な address など）は、shipmentCreateWorkflow 上の GraphQL エラーとして返されます。リトライが必要な場合はサポートにお問い合わせください — 推奨される方法は、修正した入力で mutation 全体を再送信することです。

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

このエラーは、実際に問題のあるフィールドではなく variable 全体 の名前を示します。ほとんどの場合、その variable 内の 1 つの enum 値が、その enum のメンバーに含まれていないことを意味します — 最も多いのは nonDelivery.option、contentsType、serviceLevel です。

これは JSON の型の問題では ありません。boolean や number をクオートしても、クオートを外しても解決しません。payload はそこまで到達せず、enum の検証で先に reject されるためです。

問題のあるフィールドを特定するには、その variable 内のすべての enum 値を持つフィールドを、受け入れ可能な値と照合してください:

各 input の完全な enum メンバーは、API reference のタイプページに記載されています。

権限 

各ステップは個別にセキュリティが適用されます。API キーには、チェーン内の各エンティティに対する write スコープ（ITEM_WRITE、CARTON_WRITE、SHIPMENT_RATING_WRITE、LANDED_COST_WRITE、SHIPMENT_WRITE）が必要です。Verified Account の標準的な merchant ロールには、これらすべてが付与されています。

次のステップ 

• Batch dispatch (consolidation) — 1 日分の荷物を、Japan Post の後払い dispatch slip 1 枚にまとめます。