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.
Visit Wuunder’s API Docs for more information.
Wuunder provides isolated staging and production environments:
ENVIRONMENT
BASE URL
Playground
Production
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
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.
Verb
Description
GET
Used for retrieving resources.
DELETE
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.
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”,
“eori_number”: “132321321”,
“vat”: “132321321”,
“email_address”: “[email protected]”,
“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”: “dpd:cheapest”,
“number_of_items”: 1,
“order_lines”: [
{
“hs_code”: “58342450”,
“country_of_orgin”: “NL”,
“quantity”: 1,
“description”: “Gifts”,
“value”: 18.95,
“weight”: 1,
“sku”: “12345”,
“ean”: “987654321”
“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”: “[email protected]”,
“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”: “[email protected]”,
“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)