Batch-Versand (Konsolidierung)

Dieses Dokument führt Sie durch den dreistufigen Flow zur Erstellung eines Japan Post-Nachzahlungsversand-Batches über die Zonos GraphQL API: Öffnen Sie eine Konsolidierung, fügen Sie n Sendungen hinzu und schließen Sie sie, um Japans Versandschein (Manifestdokument) zu erhalten.

Wann Sie diesen Flow nutzen sollten 

Das Japan Post-Nachzahlungsprogramm (後納) ermöglicht es einem Händler, seine tägliche Versandrechnung in einer Transaktion am Tagesende abzurechnen, statt pro Paket bei der Abgabe. Der Händler bringt alle Pakete des Tages zur Postfiliale zusammen mit einem Versandschein (差出票), der bis zu 250 Sendungen abdeckt. Die Portogebühr wird der vorgemerkten Later Pay Number des Händlers in Rechnung gestellt.

Wenn Sie einzelne Japan Post-Etiketten versenden und paketweise am Schalter bezahlen, benötigen Sie diesen Flow nicht — rufen Sie die Einzel-Sendungs-Kette direkt ohne Konsolidierung auf.

Übersicht 

1. shipmentConsolidationCreate            → Batch öffnen (gibt Konsolidierungs-ID zurück)
2. Sendungen anhängen × n                 → jede Sendung + Etikett erstellen, an den Batch anhängen
3. shipmentConsolidationUpdate(CLOSED)    → Batch schließen (gibt Versandschein zurück)

Es gibt zwei Möglichkeiten, Sendungen an den Batch anzuhängen — nutzen Sie, was zu Ihrer Integration passt (oder mischen Sie beides):

• Beim Etikettenerstellen anhängen — übergeben Sie die Konsolidierungs-ID aus Schritt 1 in jedem shipmentCreateWorkflow-Aufruf über das Feld shipmentConsolidationId.
• Bestehende Sendungen per ID anhängen — übergeben Sie shipmentIds bei shipmentConsolidationCreate (um den Batch zu befüllen) oder bei shipmentConsolidationUpdate (um zu einem offenen Batch hinzuzufügen). Jede Sendung muss bereits ihr Japan Post-Etikett haben.

So oder so wird jedes Etikett mit Ihrer Later Pay Number erstellt, damit Japan Post es beim Schließen des Batches in Schritt 3 auf den Versandschein aufnehmen kann.

Warum separate Aufrufe statt einer Mutation? Schritte 2.1, 2.2, ..., 2.n finden über den Tag des Händlers verteilt statt — Etiketten werden gedruckt und Pakete versiegelt, sobald Bestellungen eingehen. Der Batch kann nicht wie die Einzel-Sendungs-Kette in einem einzigen Round-Trip sein: Zwischen dem Öffnen der Konsolidierung und dem Schließen liegt eine mehrstündige Lücke.

Voraussetzungen 

Bevor dieser Flow für ein bestimmtes Verified Account funktioniert:

• Ihr Konto muss eine Japan Post-Nachzahlungs-Later Pay Number (後納お客様番号) gespeichert haben — ein mit Bindestrichen formatierter Wert wie 1111111111-222222-3333333333-444444. Übergeben Sie ihn bei shipmentConsolidationCreate über accountNumber (Schritt 1).
• Ihr API-Schlüssel muss SHIPMENT_WRITE sowie die Standard-Scopes haben, die der pro-Sendung-Workflow benötigt.

Endpoint und Authentifizierung 

Alle drei Schritte unten sind GraphQL-Operationen, die an denselben Endpoint gesendet werden. Was Sie in den Headern übergeben, hängt von Ihrem Setup ab — wählen Sie Ihren Tab.

URL:

https://api.zonos.com/graphql

Header:

credentialToken: {{YOUR_API_TOKEN}}

Beispielanfrage 

Ein zum Anpassen kopierbares Beispiel zum Öffnen einer Konsolidierung — die Mutation, ihre Variablen und die Antwort. Dies ist der batch-spezifische Aufruf, der den Flow startet; das Anhängen von Sendungen (Schritt 2) nutzt das Einzel-Sendungs-Beispiel wieder, und das Schließen des Batches (Schritt 3) gibt das Manifestdokument zurück. Jedes Feld wird in den Schritten unten erläutert.

