Invio batch (consolidamento)

Questo documento descrive il flusso in tre fasi per creare un batch di spedizione con pagamento differito di Japan Post tramite l'API GraphQL di Zonos: aprire un consolidamento, allegarvi n spedizioni, quindi chiuderlo per ricevere la distinta di spedizione di Japan Post (documento manifest).

Quando utilizzare questo flusso 

Il programma di pagamento differito (後納) di Japan Post consente al commerciante di saldare la fattura di spedizione giornaliera in un'unica transazione a fine giornata, anziché pacco per pacco al momento della consegna. Il commerciante porta tutti i pacchi della giornata all'ufficio postale insieme a un'unica distinta di spedizione (差出票) che copre fino a 250 spedizioni. Le spese di spedizione vengono fatturate al Later Pay Number pre-registrato dal commerciante.

Se spedisci singole etichette Japan Post pagando pacco per pacco allo sportello, non hai bisogno di questo flusso: richiama direttamente la catena di spedizione singola senza un consolidamento.

Panoramica 

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)

Esistono due modi per allegare le spedizioni al batch: usa quello più adatto alla tua integrazione (o combinali):

• Allega al momento della creazione dell'etichetta — inserisci l'ID di consolidamento ottenuto al passaggio 1 in ogni chiamata shipmentCreateWorkflow tramite il campo shipmentConsolidationId.
• Allega spedizioni esistenti tramite ID — passa shipmentIds su shipmentConsolidationCreate (per popolare il lotto) oppure su shipmentConsolidationUpdate (per aggiungerle a un lotto aperto). Ogni spedizione deve già avere la propria etichetta Japan Post.

In entrambi i casi, ogni etichetta viene creata con il tuo Later Pay Number incorporato, in modo che Japan Post la accetti nella distinta di spedizione quando il lotto viene chiuso al passaggio 3.

Perché chiamate separate invece di un'unica mutazione? I passaggi 2.1, 2.2, ..., 2.n si susseguono nell'arco della giornata del commerciante: le etichette vengono stampate e i pacchi sigillati man mano che arrivano gli ordini. Il batch non può essere un'unica chiamata di andata e ritorno come nella catena di spedizione singola: tra l'apertura del consolidamento e la sua chiusura intercorrono diverse ore.

Prerequisiti 

Prima che questo flusso funzioni per un determinato account verificato:

• Il tuo account deve avere salvato un Later Pay Number per il pagamento differito di Japan Post (後納お客様番号) — un valore con trattini come 1111111111-222222-3333333333-444444. Passalo su shipmentConsolidationCreate tramite accountNumber (Passaggio 1).
• La tua chiave API deve avere l'ambito SHIPMENT_WRITE, oltre agli ambiti standard richiesti dal flusso di lavoro per la singola spedizione.

Endpoint e autenticazione 

Tutti e tre i passaggi seguenti sono operazioni GraphQL inviate allo stesso endpoint. Ciò che passi nelle intestazioni dipende dalla tua configurazione: scegli la scheda che ti riguarda.

URL:

https://api.zonos.com/graphql

Intestazioni:

credentialToken: {{YOUR_API_TOKEN}}

Esempio di richiesta 

Un esempio pronto da copiare e adattare per l'apertura di un consolidamento: la mutazione, le sue variabili e la risposta. Questa è la chiamata specifica del batch che avvia il flusso; l'aggiunta delle spedizioni (Passaggio 2) riutilizza l'esempio di spedizione singola, e la chiusura del batch (Passaggio 3) restituisce il documento manifest. Ogni campo è descritto nei passaggi seguenti.

Passaggio 1: shipmentConsolidationCreate 

Apre il consolidamento. Il codice trasportatore blocca il lotto su Japan Post: tutte le spedizioni dei membri devono utilizzare i livelli di servizio Japan Post. Se hai già spedizioni con etichetta pronte, popola il batch con i loro ID tramite shipmentIds — altrimenti crealo vuoto e allega le spedizioni al passaggio 2.

