Batch-afsendelse (konsolidering)

Dette dokument gennemgår det tretrinsflow, der opretter en Japan Post deferred-payment batch-afsendelse via Zonos GraphQL API: åbn en konsolidering, tilknyt n forsendelser til den, og luk den for at modtage Japan Posts afsendelseskvittering (manifestdokument).

Hvornår du skal bruge dette flow 

Japan Posts deferred-payment-program (後納) giver en forhandler mulighed for at afregne dagens porto i én transaktion ved dagens afslutning i stedet for pr. pakke ved indlevering. Forhandleren bringer dagens pakker til posthuset sammen med én afsendelseskvittering (差出票), der dækker op til 250 forsendelser. Portoen faktureres til forhandlerens forudregistrerede Later Pay Number.

Hvis du sender individuelle Japan Post-labels og betaler pakke for pakke ved skranken, behøver du ikke dette flow — kald enkeltforsendelseskæden direkte uden konsolidering.

Overblik 

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)

Der er to måder at tilknytte forsendelser til batchen på — brug den, der passer til din integration (eller kombiner dem):

• Tilknyt ved labeloprettelse — send konsoliderings-ID'et fra trin 1 med i hvert shipmentCreateWorkflow-kald via feltet shipmentConsolidationId.
• Tilknyt eksisterende forsendelser via ID — send shipmentIds på shipmentConsolidationCreate (for at starte batchen) eller på shipmentConsolidationUpdate (for at tilføje til en åben batch). Hver forsendelse skal allerede have sin Japan Post-label.

Uanset metode oprettes hver label med dit Later Pay Number indlejret, så Japan Post accepterer den på afsendelseskvitteringen, når trin 3 lukker batchen.

Hvorfor separate kald i stedet for én mutation? Trin 2.1, 2.2, ..., 2.n sker i løbet af forhandlerens dag — labels printes og pakker pakkes, efterhånden som ordrer kommer ind. Batchen kan ikke være ét enkelt round-trip på samme måde som enkeltforsendelseskæden: der er flere timers mellemrum mellem at åbne konsolideringen og lukke den.

Forudsætninger 

Før dette flow virker for en given Verified Account:

• Din konto skal have et Japan Post deferred-payment Later Pay Number (後納お客様番号) gemt — en værdi med bindestreger som 1111111111-222222-3333333333-444444. Send den på shipmentConsolidationCreate via accountNumber (trin 1).
• Din API-nøgle skal have SHIPMENT_WRITE plus de standardscopes, som workflowet pr. forsendelse kræver.

Endpoint og godkendelse 

Alle tre trin nedenfor er GraphQL-operationer sendt til samme endpoint. Hvad du sender i headers, afhænger af din opsætning — vælg din fane.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Eksempelanmodning 

Et kopier-og-tilpas-eksempel på at åbne en konsolidering — mutationen, dens variabler og svaret. Dette er det batch-specifikke kald, der starter flowet; tilknytning af forsendelser (trin 2) genbruger enkeltforsendelseseksemplet, og lukning af batchen (trin 3) returnerer manifestdokumentet. Hvert felt er beskrevet i trinene nedenfor.

Trin 1: shipmentConsolidationCreate 

Åbner konsolideringen. Carrier-koden låser batchen til Japan Post; alle medlemsforsendelser skal bruge Japan Post-serviceniveauer. Hvis du allerede har labeled forsendelser klar, start batchen med deres ID'er via shipmentIds — ellers opret den tom og tilknyt forsendelser i trin 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
    }
  }
}

Response:

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

Gem id (f.eks. shco_01HJK...) — du bruger den til alt nedenfor. status er OPEN indtil trin 3.

Trin 2: Tilknyt forsendelser 

For hver pakke, du skal sende i dag, kør det fulde kædede enkeltforsendelsesworkflow for at oprette forsendelsen og dens label. Tilknyt derefter forsendelsen til batchen med en af metoderne nedenfor.

Mulighed A: Tilknyt ved labeloprettelse

Send konsoliderings-ID'et i det sidste shipmentCreateWorkflow-trin i kæden. Alle foregående mutationer i kæden er identiske med enkeltforsendelsesworkflowet.

De relevante felter på shipmentCreateWorkflow:

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

Mulighed B: Tilknyt eksisterende forsendelser via ID

Hvis dine forsendelser allerede er oprettet og labeled, tilføj dem til den åbne batch med shipmentIds på shipmentConsolidationUpdate:

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

Udelad status i input, mens du stadig tilføjer forsendelser — batchen forbliver OPEN. Hver forsendelse skal bruge et Japan Post-serviceniveau og have sin label (trackingnummer), før batchen lukkes i trin 3.

Hvad tilknytning betyder for labelen

Uanset hvilken option du bruger, når en Japan Post-forsendelse er del af en konsolidering:

• Forsendelsen har et trackingnummer som sædvanligt.
• Forsendelseslabel-PDF'en inkluderer ikke kunde-/posthuskvitteringskopierne. Disse kvitteringer udskydes til trin 3, hvor de samles i afsendelseskvitteringsdokumentet for hele batchen.
• Forsendelsen er knyttet til konsolideringen; du kan forespørge den igen via shipmentConsolidation(id: ...) for at se medlemmerne.

Gentag dette trin for hver pakke i dagens batch. Op til 250 forsendelser pr. konsolidering; forsøg på at lukke en større batch fejler med en tydelig valideringsfejl, før Japan Post kaldes.

