Opret en enkelt forsendelse

CreateDeclarationShipment kæder seks *Workflow-mutationer sammen i én enkelt GraphQL-anmodning. Hvert trin bygger på data fra de foregående trin, og de sendes alle sammen, så en komplet forsendelse kan oprettes i ét 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

Workflow-mutationerne er designet til at blive kædet: du behøver ikke at sende ID'er fra ét trin til det næste, og du behøver ikke sende en separat anmodning pr. trin. Send hele dokumentet, få den endelige Shipment tilbage.

Når serviceLevel i det sidste trin er et Japan Post-serviceniveau (japan_post.*), kalder Zonos Japan Post Label API (kode 52) på dine vegne med din Verified Accounts Later Pay Numbers, genererer label og trackingnummer, opretter Declaration ID og kæder dem sammen — alt sammen i det sidste shipmentCreateWorkflow-trin.

Hvorfor én mutation? Hvert trin afhænger af det foregående (landed cost kræver varer + parter; labelen kræver alt). At samle dem i ét GraphQL-dokument holder data konsistente og undgår fem ekstra round-trips.

Endpoint og godkendelse 

Anmodningerne i denne kæde bruger alle samme endpoint. Hvad du sender i headers, afhænger af din opsætning — vælg din fane.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Eksempelanmodning 

En komplet CreateDeclarationShipment-anmodning, du kan kopiere og tilpasse — mutationen, dens variabler og svaret — for én Japan Post-pakke sendt DDP til USA. Hvert input er beskrevet trin for trin nedenfor.

Trin for trin 

Status-kolonnen i hver tabel nedenfor bruger disse termer:

• Required — anmodningen fejler uden det.
• Required for label — valgfrit i GraphQL-skemaet, men nødvendigt for en gyldig Japan Post-label til USA.
• Conditional — påkrævet afhængigt af et andet felt (noteret inline).
• Recommended — valgfrit, men driver præcis told og skat.
• Optional — ikke nødvendigt.

1. partyCreateWorkflow

Opretter parterne i forsendelsen — mindst en ORIGIN (hvor forsendelsen sendes fra) og en DESTINATION (køber / modtager).

Eksempel-payload:

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

Svaret returnerer de oprettede Party-ID'er og de opløste adressefelter.

2. itemCreateWorkflow

Opretter linjeposterne, der udgør forsendelsen. Dette er SKU'erne, der vises på handelsfakturaen og driver landed-cost-beregningen.

HS-kode, oprindelsesland og beløb er de tre felter, der mest påvirker told/skat-resultatet i trin 5.

3. cartonsCreateWorkflow

Opretter de fysiske pakker — kasser, polyposer eller breve, der indeholder varerne.

Hver karton bliver én pakke på carrier-labelen i trin 6. Flere kartoner → flerstyksforsendelse med ét trackingnummer pr. karton.

4. shipmentRatingCreateWorkflow

Registrerer prisudbuddet, forhandleren opkræver køberen for forsendelse.

Dette er den pris, køberen fik ved checkout. Den indgår i landed-cost-beregningen som „shipping"-subtotal, så told og skat beregnes mod den korrekte CIF-værdi.

5. landedCostCalculateWorkflow

Kører beregning af told, skat og gebyrer for destinationslandet. Bruger varer, parter og forsendelsesomkostninger fra de foregående trin.

Svaret inkluderer amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — disse er tallene, du viser køberen ved checkout og som printes på handelsfakturaen.

6. shipmentCreateWorkflow

Det afsluttende trin — opretter Shipment-entiteten, genererer carrier-labelen og (valgfrit) handelsfaktura / pakkeliste.

For Japan Post Verified Accounts er det også her, Zonos kalder Japan Post Label API (kode 52) på dine vegne, indsætter dine Later Pay Numbers, opretter Declaration ID og kæder Declaration ID til trackingnummeret returneret af Japan Post.

Vigtige felter:

references sub-input

Disse felter printes på carrier-labelen og/eller handelsfakturaen. Brug dem til PO-numre, licensnumre og fritekstbemærkninger, modtageren eller toldmyndigheden skal se.

Response

De interessante felter på den returnerede Shipment er:

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

trackingDetails.number er Japan Post-trackingnummeret.

label-objektet kan returnere labelen på to måder — anmod om det, der passer til dit workflow (eller begge):

Vælg kun de felter, du har brug for. Anmodning om url holder svaret lille; anmodning om labelImage returnerer hele labelen inline, så du ikke behøver et andet round-trip for at hente den. Eksemplet ovenfor anmoder om url.

Fejlhåndtering 

• Valideringsfejl (manglende påkrævede felter, ugyldige landekoder osv.) returneres i det standard GraphQL errors-array og afbryder resten af kæden.
• Japan Post-fejl (labelgenerering fejlede, ugyldig adresse osv.) vises som GraphQL-fejl på shipmentCreateWorkflow. Hvis et nyt forsøg er nødvendigt, kontakt support — den anbefalede vej er at sende hele mutationen igen med rettet input.

Tilladelser 

Hvert trin er uafhængigt sikret. Din API-nøgle skal have write-scope for hver entitet i kæden (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Standard forhandlerrollen på en Verified Account giver alle disse.

Næste skridt 

• Batch-afsendelse (konsolidering) — pak dagens pakker i én Japan Post deferred-payment-afsendelseskvittering.