Batchavsändning (konsolidering)

Det här dokumentet går igenom det tredelade flödet för att skapa en batch för avsändning med uppskjuten betalning hos Japan Post via Zonos GraphQL-API: öppna en konsolidering, koppla n sändningar till den och stäng den för att få Japan Posts avsändningskvitto (manifestdokument).

När det här flödet ska användas 

Japan Posts program för uppskjuten betalning (後納) gör det möjligt för en handlare att reglera dagens fraktkostnad i en enda transaktion vid dagens slut, i stället för per paket vid inlämning. Handlaren tar med sig dagens samtliga paket till postkontoret tillsammans med ett avsändningskvitto (差出票) som täcker upp till 250 sändningar. Portot faktureras mot handlarens i förväg registrerade Later Pay Number.

Om du skickar enskilda Japan Post-fraktetiketter och betalar paket för paket vid disken behöver du inte det här flödet — anropa kedjan för en enskild sändning direkt, utan konsolidering.

Översikt 

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)

Det finns två sätt att koppla sändningar till batchen — använd det som passar din integration (eller blanda dem):

• Koppla vid tidpunkten för fraktetikettskapande — för in konsolideringens ID från steg 1 i varje anrop av shipmentCreateWorkflow via fältet shipmentConsolidationId.
• Koppla befintliga sändningar via ID — skicka med shipmentIds i shipmentConsolidationCreate (för att initiera batchen) eller i shipmentConsolidationUpdate (för att lägga till i en öppen batch). Varje sändning måste redan ha sin Japan Post-fraktetikett.

Oavsett metod skapas varje fraktetikett med ditt Later Pay Number inbäddat, så att Japan Post accepterar den på avsändningskvittot när batchen stängs i steg 3.

Varför separata anrop i stället för en enda mutation? Stegen 2.1, 2.2, ..., 2.n sker utspridda över handlarens dag — fraktetiketter skrivs ut och paket förseglas allt eftersom beställningar kommer in. Batchen kan inte hanteras i en enda tur-och-retur på samma sätt som kedjan för enskild sändning: det är flera timmars mellanrum mellan att konsolideringen öppnas och att den stängs.

Förutsättningar 

För att det här flödet ska fungera för ett givet Verified Account krävs följande:

• Ditt konto måste ha ett Later Pay Number för uppskjuten betalning hos Japan Post (後納お客様番号) sparat på sig — ett värde med bindestreck, till exempel 1111111111-222222-3333333333-444444. Skicka med det i shipmentConsolidationCreate via accountNumber (steg 1).
• Din API-nyckel måste ha SHIPMENT_WRITE, samt de vanliga behörigheter (scopes) som arbetsflödet per sändning kräver.

Slutpunkt och autentisering 

Alla tre steg nedan är GraphQL-operationer som skickas till samma slutpunkt. Vad du skickar i headers beror på din uppsättning — välj din flik.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Exempelbegäran 

Ett exempel att kopiera och anpassa för att öppna en konsolidering — mutationen, dess variabler och svaret. Det här är det batch-specifika anropet som startar flödet; att koppla sändningar (steg 2) återanvänder exemplet för enskild sändning, och att stänga batchen (steg 3) returnerar manifestdokumentet. Varje fält bryts ner i stegen nedan.

Steg 1: shipmentConsolidationCreate 

Öppnar konsolideringen. Transportörskoden låser batchen till Japan Post; alla medlemssändningar måste använda Japan Post-tjänstenivåer. Om du redan har färdiga sändningar med fraktetiketter kan du initiera batchen med deras ID:n via shipmentIds — annars skapar du den tom och kopplar sändningar i steg 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
    }
  }
}

Svar:

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

Spara id (t.ex. shco_01HJK...) — du kommer att använda det för allt nedan. status är OPEN fram till steg 3.

Steg 2: Koppla sändningar 

Kör hela det sammankopplade arbetsflödet för enskild sändning för varje paket du behöver skicka i dag, för att skapa sändningen och dess fraktetikett. Koppla sedan sändningen till batchen med någon av metoderna nedan.

Alternativ A: Koppla vid tidpunkten för fraktetikettskapande

Skicka med konsolideringens ID i kedjans sista shipmentCreateWorkflow-steg. Alla föregående mutationer i kedjan är identiska med arbetsflödet för enskild sändning.

De relevanta fälten på shipmentCreateWorkflow:

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

Alternativ B: Koppla befintliga sändningar via ID

Om dina sändningar redan är skapade och har fraktetiketter kan du lägga till dem i den öppna batchen med shipmentIds i shipmentConsolidationUpdate:

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

Utelämna status i indata medan du fortfarande lägger till sändningar — batchen förblir OPEN. Varje sändning måste använda en Japan Post-tjänstenivå och ha sin fraktetikett (spårningsnummer) innan batchen stängs i steg 3.

Vad kopplingen innebär för fraktetiketten

Oavsett vilket alternativ du använder gäller följande när en Japan Post-sändning ingår i en konsolidering:

• Sändningen har ett spårningsnummer, precis som vanligt.
• Fraktetikettens PDF innehåller inte kvittokopiorna för kund/postkontor. Dessa kvitton skjuts upp till steg 3, där de samlas i avsändningskvittots dokument för hela batchen.
• Sändningen är kopplad till konsolideringen; du kan fråga om den igen via shipmentConsolidation(id: ...) för att se dess medlemmar.

Upprepa det här steget för varje paket i dagens batch. Upp till 250 sändningar per konsolidering; ett försök att stänga en större batch misslyckas med ett tydligt valideringsfel innan något anrop görs till Japan Post.

