A step-by-step guide and best practices for integrating a shipper solution.
Please be aware that some of them may contain only partial requests.
Due to fact, that complete requests and responses are very long in many cases they were trimmed down to what’s really important in given use case.
Complete solution for integrating all available Trans.eu API for the highest possible automation level, considering:
- carrier is yet to be determined
- carrier is using Trans.eu Platform only, with no additional freight management software involved
- both shipper and carriers have existing and valid Trans.eu account
- all shipper’s freight management will be done using api
Before it is possible to send any request, user needs to authorize access.
- client app was registered using registration form
- external app was granted api keys (client_id and client_secret)
- authorization process has been implemented in external app
Create new freight
Once the authorization has been granted, it is now possible to create new freight. This element is being used when:
- trusted carriers operate on Trans.eu Platform and been assigned to appropriate groups
- new carriers can be assigned using Smartmatch algorithm
- own fleet is insufficient
- additional, spot freight has been assigned
Each freight must consist of:
- loading location and time
- unloading location and time
- required truck body type
- summary of freight’s loads weight
- ftl/ltl parameter
The use of all the possibilities of freight consists of:
- providing precise information about spots on freight route, including address, coordinates and schedule
- assigning detailed information regarding loads
- creating detailed operations of loading and unloading each load in specified spots
In this use case only publication using automation rules is considered.
Other freight parameters:
- external_source — allows to send internal freight identifier to Trans.eu Platform
- loading meters — summary of loading meters for loads assigned to freight (described below)
- other requirements, such as mandatory GPS device, adr classes, loading type, packaging type, etc.
- there has to be at least one loading spot and one unloading spot
- summary of loads weight must equal freight capacity
- summary of load operation weight must equal zero
- summary of loads length and width must equal appropriate amount of loading meters
Additional possibilities available during freight creation:
- if there are no coordinates set for spots location, API will assign coordinates for recognized locations
Example payload and freight creation description can be found here.
Negotiate freight conditions
If freight pricing conditions did not meet carriers expectation, they might be allowed to negotiate the price.
Each price negotiation offer consists of:
- price value
- price currency
- identification of offer creator
- version of offer
- date and time of offer creation
Freight negotiation details can be found here.
Cancel freight publication
How to cancel freight publication is described here.
For freight where publication was cancelled or never invoked it is possible to archive the freight. Archived freight are removed from list of active freights, but are still available using get freight by id or by getting the list of archived freights.
How to get archived freights list is described here.
Receive transport order
Accepted freight creates transport order, which consists of:
- freight details (freight id, locations, loads, requirements, etc)
- carrier details (address and vat number)
- freight forwarder details (address and vat number)
- driver details
- vehicle details
Details about receiving list of transport orders can be found here.
Get monitoring task
Accepted freight, depending on properties, might also immediately create new monitoring task.
- vehicle id