Schritt 1: shipmentConsolidationCreate 

Öffnet die Konsolidierung. Der Carrier-Code bindet den Batch an Japan Post; alle Mitgliedssendungen müssen Japan Post-Serviceebenen nutzen. Wenn Sie bereits etikettierte Sendungen bereit haben, befüllen Sie den Batch mit deren IDs über shipmentIds — andernfalls erstellen Sie ihn leer und hängen Sendungen in Schritt 2 an.

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

Antwort:

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

Behalten Sie die id (z. B. shco_01HJK...) — Sie verwenden sie für alles Folgende. Der status ist OPEN, bis Schritt 3.

Schritt 2: Sendungen anhängen 

Für jedes Paket, das Sie heute versenden müssen, führen Sie den vollständigen verketteten Einzel-Sendungs-Workflow aus, um die Sendung und ihr Etikett zu erstellen. Hängen Sie die Sendung dann mit einer der Methoden unten an den Batch an.

Option A: Beim Etikettenerstellen anhängen

Übergeben Sie die Konsolidierungs-ID im letzten shipmentCreateWorkflow-Schritt der Kette. Alle vorherigen Mutationen in der Kette sind identisch mit dem Einzel-Sendungs-Workflow.

Die relevanten Felder bei shipmentCreateWorkflow:

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

Option B: Bestehende Sendungen per ID anhängen

Wenn Ihre Sendungen bereits erstellt und etikettiert sind, fügen Sie sie dem offenen Batch mit shipmentIds bei shipmentConsolidationUpdate hinzu:

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

Lassen Sie status aus der Eingabe, solange Sie noch Sendungen hinzufügen — der Batch bleibt OPEN. Jede Sendung muss eine Japan Post-Serviceebene nutzen und ihr Etikett (Sendungsnummer) haben, bevor der Batch in Schritt 3 geschlossen wird.

Was Anhängen für das Etikett bedeutet

Unabhängig von der gewählten Option gilt bei einer Japan Post-Sendung in einer Konsolidierung:

• Die Sendung hat wie üblich eine Sendungsnummer.
• Das Versandetikett-PDF enthält nicht die Kunden-/Postfilial-Quittungskopien. Diese Quittungen werden auf Schritt 3 verschoben, wo sie in das Versandschein-Dokument für den gesamten Batch gebündelt werden.
• Die Sendung ist mit der Konsolidierung verknüpft; Sie können sie über shipmentConsolidation(id: ...) erneut abfragen, um ihre Mitglieder zu sehen.

Wiederholen Sie diesen Schritt für jedes Paket im Tages-Batch. Bis zu 250 Sendungen pro Konsolidierung; der Versuch, einen größeren Batch zu schließen, schlägt mit einem klaren Validierungsfehler fehl, bevor ein Japan Post-Aufruf erfolgt.

Sie können den Batch-Inhalt auch vor dem Schließen prüfen:

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

Jede Sendung sollte hier eine Sendungsnummer zeigen. Wenn nicht, wurde ihr Etikett nie erstellt — klären Sie das, bevor Sie schließen. status ist OPEN, bis die Konsolidierung in Schritt 3 geschlossen wird.

Schritt 3: shipmentConsolidationUpdate(status: CLOSED) 

Schließt den Batch. Dies ist der Aufruf, der Japan Post auffordert, den Nachzahlungsversandschein für alle Sendungsnummern der Mitglieder zu generieren, und das resultierende PDF an die Konsolidierung anhängt.

Mutation:

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

Bei einer CLOSED-Anfrage:

