skip to Main Content

BOEKUWZENDING WEBSERVICES V 2.4.0

TABLE OF CONTENTS

Version history2
Table of contents3
Environments4
Credentials4
Endpoints5
Shipment5
Rate request6
Services6
Examples7
Create shipment (POST)7
Shipment response8
Rate Request (POST)9
Rate Request response9
Services (POST)10
Services response10
CURL examples11

VERSION HISTORY

29-11-20192.0.0First public release
9-1-20202.0.1Improvements
13-1-20202.1.0Updated endpoints URL’s
14-1-20202.1.1Added service in shipment POST
29-01-20202.1.5Added options in shipment POST
25-03-20202.2.7Several improvements to documentation
20-04-20202.3.0Updated services and added Rate request
04-05-20202.4.0Added Track and Trace

ENVIRONMENTS

There are separate environments available for development/testing (staging) and production. The staging environment should be used to test the implementation. After successful implementation and acceptance access to the production environment will be granted.

Staging 
Endpoint:https://api.staging.mijn.boekuwzending.com
Documentation:https://api.staging.mijn.boekuwzending.com/docs
Production 
Endpointhttps://api.mijn.boekuwzending.com
Documentationhttps://api.mijn.boekuwzending.com/docs

CREDENTIALS

To make a connection tot he API credentials are required. Credentials can be requested by (info@boekuwzending.com). When granted, a clientId and clientSecret will be provided.
For both environments there are separate credentials. Credentials for the staging environment can’t be used in the production environment.

ENDPOINTS SHIPMENT

Through the shipment endpoint a shipment can be created and information about existing shipments can be retrieved.

