Batch dispatch (consolidation)

本 document は Zonos GraphQL API 経由で Japan Post deferred-payment dispatch batch を作成する 3 stage flow を説明: consolidation を open、n shipment を attach、close して Japan Post dispatch slip（manifest document）を受信。

この flow を使用する場合 

Japan Post deferred-payment program（後納）により merchant は drop-off ごとではなく end-of-day に 1 transaction で daily shipping bill を settle 可能。merchant は 250 shipment までをカバーする 1 枚の dispatch slip（差出票）とともに 1 日分の parcel を post office に持参。postage は pre-registered Later Pay Number に invoice。

individual Japan Post label を ship し counter で parcel-by-parcel 支払いする場合この flow は不要 — consolidation なしで single-shipment chain を直接 call。

概要 

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 に合う方を使用（または mix）:

• Attach at label-creation time — step 1 の consolidation ID を shipmentConsolidationId field 経由で各 shipmentCreateWorkflow call に thread。
• Attach existing shipments by ID — shipmentConsolidationCreate（batch seed）または shipmentConsolidationUpdate（open batch に add）で shipmentIds を pass。各 shipment は既に Japan Post label 必須。

いずれも各 label は Later Pay Number embedded で作成され step 3 で batch close 時 dispatch slip に accept されます。

1 mutation ではなく separate calls の理由: Step 2.1、2.2、...、2.n は merchant の 1 日を通じて発生 — order 到着に伴い label 印刷・parcel seal。single-shipment chain のような single round-trip 不可: consolidation open と close の間に multi-hour gap。

前提条件 

指定 Verified Account でこの flow が function する前に:

• account に Japan Post deferred-payment Later Pay Number（後納お客様番号）保存必須 — 1111111111-222222-3333333333-444444 形式。shipmentConsolidationCreate の accountNumber で pass（Step 1）。
• API key に SHIPMENT_WRITE および per-shipment workflow に必要な standard scopes 必須。

Endpoint and authentication 

以下 3 step は同一 endpoint への GraphQL operations。headers は setup により異なる — tab を選択。

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Example request 

consolidation open の copy-and-adapt example — mutation、variables、response。flow 開始の batch-specific call。shipment attach（Step 2）は single-shipment example を reuse、batch close（Step 3）で manifest document を return。各 field は以下 step で breakdown。

Step 1: shipmentConsolidationCreate 

consolidation を open。carrier code が batch を Japan Post に lock — 全 member shipment は Japan Post service level 必須。labeled shipment 準備済みなら shipmentIds で batch seed — そうでなければ empty で create し step 2 で 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 3 まで status は OPEN。

Step 2: shipment attach 

本日 ship する各 parcel について full chained single-shipment workflow を実行して shipment と label を create。以下いずれかの方法で batch に attach。

Option A: label 作成時 attach

chain 最終 shipmentCreateWorkflow step で consolidation ID を pass。chain 内 preceding mutations は single-shipment workflow と同一。

shipmentCreateWorkflow の relevant fields:

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 が既に created かつ labeled なら shipmentConsolidationUpdate の shipmentIds で open batch に add:

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

shipment 追加中は input から status を omit — batch は OPEN のまま。Step 3 close 前に各 shipment は Japan Post service level と label（tracking number）必須。

attachment が label に意味すること

いずれの option でも Japan Post shipment が consolidation の一部の場合:

• shipment は通常通り tracking number を持つ。
• shipping-label PDF に customer/post-office receipt copies は含まれない。receipts は Step 3 に defer され whole batch の dispatch-slip document に bundle。
• shipment は consolidation に associated — shipmentConsolidation(id: ...) で re-query して members 確認可能。

1 日 batch の各 parcel でこの step を repeat。consolidation あたり最大 250 shipment — 超過 close は Japan Post call 前に validation error。

close 前に batch contents を verify 可能:

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

全 shipment に tracking number 表示必須。なければ label 未作成 — close 前に resolve。Step 3 close まで status は OPEN。

Step 3: shipmentConsolidationUpdate(status: CLOSED) 

batch を close。全 member tracking number をカバーする deferred-payment dispatch slip を Japan Post に generate 依頼し resulting PDF を consolidation に attach する call。

GraphQL operation 名 CloseConsolidation — batch close intent。status: CLOSED で shipmentConsolidationUpdate mutation を実行。

Mutation:

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

CLOSED request 時:

1. consolidation validate: ≤250 shipment、全 member に tracking number 必須。tracking number 欠如（label 未作成）なら reject。
2. Japan Post に全 member tracking number をカバーする deferred-payment dispatch slip 生成を依頼。
3. slip PDF fetch 中 MANIFEST_CREATED、document attach 後 CLOSED。
4. dispatch slip PDF（slip + 全 member customer/post-office receipts を含む 1 file）を documentType: MANIFEST_DOCUMENT の CustomsDocument として attach。

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 に直接 attach — 上記 close response の fileUrl または後から query:

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

fileUrl の PDF を print。内容:

• Page 1: deferred-payment dispatch slip — post office に渡す。
• Pages 2+: 各 parcel の customer/post-office receipts — 1 枚 parcel に staple、もう 1 枚 post office が保持。

print 後 parcel + dispatch slip + receipts を 1 trip で post office へ。Japan Post は billing period 終了時 Later Pay Number に invoice。

全体像 

50 Japan Post parcel を ship する merchant の代表日:

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

end-of-day batch を希望？consolidation ID なしで label 作成後、全 shipmentIds で 1 回 consolidation open（または shipmentConsolidationUpdate で chunk add）し同一または follow-up call で close。

複数 business unit / billing account なら account ごと separate consolidation — 各 shipmentConsolidationCreate で異なる accountNumber を pass し shipment を route。1 日 250 parcel 超？2 つ目 consolidation を open。

Error handling 

Validation errors（Japan Post call 前）

• accountNumber malformed — Step 1（shipmentConsolidationCreate）で consolidation save 前 reject。error message が offending segment を特定。
• >250 shipments — Step 3、Japan Post call 前 reject。
• Member shipment missing tracking number — Step 3 reject。label create が silently failed — shipment(id: ...) { trackingDetails } で調査。
• consolidation に deferred-payment number 未設定 — Step 3 reject。shipmentConsolidationCreate で accountNumber pass または Japan Post carrier account に default save。

Japan Post API errors

Japan Post が dispatch slip request を reject した場合 close mutation が carrier error code/message を GraphQL error として surface。最も common:

Retries

close call が Japan Post dispatch slip accept 後（PDF retrieval 中）fail した場合 shipmentConsolidationUpdate(status: CLOSED) retry は safe — platform は carrier call を skip し document fetch/attach を re-attempt。

close が Japan Post accept 前（validation error、E0xx、network timeout）fail なら state 変更なし — root cause を fix して retry。