1. Die Konsolidierung wird validiert: ≤250 Sendungen, und jedes Mitglied muss eine Sendungsnummer haben. Wenn einer Sendung die Sendungsnummer fehlt (ihr Etikett wurde nie erstellt), wird der Aufruf abgelehnt.
2. Japan Post wird aufgefordert, einen Nachzahlungsversandschein für alle Sendungsnummern der Mitglieder zu generieren.
3. Der Status wechselt kurz zu MANIFEST_CREATED, während das Schein-PDF abgerufen wird, dann zu CLOSED, sobald das Dokument angehängt wurde.
4. Das Versandschein-PDF (eine Datei mit dem Schein plus allen Kunden-/Postfilial-Quittungen der Mitglieder) wird als CustomsDocument mit documentType: MANIFEST_DOCUMENT an die Konsolidierung angehängt.

Antwort:

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

Dokumente abrufen

Der Versandschein wird direkt als CustomsDocument mit documentType: MANIFEST_DOCUMENT an die Konsolidierung angehängt — holen Sie die fileUrl aus der Schließ-Antwort oben oder fragen Sie sie später jederzeit ab:

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

Drucken Sie das PDF unter fileUrl. Es enthält:

• Seite 1: Der Nachzahlungsversandschein — geben Sie diesen an die Postfiliale ab.
• Seiten 2+: Die Kunden-/Postfilial-Quittungen für jedes Paket — eine an jedes Paket geheftet, die andere behält die Postfiliale.

Nach dem Drucken bringen Sie die Pakete + den Versandschein + die Quittungen in einem Gang zur Postfiliale. Japan Post stellt Ihrer Later Pay Number am Ende des Abrechnungszeitraums in Rechnung.

Alles zusammenfügen 

Ein typischer Tag für einen Händler, der 50 Japan Post-Pakete versendet, sieht so aus:

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

Lieber am Tagesende bündeln? Erstellen Sie die Etiketten des Tages ohne Konsolidierungs-ID, öffnen Sie dann einmal die Konsolidierung mit allen shipmentIds-Werten (oder fügen Sie sie in Blöcken über shipmentConsolidationUpdate hinzu) und schließen Sie sie im selben oder einem Folgeaufruf.

Wenn Sie über mehrere Geschäftseinheiten / Abrechnungskonten versenden, führen Sie eine separate Konsolidierung pro Konto aus — übergeben Sie bei jedem shipmentConsolidationCreate eine andere accountNumber und leiten Sie Sendungen entsprechend. Mehr als 250 Pakete an einem Tag? Öffnen Sie eine zweite Konsolidierung.

Fehlerbehandlung 

Validierungsfehler (vor jedem Japan Post-Aufruf abgefangen)

• accountNumber fehlerhaft formatiert — wird in Schritt 1 (shipmentConsolidationCreate) abgelehnt, bevor die Konsolidierung gespeichert wird. Die Fehlermeldung identifiziert das fehlerhafte Segment.
• >250 Sendungen — wird in Schritt 3 abgelehnt, bevor der Japan Post-Aufruf erfolgt.
• Mitgliedssendung ohne Sendungsnummer — wird in Schritt 3 abgelehnt. Bedeutet, dass eine Etikettenerstellung früher still fehlgeschlagen ist; untersuchen Sie die betroffene Sendung über shipment(id: ...) { trackingDetails }.
• Keine Nachzahlungsnummer an der Konsolidierung gesetzt — wird in Schritt 3 abgelehnt. Übergeben Sie accountNumber bei shipmentConsolidationCreate oder speichern Sie eine Standardnummer auf Ihrem Japan Post-Carrier-Konto.

Japan Post API-Fehler

Wenn Japan Post die Versandschein-Anfrage ablehnt, gibt die Schließ-Mutation den Fehlercode und die Meldung des Carriers als GraphQL-Fehler zurück. Die häufigsten:

Wiederholungen

Wenn der Schließaufruf nachdem Japan Post die Versandschein-Anfrage akzeptiert hat fehlschlägt (d. h. beim PDF-Abruf), ist ein erneuter Aufruf von shipmentConsolidationUpdate(status: CLOSED) sicher — die Plattform überspringt den Carrier-Aufruf und versucht nur erneut, das Dokument abzurufen und anzuhängen.

Wenn das Schließen bevor Japan Post die Anfrage akzeptiert hat fehlschlägt (Validierungsfehler, E0xx, Netzwerk-Timeout), hat sich kein Status geändert — beheben Sie die Ursache und versuchen Sie es erneut.