API-Spezifikation für Sendungsentwürfe buchen
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. Auf diese Seite Sie können alle Details finden.
2. Eine API für Buchentwürfe
Hier können Sie Sendungsentwürfe an Wuunder senden. Das Senden des jeweiligen Spediteurs und Dienstes ist optional. Diese Sendungsentwürfe können Sie sofort über die Massenbuchungsfunktion in MyWuunder buchen.
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.
Besuchen Sie Wuunders API-Dokumente um mehr zu erfahren.
Wuunder bietet isolierte Staging- und Produktionsumgebungen:
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"
}
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.
Broschüren
Alle String Felder dürfen maximal 255 Zeichen enthalten, sofern in der Beschreibung nichts anderes angegeben ist. Sie können dieses Verhalten jederzeit auf der Seite "Weiterleiten" in beobachten MyWunder.
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
Y
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.
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. Maximale Länge: 40.
Telefonnummer
N
Schnur
Mit dieser Adresse verknüpfte Telefonnummer. E.123-Format, zum Beispiel +31683243251
Chamber_of_Commerce_Number
N
Schnur
ERFORDERLICH
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 Sendungsentwürfe
Mit dieser API können Sendungsentwürfe im Wuunder-System erstellt werden.
Konzeptionell wird dieser Ablauf von einem Drittanbieter-System initiiert, das Entwürfe erstellt. Das Wuunder-System speichert die Sendungsentwürfe und antwortet mit einer URL, die verwendet werden sollte, um einen Benutzer zum Wuunder-System umzuleiten, damit die Sendung gebucht werden kann. Weitere Informationen zu Buchungsentwürfen finden Sie hier hier.
Wenn der Benutzer die Buchung im Wuunder-System abschließt, wird das zur Verfügung gestellt webhook_url wird mit Informationen zur Buchung angerufen, siehe [Buchungs-Webhook] (# Buchungs-Webhook) für Details. Darüber hinaus wird der Benutzer zu der in angegebenen URL zurückgeleitet redirect_url.
POST / Entwürfe
Anfrage Körper
NAME
ERFORDERLICH
TYP
BESCHREIBUNG
id
Y
Schnur
Eine (eindeutige) ID, die sich auf die Sendung in der Massenanforderung bezieht. Beachten Sie, dass dies nur vom Client verwendet werden soll, um die Anforderung und die Antwortelemente zu korrelieren. Diese ID wird vom Wuunder-System nicht verwendet.
Beispiel
[
{
"Id": "1",
"Entwurf": {
"Lieferadresse": {
"Geschäft": "Janssen BV",
"Chamber_of_commerce_number": null,
"Land": "NL",
"Email_address": null,
"Familienname": "Janssen",
"Vorname": "Jan",
"Hausnummer": "12",
"Lokalität": "Eindhoven",
"Telefonnummer": "+31612345678",
"Straßenname": "Lieferadresse",
"Postleitzahl": "1234AB"
},
"Kundenreferenz": "12345678",
"Beschreibung": "Test",
"Höhe": "50",
"Art": "Paket",
"Länge": "10",
"Personal_message": "test",
"Abholadresse": {
"Geschäft": "Mustergeschäft",
"Chamber_of_commerce_number": "21",
"Land": "NL",
"Eori_number": "132321321",
"Barrel": "132321321",
"E-Mail-Addresse": "[E-Mail geschützt]"
"Familienname": "NachnameKontaktperson",
"Vorname": "VornameKontaktperson",
"Hausnummer": "1",
"Lokalität": "Ort",
"Telefonnummer": "+31612345678",
"Straßenname": "Firmenadresse",
"Postleitzahl": "1111AA"
},
"Bild": null,
"Wert": "6900",
"Gewicht": "5000",
"Breite": "20",
"Anzahl_der_Elemente": 1,
"Preferred_service_level": "dpd: günstigste",
"Anzahl_der_Elemente": 1,
"Order_lines": [
{
"Hs_code": "58342450",
"Country_of_orgin": "NL",
"Menge: 1,
"Beschreibung": "Geschenke",
Wert: 18.95,
Gewicht: 1,
"Sku": "12345",
"Ean": "987654321"
"Quelle": {
"Produkt": "Magento",
"Plugin": {
"Build": "1.9",
"Versionen": "1.0"
}
},
"Webhook_url": "https://my.backend.com/webhooks",
"Redirect_url": "https://my.backend.com/admin"
}
},
… // Mehrere Entwürfe können in einer Anfrage gesendet werden
]
Erfolgreiche Antwort
Status: 200 OK
[
{
Fehler: [
{
"Feld": "Kind",
"Mitteilungen": [
"Ist ungültig"
]
}
],
"Id": "1"
},
{
Fehler: [],
"Id": "2",
“url”: “https://api.wearewuunder.com/account/drafts/ff8a3d08-e5ff-4cc2-8a7c-9eb2e4e030d6/edit”
}
]
Fehlerantworten
HTTPS-STATUSCODE
FEHLERBESCHREIBUNG
200
Diese API gibt im Allgemeinen immer eine HTTP 200-Antwort zurück, selbst wenn die Entwürfe in der Anforderung Validierungsfehler aufweisen. Dies liegt daran, dass diese API eine Massen-API ist, bei der einige Ressourcen gültig sein können, andere jedoch nicht.
Webhook buchen
Wenn der Benutzer eine Buchung erfolgreich abgeschlossen hat, wird der beim Erstellen der Buchung angegebene Webhook mit der folgenden Nutzlast aufgerufen:
{
"Aktion": "Versand_Buch",
"Sendung": {
“id”: “7db6bba2-9b85-4624-a22f-ab4c7ac57611”,
"Beschreibung": "Drucker",
"Personal_message": "Hier sind die bestellten Drucker, viel Spaß!",
Wert: 189,
"Art": "Paket",
Länge: 100,
Breite: 100,
"Höhe": 100,
Gewicht: 2000,
"Status": "pending_label",
"Is_return": false,
"Kundenreferenz": "12345678",
"Kundenreferenz": "Referenz",
"Drop_off": false,
“parcelshop_id”: “7db6bba2-9b85-4624-a22f-ab4c7ac57611”,
"Abholadresse": {
"Geschäft": "Mycompany BV",
"Chamber_of_commerce_number": "21",
"E-Mail-Addresse": "[E-Mail geschützt]"
"Familienname": "NachnameKontaktperson",
"Vorname": "VornameKontaktperson",
"Lokalität": "Ort",
"Telefonnummer": "+31612345678",
"Straßenname": "Firmenadresse",
"Hausnummer": "1",
"Postleitzahl": "1111AA",
"Land": "NL"
},
"Lieferadresse": {
"Geschäft": "Janssen BV",
"Chamber_of_commerce_number": null,
"E-Mail-Addresse": "[E-Mail geschützt]"
"Familienname": "Janssen",
"Vorname": "Jan",
"Lokalität": "Eindhoven",
"Telefonnummer": "+31612345678",
"Straßenname": "Firmenadresse",
"Hausnummer": "12",
"Postleitzahl": "1234AB",
"Land": "NL"
},
"Label_url": "https://api.wearewuunder.com/shipments/123/label",
"Track_and_trace_url": "https://api.wearewuunder.com/shipments/123/track_and_trace",
"Picture_url": "https://s3.amazonaws.com/some-bucket/printer.jpg"
},
"Bewertung": {
"Carrier_name": "DPD",
"Währung": "EUR",
“id”: “e3a06e99-d1a2-4aa8-b6fe-2be7fa25cdde”,
"Info": "Info",
"Modalität": "Straße",
"Pickup_date": "2018-04-13",
"Preis": 695,
"Rate_modifier": 1,
"Service_level": "DPD Home",
"Servicezeit": {
"Nach": "15:00:00",
"Vorher": "17:00:00"
},
"Fass": 146
},
"Authentication_token": "Token" // JWT-Token
}
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)
