Die API "Shipping order create" ist eine RESTful API, mit der Sie eine Bestellung für den Versand erstellen können, um ein Versandetikett und einen Tracking-Code für ein Paket zu generieren.

POST /v1/shipping-orders

Beispiel anfordern

{  "orderReferenceId": "EXMPL0001234",  "currency": "EUR",  "options": {    "weightUnit": "g",    "dimensionUnit": "mm",    "label": {      "format": "pdf"    }  },  "partner": {    "clientName": "ExampleCustomer"  },  "shippingMethod": {    "uid": "",    "carrier": "",    "tier": "standard"  },  "receiver": {    "person": {      "firstName": "Foo",      "lastName": "Bar",      "company": "",      "email": "[email protected]",      "phone": "01273552886"    },    "address": {      "country": "GB",      "state": "East Sussex",      "city": "Brighton",      "postcode": "BN1 8YQ",      "addressLine1": "11 London Rd",      "addressLine2": "",      "addressLine3": "",      "street": "London Rd",      "houseNumber": "11",      "suburb": null    },    "customs": {      "vatNumber": null    }  },  "sender": {    "person": {      "firstName": "",      "lastName": "",      "company": "Example Company",      "email": "[email protected]",      "phone": "01666 123456"    },    "address": {      "country": "DE",      "state": "",      "city": "Donauwörth",      "postcode": "86609",      "addressLine1": "Am Wassergraben 11",      "addressLine2": null,      "addressLine3": null,      "street": "Am Wassergraben",      "houseNumber": "11",      "suburb": null    },    "customs": {      "vatNumber": "DE123456789000",      "iossNumber": null,      "eoriNumber": "GB987654321000",      "pcccNumber": null,      "australianBusinessNumber": null    }  },  "packages": [    {      "packageReferenceId": "EXMPL0001234-0-1",      "grossWeight": 810,      "netWeight": 760,      "length": 229,      "width": 200,      "height": 36,      "boxType": "rectangle",      "volumetricWeight": 700,      "items": [        {          "itemReferenceId": "EXMPL0001234-0-1-ITEM1",          "description": "Mug",          "value": 18.42,          "quantity": 4,          "weight": 760,          "hsCode": "44199090",          "countryOfOrigin": "DE"        }      ]    }  ]}

Beispiel für eine erfolgreiche Antwort

{  "orderId": "fb7c0bf6-bdb1-4443-b5db-7263793be32b",  "orderReferenceId": "EXMPL0001234",  "shippingMethod": {    "carrier": "UPS",    "uid": "ups_standard_tariff"  },  "packages": [    {      "packageReferenceId": "EXMPL0001234-0-1",      "trackingNumber": "EXMPL0001234TRCKNUM",      "trackingUrl": "https://www.ups.com/track?track=yes&trackNums=EXMPL0001234TRCKNUM&loc=en_US&requester=ST",      "label": {        "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf",        "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf",        "contentType": "application/pdf"      },      "documents": [        {          "documentType": "invoice",          "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf",          "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf",          "contentType": "application/pdf"        }      ],      "totalCost": {        "value": 2.56,        "currency": "EUR"      }    }  ]}

Beispiel für eine Fehlermeldung

{  "orderReferenceId": "EXMPL0001234",  "code": "PUBLIC_API_ERROR",  "message": "Processing error",  "detail": {    "code": "UPS_API_ERROR",    "message": {      "status": {        "title": "Bad Request",        "status": 400,        "detail": "0 of 1 shipment successfully created.",        "statusCode": 400      },      "items": [        {          "sstatus": {            "title": "Bad Request",            "status": 400,            "statusCode": 400          },          "validationMessages": [            {              "property": "packages[0].items[0].hsCode",              "validationMessage": "Parameter hsCode must be between 4 and 11 characters long.",              "validationState": "Error"            }          ]        }      ]    }  },  "errors": [    {      "code": "IS_BLANK_ERROR",      "reference": "receiver.address.country",      "message": "This value should not be blank."    },    {      "code": "IS_BLANK_ERROR",      "reference": "receiver.address.city",      "message": "This value should not be blank."    },    {      "code": "MISSING_FIELD_ERROR",      "reference": "packages[EXMPL0001234-0-1][length]",      "message": "This field is missing."    }  ]}

