Eén zending aanmaken

CreateDeclarationShipment koppelt zes *Workflow-mutaties aaneen tot één GraphQL-verzoek. Elke stap bouwt voort op de gegevens die de vorige stappen hebben geleverd, en ze worden allemaal samen verzonden, zodat een complete zending in één round trip kan worden aangemaakt:

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

De Workflow-mutaties zijn ontworpen om gekoppeld te worden: u hoeft geen ID's van de ene stap naar de volgende door te geven en u hoeft niet per stap een apart verzoek te verzenden. Verstuur het volledige document en ontvang de uiteindelijke Shipment terug.

Wanneer de serviceLevel in de laatste stap een Japan Post-servicelevel is (japan_post.*), roept Zonos namens u de Japan Post Label API (code 52) aan met de Later Pay Numbers van uw Verified Account, genereert het label en trackingnummer, maakt de Declaration ID aan en koppelt deze aan elkaar — allemaal binnen die laatste shipmentCreateWorkflow-stap.

Waarom één mutatie? Elke stap is afhankelijk van de vorige (landed cost heeft de items en partijen nodig; het label heeft alles nodig). Door ze te bundelen in één GraphQL-document blijven de gegevens consistent en worden vijf extra round trips vermeden.

Endpoint en authenticatie 

Alle verzoeken in deze keten gebruiken hetzelfde endpoint. Wat u in de headers meegeeft, hangt af van uw configuratie — kies uw tabblad.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Voorbeeldverzoek 

Een compleet CreateDeclarationShipment-verzoek dat u kunt kopiëren en aanpassen — de mutatie, de variabelen en het antwoord — voor één Japan Post-pakket dat DDP naar de VS wordt verzonden. Elke invoer wordt hieronder stapsgewijs uitgelegd.

Stap voor stap 

De kolom Status in elke tabel hieronder gebruikt de volgende termen:

• Vereist — het verzoek mislukt zonder dit veld.
• Vereist voor label — optioneel in het GraphQL-schema, maar nodig om een geldig Japan Post-label voor de VS te genereren.
• Voorwaardelijk — verplicht, afhankelijk van een ander veld (inline toegelicht).
• Aanbevolen — optioneel, maar bepaalt nauwkeurige invoerrechten en belastingen.
• Optioneel — niet nodig.

1. partyCreateWorkflow

Maakt de partijen aan die bij de zending betrokken zijn — op zijn minst een ORIGIN (waar de zending vandaan wordt verzonden) en een DESTINATION (de koper/geadresseerde).

Example payload:

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

Het antwoord retourneert de aangemaakte Party-ID's en de herleide adresvelden.

2. itemCreateWorkflow

Maakt de regelitems aan waaruit de zending bestaat. Dit zijn de SKU's die op de handelsfactuur worden vermeld en die de landed-cost-berekening aansturen.

De HS-code, het land van herkomst en het bedrag zijn de drie velden die de uitkomst van invoerrechten/belasting in stap 5 het meest beïnvloeden.

3. cartonsCreateWorkflow

Maakt de fysieke verpakkingen aan — de dozen, polybags of enveloppen waarin de items worden verpakt.

Elke carton wordt in stap 6 één pakket op het vervoerderslabel. Meerdere cartons → een zending met meerdere pakketten, met één trackingnummer per carton.

4. shipmentRatingCreateWorkflow

Registreert de tariefopgave die de handelaar de koper voor verzending in rekening brengt.

Dit is het tarief dat aan de koper is aangeboden bij het afrekenen. Het wordt meegenomen in de landed-cost-berekening als het subtotaal „shipping”, zodat invoerrechten en belastingen worden berekend op basis van de juiste CIF-waarde.

5. landedCostCalculateWorkflow

Voert de berekening van invoerrechten, belastingen en kosten uit voor het land van bestemming. Gebruikt de items, partijen en verzendkosten uit de voorgaande stappen.

Het antwoord bevat amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — dit zijn de bedragen die u aan de koper toont bij het afrekenen en die op de handelsfactuur worden afgedrukt.

6. shipmentCreateWorkflow

De laatste stap — maakt de entiteit Shipment aan, genereert het vervoerderslabel en (optioneel) de handelsfactuur/pakbon.

Voor Japan Post Verified Accounts is dit ook waar Zonos namens u de Japan Post Label API (code 52) aanroept, uw Later Pay Numbers invoegt, de Declaration ID aanmaakt en deze koppelt aan het trackingnummer dat door Japan Post wordt geretourneerd.

Belangrijke velden:

Bij contentsType zijn de twee meest gebruikte waarden voor verkeer via een Verified Account ECOMMERCE_GOODS (verkocht aan een consument, BtoC) en COMMERCIAL_GOODS (verkocht tussen bedrijven, BtoB). Deze bepalen het pkgType dat Zonos meestuurt bij de Japan Post-labelaanvraag, dus deze keuze verandert wat er op de douaneaangifte wordt afgedrukt — het is niet alleen een label.

nonDelivery sub-input

Vertelt Japan Post wat er met het pakket moet gebeuren als het niet kan worden bezorgd — geweigerd door de geadresseerde, tegengehouden aan de grens, of onbestelbaar zoals geadresseerd.

option accepteert precies deze vier waarden. Er bestaat geen waarde RETURN — gebruik RETURN_AFTER_RETENTION of RETURN_IMMEDIATELY om te kiezen wanneer het pakket terugkomt.

