Crea un'unica spedizione

CreateDeclarationShipment concatena sei mutazioni *Workflow in un'unica richiesta GraphQL. Ogni passaggio si basa sui dati forniti dai passaggi precedenti e vengono inviati tutti insieme, in modo da poter creare una spedizione completa in un solo round trip:

partyCreateWorkflow            → describe origin + destination parties
itemCreateWorkflow             → describe the line items
cartonsCreateWorkflow          → describe the physical packaging
shipmentRatingCreateWorkflow   → record the carrier rate quote
landedCostCalculateWorkflow    → calculate duties / taxes / fees
shipmentCreateWorkflow         → create the shipment + label

Le mutazioni Workflow sono progettate per essere concatenate: non è necessario passare gli ID da un passaggio all'altro né inviare una richiesta separata per ogni passaggio. Invia l'intero documento e ottieni indietro lo Shipment finale.

Quando il serviceLevel dell'ultimo passaggio è un livello di servizio Japan Post (japan_post.*), Zonos chiama per tuo conto l'API etichette di Japan Post (codice 52) utilizzando i Later Pay Number del tuo Verified Account, genera l'etichetta e il numero di tracciamento, crea il Declaration ID e li collega — tutto all'interno di quello stesso passaggio finale shipmentCreateWorkflow.

Perché un'unica mutazione? Ogni passaggio dipende dal precedente (il costo allo sbarco richiede gli articoli e le parti; l'etichetta richiede tutto). Raggruppare tutto in un unico documento GraphQL mantiene i dati coerenti ed evita cinque round trip aggiuntivi.

Endpoint e autenticazione 

Le richieste di questa catena usano tutte lo 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}}

Richiesta di esempio 

Una richiesta CreateDeclarationShipment completa che puoi copiare e adattare — la mutazione, le sue variabili e la risposta — per una singola spedizione Japan Post inviata in DDP verso gli Stati Uniti. Ogni input viene descritto nel dettaglio nella sezione passo-passo qui sotto.

Passo per passo 

La colonna Status in ciascuna tabella qui sotto usa questi termini:

• Obbligatorio — la richiesta fallisce senza questo campo.
• Obbligatorio per l'etichetta — facoltativo nello schema GraphQL, ma necessario per produrre un'etichetta Japan Post statunitense valida.
• Condizionale — obbligatorio in base a un altro campo (indicato nella nota).
• Consigliato — facoltativo, ma determina dazi e tasse accurati.
• Facoltativo — non necessario.

1. partyCreateWorkflow

