Service shipment

Documenation

View and create shipments in TOP. Print barcode labels.

Summary

Name: Shipping Webservice.
Reason to Call: Create a shipment and retrieve barcode labels.
Input: All information about the shipment.
Output: One or more shipping labels.

Methods

Method	Query parameters	Description
GET		Retrieve a list of all Shipments.
	shipment_id	Retrieve the details of a Shipment, this parameter can directly be appended to the endpoint
	label_type	(optional) The label type, valid types are: a4, horizontal, vertical
	label_width	(optional) label width in mm
	label_height	(optional) label height in mm
	suppress_label	(optional) Suppresses the output of a base64 encoded label in the response
POST		Creates a new Shipment in TOP
	label_type	(optional) The label type, valid types are: a4, horizontal, vertical
	label_width	(optional) label width in mm
	label_height	(optional) label height in mm
	suppress_label	(optional) Suppresses the output of a base64 encoded label in the response

Call details

Interface version	Endpoint
Production endpoint	https://api-test.tofbe.eu/v1/shipment

Versioning

API	Version	Release date	Status	Release notes
Shipment	v1	Sep 2020	Current version
Shipment/ADR	v1	Nov 2023	Current version	Added dangerous goods

Error codes

The Rest service will use standard HTTP status code to indicate wheter an error has occured or not

HTTP status	Description
200	Successful request, for example a GET request to retrieve shipment details
201	Successfully created, for example a POST request to create a shipment
401	Unauthorized. The request was made with invalid credentials
404	Not Found, the endpoint used was not valid
422	Data validation failed. The data in the request could not be validated, for example postal code is not valid
500	Internal server error.

In case of an error, the REST service will send a JSON response with information regarding the error:

HTTP:422
[
    {
        "field": "HouseNumber",
        "message": "House Number cannot be blank."
    },
    {
        "field": "DeliveryDate",
        "message": "Weekend delivery not allowed"
    }
]

Shipment data

To create a shipment, POST Shipment data in JSON format. The following attributes are allowed

Attribute	Mandatory	Format	Description	Example
ShipmentId	O	Number	NOTE: This field is only available in API Responses and contains the Unique shipmentId in TOP.	89362736
AccountId	M	Number	AccountId, you can retrieve valid accountIds from the customer service	1126
DeliveryDate	O	Date	DeliveryDate (format yyyy-mm-dd), delivery day of your shipment. The delivery day is always at least one working day after today. Weekend days are not allowed. If this field is omitted, the next working day is automatically selected.	29-10-2020
ReferenceNumber	M	String	ReferenceNumber for this shipment	1234
ReceiverName1	M	String	Name of receiver	PostNLBelgië - Pharma & Care
ReceiverName2	O	String	Extra Receiver adress info	Customer service
ReceiverName3	O	String	Extra Receiver adress info	First floor
ConsigneeInformation	O	String	Extra information for this consignee	Consignee info
OrderComment	O	String	Extra comment for this shipment	Order info
Street	M	String	Street	Bremheidelaan
HouseNumber	M	String	House number	10
PostalCode	M	String	Zip code	2300
City	M	String	City	Turnhout
CountryCode	M	String	ISO 2-char country code	BE
NumPal	M/O	Number	Number of pallets in this shipment	1
NumCol	M/O	Number	Number of colli in this shipment	1
Weight	M	Number	Total weight of this shipment	1
Pickup	M	Boolean	Is this shipment a pickup?	false
ServiceLevel	O	String	Service Level for this shipment. Valid ServiceLevels are: N => Normal \| A => Plus8 \| F => Plus10 \| V => Plus12 \| M => Plus17 \| A => Evening	N
Confidential	O	Boolean	Turn on/off service confidential	false
Inhouse	O	Boolean	Turn on/off service Inhouse delivery	false
PalletBreakdown	O	Boolean	Turn on/off service Pallet breakdown	false
ValueCod	O	Number	Value service Cash on delivery	11.31
Adr	O	Array	Zero or more ADR records for this shipment (Dangerous goods).	[]
Labels	O	Base64 encoded PDF binary data	NOTE: This field is only available in API Responses and contains the shipment PDF labels in Base64 encoded format.

ADR data (Dangerous goods)

Attribute	Mandatory	Format	Description	Example
UnNo	M	String	Un number	1760
Lq	M	String	Limited quantity	LQ22
PackingGroup	M	String	PackingGroup	II
TransportCategory	M	String	TransportCategory	2
Quantity	M	Number	Quantity of items within this shipment	1
Remark	O	String	Free remark for this dangerous goods item	Extra remark
MaterialCategory	M	String	Category of the packing material	Barrels
MaterialName	M	String	Name of the packing material	steel
Weight	M	Number	Weight of the dangerous goods within this shipment	1
ExemptLq	O	Boolean	Exempt for Limited quantity	0 or 1