バッチ差出（コンソリデーション）

本ドキュメントでは、Zonos GraphQL API を使って Japan Post の 後納差出バッチ を作成する 3 段階のフローを説明します。コンソリデーションを作成（オープン）し、そこに n 件の出荷を追加してから、クローズして Japan Post の差出票（マニフェストドキュメント）を受け取ります。

米国向けと EU 向けの出荷も、同じ方法でバッチにまとめられます。EU 向けの出荷では、EU への発送の説明に従って、各出荷に IOSS と VAT のフィールドを設定してください。

このフローを使う場面 

Japan Post の後納制度を利用すると、マーチャントは荷物を差し出すたびに個別に支払うのではなく、1 日分の送料を営業終了時に 1 回の取引でまとめて精算できます。マーチャントは、最大 250 件の出荷を記載した 1 枚の 差出票 とともに、その日の荷物をすべて郵便局へ持ち込みます。郵便料金は、事前に登録された Later Pay Number（後納お客様番号）宛てに請求されます。

Japan Post のラベルを 1 件ずつ発行し、窓口で荷物ごとに支払っている場合、このフローは不要です。コンソリデーションを使わずに、単一出荷のチェーンを直接呼び出してください。

概要 

1. shipmentConsolidationCreate            → open the batch (returns consolidation ID)
2. Attach shipments × n                   → create each shipment + label, attached to the batch
3. shipmentConsolidationUpdate(CLOSED)    → close the batch (returns the dispatch slip)

バッチに出荷を追加する方法は 2 つあります。インテグレーションに合う方法を選んでください（併用も可能です）。

• ラベル作成時に追加する — ステップ 1 で取得したコンソリデーション ID を、shipmentConsolidationId フィールドで各 shipmentCreateWorkflow の呼び出しに渡します。
• 既存の出荷を ID で追加する — shipmentConsolidationCreate（バッチの初期メンバーとして登録する場合）または shipmentConsolidationUpdate（オープン中のバッチに追加する場合）で shipmentIds を渡します。各出荷には、Japan Post のラベルが作成済みである必要があります。

どちらの方法でも、各ラベルにはお客様の Later Pay Number が埋め込まれて作成されるため、ステップ 3 でバッチをクローズした際に、Japan Post がその出荷を差出票に受け入れます。

1 つの mutation にまとめず、呼び出しを分けるのはなぜですか？ ステップ 2.1、2.2、…、2.n はマーチャントの 1 日を通して行われます。注文が入るたびにラベルが印刷され、荷物が梱包されるためです。単一出荷のチェーンのように、バッチを 1 回のラウンドトリップで処理することはできません。コンソリデーションをオープンしてからクローズするまでに、数時間の間隔があります。

前提条件 

Verified Account でこのフローを利用するには、次の条件を満たしている必要があります。

• アカウントに Japan Post の後納お客様番号（Later Pay Number）が保存されていること。これは 1111111111-222222-3333333333-444444 のようなハイフン区切りの値です。ステップ 1 の shipmentConsolidationCreate で accountNumber として渡します。
• API キーが SHIPMENT_WRITE に加え、出荷ごとのワークフローに必要な標準スコープを持っていること。

エンドポイントと認証 

以下の 3 つのステップはすべて、同じエンドポイントに送信する GraphQL オペレーションです。ヘッダーに渡す内容はご利用形態によって異なります。該当するタブを選択してください。

URL:

https://api.zonos.com/graphql

ヘッダー:

credentialToken: {{YOUR_API_TOKEN}}

リクエスト例 

コンソリデーションをオープンする例です。mutation、変数、レスポンスをコピーして、用途に合わせて調整できます。これはフローを開始する、バッチ固有の呼び出しです。出荷の追加（ステップ 2）では単一出荷の例をそのまま利用し、バッチのクローズ（ステップ 3）ではマニフェストドキュメントが返されます。各フィールドの詳細は、以下の各ステップで説明します。

ステップ 1: shipmentConsolidationCreate 

コンソリデーションをオープンします。キャリアコードによってバッチは Japan Post に固定されるため、メンバーとなるすべての出荷で Japan Post のサービスレベルを使用する必要があります。ラベル作成済みの出荷がすでにある場合は、その ID を shipmentIds で渡してバッチの初期メンバーとして登録できます。ない場合は空のバッチを作成し、ステップ 2 で出荷を追加してください。

Mutation:

mutation {
  shipmentConsolidationCreate(
    input: {
      carrierCode: JAPAN_POST
      accountNumber: "1111111111-222222-3333333333-444444"
      name: "Tokyo dispatch — 2026-05-01"
      externalId: "merchant-batch-20260501-001"
      shipmentIds: ["shipment_01hxa...", "shipment_01hxb..."]
    }
  ) {
    id
    status
    accountNumber
    carrierCode
    shipments {
      id
    }
  }
}