Mutazione:

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

Risposta:

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

Conserva l'id (ad es. shco_01HJK...) — lo utilizzerai per tutto ciò che segue. Lo status resta OPEN fino al passaggio 3.

Passaggio 2: allega le spedizioni 

Per ogni pacco da spedire oggi, esegui l'intera catena di spedizione singola per creare la spedizione e la relativa etichetta. Quindi allega la spedizione al batch utilizzando uno dei metodi seguenti.

Opzione A: allega al momento della creazione dell'etichetta

Passa l'ID di consolidamento nell'ultimo passaggio shipmentCreateWorkflow della catena. Tutte le mutazioni precedenti della catena sono identiche a quelle del flusso di spedizione singola.

I campi rilevanti su shipmentCreateWorkflow:

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

Opzione B: allega spedizioni esistenti tramite ID

Se le tue spedizioni sono già create ed etichettate, aggiungile al batch aperto con shipmentIds su shipmentConsolidationUpdate:

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

Lascia status fuori dall'input finché stai ancora aggiungendo spedizioni: il lotto resta OPEN. Ogni spedizione deve utilizzare un livello di servizio Japan Post e avere la propria etichetta (numero di tracciamento) prima che il lotto venga chiuso al passaggio 3.

Cosa significa l'aggiunta per l'etichetta

Qualunque opzione tu utilizzi, quando una spedizione Japan Post fa parte di un consolidamento:

• La spedizione ha comunque un numero di tracciamento.
• Il PDF dell'etichetta di spedizione non include le copie della ricevuta per il cliente/ufficio postale. Queste ricevute vengono rimandate al passaggio 3, dove vengono incluse nel documento di distinta di spedizione dell'intero batch.
• La spedizione è associata al consolidamento; puoi interrogarla di nuovo tramite shipmentConsolidation(id: ...) per vederne i membri.

Ripeti questo passaggio per ogni pacco del batch della giornata. Fino a 250 spedizioni per consolidamento; il tentativo di chiudere un batch più grande fallisce con un chiaro errore di convalida prima che venga effettuata qualsiasi chiamata a Japan Post.

Puoi anche verificare il contenuto del batch prima di chiuderlo:

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

Ogni spedizione dovrebbe mostrare qui un numero di tracciamento. Se non lo mostra, la sua etichetta non è mai stata creata: risolvi il problema prima di chiudere. Lo status resta OPEN fino alla chiusura del consolidamento al passaggio 3.

Passaggio 3: shipmentConsolidationUpdate(status: CLOSED) 

Chiude il batch. Questa è la chiamata che chiede a Japan Post di generare la distinta di spedizione con pagamento differito che copre il numero di tracciamento di ogni membro, e allega il PDF risultante al consolidamento.

L'operazione GraphQL si chiama CloseConsolidation per descriverne l'intento, ossia chiudere il batch. Esegue la mutazione shipmentConsolidationUpdate con status: CLOSED.

Mutazione:

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

In una richiesta CLOSED:

1. Il consolidamento viene convalidato: massimo 250 spedizioni, e ogni membro deve avere un numero di tracciamento. Se a una spedizione manca il numero di tracciamento (la sua etichetta non è mai stata creata), la chiamata viene rifiutata.
2. A Japan Post viene chiesto di generare una distinta di spedizione con pagamento differito che copra il numero di tracciamento di ogni membro.
3. Lo stato passa brevemente a MANIFEST_CREATED mentre il PDF della distinta viene recuperato, quindi a CLOSED una volta allegato il documento.
4. Il PDF della distinta di spedizione (un unico file contenente la distinta più le ricevute cliente/ufficio postale di ogni membro) viene allegato al consolidamento come CustomsDocument con documentType: MANIFEST_DOCUMENT.

Risposta:

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

Recupero dei documenti

La distinta di spedizione è allegata direttamente al consolidamento come CustomsDocument con documentType: MANIFEST_DOCUMENT — prendi il fileUrl dalla risposta di chiusura riportata sopra, oppure interrogalo in qualsiasi momento successivo:

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