Du kan også verificere batchindholdet før lukning:

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

Hver forsendelse skal vise et trackingnummer her. Hvis en ikke gør, blev dens label aldrig oprettet — løs det før lukning. status er OPEN, indtil konsolideringen lukkes i trin 3.

Trin 3: shipmentConsolidationUpdate(status: CLOSED) 

Lukker batchen. Dette er kaldet, der beder Japan Post om at generere deferred-payment-afsendelseskvitteringen, der dækker alle medlemmers trackingnumre, og vedhæfter den resulterende PDF til konsolideringen.

GraphQL-operationen hedder CloseConsolidation for at beskrive hensigten med at lukke batchen. Den kører shipmentConsolidationUpdate-mutationen med status: CLOSED.

Mutation:

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

Ved en CLOSED-anmodning:

1. Konsolideringen valideres: ≤250 forsendelser, og hvert medlem skal have et trackingnummer. Hvis en forsendelse mangler trackingnummer (labelen blev aldrig oprettet), afvises kaldet.
2. Japan Post bedes om at generere en deferred-payment-afsendelseskvittering, der dækker alle medlemmers trackingnumre.
3. Status går kortvarigt til MANIFEST_CREATED, mens kvitterings-PDF'en hentes, derefter til CLOSED, når dokumentet er vedhæftet.
4. Afsendelseskvitterings-PDF'en (én fil med kvitteringen plus alle medlemmers kunde-/posthuskvitteringer) vedhæftes konsolideringen som en CustomsDocument med documentType: MANIFEST_DOCUMENT.

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

Hentning af dokumenterne

Afsendelseskvitteringen vedhæftes direkte til konsolideringen som en CustomsDocument med documentType: MANIFEST_DOCUMENT — hent fileUrl fra lukkesvaret ovenfor, eller forespørg den når som helst senere:

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

Print PDF'en på fileUrl. Den indeholder:

• Side 1: Deferred-payment-afsendelseskvitteringen (後納差出票) — giv denne til posthuset. Alle forsendelser i batchen er angivet her, uanset hvilket serviceniveau de brugte.
• Side 2+: Kunde-/posthuskvitteringerne — én hæftes på hver pakke, den anden beholdes af posthuset. Disse sider genereres kun for EMS- og International Parcel-forsendelser, fordi de er knyttet til et trackingnummer.

En forsendelse på side 1 uden en kvitteringsside er ikke en manglende forsendelse. Small Packet (小形包装物) er ikke en sporet Japan Post-service, så den er angivet på side 1 og får ingen kvitteringsside på side 2+. En batch med fem pakker kan lovligt give en side 1, der viser alle fem, og kvitteringssider for kun EMS- og Parcel-pakkerne, og en batch bestående udelukkende af Small Packets giver en side 1 og ingen yderligere sider overhovedet. Dette er forventet Japan Post-adfærd, ikke en mislykket label eller et mislykket manifestkald. Du behøver ikke åbne en separat konsolidering pr. serviceniveau. Bekræftet med Japan Post, august 2026.

Når den er printet, bring pakkerne + afsendelseskvitteringen + kvitteringerne til posthuset i én tur. Japan Post fakturerer dit Later Pay Number ved afslutningen af faktureringsperioden.

Sådan hænger det sammen 

En typisk dag for en forhandler, der sender 50 Japan Post-pakker, kan se sådan ud:

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

Foretrækker du at batch'e ved dagens afslutning? Opret dagens labels uden konsoliderings-ID, åbn derefter konsolideringen én gang med alle shipmentIds-værdier (eller tilføj dem i bidder via shipmentConsolidationUpdate) og luk den i samme eller et opfølgende kald.

Hvis du sender på tværs af flere forretningsenheder / faktureringskonti, kør en separat konsolidering pr. konto — send et andet accountNumber på hvert shipmentConsolidationCreate og diriger forsendelser derefter. Sender du mere end 250 pakker på en dag? Åbn en anden konsolidering.

Fejlhåndtering 

Valideringsfejl (fanget før Japan Post kaldes)

• accountNumber misformateret — afvist ved trin 1 (shipmentConsolidationCreate), før konsolideringen gemmes. Fejlmeddelelsen identificerer det problematiske segment.
• >250 forsendelser — afvist ved trin 3, før Japan Post kaldes.
• Medlemsforsendelse mangler trackingnummer — afvist ved trin 3. Betyder, at labeloprettelse tidligere fejlede stille; undersøg den berørte forsendelse via shipment(id: ...) { trackingDetails }.
• Intet deferred-payment-nummer sat på konsolideringen — afvist ved trin 3. Send accountNumber på shipmentConsolidationCreate, eller gem et standardkontonummer på din Japan Post-carrierkonto.

Japan Post API-fejl

Hvis Japan Post afviser anmodningen om afsendelseskvittering, viser lukke-mutationen carrierens fejlkode og -meddelelse som en GraphQL-fejl. De mest almindelige:

Forsøg igen

Hvis lukkekaldet fejler efter Japan Post har accepteret anmodningen om afsendelseskvittering (dvs. under PDF-hentning), er det sikkert at prøve shipmentConsolidationUpdate(status: CLOSED) igen — platformen springer carrier-kaldet over og forsøger kun at hente og vedhæfte dokumentet igen.

Hvis lukningen fejler før Japan Post har accepteret anmodningen (valideringsfejl, E0xx, netværkstimeout), er der ikke ændret tilstand — ret årsagen og prøv igen.