Invio batch (consolidamento)

Questo documento illustra il flusso in tre fasi per la creazione di un Japan Post batch di spedizione con pagamento differito tramite Zonos GraphQL API: aprire un consolidamento, allegare n spedizioni ad esso, quindi chiuderlo per ricevere la bolla 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 alla fine della giornata, anziché per pacco al momento della consegna. Il commerciante porta tutti i pacchi della giornata all'ufficio postale insieme a una distinta di spedizione (差出票) che copre fino a 250 spedizioni. Le spese di spedizione vengono fatturate al Later Pay Number preregistrato dal commerciante.

Se spedisci etichette Japan Post individuali e paghi pacco per pacco allo sportello, non hai bisogno di questo flusso: chiama il catena di spedizione singola direttamente senza 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: utilizza quello che si adatta alla tua integrazione (o mescolali):

• Allega al momento della creazione dell'etichetta: inserisci in ciascuna l'ID di consolidamento del passaggio 1 shipmentCreateWorkflow chiamare tramite il shipmentConsolidationId campo.
• Allega le spedizioni esistenti tramite ID — pass shipmentIds SU shipmentConsolidationCreate (per seminare il lotto) o su shipmentConsolidationUpdate (da aggiungere a un batch aperto). Ogni spedizione deve già avere la sua etichetta Japan Post.

In ogni caso, ogni etichetta viene creata con il numero di pagamento successivo incorporato in modo che Japan Post la accetterà sulla ricevuta di spedizione quando il passaggio 3 chiude il lotto.

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

Prerequisiti 

Prima che questo flusso funzioni per un determinato account verificato:

• Il tuo account deve avere un numero di pagamento differito Japan Post per pagamento differito (後納お客様番号) salvato su di esso: un valore formattato da un trattino come 1111111111-222222-3333333333-444444. Passamelo shipmentConsolidationCreate tramite accountNumber (Passaggio 1).
• La tua chiave API deve contenere SHIPMENT_WRITE, oltre agli ambiti standard richiesti dal flusso di lavoro per 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 tua scheda.

URL:

https://api.zonos.com/graphql

Intestazioni:

credentialToken: {{YOUR_API_TOKEN}}

Richiesta di esempio 

Un esempio di copia e adattamento di apertura di un consolidamento: la mutazione, le sue variabili e la risposta. Questa è la chiamata specifica del batch che avvia il flusso; allegando le spedizioni (Passaggio 2) si riutilizza il file esempio di spedizione singolae la chiusura del batch (passaggio 3) restituisce il documento manifest. Ogni campo è suddiviso 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à etichettato le spedizioni, semina il batch con i loro ID tramite shipmentIds — altrimenti crealo vuoto e allega le spedizioni al punto 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..." }
      ]
    }
  }
}

Tieni duro il id (per esempio. shco_01HJK...) - lo utilizzerai per tutto ciò che segue. IL status È OPEN fino al passaggio 3.

Passaggio 2: allega le spedizioni 

Per ogni pacco che devi spedire oggi, esegui l'intera catena flusso di lavoro a 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 sul finale shipmentCreateWorkflow passo della catena. Tutte le mutazioni precedenti nella catena sono identiche al flusso di lavoro a spedizione singola.

I campi pertinenti su shipmentCreateWorkflow:

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

Opzione B: allega le spedizioni esistenti per 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
    }
  }
}

Partire status dall'input mentre stai ancora aggiungendo le spedizioni: il lotto rimane OPEN. Ogni spedizione deve utilizzare un livello di servizio Japan Post e avere la propria etichetta (numero di tracciabilità) prima che il lotto venga chiuso nella fase 3.

Cosa significa allegato per l'etichetta

Qualunque sia l'opzione utilizzata, quando una spedizione Japan Post fa parte di un consolidamento:

• La spedizione ha un numero di tracciabilità, come al solito.
• L'etichetta di spedizione PDF non include le copie della ricevuta cliente/postale. Tali ricevute vengono rinviate alla fase 3, dove vengono raggruppate nel documento di accompagnamento dell'intero lotto.
• La spedizione è associata al consolidamento; puoi ripetere la query tramite shipmentConsolidation(id: ...) per vedere i suoi membri.