Crea le parti coinvolte nella spedizione — come minimo un ORIGIN (da dove parte la spedizione) e un DESTINATION (l'acquirente / destinatario).

Example payload:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

La risposta restituisce gli ID Party creati e i campi indirizzo risolti.

2. itemCreateWorkflow

Crea le righe articolo che compongono la spedizione. Sono gli SKU che compariranno sulla fattura commerciale e che determinano il calcolo del costo allo sbarco.

Il codice HS, il paese di origine e l'importo sono i tre campi che influenzano maggiormente l'esito di dazi/tasse nel passaggio 5.

3. cartonsCreateWorkflow

Crea i colli fisici — le scatole, i polybag o le buste che conterranno gli articoli.

Ogni collo diventa un pacco sull'etichetta del corriere nel passaggio 6. Più colli → spedizione multi-collo con un numero di tracciamento per collo.

4. shipmentRatingCreateWorkflow

Registra il preventivo tariffario che il commerciante addebita all'acquirente per la spedizione.

Questa è la tariffa proposta all'acquirente al checkout. Confluisce nel calcolo del costo allo sbarco come subtotale "shipping", così dazi e tasse vengono calcolati sul valore CIF corretto.

5. landedCostCalculateWorkflow

Esegue il calcolo di dazi, tasse e commissioni per il paese di destinazione. Utilizza gli articoli, le parti e il costo di spedizione dei passaggi precedenti.

La risposta include amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — questi sono i valori che mostri all'acquirente al checkout e che vengono stampati sulla fattura commerciale.

6. shipmentCreateWorkflow

Il passaggio finale — crea la Shipment, genera l'etichetta del corriere e (facoltativamente) la fattura commerciale / packing slip.

Per i Verified Account Japan Post, è anche qui che Zonos chiama per tuo conto l'API etichette di Japan Post (codice 52), inserisce i tuoi Later Pay Number, crea il Declaration ID e collega il Declaration ID al numero di tracciamento restituito da Japan Post.

Campi principali:

Per contentsType, i due valori più comuni per il traffico dei Verified Account sono ECOMMERCE_GOODS (venduto a un consumatore, BtoC) e COMMERCIAL_GOODS (venduto tra aziende, BtoB). Questi valori determinano il pkgType che Zonos invia nella chiamata all'etichetta Japan Post, quindi la scelta cambia ciò che viene stampato sulla dichiarazione doganale — non è solo una questione di etichetta.

Sotto-input nonDelivery

Indica a Japan Post cosa fare del pacco se non può essere consegnato — rifiutato dal destinatario, respinto alla frontiera o non recapitabile all'indirizzo indicato.

option accetta esattamente questi quattro valori. Non esiste un valore RETURN — usa RETURN_AFTER_RETENTION o RETURN_IMMEDIATELY per scegliere quando il pacco torna indietro.

L'API espone separatamente entrambe le varianti di reso; l'opzione Return della Dashboard le copre entrambe.

transportMethod accetta AIR o MOST_ECONOMICAL e determina come viaggia un pacco reso. Si applica solo alle due opzioni RETURN_* — la Dashboard mostra il campo Return method corrispondente solo quando è selezionato Return.

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

Il selettore If undeliverable nella finestra di dialogo Create label della Dashboard scrive esattamente questo stesso campo, quindi un'etichetta creata dalla Dashboard e una creata tramite API si comportano in modo identico.

Sotto-input references

Questi campi vengono stampati sull'etichetta del corriere e/o sulla fattura commerciale. Usali per riportare numeri di ordine d'acquisto, numeri di licenza e note in testo libero che il destinatario o l'autorità doganale devono vedere.

Response

I campi rilevanti sullo Shipment restituito sono:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number è il numero di tracciamento Japan Post.

L'oggetto label può restituire l'etichetta in due modi — richiedi quello più adatto al tuo workflow (o entrambi):

Seleziona solo i campi di cui hai bisogno. Richiedere url mantiene la risposta compatta; richiedere labelImage restituisce l'etichetta completa inline, così non serve un secondo round trip per recuperarla. L'esempio sopra richiede url.

Livelli di servizio Japan Post 

Passa uno di questi codici come serviceLevelCode in shipmentRatingCreateWorkflow.

I codici dei livelli di servizio usano punti, non underscore. Potresti vedere la forma con underscore (japan_post_air_parcel) nei messaggi di errore e nei riferimenti interni, ma non è un input valido.

Servizi aerei

Servizi di superficie

Scegliere tra servizi simili

Small packet vs. International Air Packet. Entrambi hanno un limite di 2 kg. japan_post.air.packet è il servizio small-packet tracciato di Japan Post. japan_post.air.small_packet è l'equivalente non tracciato. Se ti serve il tracciamento su un pacco leggero, usa japan_post.air.packet.

Varianti raccomandate. Per lettere e stampe, il tracciamento viene aggiunto dalla versione raccomandata (書留) del servizio. japan_post.air.printed_matter e japan_post.air.letter non lo includono da soli.

Codici deprecati

japan_post.air.epacket_light era International e-Packet Light. Japan Post ha rinominato il servizio in International Air Packet il 1° giugno 2026, estendendolo a tutti i paesi e le regioni. Il servizio in sé è rimasto invariato.

Il vecchio codice continua a essere risolto, così le integrazioni esistenti continuano a funzionare, ma per i nuovi sviluppi usa japan_post.air.packet.

Codici di modalità di trasporto

Anche japan_post.air, japan_post.surface, japan_post.economy_air e japan_post.custom vengono risolti, ma identificano una modalità di trasporto o un fallback, non un prodotto postale specifico. Per le spedizioni normali usa uno dei codici servizio elencati sopra.

Convalida il codice che invii

Un serviceLevelCode non riconosciuto non genera un errore. La richiesta restituisce HTTP 200 senza array errors, serviceLevel torna null e il costo di spedizione esce dal totale del costo allo sbarco — quindi la risposta sembra corretta mentre gli importi sono sbagliati.

Verifica sempre che shipmentRatingCreateWorkflow.serviceLevel non sia nullo prima di fare affidamento sui totali.

Per recuperare l'elenco aggiornato in qualsiasi momento:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

Questa query richiede l'ID del corriere. Passare il codice corriere japan_post restituisce un elenco vuoto senza errori.

Gestione degli errori 

• Gli errori di convalida (campi obbligatori mancanti, codici paese non validi, ecc.) vengono restituiti nel consueto array GraphQL errors e interrompono il resto della catena.
• Gli errori Japan Post (errore nella generazione dell'etichetta, indirizzo non valido, ecc.) compaiono come errori GraphQL su shipmentCreateWorkflow. Se è necessario un nuovo tentativo, contatta l'assistenza — il percorso consigliato è inviare di nuovo l'intera mutazione con l'input corretto.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

Questo errore indica l'intera variabile, non il campo che in realtà è sbagliato. Nella quasi totalità dei casi significa che un valore enum all'interno di quella variabile non appartiene al suo enum — più spesso nonDelivery.option, contentsType o serviceLevel.

Non è un problema di tipizzazione JSON. Mettere o togliere le virgolette da booleani e numeri non risolve nulla, perché il payload non arriva nemmeno a quel punto: l'enum viene respinto prima.

Per trovare il campo sbagliato, controlla ogni campo di tipo enum nella variabile rispetto ai suoi valori accettati:

L'elenco completo dei membri dell'enum per qualsiasi input è disponibile nella pagina del suo tipo nella documentazione API.

Autorizzazioni 

Ogni passaggio è protetto in modo indipendente. La tua API key deve avere lo scope di scrittura per ogni entità della catena (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Il ruolo commerciante standard su un Verified Account concede tutti questi scope.

Passaggi successivi 

• Invio in batch (consolidamento) — raggruppa i pacchi della giornata in un'unica distinta di spedizione a pagamento differito Japan Post.