De API biedt beide retourvarianten afzonderlijk aan; de Return-optie in het Dashboard dekt beide.

transportMethod accepteert AIR of MOST_ECONOMICAL en bepaalt hoe een geretourneerd pakket terugreist. Dit geldt alleen voor de twee RETURN_*-opties — het Dashboard toont het bijbehorende veld Return method alleen wanneer Return is geselecteerd.

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

De keuzelijst If undeliverable in het dialoogvenster Create label van het Dashboard schrijft naar hetzelfde veld, dus een label dat in het Dashboard is aangemaakt en een label dat via de API is aangemaakt, gedragen zich identiek.

references sub-input

Deze velden worden afgedrukt op het vervoerderslabel en/of de handelsfactuur. Gebruik ze om PO-nummers, vergunningsnummers en vrije-tekstopmerkingen te tonen die de geadresseerde of douaneautoriteit moet zien.

Antwoord

De interessante velden op de geretourneerde Shipment zijn:

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

trackingDetails.number is het Japan Post-trackingnummer.

Het object label kan het label op twee manieren retourneren — vraag op wat past bij uw workflow (of beide):

Selecteer alleen de velden die u nodig hebt. Het opvragen van url houdt het antwoord klein; het opvragen van labelImage retourneert het volledige label inline, zodat u geen tweede round trip nodig hebt om het op te halen. Het voorbeeld hierboven vraagt url op.

Japan Post-servicelevels 

Geef een van deze codes op als serviceLevelCode in shipmentRatingCreateWorkflow.

Servicelevelcodes gebruiken punten, geen underscores. U kunt de underscore-vorm (japan_post_air_parcel) tegenkomen in foutmeldingen en interne verwijzingen, maar deze is geen geldige invoer.

Luchtdiensten

Oppervlaktediensten

Kiezen tussen vergelijkbare services

Small packet versus International Air Packet. Beide zijn beperkt tot maximaal 2 kg. japan_post.air.packet is de traceerbare small-packet-service van Japan Post. japan_post.air.small_packet is het niet-traceerbare equivalent. Gebruik japan_post.air.packet als u tracking nodig hebt voor een lichtgewicht pakket.

Aangetekende varianten. Voor brieven en drukwerk wordt tracking toegevoegd via de aangetekende (書留) versie van de service. japan_post.air.printed_matter en japan_post.air.letter bevatten dit niet op zichzelf.

Verouderde codes

japan_post.air.epacket_light was International e-Packet Light. Japan Post heeft de service op 1 juni 2026 hernoemd naar International Air Packet en uitgebreid naar alle landen en regio's. De service zelf is ongewijzigd.

De oude code blijft werken, zodat bestaande integraties gewoon blijven functioneren, maar gebruik voor nieuw werk japan_post.air.packet.

Transportmoduscodes

japan_post.air, japan_post.surface, japan_post.economy_air en japan_post.custom werken ook, maar deze geven een transportmodus of fallback aan in plaats van een specifiek postproduct. Gebruik voor normale zendingen een van de bovenstaande servicecodes.

Valideer de code die u verzendt

Een niet-herkende serviceLevelCode levert geen foutmelding op. Het verzoek retourneert HTTP 200 zonder errors-array, serviceLevel komt terug als null, en de verzendkosten vallen weg uit het landed-cost-totaal — waardoor het antwoord correct lijkt, terwijl de bedragen onjuist zijn.

Controleer altijd dat shipmentRatingCreateWorkflow.serviceLevel niet null is voordat u op de totalen vertrouwt.

Om op elk moment de actuele lijst op te halen:

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

Deze query gebruikt de carrier-ID. Als u de carriercode japan_post doorgeeft, wordt een lege lijst geretourneerd zonder foutmelding.

Foutafhandeling 

• Validatiefouten (ontbrekende verplichte velden, ongeldige landcodes, enz.) komen terug in de standaard GraphQL-array errors en breken de rest van de keten af.
• Japan Post-fouten (mislukte labelgeneratie, ongeldig adres, enz.) verschijnen als GraphQL-fouten bij shipmentCreateWorkflow. Als een nieuwe poging nodig is, neem dan contact op met support — de aanbevolen aanpak is om de volledige mutatie opnieuw in te dienen met gecorrigeerde invoer.

VALIDATION_INVALID_TYPE_VARIABLE

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

Deze foutmelding noemt de hele variabele, niet het veld dat daadwerkelijk fout is. Meestal betekent dit dat een enum-waarde binnen die variabele geen geldig lid van zijn enum is — meestal nonDelivery.option, contentsType of serviceLevel.

Dit is geen JSON-typeprobleem. Het wel of niet aanhalen van uw booleans en getallen verandert hier niets aan, omdat de payload nooit zo ver komt — de enum wordt al eerder afgewezen.

Controleer elk veld met een enum-waarde in de variabele aan de hand van de geaccepteerde waarden om het foutieve veld te vinden:

De volledige lijst met enum-leden voor elke invoer staat op de bijbehorende typepagina in de API-referentie.

Machtigingen 

Elke stap is afzonderlijk beveiligd. Uw API-key moet de schrijfscope hebben voor elke entiteit in de keten (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). De standaard handelaarsrol op een Verified Account verleent al deze rechten.

Volgende stappen 

• Batch dispatch (consolidatie) — bundel de pakketten van de dag in één Japan Post-dispatchbon met uitgestelde betaling.