Anfrage

Parameter	Typ	Beschreibung
orderReferenceId (erforderlich)	Zeichenkette	Eindeutige ID für die Versandbestellung. Von Ihnen bereitgestellte ID.
Währung (erforderlich)	Zeichenkette	Währung der Versandbestellung im 3-Buchstaben-Format.
Optionen (optional)	Optionen	Optionale Parameter.
Partnerin (optional)*	Partner	Partner*in-Details.
shippingMethod (erforderlich)	Versandmethode	Details zur Versandart.
Empfängerin (erforderlich)*	Empfänger*in	Empfänger*innendaten.
Absenderin (erforderlich)*	Absender*in	Absenderdaten.
Pakete (erforderlich)	Paket[]	Paketdetails.

Optionen

Parameter	Typ	Beschreibung
Gewichtseinheit (optional)	Zeichenkette	Gewichtseinheit. Verfügbare Optionen: g, kg, oz, lb. Standardmäßig: g.
dimensionUnit (optional)	Zeichenkette	Längeneinheit. Verfügbare Optionen: mm, cm, in. Standardmäßig: mm.
Etikett (optional)	Etikett	Einstellungen für das Etikettenformat.

Etikett

Parameter	Typ	Beschreibung
Format (optional)	Zeichenkette	Etikettenformat. Verfügbare Optionen: pdf, zpl (). Standardmäßig: pdf*.

Hinweis: Formate, die nicht PDF sind, sind möglicherweise nicht für bestimmte Versanddienstleister aktiviert.

Partner

Parameter	Typ	Beschreibung
Kundinnenname (optional)*	Zeichenkette	Versandkundenprofil. Wird verwendet, um einen Markennamen auf dem Etikett anzugeben (basierend auf den Spezifikationen des Trägers).

Versandmethode

Parameter	Typ	Beschreibung
UID (optional)*	Zeichenkette	Zur Verwendung für eine bestimmte Versandmethode, z. B. amazon_shipping_24.
Versanddienstleister (optional)	Zeichenkette	Name des Versanddienstleisters, z. B. Amazon, DHL
Stufe (erforderlich)*	Zeichenkette	Versandoption. Verfügbare Optionen: Standard, Express. Die Versandoption `Standard` sollte verwendet werden, wenn wir die `günstigste` Versandmethode für Sie auswählen. Die Versandoption `express` sollte verwendet werden, wenn wir die `fastest` Versandmethode für Sie auswählen.

Hinweis: *Verwenden Sie tier für Gelatos optimierte Versanddienstleisterauswahl. Wenn Sie tier verwenden, lassen Sie uid leer und umgekehrt.

Empfänger*in

Parameter	Typ	Beschreibung
Person (erforderlich)	Empfänger*in	Persönliche Daten der empfangenden Person.
Adresse (erforderlich)	Adresse	Adressdaten der empfangenden Person.
Zoll (optional)	Empfänger*inZoll	Zolldaten der empfangenden Person.

Absender*in

Parameter	Typ	Beschreibung
Person (erforderlich)	Absender*in	Persönliche Angaben der Absenderin oder des Absenders.
Adresse (erforderlich)	Adresse	Adressdaten der Absender*in.
Zoll (erforderlich für den internationalen Versand)	SenderCustoms	Zolldetails der Absender*in.

Empfänger*in

Parameter	Typ	Beschreibung
Vorname (erforderlich)	Zeichenkette	Vorname der empfangenden Person.
Nachname (erforderlich)	Zeichenkette	Nachname der empfangenden Person.
Unternehmen (optional)	Zeichenkette	Der Name des Unternehmens.
E-Mail (optional)*	Zeichenkette	E-Mail-Adresse der Person. Diese kann für Versandbenachrichtigungen verwendet werden.
Telefonnummer (optional)*	Zeichenkette	Telefonnummer der Person. Diese kann für Versandbenachrichtigungen verwendet werden.

