Batchforsendelse (konsolidering)

Dette dokumentet gjennomgår tre-steg-flyten for å lage en Japan Post utsatt betalingsforsendelsebatch via Zonos GraphQL API: åpne en konsolidering, legg til n forsendelser til den, og lukk den for å motta Japan Posts forsendelsesslipp (manifestdokument).

Når du skal bruke denne flyten 

Japan Posts utsatt betalingsprogram (後納) tillater en selger å betale sitt daglige forsendelseskonto i én transaksjon på slutten av dagen, i stedet for per pakke ved levering. Selgeren bringer alle dagens pakker til postkontoret sammen med én forsendelsesslipp (差出票) som dekker opptil 250 forsendelser. Porto blir fakturert til selgerens forhåndsregistrerte Later Pay-nummer.

Hvis du sender individuelle Japan Post-etiketter og betaler pakke for pakke ved skranken, trenger du ikke denne flyten — kjør ensendelseskjeden direkte uten en konsolidering.

Oversikt 

1. shipmentConsolidationCreate            → åpne batchen (returnerer konsolider-ID)
2. Legg til forsendelser × n              → lag hver forsendelse + etikett, knyttet til batchen
3. shipmentConsolidationUpdate(CLOSED)    → lukk batchen (returnerer forsendelsesslippen)

Det finnes to måter å legge til forsendelser i batchen — bruk den som passer best til integrasjonen din (eller blandingen):

• Legg til ved etikett-opprettelse — før konsolider-ID-en fra steg 1 inn i hvert shipmentCreateWorkflow-anrop via feltet shipmentConsolidationId.
• Legg til eksisterende forsendelser etter ID — pass shipmentIds på shipmentConsolidationCreate (for å fylle batchen) eller på shipmentConsolidationUpdate (for å legge til i en åpen batch). Hver forsendelse må allerede ha sin Japan Post-etikett.

Uansett hvilken metode du bruker, er hver etikett opprettet med ditt Later Pay-nummer innebygd slik at Japan Post vil akseptere det på forsendelsesslippen når steg 3 lukker batchen.

Hvorfor separate anrop i stedet for én mutasjon? Steg 2.1, 2.2, ..., 2.n skjer gjennom selgerens dag — etiketter skrives ut og pakker forsegles når ordrer kommer inn. Batchen kan ikke være en enkelt rundtur slik ensendelseskjeden er: det er et flertimers gap mellom åpning av konsolideringen og lukkingen.

Forutsetninger 

Før denne flyten fungerer for en gitt verifisert konto:

• Kontoen din må ha et Japan Post utsatt betalings Later Pay-nummer (後納お客様番号) lagret på den — en hyphen-formatert verdi som 1111111111-222222-3333333333-444444. Send det på shipmentConsolidationCreate via accountNumber (Steg 1).
• API-nøkkelen din må inneholde SHIPMENT_WRITE, pluss standardomfanget som per-forsendelsesarbeidsflyten trenger.

Endepunkt og autentisering 

Alle tre stegene nedenfor er GraphQL-operasjoner sendt til samme endepunkt. Hva du sender i hodene, avhenger av oppsettet ditt — velg din fane.

URL:

https://api.zonos.com/graphql

Hoder:

credentialToken: {{YOUR_API_TOKEN}}

Eksempel forespørsel 

En kopi-og-tilpass eksempel på åpning av en konsolidering — mutasjonen, dens variabler, og svaret. Dette er det batch-spesifikke anropet som starter flyten; legge til forsendelser (Steg 2) gjenbruker ensendelseseksemplet, og lukking av batchen (Steg 3) returnerer manifestdokumentet. Hvert felt er oppstykket i stegene nedenfor.

Steg 1: shipmentConsolidationCreate 

Åpner konsolideringen. Bærekoden låser batchen til Japan Post; alle medlemsforsendelser må bruke Japan Post servicenivåer. Hvis du allerede har merkede forsendelser klare, fyll batchen med deres ID-er via shipmentIds — ellers opprett den tom og legg til forsendelser i steg 2.

Mutasjon:

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

Svar:

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

Behold id-en (f.eks. shco_01HJK...) — du bruker den til alt nedenfor. status er OPEN til steg 3.

Steg 2: Legg til forsendelser 

For hver pakke du trenger å sende i dag, kjør hele den kjedede ensendelsesarbeidsflyten for å lage forsendelsen og etiketten. Legg deretter til forsendelsen i batchen ved å bruke en av metodene nedenfor.

Alternativ A: Legg til ved etikett-opprettelse

Send konsolider-ID-en på det siste trinnet shipmentCreateWorkflow i kjeden. Alle forrige mutasjoner i kjeden er identiske med ensendelsesarbeidsflyten.

De relevante feltene på shipmentCreateWorkflow:

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

Alternativ B: Legg til eksisterende forsendelser etter ID

Hvis forsendelsene dine allerede er opprettet og merkede, legg dem til i den åpne batchen med shipmentIds på shipmentConsolidationUpdate:

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

La status være utenfor inndataene mens du fortsatt legger til forsendelser — batchen forblir OPEN. Hver forsendelse må bruke et Japan Post servicenivå og ha sin etikett (sporingsnummer) før batchen lukkes i Steg 3.

Hva vedlegg betyr for etiketten

Uansett hvilken alternativ du bruker, når en Japan Post-forsendelse er en del av en konsolidering:

• Forsendelsen har et sporingsnummer, som vanlig.
• Forsendelsesetikett-PDF-en inkluderer ikke kunde/postkontor-mottakskopiene. Disse mottakene utsettes til Steg 3, hvor de blir bundlet inn i forsendelsesslippdokumentet for hele batchen.
• Forsendelsen er knyttet til konsolideringen; du kan re-spørre den via shipmentConsolidation(id: ...) for å se medlemmene.

