Opprett en enkelt forsendelse

CreateDeclarationShipment kjeder sammen seks *Workflow-mutasjoner i én enkelt GraphQL-forespørsel. Hvert trinn bygger på dataene fra de foregående trinnene, og alle sendes inn sammen, slik at en komplett forsendelse kan opprettes i én runde:

partyCreateWorkflow            → beskriv opprinnelses- og destinasjonsparter
itemCreateWorkflow             → beskriv varelinjene
cartonsCreateWorkflow          → beskriv den fysiske emballasjen
shipmentRatingCreateWorkflow   → registrer transportørens fraktpristilbud
landedCostCalculateWorkflow    → beregn toll / avgifter / gebyrer
shipmentCreateWorkflow         → opprett forsendelsen + etikett

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

Når serviceLevel i 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-numrene til din verifiserte konto, genererer etiketten og sporingsnummeret, oppretter deklarasjons-IDen, og kobler dem sammen – alt innenfor det siste shipmentCreateWorkflow-trinnet.

Hvorfor én mutasjon? Hvert trinn er avhengig av det forrige (landed cost trenger varene + partene; etiketten trenger alt). Å samle dem i ett 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 én enkelt Japan Post-pakke sendt DDP til USA. Hver inndata er brutt ned i trinn-for-trinn-delen nedenfor.

Trinn for trinn 

Status-kolonnen i hver tabell nedenfor bruker disse begrepene:

• Required – forespørselen 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 (angitt i teksten).
• Recommended – valgfritt, men gir mer nøyaktig toll og avgifter.
• 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 de oppløste adressefeltene.

2. itemCreateWorkflow

Oppretter varelinjene som utgjør forsendelsen. Dette er SKU-ene som vises på handelsfakturaen og driver landed cost-beregningen.

HS-koden, opprinnelsesland og beløp er de tre feltene som har størst innvirkning på toll-/avgiftsutfallet i trinn 5.

3. cartonsCreateWorkflow

Oppretter de fysiske pakkene – boksene, polyposene eller brevene som skal inneholde varene.

Hver kartong blir én pakke på transportøretiketten i trinn 6. Flere kartonger → flerstykks forsendelse med ett sporingsnummer per kartong.

4. shipmentRatingCreateWorkflow

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

Dette er taksten kjøperen fikk oppgitt i kassen. Den inngår i landed cost-beregningen som «shipping»-delsummen, slik at toll og avgifter beregnes mot riktig CIF-verdi.

5. landedCostCalculateWorkflow

Kjører beregningen av toll, avgifter og gebyrer for mottakerlandet. Bruker varene, partene og fraktkostnaden fra de foregående trinnene.

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

6. shipmentCreateWorkflow

Det avsluttende trinnet – oppretter Shipment-enheten, genererer transportøretiketten, og (valgfritt) handelsfakturaen / pakkseddelen.

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

Nøkkelfelt:

For contentsType er de to vanligste verdiene for trafikk fra verifiserte kontoer ECOMMERCE_GOODS (solgt til en forbruker, B2C) og COMMERCIAL_GOODS (solgt mellom bedrifter, B2B). Disse styrer pkgType-en Zonos sender i Japan Post-etikettkallet, så valget endrer hva som skrives ut på tolldeklarasjonen – det er ikke bare en etikett.

nonDelivery-underinput

Forteller Japan Post hva som skal gjøres med pakken hvis den ikke kan leveres – nektet mottatt av mottakeren, avvist ved grensen, eller ikke leverbar til den oppgitte adressen.

option godtar nøyaktig disse fire verdiene. Det finnes ingen RETURN-verdi – bruk RETURN_AFTER_RETENTION eller RETURN_IMMEDIATELY for å velge når pakken kommer tilbake.

API-et eksponerer begge returvariantene separat; Dashboard-alternativet Return dekker begge.

transportMethod godtar AIR eller MOST_ECONOMICAL, og angir hvordan en returnert pakke fraktes tilbake. Det gjelder kun for de to RETURN_*-alternativene – Dashboard viser det tilhørende Return method-feltet bare når Return er valgt.

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

Velgeren If undeliverable i Dashboard-dialogen Create label skriver til det samme feltet, slik at en etikett opprettet i Dashboard og en etikett opprettet via API-et oppfører seg identisk.

