Integration scenario for shipper

A step-by-step guide and best prac­tices for inte­grat­ing a ship­per solu­tion.

Please be aware that some of them may con­tain only par­tial requests.

Due to fact, that com­plete requests and respons­es are very long in many cas­es they were trimmed down to what’s real­ly impor­tant in giv­en use case.

Scenario

Com­plete solu­tion for inte­grat­ing all avail­able Trans.eu API for the high­est pos­si­ble automa­tion lev­el, con­sid­er­ing:

• car­ri­er is yet to be deter­mined
• car­ri­er is using Trans.eu Plat­form only, with no addi­tion­al freight man­age­ment soft­ware involved
• both ship­per and car­ri­ers have exist­ing and valid Trans.eu account
• all ship­per’s freight man­age­ment will be done using api

Scenario diagram

Authorize access

Before it is pos­si­ble to send any request, user needs to autho­rize access.

• client app was reg­is­tered using reg­is­tra­tion form
• exter­nal app was grant­ed api keys (client_id and client_secret)
• autho­riza­tion process has been imple­ment­ed in exter­nal app

Create new freight

Once the autho­riza­tion has been grant­ed, it is now pos­si­ble to cre­ate new freight. This ele­ment is being used when:

• trust­ed car­ri­ers oper­ate on Trans.eu Plat­form and been assigned to appro­pri­ate groups
• new car­ri­ers can be assigned using Smart­match algo­rithm
• own fleet is insuf­fi­cient
• addi­tion­al, spot freight has been assigned

Each freight must consist of:

• load­ing loca­tion and time
• unload­ing loca­tion and time
• required truck body type
• sum­ma­ry of freight’s loads weight
• ftl/ltl para­me­ter

The use of all the possibilities of freight consists of:

• pro­vid­ing pre­cise infor­ma­tion about spots on freight route, includ­ing address, coor­di­nates and sched­ule
• assign­ing detailed infor­ma­tion regard­ing loads
• cre­at­ing detailed oper­a­tions of load­ing and unload­ing each load in spec­i­fied spots

In this use case only pub­li­ca­tion using automa­tion rules is con­sid­ered.

Other freight parameters:

• external_source — allows to send inter­nal freight iden­ti­fi­er to Trans.eu Plat­form
• load­ing meters — sum­ma­ry of load­ing meters for loads assigned to freight (described below)
• oth­er require­ments, such as manda­to­ry GPS device, adr class­es, load­ing type, pack­ag­ing type, etc.
• loads

Validation rules:

• there has to be at least one load­ing spot and one unload­ing spot
• sum­ma­ry of loads weight must equal freight capac­i­ty
• sum­ma­ry of load oper­a­tion weight must equal zero
• sum­ma­ry of loads length and width must equal appro­pri­ate amount of load­ing meters

Addi­tion­al pos­si­bil­i­ties avail­able dur­ing freight cre­ation:

• if there are no coor­di­nates set for spots loca­tion, API will assign coor­di­nates for rec­og­nized loca­tions

Exam­ple pay­load and freight cre­ation descrip­tion can be found here.

Negotiate freight conditions

If freight pric­ing con­di­tions did not meet car­ri­ers expec­ta­tion, they  might be allowed to nego­ti­ate the price.

Each price nego­ti­a­tion offer con­sists of:

• price val­ue
• price cur­ren­cy
• iden­ti­fi­ca­tion of offer cre­ator
• ver­sion of offer
• date and time of offer cre­ation

Freight nego­ti­a­tion details can be found here.

Cancel freight publication

How to can­cel freight pub­li­ca­tion is described here.

Archive freight

For freight where pub­li­ca­tion was can­celled or nev­er invoked it is pos­si­ble to archive the freight. Archived freight are removed from list of active freights, but are still avail­able using get freight by id or by get­ting the list of archived freights.

How to get archived freights list is described here.

Receive transport order

Accept­ed freight cre­ates trans­port order, which con­sists of:

• freight details (freight id, loca­tions, loads, require­ments, etc)
• car­ri­er details (address and vat num­ber)
• freight for­warder details (address and vat num­ber)
• dri­ver details
• vehi­cle details

Details about receiv­ing list of trans­port orders can be found here.

Get monitoring task

Accept­ed freight, depend­ing on prop­er­ties, might also imme­di­ate­ly cre­ate new mon­i­tor­ing task.

• loca­tions
• vehi­cle id
• coor­di­nates