Hinweis: *E-Mail und Telefonnummer können ein Pflichtfeld sein, abhängig vom Versanddienstleister

Absender*in

Parameter	Typ	Beschreibung
Vorname (optional)	Zeichenkette	Vorname der sendenden Person.
Nachname (optional)	Zeichenkette	Nachname der sendenden Person.
Unternehmen (erforderlich)	Zeichenkette	Der Name des Absenderunternehmens.
E-Mail (optional)*	Zeichenkette	E-Mail-Adresse der sendenden Person / des Unternehmens.
Telefonnummer (optional)*	Zeichenkette	Telefonnummer der absendenden Person / des Unternehmens.

Hinweis: *E-Mail und Telefonnummer können ein Pflichtfeld sein, abhängig vom Versanddienstleister

Adresse

Parameter	Typ	Beschreibung
Land (erforderlich)	Zeichenkette	Ländercode im 2-Buchstaben-Format.
Bundesland (optional)*	Zeichenkette	Bundesland / Landkreis / Region.
Stadt (erforderlich)	Zeichenkette	Stadt.
Postleitzahl (erforderlich)	Zeichenkette	Postleitzahl.
addressLine1 (erforderlich)	Zeichenkette	Erste Zeile der Postadresse. Sollte Straße und Hausnummer enthalten.
Adresszeile 2 (optional)	Zeichenkette	Zweite Zeile der Postadresse. Wohnungs-/Büro-/Stockwerksnummer.
Adresszeile 3 (optional)	Zeichenkette	Dritte Zeile der Postadresse.
Straße (optional)*	Zeichenkette	Straße (erforderlich für DE-Adressen).
Hausnummer (optional)*	Zeichenkette	Hausnummer (erforderlich für Adressen in Deutschland).
Vorort (optional)*	Zeichenkette	Vorort (erforderlich für AU/NZ-Adressen).

Hinweis: *Diese optionalen Felder sind für bestimmte Länder und Versanddienstleister erforderlich.

Empfänger*inZoll

Parameter	Typ	Beschreibung
Umsatzsteuer-Identifikationsnummer (optional)	Zeichenkette	MwSt.-Nummer der empfangenden Person.

SenderCustoms

Parameter	Typ	Beschreibung
Umsatzsteuer-Identifikationsnummer (optional)*	Zeichenkette	MwSt.-Nummer des Absenders.
iossNumber (optional)*	Zeichenkette	IOSS-Nummer der Absender*in.
EORI-Nummer (optional)*	Zeichenkette	EORI-Nummer der Absenderin oder des Absenders.
pcccNumber (optional)*	Zeichenkette	PCCC-Nummer der Absenderin oder des Absenders.
Australian Business Number (optional)*	Zeichenkette	Australische Unternehmensnummer derdes Absenderin.

Hinweis: *Je nach Absender- und Empfängerland können diese Felder erforderlich sein.

Paket

Parameter	Typ	Beschreibung
packageReferenceId (erforderlich)	Zeichenkette	Vom Partner bereitgestellte ID des Pakets.
Bruttogewicht (erforderlich)	Zahl	Verpackungsgewicht + Artikelgewicht (standardmäßig in Gramm).
Nettogewicht (optional)	Zahl	Gewicht der Artikel (standardmäßig in Gramm).
Länge (erforderlich)	Zahl	Länge des Pakets (standardmäßig in mm angegeben).
Breite (erforderlich)	Zahl	Paketbreite (standardmäßig in mm).
Höhe (erforderlich)	Zahl	Höhe des Pakets (standardmäßig in mm angegeben).
Volumengewicht (optional)	Zahl	Das Gewicht wird basierend auf der Größe des Pakets berechnet (standardmäßig in Gramm).
boxType (optional)	Zeichenkette	Form der Verpackung (z. B. Rechteck, Röhre).
Warenwert (erforderlich für den internationalen Versand)	Zahl	Gesamtwert aller Artikel im Paket (in der ausgewählten Währung).
Artikel (erforderlich für den internationalen Versand)	Artikel[]	Liste der Artikel im Paket.