references-underinput

Disse feltene skrives ut på transportøretiketten og/eller handelsfakturaen. Bruk dem til å vise PO-numre, lisensnumre og fritekstmerknader som mottakeren eller tollmyndighetene må se.

Respons

De interessante feltene på den returnerte Shipment-en 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 ekstra runde for å hente den. Eksempelet over ber om url.

Japan Post-servicenivåer 

Send en av disse kodene som serviceLevelCode i shipmentRatingCreateWorkflow.

Servicenivåkoder bruker punktum, ikke understrek. Du kan se understrek-formen (japan_post_air_parcel) i feilmeldinger og interne referanser, men den er ikke gyldig input.

Luftpost

Overflatepost

Velge mellom lignende tjenester

Liten pakke vs. International Air Packet. Begge er begrenset til 2 kg. japan_post.air.packet er Japan Posts sporede tjeneste for små pakker. japan_post.air.small_packet er den usporede tilsvarende tjenesten. Hvis du trenger sporing på en lett pakke, bruk japan_post.air.packet.

Rekommanderte varianter. For brev og trykksaker legges sporing til av den rekommanderte (書留) versjonen av tjenesten. japan_post.air.printed_matter og japan_post.air.letter inkluderer den ikke i seg selv.

Utfasede koder

japan_post.air.epacket_light var International e-Packet Light. Japan Post ga tjenesten nytt navn til International Air Packet 1. juni 2026, og utvidet den til å gjelde alle land og regioner. Selve tjenesten er uendret.

Den gamle koden fungerer fortsatt, slik at eksisterende integrasjoner fortsetter å virke, men bruk japan_post.air.packet for nytt arbeid.

Transportmodus-koder

japan_post.air, japan_post.surface, japan_post.economy_air og japan_post.custom fungerer også, men de identifiserer en transportmodus eller en reserveløsning i stedet for et spesifikt postprodukt. Bruk en av servicekodene over for vanlige forsendelser.

Valider koden du sender

En ukjent serviceLevelCode gir ikke en feilmelding. Forespørselen returnerer HTTP 200 uten errors-matrise, serviceLevel kommer tilbake som null, og frakt faller ut av landed cost-totalen – slik at responsen ser riktig ut mens beløpene er feil.

Kontroller alltid at shipmentRatingCreateWorkflow.serviceLevel ikke er null, før du stoler på totalene.

For å hente den gjeldende listen når som helst:

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

Denne spørringen tar transportørens ID. Å sende transportørkoden japan_post returnerer en tom liste uten feil.

Feilhåndtering 

• Valideringsfeil (manglende påkrevde felt, ugyldige landskoder, osv.) kommer tilbake i den vanlige GraphQL errors-matrisen og avbryter resten av kjeden.
• Japan Post-feil (feil ved etikettgenerering, ugyldig adresse, osv.) vises som GraphQL-feil på shipmentCreateWorkflow. Hvis et nytt forsøk er nødvendig, kontakt kundestøtte – den anbefalte fremgangsmåten er å sende inn hele mutasjonen på nytt med korrigert input.

VALIDATION_INVALID_TYPE_VARIABLE

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

Denne feilen navngir hele variabelen, ikke feltet som faktisk er feil. Den betyr nesten alltid at én enum-verdi inne i variabelen ikke er medlem av enumen sin – oftest nonDelivery.option, contentsType, eller serviceLevel.

Det er ikke et JSON-typeproblem. Å sette eller fjerne anførselstegn rundt boolske verdier og tall endrer ikke noe, fordi payloaden aldri kommer så langt – enumen avvises først.

For å finne det feilaktige feltet, sjekk hvert enum-felt i variabelen mot dets godkjente verdier:

Alle enum-medlemmene for en input er oppført på typesiden i API-referansen.

Tillatelser 

Hvert trinn er sikret uavhengig. API-nøkkelen din må ha skrivetilgang for hver enhet i kjeden (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Standard kjøpmannsrolle på en verifisert konto gir alle disse.

Neste steg 

• Batch-utsendelse (konsolidering) – samle dagens pakker i én Japan Post-forsendelsesliste med utsatt betaling.