Batchverzending (consolidatie)

Dit document doorloopt de driefasige flow voor het aanmaken van een Japan Post batch met uitgestelde betaling via de Zonos GraphQL API: open een consolidatie, koppel er n zendingen aan en sluit deze vervolgens af om Japan Post's verzendbon (manifestdocument) te ontvangen.

Wanneer u deze flow gebruikt 

Met het programma voor uitgestelde betaling van Japan Post (後納) kan een handelaar de dagelijkse verzendkosten aan het einde van de dag in één transactie afrekenen, in plaats van per pakket bij inlevering. De handelaar brengt alle pakketten van die dag naar het postkantoor, samen met één verzendbon (差出票) die tot 250 zendingen dekt. De verzendkosten worden gefactureerd aan het vooraf geregistreerde Later Pay Number van de handelaar.

Als u afzonderlijke Japan Post-labels verzendt en per pakket aan de balie betaalt, hebt u deze flow niet nodig — roep de workflow voor één zending rechtstreeks aan, zonder consolidatie.

Overzicht 

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)

Er zijn twee manieren om zendingen aan de batch te koppelen — gebruik wat het beste bij uw integratie past (of combineer ze):

• Koppelen op het moment van labelaanmaak — geef de consolidatie-ID uit stap 1 door aan elke shipmentCreateWorkflow-aanroep via het veld shipmentConsolidationId.
• Bestaande zendingen koppelen via ID — geef shipmentIds door aan shipmentConsolidationCreate (om de batch te initiëren) of aan shipmentConsolidationUpdate (om aan een open batch toe te voegen). Elke zending moet al zijn Japan Post-label hebben.

Hoe u het ook doet, elk label wordt aangemaakt met uw Later Pay Number erin verwerkt, zodat Japan Post het accepteert op de verzendbon wanneer stap 3 de batch afsluit.

Waarom afzonderlijke aanroepen in plaats van één mutatie? Stappen 2.1, 2.2, ..., 2.n vinden verspreid over de dag van de handelaar plaats — labels worden afgedrukt en pakketten worden verzegeld zodra bestellingen binnenkomen. De batch kan geen enkele round-trip zijn zoals bij de workflow voor één zending: er zit een gat van meerdere uren tussen het openen en sluiten van de consolidatie.

Vereisten 

Voordat deze flow werkt voor een bepaalde Verified Account:

• Uw account moet een Japan Post Later Pay Number voor uitgestelde betaling (後納お客様番号) hebben opgeslagen — een met streepjes opgemaakte waarde zoals 1111111111-222222-3333333333-444444. Geef deze door aan shipmentConsolidationCreate via accountNumber (stap 1).
• Uw API-key moet SHIPMENT_WRITE bevatten, plus de standaardscopes die de workflow per zending nodig heeft.

Endpoint en authenticatie 

Alle drie de onderstaande stappen zijn GraphQL-bewerkingen die naar hetzelfde endpoint worden verzonden. Wat u in de headers doorgeeft, hangt af van uw configuratie — kies uw tabblad.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Voorbeeldverzoek 

Een voorbeeld om te kopiëren en aan te passen voor het openen van een consolidatie — de mutatie, de variabelen en het antwoord. Dit is de batch-specifieke aanroep waarmee de flow start; het koppelen van zendingen (stap 2) hergebruikt het voorbeeld voor één zending, en het afsluiten van de batch (stap 3) retourneert het manifestdocument. Elk veld wordt hieronder in de stappen toegelicht.

Stap 1: shipmentConsolidationCreate 

Opent de consolidatie. De carrier-code koppelt de batch aan Japan Post; alle zendingen in de batch moeten Japan Post-servicelevels gebruiken. Als u al zendingen met labels gereed hebt, initieer de batch dan met hun ID's via shipmentIds — anders maakt u deze leeg aan en koppelt u zendingen in stap 2.

Mutatie:

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

Antwoord:

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