Stampa il PDF all'indirizzo fileUrl. Contiene:

• Pagina 1: la distinta di spedizione con pagamento differito (後納差出票) — consegnala all'ufficio postale. Ogni spedizione del batch è elencata qui, indipendentemente dal livello di servizio utilizzato.
• Pagine 2+: le ricevute cliente/ufficio postale — una da graffare a ciascun pacco, l'altra trattenuta dall'ufficio postale. Queste pagine vengono generate solo per le spedizioni EMS e International Parcel, perché sono associate a un numero di tracciamento.

Una volta stampato, porta i pacchi, la distinta di spedizione e le ricevute all'ufficio postale in un unico viaggio. Japan Post fattura il tuo Later Pay Number alla fine del periodo di fatturazione.

Una spedizione in pagina 1 priva di pagina di ricevuta non è una spedizione mancante. Lo Small Packet (小形包装物) non è un servizio Japan Post tracciato, quindi viene elencato in pagina 1 e non riceve alcuna pagina di ricevuta 2+. Un batch di cinque pacchi può legittimamente produrre una pagina 1 che li elenca tutti e cinque e pagine di ricevuta solo per quelli EMS e Parcel, mentre un batch composto esclusivamente da Small Packet produce solo una pagina 1 e nessun'altra pagina. Questo è il comportamento previsto di Japan Post, non un'etichetta non riuscita né una chiamata manifest fallita. Non è necessario aprire un consolidamento separato per livello di servizio. Confermato con Japan Post, agosto 2026.

Mettere tutto insieme 

Una giornata tipo per un commerciante che spedisce 50 pacchi Japan Post si presenta così:

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

Preferisci invece raggruppare il tutto a fine giornata? Crea le etichette della giornata senza un ID di consolidamento, quindi apri il consolidamento una sola volta con tutti i valori di shipmentIds (oppure aggiungili a blocchi tramite shipmentConsolidationUpdate) e chiudilo nella stessa chiamata o in una successiva.

Spedisci per più unità aziendali/account di fatturazione? Esegui un consolidamento separato per ciascun account: passa un accountNumber diverso su ogni shipmentConsolidationCreate e instrada le spedizioni di conseguenza. Spedisci più di 250 pacchi al giorno? Apri un secondo consolidamento.

Gestione degli errori 

Errori di convalida (rilevati prima di qualsiasi chiamata a Japan Post)

• accountNumber non valido — rifiutato al passaggio 1 (shipmentConsolidationCreate) prima ancora che il consolidamento venga salvato. Il messaggio di errore identifica il segmento non valido.
• Più di 250 spedizioni — rifiutato al passaggio 3, prima che venga effettuata la chiamata a Japan Post.
• Spedizione membro priva di numero di tracciamento — rifiutato al passaggio 3. Significa che la creazione di un'etichetta è fallita silenziosamente in precedenza; verifica la spedizione interessata tramite shipment(id: ...) { trackingDetails }.
• Nessun numero per il pagamento differito impostato sul consolidamento — rifiutato al passaggio 3. Passa accountNumber su shipmentConsolidationCreate, oppure salva un numero account predefinito sul tuo account trasportatore Japan Post.

Errori dell'API di Japan Post

Se Japan Post rifiuta la richiesta di distinta di spedizione, la mutazione di chiusura restituisce il codice di errore e il messaggio del corriere come errore GraphQL. I più comuni:

Nuovi tentativi

Se la chiamata di chiusura fallisce dopo che Japan Post ha accettato la richiesta di distinta di spedizione (cioè durante il recupero del PDF), ritentare shipmentConsolidationUpdate(status: CLOSED) è sicuro: la piattaforma salterà la chiamata al corriere e tenterà semplicemente di recuperare e allegare di nuovo il documento.

Se la chiusura fallisce prima che Japan Post abbia accettato la richiesta (errore di convalida, E0xx, timeout di rete), nessuno stato è cambiato: correggi la causa principale e riprova.