Skapa en enskild försändelse

CreateDeclarationShipment kedjar samman sex *Workflow-mutationer i en enda GraphQL-förfrågan. Varje steg bygger på de data föregående steg gav, och alla skickas in tillsammans så att en komplett försändelse kan skapas i ett enda anrop:

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-mutationerna är utformade för att vara kedjade: du behöver inte skicka med ID:n från ett steg till nästa, och du behöver inte skicka en separat förfrågan för varje steg. Skicka in hela dokumentet och få tillbaka den slutliga Shipment-posten.

När serviceLevel i det sista steget är en Japan Post-servicenivå (japan_post.*) anropar Zonos Japan Post Label API (kod 52) å dina vägnar med hjälp av ditt verifierade kontos Later Pay-nummer, genererar etiketten och spårningsnumret, skapar deklarations-ID:t och kopplar samman dem — allt inom det sista shipmentCreateWorkflow-steget.

Varför en enda mutation? Varje steg är beroende av det föregående (landed cost behöver artiklarna och parterna; etiketten behöver allt). Genom att samla dem i ett enda GraphQL-dokument hålls data konsekvent och du undviker fem extra anrop.

Slutpunkt och autentisering 

Alla förfrågningar i den här kedjan använder samma slutpunkt. Vad du skickar i headers beror på din uppsättning — välj din flik.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Exempel på förfrågan 

En komplett CreateDeclarationShipment-förfrågan som du kan kopiera och anpassa — mutationen, dess variabler och svaret — för en enskild Japan Post-försändelse som skickas DDP till USA. Varje indata beskrivs i detalj i avsnittet steg för steg nedan.

Steg för steg 

Kolumnen Status i tabellerna nedan använder följande termer:

• Krävs — förfrågan misslyckas utan det.
• Krävs för etikett — valfritt i GraphQL-schemat, men behövs för att skapa en giltig Japan Post-etikett för USA.
• Villkorat — krävs beroende på ett annat fält (anges i texten).
• Rekommenderas — valfritt, men styr korrekta tullar och skatter.
• Valfritt — behövs inte.

1. partyCreateWorkflow

Skapar de parter som ingår i försändelsen — minst en ORIGIN (varifrån försändelsen skickas) och en DESTINATION (köparen/mottagaren).

Exempel på nyttolast:

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

Svaret returnerar de skapade Party-ID:erna och de matchade adressfälten.

2. itemCreateWorkflow

Skapar de radartiklar som utgör försändelsen. Dessa är de SKU:er som visas på handelsfakturan och som styr beräkningen av landed cost.

HS-koden, ursprungslandet och beloppet är de tre fält som mest påverkar resultatet för tull/skatt i steg 5.

3. cartonsCreateWorkflow

Skapar de fysiska paketen — de kartonger, polybags eller brev som ska innehålla artiklarna.

Varje kartong blir ett paket på transportörens etikett i steg 6. Flera kartonger → en försändelse med flera delar och ett spårningsnummer per kartong.

4. shipmentRatingCreateWorkflow

Registrerar den fraktprisuppgift som handlaren tar ut av köparen för frakten.

Det här är det pris köparen fick vid kassan. Det ingår i beräkningen av landed cost som delsumman shipping, så att tullar och skatter beräknas mot rätt CIF-värde.

5. landedCostCalculateWorkflow

Kör beräkningen av tullar, skatter och avgifter för destinationslandet. Använder artiklarna, parterna och fraktkostnaden från de föregående stegen.

Svaret innehåller amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — det är de belopp du visar för köparen i kassan och som skrivs ut på handelsfakturan.

6. shipmentCreateWorkflow

Det avslutande steget — skapar entiteten Shipment, genererar transportörens etikett och (valfritt) handelsfakturan/packlistan.

För Japan Post-verifierade konton är det också här Zonos anropar Japan Post Label API (kod 52) å dina vägnar, infogar dina Later Pay-nummer, skapar deklarations-ID:t och kopplar deklarations-ID:t till spårningsnumret som returneras av Japan Post.

Viktiga fält:

För contentsType är de två vanligaste värdena för trafik från verifierade konton ECOMMERCE_GOODS (säljs till en konsument, B2C) och COMMERCIAL_GOODS (säljs mellan företag, B2B). Dessa styr det pkgType som Zonos skickar i anropet till Japan Post-etiketten, så valet påverkar vad som skrivs ut på tulldeklarationen — det är inte bara en etikett.

Underindata nonDelivery

Anger vad Japan Post ska göra med paketet om det inte kan levereras — nekas av mottagaren, avvisas vid gränsen eller är omöjligt att leverera till den angivna adressen.

option accepterar exakt dessa fyra värden. Det finns inget värde RETURN — använd RETURN_AFTER_RETENTION eller RETURN_IMMEDIATELY för att välja när paketet skickas tillbaka.

API:et exponerar båda returvarianterna separat; Dashboard-alternativet Retur täcker båda.

