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:

• Påkrævet — anmodningen fejler uden det.
• Påkrævet for label — valgfrit i GraphQL-skemaet, men nødvendigt for en gyldig Japan Post-label til USA.
• Betinget — påkrævet afhængigt af et andet felt (noteret inline).
• Anbefalet — valgfrit, men driver præcis told og skat.
• Valgfri — 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 pristilbuddet, 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:

Om contentsType: de to mest almindelige værdier for Verified Account-trafik er ECOMMERCE_GOODS (solgt til en forbruger, BtoC) og COMMERCIAL_GOODS (solgt mellem virksomheder, BtoB). Disse sætter den pkgType, Zonos sender i Japan Post-labelkaldet, så valget ændrer, hvad der printes på tolddeklarationen — det er ikke kun en label.

nonDelivery sub-input

Fortæller Japan Post, hvad der skal ske med pakken, hvis den ikke kan leveres — afvist af modtageren, afvist ved grænsen eller ikke leverbar som adresseret.

option accepterer præcis disse fire værdier. Der findes ingen RETURN-værdi — brug RETURN_AFTER_RETENTION eller RETURN_IMMEDIATELY til at vælge, hvornår pakken kommer tilbage.

API'et eksponerer begge return-varianter separat; Dashboardets Return-mulighed dækker begge.

transportMethod accepterer AIR eller MOST_ECONOMICAL og angiver, hvordan en returneret pakke transporteres tilbage. Det gælder kun for de to RETURN_*-muligheder — Dashboardet viser kun det tilsvarende felt Return method, når Return er valgt.

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

Vælgeren If undeliverable i Dashboardets dialog Create label skriver til det samme felt, så en label oprettet i Dashboardet og en label oprettet via API'et opfører sig identisk.

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.

Svar

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.

Japan Post-serviceniveauer 

Send en af disse koder som serviceLevelCode i shipmentRatingCreateWorkflow.

Serviceniveaukoder bruger punktummer, ikke understregninger. Du kan se understregningsformen (japan_post_air_parcel) i fejlmeddelelser og interne referencer, men den er ikke gyldigt input.

Luftservices

Overfladeservices

Valg mellem lignende services

Small packet vs. International Air Packet. Begge er begrænset til 2 kg. japan_post.air.packet er Japan Posts trackede small-packet-service. japan_post.air.small_packet er den utrackede pendant. Hvis du har brug for tracking på en let pakke, brug japan_post.air.packet.

Anbefalede varianter. For breve og tryksager tilføjes tracking af den anbefalede (書留) version af servicen. japan_post.air.printed_matter og japan_post.air.letter inkluderer det ikke i sig selv.

Udgåede koder

japan_post.air.epacket_light var International e-Packet Light. Japan Post omdøbte servicen til International Air Packet den 1. juni 2026 og udvidede den til alle lande og regioner. Selve servicen er uændret.

Den gamle kode fungerer stadig, så eksisterende integrationer bliver ved med at virke, men brug japan_post.air.packet til nyt arbejde.

Transportmetode-koder

japan_post.air, japan_post.surface, japan_post.economy_air og japan_post.custom fungerer også, men de angiver en transportmetode eller et fallback frem for et specifikt postprodukt. Brug en af servicekoderne ovenfor til almindelige forsendelser.

Valider koden, du sender

En ukendt serviceLevelCode udløser ikke en fejl. Anmodningen returnerer HTTP 200 uden et errors-array, serviceLevel kommer tilbage som null, og shipping falder ud af landed cost-totalen — så svaret ser korrekt ud, mens beløbene er forkerte.

Sørg altid for at kontrollere, at shipmentRatingCreateWorkflow.serviceLevel ikke er null, før du stoler på totalerne.

For at hente den aktuelle liste når som helst:

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

Denne query tager carrierens ID. Hvis du sender carrier-koden japan_post, returneres en tom liste uden fejl.

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.

VALIDATION_INVALID_TYPE_VARIABLE

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

Denne fejl navngiver hele variablen, ikke det felt, der faktisk er forkert. Det betyder næsten altid, at en enum-værdi inde i den variabel ikke er et medlem af sin enum — oftest nonDelivery.option, contentsType eller serviceLevel.

Det er ikke et JSON-typeproblem. At sætte eller fjerne anførselstegn omkring dine booleans og tal ændrer ikke noget, fordi payloaden aldrig når så langt — enum'et afvises først.

For at finde det forkerte felt skal du tjekke hvert enum-felt i variablen mod dets accepterede værdier:

De fulde enum-medlemmer for ethvert input er angivet på dets type-side i API-referencen.

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). Standardforhandlerrollen på en Verified Account giver alle disse.

Næste skridt 

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