Description of adding new transport order to selected carrier for assignment of driver and vehicle.
Scenario
- carrier is selected and present on Trans.eu Platform
- carrier’s TransId is stored in external TMS and can be sent via API
- conditions of cooperation have been agreed upon
- carrier is using Trans.eu Platform only, with no additional freight management software involved
- both freight forwarder and carriers have existing and valid Trans.eu account
- carrier has to assign vehicle and driver
- completed order with vehicle and driver is downloaded from Trans.eu API
Diagram
Authorize access
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 transport order
Each transport must consist of:
- carrier’s information
- loading location and time
- unloading location and time
- required truck body type
- summary of freight’s loads weight
- ftl/ltl parameter
Endpoint:
POST https://api.platform.trans.eu/ext/orders-api/v1/orders-createdRequest example:
Example of transport order posting request:
{
"freight": {
"requirements": {
"is_ftl": true,
"required_truck_bodies": [
"curtainsider",
"box"
],
"vehicle_size_id": "bus"
},
"carrier": {
"company_id": 111111
},
"capacity": 20,
"loads": [],
"spots": [
{
"name": null,
"spot_order": 1,
"place": {
"address": {
"locality": "Kraków",
"postal_code": "31-001",
"country": "PL"
}
},
"operations": [
{
"operation_order": 1,
"loads": [],
"type": "loading",
"timespans": {
"begin": "2021-08-22T11:00:00+0200",
"end": "2021-08-22T12:00:00+0200"
}
}
]
},
{
"spot_order": 2,
"place": {
"address": {
"locality": "Dąbrowa Środkowa",
"postal_code": "59-330",
"country": "PL"
}
},
"operations": [
{
"type": "unloading",
"loads": [],
"operation_order": 1,
"timespans": {
"begin": "2021-08-23T11:00:00+0200",
"end": "2021-08-23T11:00:00+0200"
}
}
]
}
]
},
"payment": {
"days": 30,
"price": {
"type": "km",
"value": 1500,
"currency": "pln"
}
},
"monitoring": {
"required": true
}
}Response:
Confirmation of creating new transport order
{
"additional_terms": null,
"created_at": "2021-08-03T10:46:47.095Z",
"freight": {
"carrier": {
"assignee": null,
"legal_name": "Firma Testowa Przewoźnik",
"vat_id": "1111111111"
},
"id": "",
"reference_number": null,
"requirements": {
"is_ftl": true,
"other_requirements": [],
"required_adr_classes": [],
"required_truck_bodies": [
"curtainsider",
"box"
],
"required_ways_of_loading": [],
"shipping_remarks": null,
"temperature": null,
"vehicle_size_id": "bus"
},
"shipper": {
"assignee": {
"account_id": 749989,
"email": "api@trans.eu",
"family_name": "Kowalski",
"fax": null,
"given_name": "Adam",
"telephone": "0048 1111111",
"trans_id": "2222222-1"
},
"legal_name": "Firma Testowa Spedycja",
"vat_id": "222222222"
},
"spots": [
{
"description": null,
"name": null,
"operations": [
{
"loads": [],
"operation_order": 1,
"time_window": null,
"time_window_reason": null,
"timespans": {
"begin": "2021-08-22T09:00:00.000Z",
"end": "2021-08-22T10:00:00.000Z"
},
"type": "loading"
}
],
"place": {
"address": {
"country": "pl",
"description": null,
"locality": "Kraków",
"number": null,
"postal_code": "31-001",
"street": null
},
"coordinates": null
},
"spot_order": 1
},
{
"description": null,
"name": null,
"operations": [
{
"loads": [],
"operation_order": 1,
"time_window": null,
"time_window_reason": null,
"timespans": {
"begin": "2021-08-23T09:00:00.000Z",
"end": "2021-08-23T09:00:00.000Z"
},
"type": "unloading"
}
],
"place": {
"address": {
"country": "pl",
"description": null,
"locality": "Dąbrowa Środkowa",
"number": null,
"postal_code": "59-330",
"street": null
},
"coordinates": null
},
"spot_order": 2
}
]
},
"id": "a988c5a6-6111-49e8-ae5b-225727bdbfbb",
"invoice": null,
"monitoring": {
"required": true
},
"number": "2021/08/03/2",
"payment": {
"days": 30,
"price": {
"currency": "pln",
"type": "km",
"value": 1500
}
},
"related": [],
"status": {
"value": "proposal-waiting"
}
}Receiving updated transport order:
GET https://api.platform.trans.eu/ext/orders-api/orders-created/a988c5a6-6111-49e8-ae5b-225727bdbfbbResponse example:
{
"additional_terms": null,
"archived_at": null,
"attachments": [],
"can_archive": false,
"cancellation": null,
"cooperation": {
"status": "ACTIVE"
},
"created_at": "2021-07-01T08:54:07.008Z",
"driver": {
"account_id": 771476,
"contact_phone": {
"number": "11111111111",
"prefix": "0048"
},
"email": "trans@trans.eu",
"employee_id": 999446,
"family_name": "Driver",
"full_name": "Jan Driver",
"given_name": "Jan",
"identity_document_number": null,
"phone": null
},
"freight": {
"carrier": {
"assignee": null,
"legal_name": "Test Company",
"vat_id": "11111111111"
},
"id": "",
"reference_number": null,
"requirements": {
"is_ftl": true,
"other_requirements": [
"lift",
"hds"
],
"required_adr_classes": [
"adr_1"
],
"required_truck_bodies": [
"cooler",
"isotherm"
],
"required_ways_of_loading": [
"top"
],
"shipping_remarks": "Shipping remarks",
"temperature": {
"max": 100,
"min": 10
},
"vehicle_size_id": "bus"
},
"shipper": {
"assignee": {
"account_id": 749989,
"email": "test@trans.eu",
"family_name": "Kowalski",
"fax": null,
"given_name": "Krzysztof",
"telephone": "0048 111111111",
"trans_id": "1007374-1"
},
"legal_name": "Test spedition company",
"vat_id": "222222222222"
},
"spots": [
{
"description": "Example description",
"name": "Magazine 1",
"operations": [
{
"loads": [],
"operation_order": 1,
"time_window": null,
"time_window_reason": null,
"timespans": {
"begin": "2021-06-22T09:00:00.000Z",
"end": "2021-06-22T10:00:00.000Z"
},
"type": "loading"
}
],
"place": {
"address": {
"country": "pl",
"description": null,
"locality": "Kraków",
"number": "5",
"postal_code": "31-001",
"street": "Wawel"
},
"coordinates": {
"latitude": 50.06143,
"longitude": 19.93658
}
},
"spot_order": 1
},
{
"description": null,
"name": null,
"operations": [
{
"loads": [],
"operation_order": 1,
"time_window": null,
"time_window_reason": null,
"timespans": {
"begin": "2021-06-23T09:00:00.000Z",
"end": "2021-06-23T09:00:00.000Z"
},
"type": "unloading"
}
],
"place": {
"address": {
"country": "pl",
"description": null,
"locality": "Dąbrowa Środkowa",
"number": "34",
"postal_code": "59-330",
"street": "Średnia"
},
"coordinates": {
"latitude": 51.41828,
"longitude": 16.33485
}
},
"spot_order": 2
}
]
},
"id": "da012de9-faca-4b14-b380-9b94aadff6fa",
"invoice": null,
"is_archived_permanently": false,
"legacy_freight_id": null,
"monitoring": {
"providers": [
"trans_task",
"external_telematics"
],
"required": true
},
"number": "2021/07/01/1",
"payment": {
"days": 30,
"price": {
"currency": "pln",
"type": "km",
"value": 1500
}
},
"related": [],
"source": {
"author_account_id": 749989,
"source_date": "2021-07-01T08:54:07.008Z",
"source_id": null,
"type": "api"
},
"status": {
"comment": null,
"value": "waiting-for-confirmation"
},
"vehicle": {
"semi_trailer": {
"dispatcher_id": 54083,
"id": 501737,
"kind": "4_semi_trailer",
"registration_plate_number": "PL1111111",
"type": "5_tent"
},
"truck": {
"dispatcher_id": 41483,
"id": 236503,
"kind": "5_truck",
"registration_plate_number": "DW1111111",
"revision": 1,
"type": null
}
}
}