API-Spezifikation für Buchungssendungen
Wuunder verfügt über mehrere APIs, mit denen eine Verbindung hergestellt werden kann:
1. Eine Buchversand-API
Hier können Sie eine Sendung bei einem bestimmten Spediteur buchen und einen bestimmten Service nutzen. Wir senden das Versandetikett, die Track & Trace-URL und den Namen des Spediteurs zurück. Wenn es ein Problem mit der Adresse gibt oder wenn der Service für die Sendung, die Sie buchen möchten, nicht möglich ist, geben wir einen Fehler zurück.
2. Eine API für Buchentwürfe
Wo Sie Entwürfe von Sendungen an Wuunder senden können. Das Senden des jeweiligen Spediteurs und Dienstes ist optional. Diese Sendungsentwürfe können Sie sofort über die Massenbuchungsfunktion in MyWuunder buchen. Durch Klicken auf auf diesen Link Hier finden Sie alle relevanten Details.
Dieses technische Handbuch enthält alle Informationen, die für die Arbeit mit der Wuunder-Buchentwurfs-Versand-API erforderlich sind. Wenn Sie Fragen haben, bitte, Kontaktiere uns.
Allgemein
Die Wuunder-API ist eine RESTful-API, die über HTTPS bereitgestellt wird. Alle Daten werden als JSON gesendet und empfangen und in UTF-8 codiert.
Wuunder bietet isolierte Staging- und Produktionsumgebungen:
BASIS-URL
Staging
Produktion
Mit unserer API erfolgreich erstellte Sendungen sind sichtbar in:
BASIS-URL
Staging
Produktion
Beglaubigung
API-Aufrufe werden mithilfe von API-Token authentifiziert.
Clients, die in die Wuunder-API integriert werden möchten, wird ein Client-Token zugewiesen. Wenn Sie keinen API-Schlüssel haben, können Sie einen anfordern hier.
API-Token müssen im enthalten sein Authorization Header.
Autorisierung: Inhaber HIER TOKEN
Inhaltstyp
Kunden sollen Geben Sie die Art des Inhalts an, den sie über senden Content-Type Header. Nur zu diesem Zeitpunkt application/json wird unterstützt:
Inhaltstyp: Anwendung / json
Versionierung
Kunden sollen Geben Sie die API-Version an, die sie verwenden möchten. Die Angabe der API-Version erfolgt über das Accept Header:
Akzeptieren: application / json
Fehler
Fehler verwenden nach Möglichkeit den entsprechenden HTTP-Statuscode. Fehlende Parameter antworten beispielsweise mit a 422 Unprocessable Entity Antwort.
HTTP / 1.1 422 Nicht verarbeitbare Entität
{
Fehler: [
{"Feld": "Gewicht", "Nachrichten": ["kann nicht leer sein"]}
]
}
Das Bereitstellen eines ungültigen Authentifizierungstokens führt zu a 401 Unauthorized:
HTTP / 1.1 401 Nicht autorisiert
{
"Fehler": "nicht autorisiert"
}
Einer der häufigsten Fehler bei der Buchung Ihrer ersten Sendung ist: no_rate_chosen
Dies zeigt an, dass Sie versuchen, einen Dienst oder Netzbetreiber zu buchen, der für Ihr Konto nicht aktiviert ist. Ein weiterer Grund könnte sein, dass Sie keinen Firmennamen in der Absenderadresse verwenden. Einige Spediteure führen keine Abholungen an einer privaten Adresse durch. Bitte senden Sie die Anfrage, die Sie verwenden, an unsere KUNDENDIENST und teilen Sie uns mit, welchen Netzbetreiber und Service Sie nutzen möchten, und wir aktivieren diese Services für Sie.
HTTP-Verben
Wenn möglich, bemüht sich die Wuunder-API, für jede Aktion geeignete HTTP-Verben zu verwenden.
Verb
Beschreibung
BESTELLE
Wird zum Abrufen von Ressourcen verwendet.
Adressressourcen
Alle String Felder dürfen maximal 255 Zeichen enthalten, sofern in der Beschreibung nichts anderes angegeben ist.
NAME
ERFORDERLICH
TYP
BESCHREIBUNG
Land
Y
Schnur
ISO-2-Ländercode, zum Beispiel "NL" oder "BE".
Familienname
Y
Schnur
Maximale Länge: 30.
Vorname
Y
Schnur
Maximale Länge: 30.
Hausnummer
N
Schnur
Nummer einschließlich etwaiger Ergänzungen. Maximale Länge: 8.
Lokalität
Y
Schnur
Maximale Länge: 30.
Postleitzahl
Y
Schnur
Maximale Länge: 9.
Straßenname
Y
Schnur
Straßenteil der Adressen. Maximale Länge: 35.
address2
N
Schnur
Empfohlene Länge: 35.
Geschäft
N
Schnur
Wenn diese Adressen enthalten sind, werden sie als Geschäftsadresse betrachtet, andernfalls als private Adresse
E-Mail-Addresse
N
Schnur
Mit dieser Adresse verknüpfte E-Mail-Adresse. Es wird empfohlen, weniger als 40 Zeichen zu verwenden, um mit den meisten Anbietern kompatibel zu bleiben
Telefonnummer
N
Schnur
Mit dieser Adresse verknüpfte Telefonnummer. E.123-Format, zum Beispiel +31683243251
Chamber_of_Commerce_Number
N
Schnur
eori_nummer
N
Schnur
EORI-Nummer des Absenders (nur für pickup_address) und für den Versand in Nicht-EU-Länder erforderlich (Brexit)
Mehrwertsteuer
N
Schnur
Umsatzsteuer-Identifikationsnummer einschließlich Ländercode für den Versand in Nicht-EU-Länder (Brexit)
Wenn Sie keinen Straßennamen und keine Hausnummer in separaten Feldern haben, können Sie Wuunder bitten, sie für Sie aufzuteilen, indem Sie keine Hausnummer und im Straßennamen sowohl den Straßennamen als auch die Hausnummer senden. Wir versuchen dann, den Straßennamen und die Hausnummer für Sie aufzuteilen. Seien Sie sich bewusst, dass dies nicht 100% richtig sein wird. Es ist immer besser, separate Felder zu verwenden.
Bitte verwenden Sie zu Testzwecken Ihre eigene E-Mail-Adresse, da Wuunder eine Buchungsbestätigung an den Bucher sendet (optional), eine Versandbestätigung mit dem Etikett an den Absender (optional) und eine E-Mail mit Track & Trace an den Empfänger (optional).
Erstellen Sie eine Sendung
Diese API ermöglicht es, Sendungen im Wuunder-System vollständig automatisiert zu erstellen.
POST / API / Sendungen
Anfrage Körper
NAME
ERFORDERLICH
TYP
BESCHREIBUNG
Beschreibung
Y
Schnur
Beschreibung des Inhalts der Sendung mit maximal 50 Zeichen.
Wert
Y
Numerisch
Wert des gesamten Pakets ohne Mehrwertsteuer in Eurocent.
Art
Y
Schnur
Eines von "Dokument", "Paket" oder "Palette"
Länge
Y
Numerisch
Länge der gesamten Packung in Zentimetern
Breite
Y
Numerisch
Breite der gesamten Packung in Zentimetern
Höhe
Y
Numerisch
Höhe des gesamten Pakets in Zentimetern
Gewicht
Y
Numerisch
Gewicht der gesamten Packung in Gramm
persönliche Mitteilung
N
Schnur
Persönliche Nachricht für den Kunden, die in der an ihn gesendeten E-Mail enthalten sein wird
ein Bild
N
Base64-Zeichenfolge
Bild der Sendung
Kundenreferenz
N
Schnur
Freie Kundenreferenz für den Webshop
is_return
N
Boolean
Gibt an, ob es sich um eine Rücksendung handelt. Der Standardwert ist false.
drop_off
N
Boolean
Gibt an, ob es sich um eine Sendung handelt, bei der ein Paketladen abgegeben wurde. Der Standardwert ist false.
Preferred_service_level
Y
Schnur
Das bevorzugte Service Level Label, wie in der Filterkonfiguration angegeben. Überprüfen Sie die verfügbaren Filter hier
Paketshop_id
N
Schnur
ID des Paketshops, an den die Sendung gesendet werden muss
Anzahl_der_Elemente
N
ganze Zahl
Anzahl der gleichen zu buchenden Etiketten. Sollte> = 1 <= 10 sein.
Bestellzeilen
N
Liste (Bestellposition)
Bestellpositionen werden zum Senden von Informationen über den Inhalt Ihres Pakets an die Zollabteilungen verwendet und sind für den Versand in Nicht-EU-Länder erforderlich (Brexit).
BESTELLLINIEN
NAME
ERFORDERLICH
TYP
BESCHREIBUNG
hs_code
N
ganze Zahl
Der Harmonisierungscode für diese Ware und erforderlich für den Versand in Nicht-EU-Länder (Brexit). Die meisten Fluggesellschaften verlangen den 10-stelligen HS-Code.
Herkunftsland
N
Schnur
ISO-2-Ländercode, zum Beispiel „NL“ oder „BE“, erforderlich für den Versand in Nicht-EU-Länder (Brexit)
über die menge
N
ganze Zahl
Warenmenge und für den Versand in Nicht-EU-Länder erforderlich (Brexit)
Beschreibung
N
Schnur
Beschreibung der Ware für diese Bestellposition. Zum Beispiel "Maschinenteile" und für den Versand in Nicht-EU-Länder erforderlich (Brexit)
Wert
N
Dezimal
Wert der Waren in Euro, der für den Versand in Nicht-EU-Länder erforderlich ist (Brexit)
Gewicht
N
ganze Zahl
Gewicht in Gramm des Gutes und für den Versand in Nicht-EU-Länder erforderlich (Brexit)
sku
N
Schnur
DSKU des Guten
ean
N
Schnur
EAN des Guten
Beispiel
{
"delivery_address": {
"business": "Wuunder Nederland BV",
"chamber_of_commerce_number": null,
"country": "NL",
"email_address": null,
"family_name": "Janssen",
"given_name": "Jan",
"house_number": "8",
"locality": "Weert",
"phone_number": "+31612345678",
"street_name": "Afleveradres",
"address2": "2e etage",
"zip_code": "6003DD",
"vat": "NL8559.62.100"
},
"customer_reference": "12345678",
"description": "test",
"height": "50",
"kind": "package",
"length": "10",
"personal_message": "test",
"pickup_address": {
"business": "Voorbeeldshop",
"chamber_of_commerce_number": "21",
"country": "NL",
"email_address": "[email protected]",
"family_name": "AchternaamContactpersoon",
"given_name": "VoornaamContactpersoon",
"house_number": "8",
"locality": "Weert",
"phone_number": "+31612345678",
"street_name": "Marconilaan",
"zip_code": "6003DD",
"vat": "NL8559.62.100",
"eori_number": "NL8559.62.100"
},
"picture": null,
"value": "6900",
"weight": "5000",
"width": "20",
"is_return": false,
"drop_off": false,
"preferred_service_level": "dpd:cheapest",
"number_of_items": 1,
"order_lines": [{
"hs_code": "1234567890",
"country_of_origin": "NL",
"quantity": 4,
"description": "Wuunder parcel",
"value": 100,
"weight": 1,
"sku": "54321",
"ean": "12345"
}]
}
Erfolgreiche Antwort
label_url funktioniert track_and_trace_url wird nicht sofort verfügbar sein, sondern erst, nachdem die Sendung vollständig bearbeitet wurde.
picture_url enthält einen öffentlich zugänglichen Link, der auf das Bild verweist, das in der Nutzlast enthalten ist, falls vorhanden.
Fehlerantworten
HTTPS-STATUSCODE
FEHLERBESCHREIBUNG
422
Der Versand war ungültig, zum Beispiel fehlten Pflichtfelder.
Track & Trace-Webhook
{
"Aktion": "track_and_trace_updated",
"Track_and_trace_code": "S3123",
"Carrier_code": "TNT",
"Carrier_name": "TNT Express",
"Authentication_token": "Token" // JWT-Token
}
Es wird erwartet, dass das System, das den Webhook empfängt, mit einer 2xx-Statusantwort antwortet. Jede andere Antwort wird als Fehler betrachtet. In diesem Fall versucht das Wuunder-System erneut, den Webhook mit exponentiellem Zurücksetzen zu wiederholen.
Authentifizierungstoken aus der Webhook-Antwort
Beispieldaten:
Token
“eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJib29raW5
NX2lkIjoiNzhkZTZjNDYtMWE2Ni00YmQxLTg0MmQtZTkzNmIw
ZDg4MjRiIiwiZXhwIjoxNTAzNTc3MTExNjA2Ljk0OX0.Q4ED7N
q2JUa5uZaxcaAG3m6oGI0oeFjcb_5Mz0HQOPw”
Besteht aus:
HEADER: ALGORITHMUS & TOKEN-TYP
JSON
{
"Alge": "HS256",
"Typ": "JWT"
}
PAYLOAD: DATEN
JSON
{
“booking_id: “78de6c46-1a66-4bd1-e936b0d8824b”
"Exp": 1503577111606.949
}
Wo booking_id ist die Kennung der bearbeiteten Buchung und exp ist
Ablaufzeit. Wuunder erwartet, dass der Webshop die Ablaufzeit bestätigt
ist noch nicht vergangen.
Webshops können die Gültigkeit des Tokens überprüfen, indem sie die Signatur mithilfe von berechnen
ihr Webshop-Token als gemeinsames Geheimnis.
exp = booking_inserted_at (Unix-Zeit) + default_expiration_time (24 * 60 * 60)
