Book draft shipments API specification

Wuunder has multiple API’s to connect with:

1. A book shipments API

where you can book a shipment at a specific carrier and using a specific service. We return the shipping label, track & trace url and the carrier name. If there’s a problem with the address or when the service is not possible for the shipment you want to book we return an error. On this page you can find all the details. 

2. A book draft shipments API

where you can send draft shipments to Wuunder. Sending the specific carrier and service is optional. These draft shipments you can book at once using the bulk booking feature in MyWuunder. 

This technical manual contains all the information required to work with the Wuunder book draft shipments API. If you do have any questions, please, contact us.

General

The Wuunder API is a RESTful API, served over HTTPS. All data is sent and received as JSON and encoded in UTF-8.

Wuunder provides isolated staging and production environments:

API
Shipments created succesfully with our API are visible in:

ENVIRONMENT

BASE URL

Staging

Production

Mobile app on IOS & Android

Authentication

API calls are authenticated using API tokens.
Clients that wish to integrate with the Wuunder API will be assigned a per-client token. If you do not have an API key you can request one here.

API tokens must be included in the Authorization header.

 

     Authorization: Bearer TOKEN-HERE

 

Content type

Clients must specify the type of content they are sending through the Content-Type header. At this time, only application/json is supported:

 

     Content-Type: application/json

 

Versioning

Clients must specify the API version they wish to consume. Specifying the API version is done via the Accept header:

 

     Accept: application/json+v1

 

Errors

Errors use the appropriate HTTP status code where possible. Missing parameters for example will respond with a 422 Unprocessable Entity response.

 
     HTTP/1.1 422 Unprocessable Entity

     {
       “errors” : [
         { “field”: “weight”, “messages”: [“can’t be blank”] }
       ]
     }
 

Providing an invalid authentication token will result in a 401 Unauthorized:

 
     HTTP/1.1 401 Unauthorized

     {
        “error”: “unauthorized”
     }
 

HTTP Verbs

Where possible, the Wuunder API strives to use appropriate HTTP verbs for each action.

Resources

All String fields must obey a maximum of 255 characters unless otherwise noted in the description. You can always observe this behavior in the “redirect page” in MyWuunder.

NAME

REQUIRED

TYPE

DESCRIPTION

country

Y

String

ISO-2 country code, for example "NL" or "BE".

family_name

Y

String

Max length: 30.

given_name

Y

String

Max length: 30.

house_number

Y

String

Number including any additions. Max length: 8.

locality

Y

String

Max length: 30.

zip_code

Y

String

Max length: 9.

street_name

Y

String

Street part of the addresses. Max length: 35.

business

N

String

When included this addresses will be regarded a business address, otherwise a private address

email_address

N

String

Email address associated with this address. Max length: 40.

phone_number

N

String

Phone number associated with this address. E.123 format, for example +31683243251

chamber_of_commerce_number

N

String

REQUIRED

Please use your own e-mail address for testing purposes because Wuunder will send a booking confirmation to the booker (optional), Shipping confirmation with the label to the sender (optional) and track & trace e-mail to the receiver (optional).

Create draft shipments

This API allows to create draft shipments in the Wuunder system.

Conceptually this flow is initiated by a third-party system that creates drafts. The Wuunder system will store the shipment drafts and respond with a url that should be used to redirect a user to the Wuunder system so the shipment can be booked. More information about booking drafts you can find here.

If the user completes the booking in the Wuunder system the provided webhook_url will be called with information about the booking, see [Booking webhook](#booking-webhook) for details. Additionally, the user will be redirected back to the url specified in redirect_url.

 
     POST /drafts
 

Request body

NAME

REQUIRED

TYPE

DESCRIPTION

id

Y

String

A (unique) ID referring to the shipment in the bulk request. Note that is only intended to be used by the client to correlate the request and the response items. This ID is not used by the Wuunder system.

family_name

Y

DraftShipment

You can find more info about #DraftShipments  here.

Example

   

     [
       {
         “id”: “1”,
         “draft”: {
          “delivery_address”: {
            “business”: “Janssen BV”,
            “chamber_of_commerce_number”: null,
            “country”: “NL”,
            “email_address”: null,
            “family_name”: “Janssen”,
            “given_name”: “Jan”,
            “house_number”: “12”,
            “locality”: “Eindhoven”,
            “phone_number”: “+31612345678”,
            “street_name”: “Afleveraddress”,
            “zip_code”: “1234AB”
          },
          “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”: “info@voorbeeldshop.nl”,
            “family_name”: “AchternaamContactpersoon”,
            “given_name”: “VoornaamContactpersoon”,
            “house_number”: “1”,
            “locality”: “Plaats”,
            “phone_number”: “+31612345678”,
            “street_name”: “Bedrijfsadres”,
            “zip_code”: “1111AA”
         },
         “picture”: null,
         “value”: “6900”,
         “weight”: “5000”,
         “width”: “20”,
         “number_of_items”: 1,
         “preferred_service_level”: “cheapest”,
         “source”: {
           “product”: “magento”,
           “plugin”: {
             “build”: “1.9”,
             “versions”: “1.0”
          }
         },
         “webhook_url”: “https://my.backend.com/webhooks”,
         “redirect_url”: “https://my.backend.com/admin”
       }
      },
     … // multiple drafts can be sent in one request
     ]

 