Artikel*

Parameter	Typ	Beschreibung
itemReferenceId (erforderlich)	Zeichenkette	Vom Partner bereitgestellte ID des Paketelements.
Beschreibung (erforderlich)	Zeichenkette	Beschreibung des Artikels.
Menge (erforderlich)	Zahl	Menge des Artikels.
Wert (erforderlich)	Zahl	Wert des Artikels (in ausgewählter Währung).
Gewicht (erforderlich)	Zahl	Gewicht des Artikels (standardmäßig in Gramm).
HS-Code (erforderlich)	Zeichenkette	Harmonized System Code (Wiki).
countryOfOrigin (erforderlich)	Zeichenkette	Ländercode im 2-Buchstaben-Format, in dem der Artikel produziert wurde.

Hinweis: *Alle Artikelparameter sind nur für den internationalen Versand erforderlich.

Erfolgreiche Antwort

Parameter	Typ	Beschreibung
orderId	Zeichenkette	Eindeutige ID für die Versandbestellung in unserem System.
Bestellreferenznummer	Zeichenkette	Eindeutige ID für die Versandbestellung, die von Ihnen bereitgestellt wird.
Versandmethode	ResponseShippingMethod	Versandmethode, die für die Versandbestellung verwendet wird.
Pakete	ResponsePackage[]	Verpackungen, die für die Versandbestellung verwendet werden.

ResponseShippingMethod

Parameter	Typ	Beschreibung
Versanddienstleister	Zeichenkette	Versandanbieter, der zur Erstellung einer Bestellung verwendet wird.
uid	Zeichenkette	UID der Versandmethode, die zur Erstellung einer Bestellung verwendet wird.

ResponsePackage

Parameter	Typ	Beschreibung
packageReferenceId	Zeichenkette	Vom Partner bereitgestellte ID des Pakets.
trackingNumber	Zeichenkette	Sendungsverfolgungsnummer, die vom Versanddienstleister bereitgestellt wird.
trackingUrl	Zeichenkette	Tracking-URL, die vom Versanddienstleister bereitgestellt wird.
Etikett	AntwortLabel	Versandetikett für die Versandbestellung.
Dokumente (optional)	ResponseDocument[]	Dokumente für den Versandauftrag.
totalCost (optional)	ResponseTotalCost	Geschätzte Versandkosten für das Paket.

AntwortLabel

Parameter	Typ	Beschreibung
Dateiname	Zeichenkette	Dateiname des Etiketts.
fileUrl	Zeichenkette	URL zum Herunterladen des Etiketts.
contentType	Zeichenkette	Inhaltstyp des Etiketts.

ResponseDocument

Parameter	Typ	Beschreibung
documentType	Zeichenkette	Dokumenttyp (z. B. Rechnung).
Dateiname	Zeichenkette	Dateiname des Dokuments.
fileUrl	Zeichenkette	URL zum Herunterladen des Dokuments.
contentType	Zeichenkette	Inhaltstyp des Dokuments.

ResponseTotalCost

Parameter	Typ	Beschreibung
Wert (optional)	Zahl	Geschätzte Versandkosten für das Paket. (optional)
Währung (optional)	Zeichenkette	Währung

Fehlermeldung

Parameter	Typ	Beschreibung
Bestellreferenznummer	Zeichenkette	Eindeutige ID für die Versandbestellung, die von Ihnen bereitgestellt wird.
code	Zeichenkette	Fehlercode.
Nachricht	Zeichenkette	Fehlermeldung.
Detail (optional)	Objekt	Detaillierte Fehlermeldung (JSON-Objekt einer beliebigen Struktur).
Fehler (optional)	ResponseErrorDetails[]	Fehlerliste.