レスポンス:

{
  "data": {
    "shipmentConsolidationCreate": {
      "id": "shco_01hjk...",
      "status": "OPEN",
      "accountNumber": "1111111111-222222-3333333333-444444",
      "carrierCode": "JAPAN_POST",
      "shipments": [
        { "id": "shipment_01hxa..." },
        { "id": "shipment_01hxb..." }
      ]
    }
  }
}

id（例: shco_01HJK...）を控えておいてください。以降のすべての手順で使用します。status はステップ 3 まで OPEN のままです。

ステップ 2: 出荷を追加する 

その日に発送する荷物ごとに、単一出荷のワークフローのチェーン全体を実行して、出荷とそのラベルを作成します。その後、以下のいずれかの方法で出荷をバッチに追加します。

オプション A: ラベル作成時に追加する

チェーンの最後の shipmentCreateWorkflow ステップで、コンソリデーション ID を渡します。それより前の mutation は、すべて単一出荷のワークフローと同じです。

shipmentCreateWorkflow の関連フィールド:

shipmentCreateWorkflow(
  input: {
    serviceLevel: "japan_post.air.ems_merchandise"
    shipmentConsolidationId: "shco_01hjk..."
    generateLabel: true
  }
) {
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      labelImage
    }
  }
}

オプション B: 既存の出荷を ID で追加する

出荷がすでに作成され、ラベルも発行済みの場合は、shipmentConsolidationUpdate の shipmentIds を使ってオープン中のバッチに追加します。

mutation {
  shipmentConsolidationUpdate(
    input: {
      id: "shco_01hjk..."
      shipmentIds: ["shipment_01hxd...", "shipment_01hxe..."]
    }
  ) {
    id
    status
    shipments {
      id
    }
  }
}

出荷を追加している間は、input に status を含めないでください。バッチは OPEN のまま維持されます。各出荷は、ステップ 3 でバッチをクローズする前に、Japan Post のサービスレベルを使用し、ラベル（追跡番号）を持っている必要があります。

追加がラベルに与える影響

どちらの方法でも、Japan Post の出荷がコンソリデーションに含まれる場合は次のようになります。

• 出荷には通常どおり追跡番号が付与されます。
• 配送ラベルの PDF には、お客様控え・郵便局控えの受領証が含まれません。これらの受領証はステップ 3 に持ち越され、バッチ全体の差出票ドキュメントにまとめて収録されます。
• 出荷はコンソリデーションに紐付けられます。shipmentConsolidation(id: ...) を再度クエリすると、メンバーを確認できます。

その日のバッチに含めるすべての荷物について、このステップを繰り返します。1 つのコンソリデーションに含められる出荷は最大 250 件 です。これを超えるバッチをクローズしようとすると、Japan Post への呼び出しが行われる前に、わかりやすい検証エラーで失敗します。

クローズする前に、バッチの内容を確認することもできます。

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    shipments {
      id
      trackingDetails {
        number
      }
    }
  }
}

すべての出荷に追跡番号が表示されるはずです。表示されない出荷がある場合、そのラベルは作成されていません。クローズする前に解決してください。status は、ステップ 3 でコンソリデーションをクローズするまで OPEN のままです。

ステップ 3: shipmentConsolidationUpdate(status: CLOSED) 

バッチをクローズします。この呼び出しで、すべてのメンバーの追跡番号を記載した後納差出票の作成を Japan Post に依頼し、作成された PDF をコンソリデーションに添付します。

この GraphQL オペレーションは、バッチをクローズするという目的を表すために CloseConsolidation という名前になっています。実際には、status: CLOSED を指定して shipmentConsolidationUpdate mutation を実行します。

Mutation:

