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.


Com­plete solu­tion for inte­grat­ing all avail­able 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 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 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 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 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