Einzelne Sendung erstellen

CreateDeclarationShipment verknüpft sechs *Workflow-Mutationen zu einer einzigen GraphQL-Anfrage. Jeder Schritt baut auf den Daten der vorherigen Schritte auf, und alle werden gemeinsam übermittelt, sodass eine vollständige Sendung in einem Round-Trip erstellt werden kann:

partyCreateWorkflow            → Absender- und Empfängerparteien beschreiben
itemCreateWorkflow             → Positionen beschreiben
cartonsCreateWorkflow          → die physische Verpackung beschreiben
shipmentRatingCreateWorkflow   → das Carrier-Tarifangebot erfassen
landedCostCalculateWorkflow    → Zölle / Steuern / Gebühren berechnen
shipmentCreateWorkflow         → die Sendung + das Etikett erstellen

Die Workflow-Mutationen sind für die Verkettung konzipiert: Sie müssen keine IDs von einem Schritt in den nächsten durchreichen und müssen keinen separaten Request pro Schritt senden. Reichen Sie das gesamte Dokument ein und erhalten Sie die finale Shipment zurück.

Wenn der serviceLevel im letzten Schritt ein Japan Post-Servicelevel ist (japan_post.*), ruft Zonos in Ihrem Namen die Japan Post Label API (Code 52) mit den Later Pay Numbers Ihres Verified Accounts auf, generiert das Etikett und die Sendungsnummer, erstellt die Declaration ID und verknüpft sie — alles innerhalb des abschließenden Schritts shipmentCreateWorkflow.

Warum eine Mutation? Jeder Schritt hängt vom vorherigen ab (Landed Cost benötigt die Positionen + Parteien; das Etikett benötigt alles). Die Bündelung in einem einzigen GraphQL-Dokument hält die Daten konsistent und vermeidet fünf zusätzliche Round-Trips.

Endpoint und Authentifizierung 

Die Anfragen in dieser Kette nutzen alle denselben Endpoint. Was Sie in den Headern übergeben, hängt von Ihrem Setup ab — wählen Sie Ihren Tab.

URL:

https://api.zonos.com/graphql

Header:

credentialToken: {{YOUR_API_TOKEN}}

Beispielanfrage 

Eine vollständige CreateDeclarationShipment-Anfrage zum Kopieren und Anpassen — die Mutation, ihre Variablen und die Antwort — für ein einzelnes Japan Post-Paket, das per DDP in die USA versendet wird. Jede Eingabe wird im Abschnitt Schritt für Schritt unten erläutert.

Schritt für Schritt 

Die Spalte Status in jeder Tabelle unten verwendet diese Begriffe:

• Erforderlich — die Anfrage schlägt ohne dieses Feld fehl.
• Erforderlich für Etikett — im GraphQL-Schema optional, aber erforderlich für ein gültiges Japan Post-US-Etikett.
• Bedingt — abhängig von einem anderen Feld erforderlich (im Text vermerkt).
• Empfohlen — optional, beeinflusst aber die Genauigkeit von Zöllen und Steuern.
• Optional — nicht erforderlich.

1. partyCreateWorkflow

Erstellt die an der Sendung beteiligten Parteien — mindestens eine ORIGIN (Versandursprung) und eine DESTINATION (Käufer / Empfänger).

Beispiel-Payload:

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

Die Antwort gibt die erstellten Party-IDs und aufgelösten Adressfelder zurück.

2. itemCreateWorkflow

Erstellt die Positionen, aus denen die Sendung besteht. Das sind die SKUs, die auf der Handelsrechnung erscheinen und die Landed-Cost-Berechnung steuern.

Der HS-Code, das Herstellungsland und der Betrag sind die drei Felder, die das Zoll-/Steuerergebnis in Schritt 5 am stärksten beeinflussen.

3. cartonsCreateWorkflow

Erstellt die physischen Pakete — die Kartons, Polybeutel oder Briefe, die die Positionen enthalten.

Jeder Karton wird in Schritt 6 zu einem Paket auf dem Carrier-Etikett. Mehrere Kartons → Mehrstück-Sendung mit einer Sendungsnummer pro Karton.

4. shipmentRatingCreateWorkflow