Gjenta dette trinnet for hver pakke i dagens batch. Opp til 250 forsendelser per konsolidering; forsøk på lukking av en større batch mislykkes med en tydelig valideringsfeil før noen Japan Post-anrop gjøres.

Du kan også verifisere batchens innhold før lukking:

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

Hver forsendelse skal vise et sporingsnummer her. Hvis den ikke gjør det, ble etiketten aldri opprettet — ordne det før lukking. status er OPEN til konsolideringen lukkes i Steg 3.

Steg 3: shipmentConsolidationUpdate(status: CLOSED) 

Lukker batchen. Dette er anropet som ber Japan Post om å generere den utsatte betalingsforsendelsesslippen som dekker hvert medlems sporingsnummer, og legger det resulterende PDF-dokumentet ved konsolideringen.

GraphQL-operasjonen er kalt CloseConsolidation for å beskrive hensikten, lukking av batchen. Den kjører mutasjonen shipmentConsolidationUpdate med status: CLOSED.

Mutasjon:

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

På en CLOSED-forespørsel:

1. Konsolideringen valideres: ≤250 forsendelser, og alle medlemmer må ha et sporingsnummer. Hvis en forsendelse mangler sporingsnummeret (etiketten ble aldri opprettet), avvises anropet.
2. Japan Post blir bedt om å generere en utsatt betalingsforsendelsesslipp som dekker hvert medlems sporingsnummer.
3. Statusen beveger seg kort til MANIFEST_CREATED mens slipp-PDF-en hentes, deretter til CLOSED når dokumentet er vedlagt.
4. Forsendelsesslipp-PDF-en (én fil som inneholder slippen pluss hver medlems kunde/postkontor mottakskopi) legges ved konsolideringen som et CustomsDocument med documentType: MANIFEST_DOCUMENT.

Svar:

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

Hente dokumentene

Forsendelsesslippen legges ved direkte til konsolideringen som et CustomsDocument med documentType: MANIFEST_DOCUMENT — ta fileUrl fra lukksvaret ovenfor, eller spør for det når som helst senere:

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

Skriv ut PDF-en på fileUrl. Det inneholder:

• Side 1: Forsendelsesslippen med utsatt betaling (後納差出票) — lever denne til postkontoret. Hver forsendelse i batchen er oppført her, uansett hvilket servicenivå den brukte.
• Sider 2+: Kunde/postkontor-mottakskopiene — en stiftet til hver pakke, den andre beholdt av postkontoret. Disse sidene genereres kun for EMS- og internasjonale pakkeforsendelser, fordi de er knyttet til et sporingsnummer.

Når den er skrevet ut, ta pakkene + forsendelsesslippen + mottakene til postkontoret på én tur. Japan Post fakturerer ditt Later Pay-nummer ved slutten av fakturaperioden.

En forsendelse på side 1 uten mottaksside er ikke en manglende forsendelse. Small Packet (小形包装物) er ikke en sporet Japan Post-tjeneste, så den blir oppført på side 1 og får ingen mottaksside på side 2+. En batch med fem pakker kan legitimt produsere en side 1 som lister alle fem og mottakssider kun for EMS- og pakkeforsendelsene, og en batch med bare Small Packets produserer en side 1 og ingen flere sider i det hele tatt. Dette er forventet Japan Post-oppførsel, ikke en mislykket etikett eller et mislykket manifestanrop. Du trenger ikke å åpne en separat konsolidering per servicenivå. Bekreftet med Japan Post, august 2026.

Sette det hele sammen 

En representativ dag for en selger som sender 50 Japan Post-pakker ser slik ut:

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

Foretrekker å batch på slutten av dagen i stedet? Lag dagens etiketter uten en konsolider-ID, åpne deretter konsolideringen en gang med hver shipmentIds-verdi (eller legg dem til i biter via shipmentConsolidationUpdate) og lukk den i samme eller en oppfølgingsanrop.

Hvis du sender over flere forretningsenheter / fakturakontoer, kjør en separat konsolidering per konto — send en annen accountNumber på hver shipmentConsolidationCreate og rute forsendelser tilsvarende. Sender du mer enn 250 pakker på en dag? Åpne en annen konsolidering.

Feilhåndtering 

Valideringsfeil (fanget før noen Japan Post-anrop)

• accountNumber feilformatert — avvist på Steg 1 (shipmentConsolidationCreate) før konsolideringen blir engang lagret. Feilmelding identifiserer det aktuelle segmentet.
• >250 forsendelser — avvist på Steg 3, før Japan Post-anropet gjøres.
• Medlemsforsendelse mangler sporingsnummer — avvist på Steg 3. Betyr at en etikettoppretting stille mislyktes tidligere; undersøk den berørte forsendelsen via shipment(id: ...) { trackingDetails }.
• Ingen utsatt betalingsnummer satt på konsolideringen — avvist på Steg 3. Send accountNumber på shipmentConsolidationCreate, eller lagre et standardkontonummer på Japan Post-bærekontoen din.

Japan Post API-feil

Hvis Japan Post avviser forsendelsesslippen-forespørselen, vises bærerens feilkode og melding som en GraphQL-feil. Den vanligste:

Forsøk på nytt

Hvis lukksanropet mislykkes etter at Japan Post har akseptert forsendelsesslippen-forespørselen (dvs. under PDF-henting), er forsøk på nytt av shipmentConsolidationUpdate(status: CLOSED) trygt — plattformen hopper over bæreranropet og forsøker bare å hente og vedlegge dokumentet på nytt.

Hvis lukkingen mislykkes før Japan Post har akseptert forespørselen (valideringsfeil, E0xx, nettverkstidsavbrudd), har ingen tilstand endret seg — rett rotårsaken og forsøk på nytt.