Ripeti questo passaggio per ogni pacco del lotto del giorno. 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 Japan Post.

Puoi anche verificare il contenuto del batch prima della chiusura:

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

Ogni spedizione dovrebbe mostrare un numero di tracciamento qui. In caso contrario, la sua etichetta non è mai stata creata: risolvilo prima di chiudere. status È OPEN fino alla chiusura del consolidamento nel passaggio 3.

Passaggio 3: shipmentConsolidationUpdate(status: CLOSED) 

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

L'operazione GraphQL viene denominata CloseConsolidation per descrivere il suo intento, chiudendo il batch. Gestisce il shipmentConsolidationUpdate mutazione con status: CLOSED.

Mutazione:

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

On a CLOSED richiesta:

1. Il consolidamento è convalidato: ≤250 spedizioni e ogni membro deve avere un numero di tracciabilità. Se ad una spedizione manca il numero di tracciabilità (la sua etichetta non è mai stata creata), la chiamata viene rifiutata.
2. A Japan Post viene chiesto di generare una ricevuta di pagamento differito che copra il numero di tracciamento di ogni membro.
3. Lo stato passa brevemente a MANIFEST_CREATED mentre viene recuperato il tagliando PDF, quindi a CLOSED una volta allegato il documento.
4. La ricevuta di spedizione PDF (un file contenente la ricevuta più le ricevute cliente/ufficio postale di ogni membro) è allegata 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 bolla di spedizione è allegata direttamente al consolidamento come a CustomsDocument con documentType: MANIFEST_DOCUMENT - prendi il fileUrl dalla risposta chiusa sopra, oppure chiedilo in qualsiasi momento successivo:

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

Stampa il PDF a fileUrl. Contiene:

• Pagina 1: La polizza di spedizione per pagamento differito: consegnatela all'ufficio postale.
• Pagine 2+: Le ricevute del cliente/ufficio postale per ciascun pacco: una pinzata su ciascun pacco, l'altra conservata dall'ufficio postale.

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

Mettendo insieme il tutto 

Un giorno rappresentativo per un commerciante che spedisce 50 pacchi Japan Post è il seguente:

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 eseguire il batch a fine giornata? Crea le etichette del giorno senza un ID di consolidamento, quindi apri il consolidamento una volta alla volta shipmentIds value (o aggiungerli in blocchi tramite shipmentConsolidationUpdate) e chiuderlo nella stessa chiamata o in una chiamata successiva.

Se effettui spedizioni tra più unità aziendali/account di fatturazione, esegui un consolidamento separato per account: passane uno diverso accountNumber su ciascuno shipmentConsolidationCreate e instradare le spedizioni di conseguenza. Spedisci più di 250 pacchi in un giorno? Aprire un secondo consolidamento.

Gestione degli errori 

Errori di validazione (rilevati prima di qualsiasi chiamata Japan Post)

• accountNumber formato non valido — rifiutato al passaggio 1 (shipmentConsolidationCreate) prima ancora che il consolidamento venga salvato. Il messaggio di errore identifica il segmento offensivo.
• >250 spedizioni: rifiutate al passaggio 3, prima che venga effettuata la chiamata Japan Post.
• Spedizione membro priva di numero di tracciabilità: rifiutata al passaggio 3. Significa che la creazione silenziosa di un'etichetta non è riuscita in precedenza; indagare sulla spedizione interessata tramite shipment(id: ...) { trackingDetails }.
• Nessun numero di pagamento differito impostato nel consolidamento — rifiutato al passaggio 3. Superato accountNumber SU shipmentConsolidationCreate, or save a default account number on your Japan Post carrier account.

Japan Post API errors

If Japan Post rejects the dispatch slip request, the close mutation surfaces the carrier's error code and message as a GraphQL error. The most common:

Retries

If the close call fails after Japan Post has accepted the dispatch slip request (i.e. during PDF retrieval), retrying shipmentConsolidationUpdate(status: CLOSED) è sicuro: la piattaforma salterà la chiamata dell'operatore e tenterà semplicemente di recuperare e allegare il documento.

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