バッチ dispatch（consolidation）

本ドキュメントでは、Zonos GraphQL API を使って Japan Post の 後納 dispatch batch を作成する 3 段階のフローを説明します：consolidation を open し、n 件の shipment を attach し、close して Japan Post の dispatch slip（manifest document）を受け取ります。

このフローを使うタイミング 

Japan Post の後納制度（後納）を使うと、マーチャントは荷物を持ち込むたびに個別に支払うのではなく、1 日分の配送料金を営業終了時に 1 回の取引でまとめて精算できます。マーチャントは、最大 250 件の shipment をカバーする 1 枚の dispatch slip（差出票）とともに、その日の荷物すべてを郵便局へ持ち込みます。郵便料金は、あらかじめ登録された Later Pay Number に請求されます。

個々の Japan Post ラベルで発送し、窓口で荷物ごとに支払っている場合は、このフローは不要です — consolidation を使わず、single-shipment chain を直接呼び出してください。

概要 

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)

batch に shipment を attach する方法は 2 つあります。ご自身の integration に合う方を使用してください（両方を組み合わせても構いません）：

• ラベル作成時に attach する — Step 1 の consolidation ID を、shipmentConsolidationId フィールド経由で各 shipmentCreateWorkflow 呼び出しに渡します。
• 既存の shipment を ID で attach する — shipmentConsolidationCreate（batch を seed する場合）または shipmentConsolidationUpdate（open している batch に追加する場合）で shipmentIds を渡します。各 shipment には、あらかじめ Japan Post のラベルが作成済みである必要があります。

どちらの方法でも、各ラベルはあなたの Later Pay Number が埋め込まれた状態で作成されるため、Step 3 で batch を close するときに Japan Post がその dispatch slip への記載を受け入れます。

1 つの mutation ではなく複数回に分けて呼び出す理由: Step 2.1、2.2、…、2.n はマーチャントの営業時間全体にわたって発生します — 注文が入るたびにラベルが印刷され、荷物が梱包されます。single-shipment chain のように 1 回の round trip では完結できません。consolidation を open してから close するまでには、数時間の gap があります。

前提条件 

特定の Verified Account でこのフローを使用するには、あらかじめ以下が必要です:

• account に Japan Post の後納 Later Pay Number（後納お客様番号）が保存されていること — 1111111111-222222-3333333333-444444 のようなハイフン区切りの値です。Step 1 の shipmentConsolidationCreate で accountNumber として渡します。
• API key が SHIPMENT_WRITE、および per-shipment workflow に必要な標準スコープを保持していること。

エンドポイントと認証 

以下の 3 つの Step はすべて、同一の endpoint に送る GraphQL operations です。headers に渡す内容は setup によって異なります — 該当する tab を選んでください。

URL:

https://api.zonos.com/graphql

ヘッダー:

credentialToken: {{YOUR_API_TOKEN}}

リクエスト例 

consolidation を open する example です — mutation、variables、response をそのままコピーして調整できます。これはフローを開始する batch 固有の呼び出しです。shipment の attach（Step 2）は single-shipment example を再利用し、batch の close（Step 3）で manifest document が返されます。各 field は以下の Step でそれぞれ説明します。

Step 1: shipmentConsolidationCreate 

consolidation を open します。carrier code によって batch は Japan Post に固定され、member となる全 shipment は Japan Post の service level を使用する必要があります。すでにラベル済みの shipment があれば、その ID を shipmentIds で渡して batch を seed してください。なければ空の batch を作成し、Step 2 で shipment を attach してください。

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
    }
  }
}

Response:

{
  "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...）を保持しておいてください — これ以降すべての Step で使用します。status は Step 3 まで OPEN のままです。

Step 2: shipment の attach 

その日に発送する荷物ごとに、single-shipment workflow のチェーン全体を実行して shipment とそのラベルを作成します。その後、以下いずれかの方法で shipment を batch に attach します。

Option A: ラベル作成時に attach する

チェーンの最後の shipmentCreateWorkflow Step で consolidation ID を渡します。それより前の mutation はすべて single-shipment workflow と同一です。

shipmentCreateWorkflow の関連 field:

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

Option B: 既存の shipment を ID で attach する

shipment がすでに作成・ラベル済みであれば、shipmentConsolidationUpdate の shipmentIds で open 中の batch に追加します:

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

shipment を追加している間は input から status を外しておいてください — batch は OPEN のままになります。各 shipment は、Step 3 で batch を close する前に、Japan Post の service level とラベル（tracking number）を持っている必要があります。

attach がラベルに与える影響

どちらの方法を使っても、Japan Post の shipment が consolidation の一員である場合:

• shipment は通常どおり tracking number を持ちます。
• 配送ラベルの PDF には 顧客用・郵便局用の受領書は含まれません。これらの受領書は Step 3 まで保留され、batch 全体の dispatch document にまとめて収録されます。
• shipment は consolidation に紐づけられ、shipmentConsolidation(id: ...) で再度 query してメンバーを確認できます。

その日の batch に含める荷物ごとに、この Step を繰り返してください。1 つの consolidation につき最大 250 件の shipment までです — それを超える batch を close しようとすると、Japan Post への呼び出しが行われる前に、明確な validation エラーになります。

close する前に batch の内容を確認することもできます:

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

すべての shipment に tracking number が表示されているはずです。表示されていないものがあれば、そのラベルは作成されていません — close する前に対応してください。status は Step 3 で consolidation を close するまで OPEN のままです。

Step 3: shipmentConsolidationUpdate(status: CLOSED) 

batch を close します。この呼び出しによって、全メンバーの tracking number をカバーする後納の dispatch slip の生成が Japan Post に依頼され、生成された PDF が consolidation に添付されます。

この GraphQL operation は、その意図（batch を close すること）を表すため 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. consolidation が検証されます: shipment 数が 250 件以下であること、全メンバーが tracking number を持っていることが確認されます。tracking number を持たない shipment（ラベルが作成されなかった shipment）があれば、リクエストは reject されます。
2. 全メンバーの tracking number をカバーする後納の dispatch slip の生成が Japan Post に依頼されます。
3. slip の PDF を取得している間、status は一時的に MANIFEST_CREATED になり、document が添付されると CLOSED になります。
4. dispatch slip の PDF（slip 本体と全メンバーの顧客用・郵便局用受領書を含む 1 つのファイル）が、documentType: MANIFEST_DOCUMENT の CustomsDocument として consolidation に添付されます。

Response:

{
  "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"
        }
      ]
    }
  }
}