mutation CloseConsolidation {
  shipmentConsolidationUpdate(input: { id: "shco_01hjk...", status: CLOSED }) {
    id
    status
    statusTransitions {
      status
      changedAt
      note
    }
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

CLOSED をリクエストすると、次の処理が行われます。

1. コンソリデーションが検証されます。出荷が 250 件以下であること、およびすべてのメンバーに追跡番号があることが条件です。追跡番号のない出荷（ラベルが作成されていない出荷）がある場合、呼び出しは拒否されます。
2. すべてのメンバーの追跡番号を記載した後納差出票の作成を、Japan Post に依頼します。
3. 差出票の PDF を取得している間、ステータスは一時的に MANIFEST_CREATED になり、ドキュメントが添付されると CLOSED になります。
4. 差出票の PDF（差出票本体と、すべてのメンバーのお客様控え・郵便局控えの受領証を含む 1 つのファイル）が、documentType: MANIFEST_DOCUMENT の CustomsDocument としてコンソリデーションに添付されます。

レスポンス:

{
  "data": {
    "shipmentConsolidationUpdate": {
      "id": "shco_01hjk...",
      "status": "CLOSED",
      "statusTransitions": [
        {
          "status": "OPEN",
          "changedAt": "2026-05-01T08:00:00Z",
          "note": "Shipment batch created"
        },
        {
          "status": "MANIFEST_CREATED",
          "changedAt": "2026-05-01T17:30:12Z",
          "note": "Dispatch slip created with Japan Post"
        },
        {
          "status": "CLOSED",
          "changedAt": "2026-05-01T17:30:14Z",
          "note": "Dispatch slip downloaded and uploaded"
        }
      ],
      "customsDocuments": [
        {
          "documentType": "MANIFEST_DOCUMENT",
          "fileUrl": "https://customs-docs.zonos.com/.../japanpost-dispatch-slip.pdf"
        }
      ]
    }
  }
}

ドキュメントの取得

差出票は、documentType: MANIFEST_DOCUMENT の CustomsDocument として、コンソリデーションに直接添付されます。上記のクローズ時のレスポンスから fileUrl を取得するか、後からいつでもクエリで取得できます。

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

fileUrl の PDF を印刷してください。内容は次のとおりです。

• 1 ページ目: 後納差出票。郵便局に提出します。使用したサービスレベルにかかわらず、バッチ内のすべての出荷がここに記載されます。
• 2 ページ目以降: お客様控え・郵便局控えの受領証。一方は各荷物に貼付し、もう一方は郵便局が保管します。これらのページは追跡番号に紐付いているため、EMS と国際小包の出荷に対してのみ 作成されます。

印刷したら、荷物・差出票・受領証をまとめて 1 回で郵便局に持ち込んでください。Japan Post は、請求期間の終了時に Later Pay Number 宛てに料金を請求します。

1 ページ目に記載された出荷に受領証ページがなくても、出荷が欠落しているわけではありません。 小形包装物（Small Packet）は追跡サービスの対象外のため、1 ページ目には記載されますが、2 ページ目以降の受領証は作成されません。たとえば 5 件の荷物のバッチで、1 ページ目に 5 件すべてが記載され、受領証ページは EMS と小包の分だけ、ということは正常に起こり得ます。また、小形包装物だけのバッチでは、1 ページ目のみが作成され、2 ページ目以降は一切作成されません。これは Japan Post の想定どおりの動作であり、ラベル作成やマニフェスト呼び出しの失敗ではありません。サービスレベルごとに別のコンソリデーションをオープンする必要はありません。2026 年 8 月に Japan Post に確認済みです。

全体の流れ 

50 件の Japan Post の荷物を発送するマーチャントの、典型的な 1 日の例は次のとおりです。

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → Print PDF

1 日の終わりにまとめてバッチ処理したい場合は、コンソリデーション ID を指定せずにその日のラベルを作成しておき、すべての出荷を shipmentIds で指定してコンソリデーションを一度にオープンします（または shipmentConsolidationUpdate で数回に分けて追加します）。クローズは同じ呼び出しでも、後続の呼び出しでも行えます。

複数の事業部門や請求アカウントで発送する場合は、アカウントごとに別のコンソリデーションを使用してください。shipmentConsolidationCreate ごとに異なる accountNumber を渡し、出荷をそれぞれに振り分けます。1 日に 250 件を超える荷物を発送する場合は、2 つ目のコンソリデーションをオープンしてください。

エラー処理 

検証エラー（Japan Post への呼び出し前に検出）

• accountNumber の形式が不正 — コンソリデーションが保存される前に、ステップ 1（shipmentConsolidationCreate）で拒否されます。エラーメッセージで、問題のある区切りが示されます。
• 出荷が 250 件を超える — Japan Post への呼び出しが行われる前に、ステップ 3 で拒否されます。
• メンバーの出荷に追跡番号がない — ステップ 3 で拒否されます。以前のラベル作成がエラーを出さずに失敗していたことを意味します。shipment(id: ...) { trackingDetails } で該当の出荷を調査してください。
• コンソリデーションに後納お客様番号が設定されていない — ステップ 3 で拒否されます。shipmentConsolidationCreate で accountNumber を渡すか、Japan Post のキャリアアカウントにデフォルトのアカウント番号を保存してください。

Japan Post API のエラー

Japan Post が差出票のリクエストを拒否した場合、クローズの mutation はキャリアのエラーコードとメッセージを GraphQL エラーとして返します。主なエラーは次のとおりです。

再試行

Japan Post が差出票のリクエストを受け付けた 後（PDF の取得中など）にクローズの呼び出しが失敗した場合は、shipmentConsolidationUpdate(status: CLOSED) を安全に再試行できます。プラットフォームはキャリアへの呼び出しをスキップし、ドキュメントの取得と添付のみを再試行します。

Japan Post がリクエストを受け付ける 前（検証エラー、E0xx、ネットワークのタイムアウト）にクローズが失敗した場合、状態は何も変わっていません。根本原因を解決してから再試行してください。