Erfasst das Tarifangebot, das der Händler dem Käufer für den Versand berechnet.

Das ist der Tarif, der dem Käufer beim Checkout angeboten wurde. Er fließt als Teilposten „Versand“ in die Landed-Cost-Berechnung ein, damit Zölle und Steuern gegen den korrekten CIF-Wert berechnet werden.

5. landedCostCalculateWorkflow

Führt die Berechnung von Zöllen, Steuern und Gebühren für das Zielland durch. Nutzt die Positionen, Parteien und Versandkosten aus den vorherigen Schritten.

Die Antwort enthält amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — das sind die Werte, die Sie dem Käufer beim Checkout anzeigen und die auf der Handelsrechnung gedruckt werden.

6. shipmentCreateWorkflow

Der abschließende Schritt — erstellt die Shipment-Entität, generiert das Carrier-Etikett und (optional) die Handelsrechnung / den Packzettel.

Für Japan Post Verified Accounts ruft Zonos hier auch in Ihrem Namen die Japan Post Label API (Code 52) auf, bindet Ihre Later Pay Numbers ein, erstellt die Declaration ID und verknüpft die Declaration ID mit der von Japan Post zurückgegebenen Sendungsnummer.

Wichtige Felder:

Bei contentsType sind ECOMMERCE_GOODS (Verkauf an einen Verbraucher, BtoC) und COMMERCIAL_GOODS (Verkauf zwischen Unternehmen, BtoB) die beiden häufigsten Werte für Verified-Account-Traffic. Sie legen den pkgType fest, den Zonos beim Japan Post-Label-Aufruf übermittelt — die Wahl ändert also, was auf der Zollerklärung gedruckt wird, und ist nicht nur eine Frage des Etiketts.

nonDelivery-Untereingabe

Teilt Japan Post mit, was mit dem Paket geschehen soll, wenn es nicht zugestellt werden kann — vom Empfänger abgelehnt, an der Grenze zurückgewiesen oder unter der angegebenen Adresse nicht zustellbar.

option akzeptiert genau diese vier Werte. Es gibt keinen Wert RETURN — verwenden Sie RETURN_AFTER_RETENTION oder RETURN_IMMEDIATELY, um festzulegen, wann das Paket zurückkommt.

Die API bietet beide Rücksendevarianten separat an; die Return-Option im Dashboard deckt beide ab.

transportMethod akzeptiert AIR oder MOST_ECONOMICAL und legt fest, wie ein zurückgesendetes Paket transportiert wird. Es gilt nur für die beiden RETURN_*-Optionen — das Dashboard zeigt das passende Feld Return method nur an, wenn Return ausgewählt ist.

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

Die Auswahl If undeliverable im Dashboard-Dialog Create label schreibt dasselbe Feld, sodass ein im Dashboard erstelltes Etikett und ein über die API erstelltes Etikett sich identisch verhalten.

references-Untereingabe

Diese Felder werden auf dem Carrier-Etikett und/oder der Handelsrechnung gedruckt. Nutzen Sie sie, um Bestellnummern, Lizenznummern und Freitextbemerkungen anzuzeigen, die der Empfänger oder die Zollbehörde sehen muss.

Antwort

Die relevanten Felder der zurückgegebenen Shipment sind:

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

trackingDetails.number ist die Japan Post-Sendungsnummer.

Das label-Objekt kann das Etikett auf zwei Arten zurückgeben — fordern Sie an, was zu Ihrem Workflow passt (oder beides):

Fordern Sie nur die Felder an, die Sie benötigen. url hält die Antwort klein; labelImage gibt das vollständige Etikett inline zurück, sodass kein zweiter Round-Trip zum Abruf nötig ist. Das Beispiel oben fordert url an.

Japan Post-Servicelevel 

Geben Sie einen dieser Codes als serviceLevelCode in shipmentRatingCreateWorkflow an.

Servicelevel-Codes verwenden Punkte, keine Unterstriche. Die Unterstrich-Form (japan_post_air_parcel) begegnet Ihnen möglicherweise in Fehlermeldungen und internen Referenzen, ist aber keine gültige Eingabe.

Luftpost-Services

