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

Ressourcen

Alles 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 MyWuunder.

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.

Familienname

Y

DraftShipment

Weitere Informationen zu #DraftShipments finden Sie hier  Hier klicken.

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",
            "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",
         "Anzahl_der_Elemente": 1,
         "Preferred_service_level": "am billigsten",
         "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",
           "Email_address": "info@exampleshop.nl",
           "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,
           "Email_address": "Jan@JanssenBV.nl",
           "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:

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)