Opprett en forsendelse

CreateDeclarationShipment kjeder sammen seks *Workflow mutasjoner i en enkelt GraphQL-forespørsel. Hvert trinn bygger på dataene fra forrige trinn, og alle sendes inn sammen slik at en komplett forsendelse kan opprettes i en enkelt rund:

partyCreateWorkflow            → beskriv opprinnelses- og destinasjonspartner
itemCreateWorkflow             → beskriv linjeartikelene
cartonsCreateWorkflow          → beskriv den fysiske pakningen
shipmentRatingCreateWorkflow   → registrer sitatet for transportørtakst
landedCostCalculateWorkflow    → beregn toll / skatter / gebyrer
shipmentCreateWorkflow         → opprett forsendelsen + etikett

Workflow mutasjonene er designet for å være kjededet: du trenger ikke å tråde IDer fra ett trinn til det neste, og du trenger ikke å sende en separat forespørsel per trinn. Send hele dokumentet, få den endelige Shipment tilbake.

Når serviceLevel på det siste trinnet er et Japan Post-servicenivå (japan_post.*), kaller Zonos Japan Post Label API (kode 52) på dine vegne ved hjelp av Later Pay-tallene for din verifiserte konto, genererer etiketten og sporingsnummeret, oppretter deklarasjons-IDen, og kobler dem sammen – alt innenfor det siste shipmentCreateWorkflow-trinnet.

Hvorfor en mutasjon? Hvert trinn avhenger av det forrige (landed cost trenger artiklene + partene; etiketten trenger alt). Å samle dem i et enkelt GraphQL-dokument holder dataene konsistente og unngår fem ekstra runder.

Endepunkt og autentisering 

Forespørslene i denne kjeden bruker alle det samme endepunktet. Hva du sender i headerne avhenger av oppsettet ditt – velg fanen din.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Eksempelforespørsel 

En komplett CreateDeclarationShipment-forespørsel som du kan kopiere og tilpasse – mutasjonen, variablene og responsen – for en enkelt Japan Post-pakke som sendes DDP til USA. Hver inndata blir delt ned i delen trinn for trinn nedenfor.

Trinn for trinn 

Tabellen under bruker disse vilkårene i Status-kolonnen:

• Required – forespørselen vil mislykkes uten det.
• Required for label – valgfritt i GraphQL-skjemaet, men nødvendig for å produsere en gyldig Japan Post-etikett til USA.
• Conditional – påkrevd avhengig av et annet felt (notert inline).
• Recommended – valgfritt, men driver nøyaktige toll og skatter.
• Optional – ikke nødvendig.

1. partyCreateWorkflow

Oppretter partene som er involvert i forsendelsen – minst en ORIGIN (der forsendelsen sendes fra) og en DESTINATION (kjøperen / mottakeren).

Eksempelpayload:

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

Responsen returnerer de opprettede Party-IDene og løste adressefelt.

2. itemCreateWorkflow

Oppretter linjeartikelene som utgjør forsendelsen. Disse er SKUene som vises på handelsfakturaen og driver landed-cost-beregningen.

HS-koden, opprinnelsesland og beløp er de tre feltene som mest påvirker toll-/skatteutfallet i trinn 5.

3. cartonsCreateWorkflow

Oppretter de fysiske pakkene – boksene, polyposene eller brevene som skal holde artiklene.

Hver kartong blir en pakke på transportør-etiketten i trinn 6. Flere kartong → fleirstykks forsendelse med ett sporingsnummer per kartong.

4. shipmentRatingCreateWorkflow

Registrerer takstene kjøpmannen belaster kjøperen for frakt.

Dette er taksten kjøperen fikk tilbud om ved kassen. Det går inn i landed-cost-beregningen som "frakt"-subtotalen slik at toll og skatter beregnes mot riktig CIF-verdi.

5. landedCostCalculateWorkflow

Kjør toll-, skatt- og gebyrberegningen for destinasjonslandet. Bruker artiklene, partene og fraktkostnaden fra forrige trinn.

Responsen inkluderer amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) – dette er tallene du viser til kjøperen ved kassen og som skrives ut på handelsfakturaen.

6. shipmentCreateWorkflow

Det siste trinnet – oppretter Shipment enheten, genererer transportør-etiketten, og (valgfritt) handelsfakturaen / pakkelisten.

For Japan Post-verifiserte kontoer, er dette også hvor Zonos kaller Japan Post Label API (kode 52) på dine vegne, injiserer dine Later Pay-numre, oppretter deklarasjons-IDen, og kobler deklarasjons-IDen til sporingsnummeret som ble returnert av Japan Post.

Viktige felt:

references sub-input

Disse feltene skrives ut på transportør-etiketten og/eller handelsfakturaen. Bruk dem til å vise PO-numre, lisens-numre, og fri-tekst-merknader som mottakeren eller tullmyndighetene må se.

Response

De interessante feltene på returnert Shipment er:

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

trackingDetails.number er Japan Post sporingsnummeret.

label-objektet kan returnere etiketten på to måter – be om den som passer arbeidsflyten din (eller begge):

Velg bare feltene du trenger. Å be om url holder responsen liten; å be om labelImage returnerer hele etiketten inline slik at du ikke trenger en annen rund for å hente den. Eksempelet over ber om url.

Feilhåndtering 

• Valideringsfeil (manglende påkrevde felt, ugyldige landskoder, osv.) kommer tilbake i standard GraphQL errors matrise og avbryter resten av kjeden.
• Japan Post feil (etikettgenereringsfeil, ugyldig adresse, osv.) oppstår som GraphQL feil på shipmentCreateWorkflow. Hvis et nytt forsøk er nødvendig, kontakt support – den anbefalte veien er å sende den fullstendige mutasjonen på nytt med korrigert inndata.

Tillatelser 

Hvert trinn er uavhengig sikret. Din API-nøkkel må holde skriveomfanget for hver enhet i kjeden (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Standartkjøpmannsrollen på en verifisert konto gir alle disse.

Neste steg 

• Batch dispatch (konsolidering) – samle dagens pakker til en Japan Post utsatt-betaling forsendelseslipp.