Seepost-Services

Wahl zwischen ähnlichen Services

Small Packet vs. International Air Packet. Beide sind auf 2 kg begrenzt. japan_post.air.packet ist Japan Posts nachverfolgbarer Small-Packet-Service. japan_post.air.small_packet ist das nicht nachverfolgbare Äquivalent. Wenn Sie für ein leichtes Paket eine Sendungsverfolgung benötigen, verwenden Sie japan_post.air.packet.

Eingeschriebene Varianten. Bei Briefen und Drucksachen wird die Sendungsverfolgung durch die eingeschriebene (書留) Version des Service hinzugefügt. japan_post.air.printed_matter und japan_post.air.letter enthalten sie nicht von sich aus.

Veraltete Codes

japan_post.air.epacket_light war International e-Packet Light. Japan Post hat den Service am 1. Juni 2026 in International Air Packet umbenannt und auf alle Länder und Regionen ausgeweitet. Der Service selbst ist unverändert.

Der alte Code funktioniert weiterhin, sodass bestehende Integrationen nicht betroffen sind — verwenden Sie für neue Implementierungen jedoch japan_post.air.packet.

Transportart-Codes

japan_post.air, japan_post.surface, japan_post.economy_air und japan_post.custom funktionieren ebenfalls, kennzeichnen aber eine Transportart oder einen Fallback und kein bestimmtes Postprodukt. Verwenden Sie für normale Sendungen einen der oben genannten Servicecodes.

Den gesendeten Code validieren

Ein nicht erkannter serviceLevelCode löst keinen Fehler aus. Die Anfrage liefert HTTP 200 ohne errors-Array zurück, serviceLevel kommt als null zurück, und der Versand entfällt aus dem Landed-Cost-Gesamtbetrag — die Antwort sieht also korrekt aus, während die Beträge falsch sind.

Stellen Sie immer sicher, dass shipmentRatingCreateWorkflow.serviceLevel nicht null ist, bevor Sie sich auf die Summen verlassen.

So rufen Sie die aktuelle Liste jederzeit ab:

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

Diese Abfrage nimmt die Carrier-ID entgegen. Die Übergabe des Carrier-Codes japan_post liefert eine leere Liste ohne Fehler zurück.

Fehlerbehandlung 

• Validierungsfehler (fehlende Pflichtfelder, ungültige Ländercodes usw.) werden im standardmäßigen GraphQL-errors-Array zurückgegeben und brechen den Rest der Kette ab.
• Japan Post-Fehler (Fehler bei der Etikettenerstellung, ungültige Adresse usw.) werden als GraphQL-Fehler bei shipmentCreateWorkflow ausgegeben. Wenn ein erneuter Versuch nötig ist, wenden Sie sich an den Support — der empfohlene Weg ist, die vollständige Mutation mit korrigierten Eingaben erneut einzureichen.

VALIDATION_INVALID_TYPE_VARIABLE

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

Dieser Fehler benennt die gesamte Variable, nicht das eigentlich fehlerhafte Feld. Meist bedeutet er, dass ein Enum-Wert innerhalb dieser Variable kein gültiges Mitglied seines Enums ist — am häufigsten bei nonDelivery.option, contentsType oder serviceLevel.

Es ist kein JSON-Typisierungsproblem. Das Setzen oder Entfernen von Anführungszeichen bei Booleans und Zahlen ändert daran nichts, da der Payload gar nicht so weit kommt — das Enum wird zuerst abgelehnt.

Um das fehlerhafte Feld zu finden, prüfen Sie jedes Enum-Feld in der Variable gegen seine zulässigen Werte:

Die vollständigen Enum-Werte für jede Eingabe finden Sie auf der jeweiligen Typseite in der API-Referenz.

Berechtigungen 

Jeder Schritt ist unabhängig abgesichert. Ihr API-Schlüssel muss den Schreibbereich für jede Entität in der Kette haben (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Die Standard-Händlerrolle auf einem Verified Account gewährt alle diese Berechtigungen.

Nächste Schritte 

• Batch-Versand (Konsolidierung) — bündeln Sie die Pakete eines Tages in einen Japan Post-Nachzahlungsversandschein.