Bewaar de id (bijvoorbeeld shco_01HJK...) — u gebruikt deze voor alles hieronder. De status is OPEN tot stap 3.

Stap 2: Zendingen koppelen 

Voer voor elk pakket dat u vandaag moet verzenden de volledige, geketende workflow voor één zending uit om de zending en het label aan te maken. Koppel de zending vervolgens aan de batch met een van de onderstaande methoden.

Optie A: koppelen op het moment van labelaanmaak

Geef de consolidatie-ID door bij de laatste shipmentCreateWorkflow-stap van de keten. Alle voorafgaande mutaties in de keten zijn identiek aan de workflow voor één zending.

De relevante velden op shipmentCreateWorkflow:

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

Optie B: bestaande zendingen koppelen via ID

Als uw zendingen al zijn aangemaakt en van een label voorzien, voegt u ze toe aan de open batch met shipmentIds op shipmentConsolidationUpdate:

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

Laat status weg uit de input terwijl u nog zendingen toevoegt — de batch blijft OPEN. Elke zending moet een Japan Post-servicelevel gebruiken en zijn label (trackingnummer) hebben voordat de batch in stap 3 wordt afgesloten.

Wat koppelen betekent voor het label

Welke optie u ook gebruikt, wanneer een Japan Post-zending onderdeel is van een consolidatie:

• De zending heeft zoals gewoonlijk een trackingnummer.
• De PDF van het verzendlabel bevat niet de kopieën van het klant-/postkantoorbewijs. Die bewijzen worden uitgesteld tot stap 3, waar ze worden gebundeld in het verzendbon-document voor de hele batch.
• De zending is gekoppeld aan de consolidatie; u kunt deze opnieuw opvragen via shipmentConsolidation(id: ...) om de leden te zien.

Herhaal deze stap voor elk pakket in de batch van die dag. Tot 250 zendingen per consolidatie; een poging om een grotere batch af te sluiten mislukt met een duidelijke validatiefout voordat er een aanroep naar Japan Post wordt gedaan.

U kunt ook de inhoud van de batch controleren voordat u deze afsluit:

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

Elke zending moet hier een trackingnummer laten zien. Als dat niet het geval is, is het label nooit aangemaakt — los dit op voordat u afsluit. status is OPEN totdat de consolidatie in stap 3 wordt afgesloten.

Stap 3: shipmentConsolidationUpdate(status: CLOSED) 

Sluit de batch af. Dit is de aanroep die Japan Post vraagt om de verzendbon met uitgestelde betaling te genereren die het trackingnummer van elk lid dekt, en die de resulterende PDF aan de consolidatie koppelt.

De GraphQL-bewerking heet CloseConsolidation om de intentie te beschrijven: het afsluiten van de batch. Deze voert de mutatie shipmentConsolidationUpdate uit met status: CLOSED.

Mutatie:

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

Bij een CLOSED-verzoek:

1. De consolidatie wordt gevalideerd: ≤250 zendingen, en elk lid moet een trackingnummer hebben. Als een zending geen trackingnummer heeft (het label is nooit aangemaakt), wordt de aanroep geweigerd.
2. Japan Post wordt gevraagd een verzendbon met uitgestelde betaling te genereren die het trackingnummer van elk lid dekt.
3. De status gaat kort naar MANIFEST_CREATED terwijl de PDF van de bon wordt opgehaald, en vervolgens naar CLOSED zodra het document is gekoppeld.
4. De PDF van de verzendbon (één bestand met de bon plus de klant-/postkantoorbewijzen van elk lid) wordt aan de consolidatie gekoppeld als CustomsDocument met documentType: MANIFEST_DOCUMENT.

Antwoord:

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

Documenten ophalen

De verzendbon wordt direct aan de consolidatie gekoppeld als CustomsDocument met documentType: MANIFEST_DOCUMENT — haal de fileUrl op uit het hierboven getoonde antwoord bij het afsluiten, of vraag deze op elk later moment op:

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

