Crea un'unica spedizione

CreateDeclarationShipment catene insieme sei *Workflow mutazioni in una singola richiesta GraphQL. Ogni passaggio si basa sui dati forniti dai passaggi precedenti e tutti vengono inviati insieme in modo che sia possibile creare una spedizione completa in un unico viaggio di andata e ritorno:

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

IL Workflow le mutazioni sono progettate per essere concatenate: non è necessario infilare gli ID da un passaggio a quello successivo e non è necessario inviare una richiesta separata per passaggio. Invia l'intero documento, ottieni il finale Shipment Indietro.

Quando il serviceLevel nella fase finale c'è un livello di servizio Japan Post (japan_post.*), Zonos chiama l'etichetta Japan Post API (codice 52) per tuo conto utilizzando i numeri di pagamento successivi del tuo account verificato, genera l'etichetta e il numero di tracciamento, crea l'ID dichiarazione e li collega, il tutto all'interno di quell'etichetta finale shipmentCreateWorkflow fare un passo.

Perché una mutazione? Ogni passaggio dipende dal precedente (il costo allo sbarco richiede gli articoli + le parti; l'etichetta richiede tutto). Raggrupparli in un unico documento GraphQL mantiene i dati coerenti ed evita cinque viaggi di andata e ritorno aggiuntivi.

Endpoint e autenticazione 

Le richieste in questa catena utilizzano tutte lo 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 completo CreateDeclarationShipment richiesta che puoi copiare e adattare (la mutazione, le sue variabili e la risposta) per un singolo pacco Japan Post spedito DDP negli Stati Uniti. Ogni input è suddiviso nella sezione passo passo di seguito.

Passo dopo passo 

Il Status colonna in ciascuna tabella seguente utilizza questi termini:

• Obbligatorio: senza di esso la richiesta fallisce.
• Obbligatorio per l'etichetta: facoltativo nello schema GraphQL, ma necessario per produrre un'etichetta statunitense Japan Post valida.
• Condizionale: richiesto in base a un altro campo (annotato in linea).
• Consigliato: facoltativo, ma prevede dazi e tasse accurati.
• Facoltativo: non necessario.

1. partyCreateWorkflow

Crea le parti coinvolte nella spedizione, come minimo an ORIGIN (da dove viene spedita la spedizione) e a DESTINATION (the buyer / consignee).

Example payload:

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

La risposta restituisce il file create Party ID e campi indirizzo risolti.

2. itemCreateWorkflow

Creates the line items that make up the shipment. These are the SKUs that will appear on the commercial invoice and drive the landed-cost calculation.

The HS code, country of origin, and amount are the three fields that most influence the duty/tax outcome in step 5.

3. cartonsCreateWorkflow

Creates the physical packages — the boxes, polybags, or letters that will hold the items.

Ogni cartone diventa un pacco sull'etichetta del corriere al punto 6. Cartoni multipli → spedizione in più pezzi con un numero di tracciabilità per cartone.

4. shipmentRatingCreateWorkflow

Records the rate quote the merchant is charging the buyer for shipping.

This is the rate the buyer was quoted at checkout. It feeds into the landed-cost calculation as the "shipping" subtotal so duties and taxes are computed against the correct CIF value.

5. landedCostCalculateWorkflow

Runs the duties, taxes, and fees calculation for the destination country. Uses the items, parties, and shipping cost from the prior steps.

The response includes amountSubtotals (duties, taxes, fees, shipping, landedCostTotal): questi sono i numeri che mostri all'acquirente al momento del pagamento e che vengono stampati sulla fattura commerciale.

6. shipmentCreateWorkflow

Il passaggio terminale: crea il Shipment entity, generates the carrier label, and (optionally) the commercial invoice / packing slip.

For Japan Post Verified Accounts, this is also where Zonos calls the Japan Post Label API (code 52) on your behalf, injects your Later Pay Numbers, creates the Declaration ID, and links the Declaration ID to the tracking number returned by Japan Post.

Key fields:

references sub-input

These fields print on the carrier label and/or commercial invoice. Use them to surface PO numbers, license numbers, and free-text remarks the consignee or customs authority needs to see.

Response

The interesting fields on the returned Shipment Sono:

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

trackingDetails.number è il numero di tracciamento Japan Post.

IL label object can return the label two ways — request whichever fits your workflow (or both):

Select only the fields you need. Requesting url mantiene la risposta piccola; richiedente labelImage restituisce l'etichetta completa in linea, quindi non è necessario un secondo viaggio di andata e ritorno per recuperarla. L'esempio sopra richiede url.

Gestione degli errori 

• Errori di convalida (campi obbligatori mancanti, codici paese non validi, ecc.) ritornano nello standard GraphQL errors array e interrompere il resto della catena.
• Gli errori Japan Post (errore di generazione dell'etichetta, indirizzo non valido, ecc.) vengono visualizzati come errori GraphQL su shipmentCreateWorkflow. Se è necessario riprovare, contattare l'assistenza: il percorso consigliato è inviare nuovamente la mutazione completa con l'input corretto.

Autorizzazioni 

Ogni passaggio è protetto in modo indipendente. La tua chiave API deve contenere l'ambito di scrittura per ciascuna entità nella catena (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Il ruolo di commerciante standard su un account verificato garantisce tutto ciò.

Passaggi successivi 

• Invio batch (consolidamento) — raggruppare i pacchi giornalieri in un'unica distinta di spedizione con pagamento differito Japan Post.