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, kontaktieren Sie uns.

Allgemeines

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:

API

UMGEBUNG

BASE URL

Mit unserer API erfolgreich erstellte Sendungen sind sichtbar in:

UMGEBUNG

BASE URL

Staging

Produktion

Mobile App auf IOS & androide

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

GET

Wird zum Abrufen von Ressourcen verwendet.

Adressressourcen

Alles 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

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.

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

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

Lieferadresse

Y

Adresse

Siehe die Adressressource

 

Abholadresse

Y

Adresse

Siehe die Adressressource

persönliche Mitteilung

N

Schnur

Persönliche Nachricht für den Kunden, die in der an ihn gesendeten E-Mail enthalten sein wird

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

parcelshop_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.

Beispiel

     {
       "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",
         "Adresse 2": "",
         "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",
           "Email_address": "info@exampleshop.nl",
           "Familienname": "NachnameKontaktperson",
           "Vorname": "VornameKontaktperson",
           "Hausnummer": "1",
           "Lokalität": "Ort",
           "Telefonnummer": "+31612345678",
           "Straßenname": "Firmenadresse",
           "Postleitzahl": "1111AA"
         },
         "Bild": null,
         "Wert": "6900",
         "Gewicht": "5000",
         "Breite": "20",
         "Is_return": false,
         "Drop_off": false,
         "Preferred_service_level": "am billigsten",
         "Anzahl_der_Elemente": 1
     } 

Erfolgreiche Antwort

     Status: 201 Erstellt

     {
       “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",
         "Email_address": "info@exampleshop.nl",
         "Familienname": "NachnameKontaktperson",
         "Vorname": "VornameKontaktperson",
         "Lokalität": "Ort",
         "Telefonnummer": "+31612345678",
         "Straßenname": "Firmenadresse",
         "Hausnummer": "1",
         "Adresse 2": "",
         "Postleitzahl": "1111AA",
         "Land": "NL"
       },

       "Lieferadresse": {
         "Geschäft": "Janssen BV",
         "Chamber_of_commerce_number": null,
         "Email_address": "Jan@JanssenBV.nl",
         "Familienname": "Janssen",
         "Vorname": "Jan",
         "Lokalität": "Eindhoven",
         "Telefonnummer": "+31612345678",
         "Straßenname": "Firmenadresse",
         "Hausnummer": "12",
         "Adresse 2": "",
         "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",
       "Items_track_and_trace_details": [# ein Artikel pro `number_of_items` in Anfrage
        {
          "Track_and_trace_code": "09986052524805",
          “id”: “7133c9e1-424a-4eb4-86e4-27cc8543c5f0”,
          "Correlation_id": "B2C0998605252480520181121"
        }
      ]
     } 

label_url und 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:

Zeichen

     

     “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)