Print de PDF op fileUrl. Deze bevat:

• Pagina 1: De verzendbon met uitgestelde betaling (後納差出票) — overhandig deze aan het postkantoor. Elke zending in de batch staat hier vermeld, ongeacht het gebruikte servicelevel.
• Pagina 2 en verder: De klant-/postkantoorbewijzen — één aan elk pakket geniet, de andere behouden door het postkantoor. Deze pagina's worden alleen gegenereerd voor EMS- en International Parcel-zendingen, omdat ze zijn gekoppeld aan een trackingnummer.

Breng na het printen de pakketten, de verzendbon en de bewijzen in één keer naar het postkantoor. Japan Post factureert uw Later Pay Number aan het einde van de factureringsperiode.

Een zending op pagina 1 zonder bewijspagina is geen ontbrekende zending. Small Packet (小形包装物) is geen getrackte Japan Post-service, dus deze staat vermeld op pagina 1 en krijgt geen bewijspagina op pagina 2 en verder. Een batch van vijf pakketten kan terecht een pagina 1 opleveren waarop alle vijf worden vermeld, met bewijspagina's alleen voor de EMS- en Parcel-zendingen, en een batch met uitsluitend Small Packets levert een pagina 1 op zonder verdere pagina's. Dit is normaal Japan Post-gedrag, geen mislukt label of mislukte manifestaanroep. U hoeft geen aparte consolidatie per servicelevel te openen. Bevestigd door Japan Post, augustus 2026.

Alles bij elkaar 

Een representatieve dag voor een handelaar die 50 Japan Post-pakketten verzendt, ziet er als volgt uit:

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

Wilt u liever aan het einde van de dag batchen? Maak de labels van die dag aan zonder consolidatie-ID, open de consolidatie dan één keer met alle shipmentIds-waarden (of voeg ze in delen toe via shipmentConsolidationUpdate) en sluit deze af in dezelfde of een vervolgaanroep.

Als u verzendt via meerdere business units/factureringsaccounts, voert u per account een afzonderlijke consolidatie uit — geef bij elke shipmentConsolidationCreate een ander accountNumber door en route de zendingen dienovereenkomstig. Verzendt u meer dan 250 pakketten per dag? Open dan een tweede consolidatie.

Foutafhandeling 

Validatiefouten (opgevangen voordat er een Japan Post-aanroep wordt gedaan)

• accountNumber onjuist opgemaakt — geweigerd bij stap 1 (shipmentConsolidationCreate) voordat de consolidatie zelfs is opgeslagen. De foutmelding identificeert het betreffende segment.
• >250 zendingen — geweigerd bij stap 3, voordat de aanroep naar Japan Post wordt gedaan.
• Zending zonder trackingnummer — geweigerd bij stap 3. Betekent dat het aanmaken van een label eerder stilletjes is mislukt; onderzoek de betreffende zending via shipment(id: ...) { trackingDetails }.
• Geen nummer voor uitgestelde betaling ingesteld op de consolidatie — geweigerd bij stap 3. Geef accountNumber door aan shipmentConsolidationCreate, of sla een standaardaccountnummer op bij uw Japan Post-carrieraccount.

Japan Post API-fouten

Als Japan Post het verzoek om een verzendbon weigert, geeft de afsluitmutatie de foutcode en het bericht van de carrier weer als een GraphQL-fout. De meest voorkomende:

Nieuwe pogingen

Als de afsluitaanroep mislukt na dat Japan Post het verzoek om een verzendbon heeft geaccepteerd (dus tijdens het ophalen van de PDF), is het veilig om shipmentConsolidationUpdate(status: CLOSED) opnieuw uit te voeren — het platform slaat de carrieraanroep over en probeert alleen opnieuw het document op te halen en te koppelen.

Als het afsluiten voordat Japan Post het verzoek heeft geaccepteerd mislukt (validatiefout, E0xx, netwerktime-out), is er geen status veranderd — verhelp de oorzaak en probeer het opnieuw.