Successful response

 

      Status: 200 OK

      [
         {
           “errors”: [
             {
             “field”: “kind”,
             “messages”: [
               “is not valid”
             ]
          }
        ],
        “id”: “1”
      },
      {
        “errors”: [],
        “id”: “2”,
        “url”: “https://api.wearewuunder.com/account/drafts/ff8a3d08-e5ff-4cc2-8a7c-9eb2e4e030d6/edit”
      }
     ]

 

Error responses

HTTPS STATUS CODE

ERROR DESCRIPTION

200

This API will generally always return an HTTP 200 response, even if the drafts in the request have validation errors. This is because this API is a bulk API, where some resources can be valid while others are not.

Booking Webhook

When the user successfully completes a booking the webhook specified when creating the booking will be called with the following payload:

 

     {
       “action”: “shipment_booked”,
       “shipment”: {
         “id”: “7db6bba2-9b85-4624-a22f-ab4c7ac57611”,
         “description”: “Printer”,
         “personal_message”: “Hier zijn de bestelde printers, veel plezier!”,
         “value”: 189,
         “kind”: “package”,
         “length”: 100,
         “width”: 100,
         “height”: 100,
         “weight”: 2000,
         “status”: “pending_label”,
         “is_return”: false,
         “customer_reference”: “12345678”,
         “customer_reference”: “reference”,
         “drop_off”: false,
         “parcelshop_id”: “7db6bba2-9b85-4624-a22f-ab4c7ac57611”,

         “pickup_address”: {
           “business”: “Mycompany B.V.”,
           “chamber_of_commerce_number”: “21”,
           “email_address”: “info@voorbeeldshop.nl”,
           “family_name” :”AchternaamContactpersoon”,
           “given_name”: “VoornaamContactpersoon”,
           “locality”: “Plaats”,
           “phone_number”: “+31612345678”,
           “street_name”: “Bedrijfsadres”,
           “house_number”: “1”,
           “zip_code”: “1111AA”,
           “country”: “NL”
         },

         “delivery_address”: {
           “business”: “Janssen BV”,
           “chamber_of_commerce_number”: null,
           “email_address”: “Jan@JanssenBV.nl”,
           “family_name”: “Janssen”,
           “given_name”: “Jan”,
           “locality”: “Eindhoven”,
           “phone_number”: “+31612345678”,
           “street_name”: “Bedrijfsadres”,
           “house_number”: “12”,
           “zip_code”: “1234AB”,
           “country”: “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”
       },
       “rate”: {
         “carrier_name”: “DPD”,
         “currency”: “EUR”,
         “id”: “e3a06e99-d1a2-4aa8-b6fe-2be7fa25cdde”,
         “info”: “info”,
         “modality”: “road”,
         “pickup_date”: “2018-04-13”,
         “price”: 695,
         “rate_modifier”: 1,
         “service_level”: “DPD Home”,
         “service_time”: {
           “after”: “15:00:00”,
           “before”: “17:00:00”
         },
         “vat”: 146
       },
       “authentication_token”: “token” // JWT token
     }

 

 

Track and Trace Webhook

 

     {
       “action”: “track_and_trace_updated”,
       “track_and_trace_code”: “S3123”,
       “carrier_code”: “TNT”,
       “carrier_name”: “TNT Express”,
       “authentication_token”: “token” // JWT token
     }

 

It is expected that the system receiving the webhook responds with a 2xx status response. Any other response will be regarded as a failure, in which case the Wuunder system will start retrying the webhook using exponential back off.

Authentication token from the webhook response

Sample data:

Token

     

     “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJib29raW5
      nX2lkIjoiNzhkZTZjNDYtMWE2Ni00YmQxLTg0MmQtZTkzNmIw
      ZDg4MjRiIiwiZXhwIjoxNTAzNTc3MTExNjA2Ljk0OX0.Q4ED7N
      q2JUa5uZaxcaAG3m6oGI0oeFjcb_5Mz0HQOPw” 

 

Consist of:

HEADER: ALGORITHM & TOKEN TYPE

   

     json
     {
       “alg”: “HS256”,
       “typ”: “JWT”
     }

 

PAYLOAD: DATA

     

     json
     {
       “booking_id: “78de6c46-1a66-4bd1-e936b0d8824b”
       “exp”: 1503577111606.949
     }

 

Where booking_id is the identifier of processed booking and exp is
expiration time. Wuunder expects the webshop to validate that the expiry time
has not passed yet.

Webshops can verify the validity of the token by calculating the signature, using
their webshop token as the shared secret.

     

     exp = booking_inserted_at (unix time) + default_expiration_time (24 * 60 * 60)