document の取得

dispatch slip は、documentType: MANIFEST_DOCUMENT の CustomsDocument として consolidation に直接添付されます — 上記の close response から fileUrl を取得するか、後からいつでも query できます:

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

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

• 1 ページ目: 後納の dispatch slip（後納差出票）— これを郵便局に渡します。batch 内のすべての shipment が、使用したサービスレベルにかかわらずここに記載されます。
• 2 ページ目以降: 各荷物の顧客用・郵便局用受領書 — 1 枚は荷物に貼付し、もう 1 枚は郵便局が保管します。これらのページは追跡番号に紐づいているため、EMS と International Parcel の shipment のみを対象に生成されます。

印刷したら、荷物・dispatch slip・受領書を 1 回で郵便局に持ち込んでください。Japan Post は、課金期間の終了時に Later Pay Number へ請求します。

1 ページ目に記載されている shipment に receipt ページがない場合、それは shipment が欠落しているわけではありません。 Small Packet（小形包装物）は追跡対象の Japan Post サービスではないため、1 ページ目には記載されますが、2 ページ目以降の receipt は生成されません。5 件の parcel からなる batch では、1 ページ目に 5 件すべてが記載され、receipt ページは EMS と Parcel の分のみ生成されるという結果が正常に起こり得ます。また、Small Packet のみの batch では 1 ページ目のみが生成され、それ以降のページは一切生成されません。これは想定された Japan Post の挙動であり、ラベル作成の失敗や manifest 呼び出しの失敗ではありません。サービスレベルごとに別の consolidation を開く必要はありません。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 日の終わりにまとめて batch 処理したい場合は、consolidation ID を指定せずにその日のラベルを作成し、すべての shipmentIds を指定して一度だけ consolidation を open する（または shipmentConsolidationUpdate で少しずつ追加する）方法もあります。同じ呼び出しの中で、あるいは後続の呼び出しで close してください。

複数の事業部門・課金アカウントにまたがって発送する場合は、アカウントごとに別々の consolidation を実行してください — 各 shipmentConsolidationCreate で異なる accountNumber を渡し、それに応じて shipment を振り分けます。1 日に 250 件を超える荷物を発送する場合は、2 つ目の consolidation を open してください。

エラー処理 

Validation エラー（Japan Post への呼び出し前に検出されるもの）

• accountNumber の format 不正 — consolidation が保存される前に、Step 1（shipmentConsolidationCreate）で reject されます。エラーメッセージには、問題のある segment が示されます。
• shipment が 250 件を超えている — Japan Post への呼び出しが行われる前に、Step 3 で reject されます。
• member の shipment に tracking number がない — Step 3 で reject されます。これは、以前のラベル作成が静かに失敗していたことを意味します — shipment(id: ...) { trackingDetails } で該当の shipment を確認してください。
• consolidation に後納番号が設定されていない — Step 3 で reject されます。shipmentConsolidationCreate で accountNumber を渡すか、Japan Post の carrier account に default の account number を保存してください。

Japan Post API のエラー

Japan Post が dispatch slip のリクエストを reject した場合、close の mutation は carrier のエラーコードとメッセージを GraphQL エラーとして返します。よくあるものは次のとおりです:

再試行

close の呼び出しが、Japan Post が dispatch slip のリクエストを受け付けた 後（PDF 取得中）に失敗した場合、shipmentConsolidationUpdate(status: CLOSED) を再試行しても問題ありません — platform は carrier への呼び出しをスキップし、document の取得と添付だけを再試行します。

close が、Japan Post がリクエストを受け付ける 前（validation エラー、E0xx、network timeout）に失敗した場合は、状態は何も変化していません — 根本原因を修正してから再試行してください。