transportMethod accepterar AIR eller MOST_ECONOMICAL och anger hur ett returnerat paket transporteras tillbaka. Det gäller endast de två RETURN_*-alternativen — Dashboard visar motsvarande fält Returmetod endast när Retur är valt.

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

Väljaren Om ej leveransbar i Dashboard-dialogen Skapa etikett skriver till samma fält, så en etikett som skapas i Dashboard och en etikett som skapas via API:et beter sig identiskt.

Underindata references

Dessa fält skrivs ut på transportörens etikett och/eller handelsfakturan. Använd dem för att visa PO-nummer, licensnummer och fritextanmärkningar som mottagaren eller tullmyndigheten behöver se.

Svar

De mest relevanta fälten på det returnerade Shipment-objektet är:

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

trackingDetails.number är Japan Posts spårningsnummer.

Objektet label kan returnera etiketten på två sätt — begär det som passar ditt arbetsflöde (eller båda):

Välj bara de fält du behöver. Om du begär url hålls svaret litet; om du begär labelImage returneras hela etiketten direkt så att du inte behöver ett andra anrop för att hämta den. Exemplet ovan begär url.

Japan Post-servicenivåer 

Skicka en av dessa koder som serviceLevelCode i shipmentRatingCreateWorkflow.

Servicenivåkoder använder punkter, inte understreck. Du kan se understrecksformen (japan_post_air_parcel) i felmeddelanden och interna referenser, men den är inte giltig indata.

Flygtjänster

Yttjänster

Att välja mellan liknande tjänster

Litet paket jämfört med International Air Packet. Båda är begränsade till 2 kg. japan_post.air.packet är Japan Posts spårbara tjänst för mindre paket. japan_post.air.small_packet är motsvarigheten utan spårning. Om du behöver spårning för ett lätt paket, använd japan_post.air.packet.

Rekommenderade varianter. För brev och trycksaker läggs spårning till av den rekommenderade (書留) versionen av tjänsten. japan_post.air.printed_matter och japan_post.air.letter inkluderar den inte på egen hand.

Utfasade koder

japan_post.air.epacket_light var International e-Packet Light. Japan Post bytte namn på tjänsten till International Air Packet den 1 juni 2026 och utökade den till alla länder och regioner. Tjänsten i sig är oförändrad.

Den gamla koden fungerar fortfarande, så befintliga integrationer fortsätter att fungera, men använd japan_post.air.packet för nytt arbete.

Transportsättskoder

japan_post.air, japan_post.surface, japan_post.economy_air och japan_post.custom fungerar också, men de anger ett transportsätt eller en reservlösning snarare än en specifik posttjänst. Använd en av servicekoderna ovan för vanliga försändelser.

Validera koden du skickar

En okänd serviceLevelCode genererar inget fel. Förfrågan returnerar HTTP 200 utan någon errors-array, serviceLevel kommer tillbaka som null, och frakten faller bort ur den totala landed cost-summan — så svaret ser korrekt ut trots att beloppen är fel.

Kontrollera alltid att shipmentRatingCreateWorkflow.serviceLevel inte är null innan du litar på totalsummorna.

Hämta den aktuella listan när som helst:

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

Den här frågan tar transportörens ID. Om du skickar transportörskoden japan_post returneras en tom lista utan fel.

Felhantering 

• Valideringsfel (saknade obligatoriska fält, ogiltiga landskoder osv.) kommer tillbaka i den vanliga GraphQL-arrayen errors och avbryter resten av kedjan.
• Japan Post-fel (fel vid etikettgenerering, ogiltig adress osv.) visas som GraphQL-fel på shipmentCreateWorkflow. Om ett nytt försök behövs, kontakta supporten — den rekommenderade vägen är att skicka in hela mutationen igen med korrigerad indata.

VALIDATION_INVALID_TYPE_VARIABLE

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

Det här felet anger hela variabeln, inte det fält som faktiskt är felaktigt. Det betyder nästan alltid att ett enum-värde inuti variabeln inte är en medlem av sin enum — oftast nonDelivery.option, contentsType eller serviceLevel.

Det är inte ett JSON-typningsproblem. Att sätta eller ta bort citattecken kring dina booleaner och nummer ändrar inget, eftersom nyttolasten aldrig kommer så långt — enum-värdet avvisas först.

För att hitta det felaktiga fältet, kontrollera varje enum-fält i variabeln mot dess tillåtna värden:

Alla enum-medlemmar för en indatatyp finns listade på dess typsida i API-referensen.

Behörigheter 

Varje steg säkras separat. Din API-nyckel måste ha skrivbehörighet (write scope) för varje entitet i kedjan (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Standardrollen för handlare på ett verifierat konto ger alla dessa.

Nästa steg 

• Samlad avsändning (konsolidering) — samla dagens paket i en enda Japan Post-avsändningssedel med uppskjuten betalning.