Du kan även verifiera batchens innehåll innan du stänger den:

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

Varje sändning bör visa ett spårningsnummer här. Om någon inte gör det har dess fraktetikett aldrig skapats — åtgärda det innan du stänger. status är OPEN fram till konsolideringen stängs i steg 3.

Steg 3: shipmentConsolidationUpdate(status: CLOSED) 

Stänger batchen. Det här är anropet som ber Japan Post generera avsändningskvittot med uppskjuten betalning som täcker samtliga medlemmars spårningsnummer, och kopplar den resulterande PDF-filen till konsolideringen.

GraphQL-operationen heter CloseConsolidation för att beskriva sitt syfte, att stänga batchen. Den kör mutationen shipmentConsolidationUpdate med status: CLOSED.

Mutation:

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

Vid en CLOSED-begäran:

1. Konsolideringen valideras: ≤250 sändningar, och varje medlem måste ha ett spårningsnummer. Om en sändning saknar spårningsnummer (dess fraktetikett skapades aldrig) avvisas anropet.
2. Japan Post ombeds generera ett avsändningskvitto med uppskjuten betalning som täcker samtliga medlemmars spårningsnummer.
3. Statusen övergår tillfälligt till MANIFEST_CREATED medan kvittots PDF hämtas, och sedan till CLOSED när dokumentet har kopplats.
4. Avsändningskvittots PDF (en fil som innehåller kvittot samt kund-/postkontorskvittona för varje medlem) kopplas till konsolideringen som ett 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"
        }
      ]
    }
  }
}

Hämta dokumenten

Avsändningskvittot kopplas direkt till konsolideringen som ett CustomsDocument med documentType: MANIFEST_DOCUMENT — hämta fileUrl från stängningssvaret ovan, eller fråga om det när som helst senare:

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

Skriv ut PDF-filen på fileUrl. Den innehåller:

• Sida 1: Avsändningskvittot med uppskjuten betalning (後納差出票) — lämna det här till postkontoret. Varje sändning i batchen listas här, oavsett vilken tjänstenivå den använde.
• Sida 2 och framåt: Kund-/postkontorskvittona — ett häftat på varje paket, det andra behålls av postkontoret. Dessa sidor genereras endast för EMS- och International Parcel-sändningar, eftersom de är kopplade till ett spårningsnummer.

När det är utskrivet tar du med paketen, avsändningskvittot och kvittona till postkontoret i en och samma tur. Japan Post fakturerar ditt Later Pay Number vid faktureringsperiodens slut.

En sändning på sida 1 utan kvittosida är inte en saknad sändning. Small Packet (小形包装物) är inte en spårad Japan Post-tjänst, så den listas på sida 1 men får ingen kvittosida på sida 2 och framåt. En batch med fem paket kan helt korrekt ge en sida 1 som listar samtliga fem samt kvittosidor endast för EMS- och Parcel-sändningarna, och en batch med enbart Small Packet-sändningar ger en sida 1 och inga ytterligare sidor alls. Det här är förväntat beteende hos Japan Post, inte en misslyckad fraktetikett eller ett misslyckat manifestanrop. Du behöver inte öppna en separat konsolidering per tjänstenivå. Bekräftat med Japan Post, augusti 2026.

Sätta ihop allt 

En representativ dag för en handlare som skickar 50 Japan Post-paket kan se ut så här:

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

Föredrar du att batcha i slutet av dagen i stället? Skapa dagens fraktetiketter utan konsolideringsID, öppna sedan konsolideringen en gång med samtliga shipmentIds-värden (eller lägg till dem i omgångar via shipmentConsolidationUpdate), och stäng den i samma anrop eller i ett senare.

Om du skickar över flera affärsenheter/faktureringskonton kör du en separat konsolidering per konto — skicka med ett annat accountNumber i varje shipmentConsolidationCreate och dirigera sändningarna därefter. Skickar du fler än 250 paket på en dag? Öppna en andra konsolidering.

Felhantering 

Valideringsfel (fångas innan något anrop till Japan Post)

• accountNumber felaktigt formaterat — avvisas i steg 1 (shipmentConsolidationCreate) innan konsolideringen ens har sparats. Felmeddelandet identifierar det felaktiga segmentet.
• Fler än 250 sändningar — avvisas i steg 3, innan anropet till Japan Post görs.
• Medlemssändning saknar spårningsnummer — avvisas i steg 3. Innebär att ett skapande av fraktetikett misslyckades tyst tidigare; undersök den berörda sändningen via shipment(id: ...) { trackingDetails }.
• Inget nummer för uppskjuten betalning angivet på konsolideringen — avvisas i steg 3. Skicka med accountNumber i shipmentConsolidationCreate, eller spara ett standardkontonummer på ditt Japan Post-transportörskonto.

Japan Post API-fel

Om Japan Post avvisar begäran om avsändningskvitto exponerar stängningsmutationen transportörens felkod och meddelande som ett GraphQL-fel. De vanligaste:

Nya försök

Om stängningsanropet misslyckas efter att Japan Post har accepterat begäran om avsändningskvitto (dvs. under hämtningen av PDF-filen) är det säkert att försöka igen med shipmentConsolidationUpdate(status: CLOSED) — plattformen hoppar då över anropet till transportören och försöker bara hämta och koppla dokumentet på nytt.

Om stängningen misslyckas innan Japan Post har accepterat begäran (valideringsfel, E0xx, timeout i nätverket) har inget tillstånd ändrats — åtgärda grundorsaken och försök igen.