Einzel-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 eine Japan Post-Serviceebene 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:

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.

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.

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.