FieldnameType (length)RequiredRemark
invoiceReferenceString (35 chars)NoThis field will be shown on the invoice
transportTyperoad_transport,YesType of transport, road_transport should be used in most cased.
sea_fright of air_freight
incoTermsDAP of DDPNoOnly for shipments outside the EU (import / export)
Delivery At Place (DAP) / Delivery Duty Paid (DDP)
serviceString (45 chars)No, but recommendedExamples: buz-dpd-home, buz-dpd-classic, buz-dpd-e10, buz-dpd-e12, buz-dpd-e18
shipFromNoIf not given, the default shipFrom address will be used, consult Boekuwzending if you want to know what your default shipFrom address is
shipFrom.contactYes, if shipFrom is given
shipFrom.contact.nameString (45 chars)Yes, if shipFrom is given
shipFrom.contact.companyString (35 chars)No
shipFrom.contact.phoneNumberString (25 chars)Yes, if shipFrom is givenTelephone number must be in internal format
shipFrom.contact.emailAddressString (50 chars)Yes, if shipFrom is given
shipFrom.addressYes, if shipFrom is given
shipFrom.address.streetString (35 chars)No
shipFrom.address.numberString (5 chars)No
shipFrom.address.numberAdditionString (10 chars)No
shipFrom.address.addressLine2String (35 chars)No
shipFrom.address.postcodeString (12 chars)Yes, if shipFrom is givenMust be a valid postcode within the country
shipFrom.address.cityString (25 chars)Yes, if shipFrom is given
shipFrom.address.countryString (2 chars)Yes, if shipFrom is givenISO 3166-1 alpha-2 country code
shipFrom.address.privateAddressBooleanYes, if shipFrom is given
shipFrom.address.forkliftOrLoadingDockAvailableBooleanNo
shipFrom.address.accessibleWithTrailerBooleanYes, if shipFrom is given
shipToYes
shipTo.contactYes
shipTo.contact.nameString (45 chars)Yes
shipTo.contact.companyString (35 chars)
shipTo.contact.phoneNumberString (25 chars)YesTelephone number must be in internal format
shipTo.contact.emailAddressString (50 chars)Yes
shipTo.addressYes
shipTo.address.streetString (35 chars)No
shipTo.address.numberString (5 chars)No
shipTo.address.numberAdditionString (10 chars)No
shipTo.address.addressLine2String (35 chars)No
shipTo.address.postcodeString (12 chars)YesMust be a valid postcode within the country
shipTo.address.cityString (25 chars)Yes
shipTo.address.countryString (2 chars)YesISO 3166-1 alpha-2 country code
shipTo.address.privateAddressBooleanYes
shipTo.address.forkliftOrLoadingDockAvailableBooleanNo
shipTo.address.accessibleWithTrailerBooleanYes
dpdNumberString (17 chars)NoDPD customer number (on request)
dpdDepotCodeString (4 chars)NoDPD Depot code (on request)
dispatchYes
dispatch.instructionsString (75 chars)NoPickup instruction
dispatch.referenceString (75 chars)NoPickup reference
dispatch.dateDateYesPickup date (must be greater than or equal to today
dispatch.timewindowNo
dispatch.timeWindow.beginTimeNo
dispatch.timeWindow.endTimeNo
deliveryNo
delivery.instructionsString (75 chars)NoDelivery instruction
delivery.referenceString (75 chars)NoDelivery reference
delivery.dateDateNoPreferred delivery date
delivery.timeWindowNo
delivery.timeWindow.beginTimeNo
delivery.timeWindow.endTimeNo
itemsYes
optionsArrayNoPossible values: ‘saturday_delivery’
items.quantityIntegerYes
items.typestringYesItem type (see API for available types)
items.stackableBooleanNo
items.dimensionsYes
items.dimensions.lengthFloatYesLength of item (cm)
items.dimensions.widthFloatYesWidth of item (cm)
items.dimensions.heightFloatYesHeight of item (cm)
items.weightFloatYesWeight of item (KG)
items.descriptionString (70 chars)Yes
items.customerReferenceString (35 chars)No
items.valueFloatNoOnly for shipments outside the EU (import / export) or insurance
items.tariffNumberString (35 chars)NoHS-code, only for shipments outside the EU (import / export)
items.countryOfOriginString (2 chars)NoISO 3166-1 alpha-2 landcode, only for shipments outside the EU (import / export)

RATE REQUEST

Through the rate request endpoint rates can be retrieved based on the given shipment information

FieldnameType (length)RequiredRemark
shipFromNoIf not given, the default shipFrom address will be used, consult Boekuwzending if you want to know what your default shipFrom address is
shipFrom.contactYes, if shipFrom is given
shipFrom.contact.nameString (45 chars)Yes, if shipFrom is given
shipFrom.contact.companyString (35 chars)No
shipFrom.contact.phoneNumberString (25 chars)Yes, if shipFrom is givenTelephone number must be in internal format
shipFrom.contact.emailAddressString (50 chars)Yes, if shipFrom is given
shipFrom.addressYes, if shipFrom is given
shipFrom.address.streetString (35 chars)No
shipFrom.address.numberString (5 chars)No
shipFrom.address.numberAdditionString (10 chars)No
shipFrom.address.addressLine2String (35 chars)No
shipFrom.address.postcodeString (12 chars)Yes, if shipFrom is givenMust be a valid postcode within the country
shipFrom.address.cityString (25 chars)Yes, if shipFrom is given
shipFrom.address.countryString (2 chars)Yes, if shipFrom is givenISO 3166-1 alpha-2 country code
shipFrom.address.privateAddressBooleanYes, if shipFrom is given
shipFrom.address.forkliftOrLoadingDockAvailableBooleanNo
shipFrom.address.accessibleWithTrailerBooleanYes, if shipFrom is given
shipToYes
shipTo.contactYes
shipTo.contact.nameString (45 chars)Yes
shipTo.contact.companyString (35 chars)
shipTo.contact.phoneNumberString (25 chars)YesTelephone number must be in internal format
shipTo.contact.emailAddressString (50 chars)Yes
shipTo.addressYes
shipTo.address.streetString (35 chars)No
shipTo.address.numberString (5 chars)No
shipTo.address.numberAdditionString (10 chars)No
shipTo.address.addressLine2String (35 chars)No
shipTo.address.postcodeString (12 chars)YesMust be a valid postcode within the country
shipTo.address.cityString (25 chars)Yes
shipTo.address.countryString (2 chars)YesISO 3166-1 alpha-2 country code
shipTo.address.privateAddressBooleanYes
shipTo.address.forkliftOrLoadingDockAvailableBooleanNo
shipTo.address.accessibleWithTrailerBooleanYes
itemsYes
optionsArrayNoPossible values: ‘saturday_delivery’
items.quantityIntegerYes
items.typestringYesItem type (see API for available types)
items.stackableBooleanNo
items.dimensionsYes
items.dimensions.lengthFloatYesLength of item (cm)
items.dimensions.widthFloatYesWidth of item (cm)
items.dimensions.heightFloatYesHeight of item (cm)
items.weightFloatYesWeight of item (KG)
items.descriptionString (70 chars)Yes
items.customerReferenceString (35 chars)No
items.valueFloatNoOnly for shipments outside the EU (import / export) or insurance
items.tariffNumberString (35 chars)NoHS-code, only for shipments outside the EU (import / export)
items.countryOfOriginString (2 chars)NoISO 3166-1 alpha-2 landcode, only for shipments outside the EU (import / export)

SERVICES

Through the services endpoint all the available services can be retrieved based on the given shipment information

FieldnameType (length)RequiredRemark
shipFromNoIf not given, the default shipFrom address will be used, consult Boekuwzending if you want to know what your default shipFrom address is
shipFrom.contactYes, if shipFrom is given
shipFrom.contact.nameString (45 chars)Yes, if shipFrom is given
shipFrom.contact.companyString (35 chars)No
shipFrom.contact.phoneNumberString (25 chars)Yes, if shipFrom is givenTelephone number must be in internal format
shipFrom.contact.emailAddressString (50 chars)Yes, if shipFrom is given
shipFrom.addressYes, if shipFrom is given
shipFrom.address.streetString (35 chars)No
shipFrom.address.numberString (5 chars)No
shipFrom.address.numberAdditionString (10 chars)No
shipFrom.address.addressLine2String (35 chars)No
shipFrom.address.postcodeString (12 chars)Yes, if shipFrom is givenMust be a valid postcode within the country
shipFrom.address.cityString (25 chars)Yes, if shipFrom is given
shipFrom.address.countryString (2 chars)Yes, if shipFrom is givenISO 3166-1 alpha-2 country code
shipFrom.address.privateAddressBooleanYes, if shipFrom is given
shipFrom.address.forkliftOrLoadingDockAvailableBooleanNo
shipFrom.address.accessibleWithTrailerBooleanYes, if shipFrom is given
shipToYes
shipTo.contactYes
shipTo.contact.nameString (45 chars)Yes
shipTo.contact.companyString (35 chars)
shipTo.contact.phoneNumberString (25 chars)YesTelephone number must be in internal format
shipTo.contact.emailAddressString (50 chars)Yes
shipTo.addressYes
shipTo.address.streetString (35 chars)No
shipTo.address.numberString (5 chars)No
shipTo.address.numberAdditionString (10 chars)No
shipTo.address.addressLine2String (35 chars)No
shipTo.address.postcodeString (12 chars)YesMust be a valid postcode within the country
shipTo.address.cityString (25 chars)Yes
shipTo.address.countryString (2 chars)YesISO 3166-1 alpha-2 country code
shipTo.address.privateAddressBooleanYes
shipTo.address.forkliftOrLoadingDockAvailableBooleanNo
shipTo.address.accessibleWithTrailerBooleanYes
itemsYes
optionsArrayNoPossible values: ‘saturday_delivery’
items.quantityIntegerYes
items.typestringYesItem type (see API for available types)
items.stackableBooleanNo
items.dimensionsYes
items.dimensions.lengthFloatYesLength of item (cm)
items.dimensions.widthFloatYesWidth of item (cm)
items.dimensions.heightFloatYesHeight of item (cm)
items.weightFloatYesWeight of item (KG)
items.descriptionString (70 chars)Yes
items.customerReferenceString (35 chars)No
items.valueFloatNoOnly for shipments outside the EU (import / export) or insurance
items.tariffNumberString (35 chars)NoHS-code, only for shipments outside the EU (import / export)
items.countryOfOriginString (2 chars)NoISO 3166-1 alpha-2 landcode, only for shipments outside the EU (import / export)

TRACK AND TRACE (GET)

FieldnameType (length)RequiredRemark
idyesThe ID of te label, not the waybill
distributorNoIf given, extra information with of the distributor will be given
DetailsNoIf given, historical data will be given of the label

EXAMPLES

CREATE SHIPMENT (POST)

{

“invoiceReference”: “API TEST”,

“transportType”: “road_transport”,

“incoTerms”: “DAP”,

“service”: “buz-dpd-classic”,

“shipTo”: {

“contact”: {

“name”: “Rik Balder”,

“company”: “Boekuwzending”,

“phoneNumber”: “+31252245480”,

“emailAddress”: “info@boekuwzending.com”

},

“address”: {

“street”: “Bennebroekweg”,

“number”: “267”,

“numberAddition”: “”,

“addressLine2”: null,

“postcode”: “1435CJ”,

“city”: “Rijsenhout”,

“country”: “NL”,

“privateAddress”: false,

“forkliftOrLoadingDockAvailable”: false,

“accessibleWithTrailer”: false

}

},

“dispatch”: {

“instructions”: “Doorbell doesn’t work”,

“reference”: “My first API shipment”,

“date”: “2019-12-01”,

“timeWindow”: {

“begin”: “8:00”,

“end”: “16:00”

}

},

“delivery”: {

“instructions”: “Loading dock”,

“reference”: “API API”,

“date”: “2019-12-05”

},

“options”: [

“saturday_delivery”

],

“items”: [

{

“quantity”: 1,

“type”: “package”,

“stackable”: true,

“dimensions”: {

“length”: 20,

“width”: 20,

“height”: 20

},

“weight”: 20,

“description”: “General cargo”,

“customerReference”: “API TEST”,

“value”: 100,

“tariffNumber”: “1234”,

“countryOfOrigin”: “NL”

}

]

}

Shipment response

 

{

“items”: [

{

“quantity”: 1,

“type”: “package”,

“stackable”: true,

“dimensions”: {

“length”: 20,

“width”: 20,

“height”: 20

},

“weight”: 20,

“description”: “General cargo”,

“value”: 100,

“customerReference”: “API TEST”,

“tariffNumber”: “1234”,

“countryOfOrigin”: “NL”,

“createdAt”: “2020-03-25T16:09:37+01:00”,

“updatedAt”: “2020-03-25T16:09:37+01:00”

}

],

“invoiceReference”: “API TEST”,

“options”: [

{

“surchargeSet”: “/surcharge_sets/030270cc-2ac6-11e9-a938-acde48001122”,

“manual”: true

}

],

“status”: “assigned”,

“transportType”: “road_transport”,

“service”: “/services/da18ea1c-f7f1-11e8-ab4b-02fec4d73ad5”,

“shipFrom”: {

“contact”: {

“name”: “R. Balder”,

“company”: “Boekuwzending.com”,

“phoneNumber”: “+31252245480”,

“emailAddress”: “verkoop@boekuwzending.com”

},

“address”: {

“street”: “Bennebroekerweg 121”,

“number”: “267”,

“numberAddition”: null,

“postcode”: “1435CJ”,

“city”: “Rijsenhout”,

“country”: “NL”,

“addressLine1”: “Bennebroekerweg 121 267”,

“addressLine2”: null,

“forkliftOrLoadingDockAvailable”: true,

“privateAddress”: false,

“accessibleWithTrailer”: true

}

},

“shipTo”: {

“contact”: {

“name”: “Rik Balder”,

“company”: “Boekuwzending”,

“phoneNumber”: “+31252245480”,

“emailAddress”: “info@boekuwzending.com”

},

“address”: {

“street”: “Bennebroekweg”,

“number”: “267”,

“numberAddition”: “”,

“postcode”: “1435CJ”,

“city”: “Rijsenhout”,

“country”: “NL”,

“addressLine1”: “Bennebroekweg 267”,

“addressLine2”: null,

“forkliftOrLoadingDockAvailable”: false,

“privateAddress”: false,

“accessibleWithTrailer”: false

}

},

“dispatch”: {

“instructions”: null,

“reference”: “My first API shipment”,

“date”: “2019-12-01T00:00:00+01:00”,

“timeWindow”: {

“begin”: “1970-01-01T08:00:00+01:00”,

“end”: “1970-01-01T16:00:00+01:00”

},

“vatNumber”: null,

“eoriNumber”: null

},

“delivery”: {

“instructions”: “Loading dock”,

“reference”: “API API”,

“date”: “2019-12-05T00:00:00+01:00”,

“timeWindow”: {

“begin”: null,

“end”: null

},

“vatNumber”: null,

“eoriNumber”: null

},

“incoTerms”: “dap”,

“insurance”: {

“deductibleExcess”: null,

“insuredValue”: null

},

“draft”: false,

“id”: “a472648e-6eaa-11ea-b8e0-0242ac12000e”,

“createdAt”: “2020-03-25T16:09:37+01:00”,

“updatedAt”: “2020-03-25T16:10:07+01:00”

}

 

Rate Request (POST)

 

{

“shipTo”: {

“contact”: {

“name”: “Rik Balder”,

“company”: “Boekuwzending”,

“phoneNumber”: “+31252245480”,

“emailAddress”: “info@boekuwzending.com”

},

“address”: {

“street”: “Bennebroekweg”,

“number”: “267”,

“numberAddition”: “”,

“addressLine2”: null,

“postcode”: “1435CJ”,

“city”: “Rijsenhout”,

“country”: “NL”,

“privateAddress”: false,

“forkliftOrLoadingDockAvailable”: false,

“accessibleWithTrailer”: false

}

},

“items”: [

{

“quantity”: 1,

“type”: “package”,

“stackable”: true,

“dimensions”: {

“length”: 20,

“width”: 20,

“height”: 20

},

“weight”: 20,

“description”: “General cargo”,

“customerReference”: “API TEST”,

“value”: 100,

“tariffNumber”: “1234”,

“countryOfOrigin”: “NL”

}

]

}

 

Rate Request response

 

{

[

{

“service”:[

“description” : PostNL Standaard“,

“code”: “postnl-3085”

],

“price”: 9,50,
“taxt”: 2.11

 

 

“breakdown”: [

{

“description”: “PostNL Standaard”,
“price”: 8.50,

“tax”: 1.90

},

{

“description”: “Dieseltoeslag”,
“price”: 1,

“tax”: 0.21

}
]

 

Services (POST)

 

{

“shipTo”: {

“contact”: {

“name”: “Rik Balder”,

“company”: “Boekuwzending”,

“phoneNumber”: “+31252245480”,

“emailAddress”: “info@boekuwzending.com”

},

“address”: {

“street”: “Bennebroekweg”,

“number”: “267”,

“numberAddition”: “”,

“addressLine2”: null,

“postcode”: “1435CJ”,

“city”: “Rijsenhout”,

“country”: “NL”,

“privateAddress”: false,

“forkliftOrLoadingDockAvailable”: false,

“accessibleWithTrailer”: false

}

},

“items”: [

{

“quantity”: 1,

“type”: “package”,

“stackable”: true,

“dimensions”: {

“length”: 20,

“width”: 20,

“height”: 20

},

“weight”: 20,

“description”: “General cargo”,

“customerReference”: “API TEST”,

“value”: 100,

“tariffNumber”: “1234”,

“countryOfOrigin”: “NL”

}

]

}

 

Services response

 

[

{
“distributor”: “postnl”,

“description” : PostNL Standaard“,

“code”: “postnl-3085”

}
]

 

Track and Trace response

 

{

“active”: {

“status”: “string”,

“code”: “string”,

“description”: “string”,

“date”: {

“date”: “string”,

“timezone_type”: 0,

“timezone”: “string”

}

},

“details”: [

{

“status”: “string”,

“code”: “string”,

“description”: “string”,

“date”: {

“date”: “string”,

“timezone_type”: 0,

“timezone”: “string”

}

}

],

“distributor”: [

{

“code”: “string”,

“name”: “string”

}

]

}

CURL EXAMPLES

REQUEST ACCESS TOKEN

curl -X POST -d “grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}” https://api.staging.boekuwzending.com/token

Replace  {{clientId}} and {{clientSecret}} with yourAPI credentials.

CREATE A SHIPMENT

curl -X POST -d “@shipment.json” -H “Content-Type: application/json” -H “Authorization: Bearer {{accessToken}}” https://api.staging.mijn.boekuwzending.com/shipments

Replace  {{accessToken}} with the accessToken retreived from the above request.

RATE REQUEST

curl -X POST -d “@shipment.json” -H “Content-Type: application/json” -H “Authorization: Bearer {{accessToken}}” https://staging.api.boekuwzending.com/rate-request

Replace  {{accessToken}} with the accessToken retreived from the above request.

RETRIEVE SERVICES

curl -X POST -d “@shipment.json” -H “Content-Type: application/json” -H “Authorization: Bearer {{accessToken}}” https://staging.api.boekuwzending.com/services

Replace  {{accessToken}} with the accessToken retreived from the above request.