Description of transport orders elements with the usage and conditions.

Transport orders allow to send cooperation details to previously selected carrier, which is specified with TransId.

Creating new order

With the use of Trans.eu API it is possible to create new own transport order, displayed in Trans.eu Platform in Orders Sent module. After the order is created, it is also possible to update it’s content if it was not yet sent to carrier for acceptance.


Components of a single transport order

Each order consists of:

  • valid carrier id
  • summary and requirements
  • list of loads
  • spots, which are divided into:
    • addresses
    • operations

Validation rules

Most important validation rules considering creating new transport order:

  • all dates must be greater or equal today
  • first operation date has to be lower than last operation date
  • first operation always has to be loading
  • last operation always has to be unloading
  • each spot has own sequence of operations performed, therefore in each spot first operation always has operation_order set to 1
  • address must consists country, postal code and locality
  • payment value must be greater than 0
  • for list of required fields please refer to the summary table below

Order statuses

  • in-preparation,
  • proposal-waiting,
  • waiting-for-vehicle-and-driver,
  • ready,
  • cancelled,
  • proposal-rejected,
  • waiting-for-confirmation

Diagram

Visualization of transport order management process


Description and example values

Structure of posting new order

Json Is required Type Example Description
external_source No String 123xyz Order source identifier assigned to client_id provided by Trans.eu
freight Yes Object Description of freight on which created order bases
freight.requirements Yes Object Main freight requirements, including truck body and size, adr classes, ways of loading, etc
freight.requirements.is_ftl Yes Boolean True Determines if freight is a full truck load or less than truckload
freight.requirements.required_truck_bodies Yes Array Curtainsider, Box Allowed vehicle types
freight.requirements.required_ways_of_loading No Array Top Allowed ways of loading
freight.requirements.required_adr_classes No Array Adr_1 Allowed ADR classes
freight.requirements.other_requirements No Array Lift, Hds Array of additional freight requirements
freight.requirements.shipping_remarks No String Shipping remarks Additional shipping remarks
freight.requirements.vehicle_size_id No String Bus Available vehicle sizes
freight.requirements.temperature No Object Can be added for one of following truck bodies: cooler, isotherm, hook truck
freight.requirements.temperature.min No Int 10
The input is between ‘-999’ and ‘999’, inclusively”
freight.requirements.temperature.max No Int 100 The input is between ‘-999’ and ‘999’, inclusively”
freight.carrier Yes Object Carrier selected for created order
freight.carrier.company_id Yes Int 1111111 Carrier Office-Id
freight.capacity Yes Int or  float 20 Total freight capacity in tonnes. This value is being validated in comparison to the sum of all loads.
Range: 0,001 – 100000
freight.loading_meters No Int or  float 10 Total freight loading meters
Range: 0,01 – 417
freight.loads Yes Array of objects Array of loads. At least an empty array has to be sent.
freight.loads.load_id Yes String
11xxzz
Load id, which should help identify loads designated to freight
freight.loads.name Yes String
Name1
Name of a load
freight.loads.type_of_load Yes String
Europalette
Name of supported type of load
freight.loads.weight No Int or float
15
Load weight
freight.loads.height No Int or float
1
Load height
freight.loads.width No Int or float
2
Load width
freight.loads.length No Int or float
3
Load length
freight.loads.volume No Int or float
4
Load volume
freight.loads.amount No Int 5 Amount of load types within given load
freight.loads.description No String
Description1
Load description
freight.loads.is_stackable No Boolean
True
Specifies whether the type of load allows stacking
freight.loads.is_exchangable No Boolean
True
Determines if type of load is available for exchange at unloading place
freight.spots Yes Object Spots for designated route, at least one spot with operation_type loading and one with operation_type unloading are required.
freight.spots.name No String Magazine 1 Name of the loading or unloading place
freight.spots.description No String Example description Description of the loading or unloading place
freight.spots.spot_order Yes Int 1 Information about the order of spot places – first spot always has spot_order set to 1
freight.spots.place Yes Object Information related to single place on freight’s route
freight.spots.place.address Yes Object Address data
freight.spots.place.address.country Yes String
PL
Country ISO value
freight.spots.place.address.postal_code Yes String
31-001
Postal code
freight.spots.place.address.locality Yes String
Kraków
City name
freight.spots.place.address.street No String
Wawel
Street name
freight.spots.place.address.number No String 5 Number
freight.spots.place.address.description No String
Example description
Spot address description
freight.spots.place.address.coordinates No Object Longitude and latitude for selected point
freight.spots.place.address.coordinates.latitude No Float
50.06143
Latitude of the point along the freight route
freight.spots.place.address.coordinates.longitude No Float
19.93658
Longitude of the point along the freight route
freight.spots.operations Yes Array of objects Array of operations to be completed in given spot
freight.spots.operations.operation_order Yes Int 1 The order of loading and unloading operations at a given spot.  First operation always has operation_order set to 1
freight.spots.operations.loads Yes Array of objects Array of loads to be loaded or unloaded during operation
freight.spots.operations.type Yes String Loading Could be either loading or unloading, at least one of each is required. First operation always has to be loadig, last operation always has to be unloading
freight.spots.operations.timespans Yes Object Timespan for selected operation
freight.spots.operations.timespans.begin Yes Timestamp
2021-06-22T11:00:00+0200
Beginning of loading or unloading operation
freight.spots.operations.timespans.end Yes Timestamp
2021-06-22T12:00:00+0200
End of loading or unloading operation
additional_terms No String Null Transport order additional terms
number No String 2021/06/22/2 Transport order number
payment Yes Object Information about payment
payment.days Yes Int 30 Payment due date in callendar days
payment.price Yes Object Price information
payment.price.type Yes String Km Can be either route or km
payment.price.value Yes Int or float 1500 Price value
payment.price.currency Yes String Pln Price currency
monitoring No Object Information about monitoring
monitoring.required No Boolean True Defines if monitoring is demanded
insurance No Object Information about insurance
insurance.load No Object Information about load insurance
insurance.load.value No Int 1000 Load value
insurance.load.currency No String Pln Load value currency
insurance.third_party No Object Required driver’s liability insurance information
insurance.third_party.value No Int 100 Required driver’s liability insurance value
insurance.third_party.currency No string Pln Required driver’s liability insurance currency

 

Json example

{
   "external_source": "123xyz",
  "freight": {
    "requirements": {
      "is_ftl": true,
      "required_truck_bodies": [
         "curtainsider", "box"
      ],
      "required_ways_of_loading": [
         "top"
      ],
       "required_adr_classes": [
         "adr_1"
          ],
      "other_requirements": [
         "lift", "hds"
      ],
      "shipping_remarks": "Shipping remarks",
       "vehicle_size_id": "bus",
       "temperature":
       {"min":10,
       "max":100}
   },
    "carrier": {
      "company_id": 1111111
    },
    "capacity": 20,
    "loading_meters": 10,
    "loads": [
    {
      "load_id": "11xxzz",
      "name": "name1",
      "type_of_load": "europalette",
      "weight": 15,
      "height":1,
      "width":2,
      "length":3,
      "volume":4,
      "amount":5,
      "description": "Description1",
      "is_exchangeable": true,
      "is_stackable": true
    }],
    "spots": [
      {
        "name": "Magazine 1",
        "description": "Example description",
        "spot_order": 1,
        "place": {
          "address": {
            "locality": "Kraków",
            "postal_code": "31-001",
            "country": "PL",
            "street": "Wawel",
            "number": "5"
          },
        "coordinates": {
          "latitude": 50.06143,
          "longitude": 19.93658
        }
        },
        "operations": [
          {"operation_order": 1,
           "loads": [],
            "type": "loading",
            "timespans": {
              "begin": "2021-06-22T11:00:00+0200",
              "end": "2021-06-22T12:00:00+0200"
            }
          }
        ]
      },
      {
        "name": null,
       "description": "Example description",
        "spot_order": 2,
        "place": {
          "address": {
            "locality": "Dąbrowa Środkowa",
            "postal_code": "59-330",
            "country": "PL",
            "street": "Średnia",
            "number": "34"
          },
        "coordinates": {
          "latitude": 51.41828,
          "longitude": 16.33485
        }
        },
        "operations": [
          {
            "type": "unloading",
            "operation_order": 1,
            "loads": [],
            "timespans": {
              "begin": "2021-06-23T11:00:00+0200",
              "end": "2021-06-23T11:00:00+0200"
            }
          }
        ]
      }
    ]
  },
  "additional_terms": null,
  "number": "2021/06/22/2",
  "payment": {
    "days": 30,
    "price": {
      "type": "km",
      "value": 1500,
      "currency": "pln"
    }
  },
  "monitoring": {
    "required": true
  },
  "insurance":{
      "load":{
          "value": 1000,
          "currency": "pln"
      },
      "third_party":{
          "value": 100,
          "currency" : "pln"
      }
  }
}

 

Structure of getting orders list

Json Type Example Description
attachments Object Information about attached documents
attachments.description String Example description Document description
attachments.media_id String 73b95cd1-2dfd-40c4-9785-469fb097bf7b Document id
attachments.media_name String File name Document name
attachments.type_id String Waybill Document type one of the following: waybill, transport_order, cession_scan, cargo_photo, invoice_scan, cmr, other
created_at Timestamp 2021-03-10T13:53:18.246Z Order creation date
driver Object Driver information
driver.account_id Int
771476
Driver account id
driver.family_name String Kowalski Driver last name
driver.full_name String Jan Kowalski Driver full name
driver.given_name String Jan Driver first name
driver.phone Int 111111111 Driver phone number
freight Object Description of freight on which created order bases
freight.carrier Object Carrier selected for created order
freight.carrier.assignee Object Freight assignee on carrier’s side
freight.carrier.assignee.account_id Int 749989 Assignee account id
freight.carrier.assignee.family_name String Kowalska Assignee last name
freight.carrier.assignee.given_name String Anna Assignee first name
freight.carrier.assignee.trans_id String 1013865-1 Assignee Trans-Id
freight.carrier.legal_name
String Przewoźnik Test Company name
freight.carrier.vat_id
String PL111111111 Company VAT number
freight.reference_number
String FR/2021/03/11/IETY Freight number
freight.shipper Object Shipper information
freight.shipper.assignee Object Freight assignee on shipper’s side
freight.shipper.assignee.account_id Int 749989 Assignee account id
freight.shipper.assignee.family_name String Kowalski Assignee last name
freight.shipper.assignee.given_name String Tomasz Assignee first name
freight.shipper.assignee.trans_id String 1007374-1 Assignee Trans-Id
freight.shipper.legal_name String
Firma Testowa
Company name
freight.shipper.vat_id String  PL2222222222 Company VAT number
freight.spots Object Spots for designated route, at least one spot with operation_type loading and one with operation_type unloading are required.
freight.spots.name String Magazine 1 Name of the loading or unloading place
freight.spots.description String Example description Description of the loading or unloading place
freight.spots.operations Array of objects Array of operations to be completed in given spot
freight.spots.operations.loads Array of objects Array of loads to be loaded or unloaded during operation
freight.spots.operations.loads.load Array of objects Array of loads
freight.spots.operations.loads.load.load_id String
11xxzz
Load id, which should help identify loads designated to freight
freight.spots.operations.loads.load.name String
Name1
Name of a load
freight.spots.operations.loads.load.type_of_load String
Europalette
Name of supported type of load
freight.spots.operations.loads.load.weight Int or float
15
Load weight
freight.spots.operations.loads.load.height Int or float
1
Load height
freight.spots.operations.loads.load.width Int or float
2
Load width
freight.spots.operations.loads.load.length Int or float
3
Load length
freight.spots.operations.loads.load.volume Int or float
4
Load volume
freight.spots.operations.loads.load.amount Int 5 Amount of load types within given load
freight.spots.operations.loads.load.description String
Description1
Load description
freight.spots.operations.loads.load.loads.is_stackable Boolean
true
Specifies whether the type of load allows stacking
freight.spots.operations.loads.load.loads.is_exchangable Boolean
true
Determines if type of load is available for exchange at unloading place
freight.spots.operations.operation_order Int 1 The order of loading and unloading operations at a given spot.  First operation always has operation_order set to 1
freight.spots.operations.time_window Object Time window information
freight.spots.operations.time_window.reference_number String
DS/206D65
Time slot reference number
freight.spots.operations.time_window_reason String Null

If time window has been created reason will be null, if not reason may be: lack_of_slots, lack_of_warehouse, more_than_one_warehouse, date_scope_exceeded

freight.spots.operations.timespans Object Timespan for selected operation
freight.spots.operations.timespans.begin Timestamp
2021-06-22T11:00:00+0200
Beginning of loading or unloading operation
freight.spots.operations.timespans.end Timestamp
2021-06-22T12:00:00+0200
End of loading or unloading operation
freight.spots.operations.type String Loading Could be either loading or unloading, at least one of each is required. First operation always has to be loading, last operation always has to be unloading
freight.spots.place Object Information related to single place on freight’s route
freight.spots.place.address Object Address data
freight.spots.place.address.country String
PL
Country ISO value
freight.spots.place.address.postal_code String
31-001
Postal code
freight.spots.place.address.locality String
Kraków
City name
freight.spots.place.address.street String
Wawel
Street name
freight.spots.place.address.number String 5 Number
freight.spots.place.address.description String
Example description
Spot address description
freight.spots.place.address.coordinates Object Longitude and latitude for selected point
freight.spots.place.address.coordinates.latitude Float
50.06143
Latitude of the point along the freight route
freight.spots.place.address.coordinates.longitude Float
19.93658
Longitude of the point along the freight route
freight.spots.spot_order Int 1 Information about the order of spot places – first spot always has spot_order set to 1
id String
7999470e-43eb-450b-bb83-9a9e07325cc6
Order id
invoice String Null Information about invoice
legacy_freight_id
Int
708481
Freight Id basing on which order was created automatically
monitoring Object Information about monitoring
monitoring.providers String
Trans_task
Monitoring provider information
monitoring.required Boolean True Defines if  monitoring is demended
number String
2021/05/24/5
Order number
payment Object Information about payment
payment.days Int 30 Payment due date in callendar days
payment.price Object Price information
payment.price.type String Km Can be either route or km
payment.price.value Int or float 1500 Price value
payment.price.currency String Pln Price currency
status Object Order status information
status.comment String Additional comment Additional comment for order in status cancelled or proposal rejected
status.value String Ready Possible status values
vehicle Object Vehicle information
vehicle.semi_trailer Object Semi trailer information
vehicle.semi_trailer.dispatcher_id Int
42026
Dispatcher id
vehicle.semi_trailer.id Int
236987
Trailer id
vehicle.semi_trailer.kind String Lorry Semi trailer kind
vehicle.semi_trailer.registration_plate_number String
DWR9999999
Semi trailer registration plate number
vehicle.semi_trailer.type String Null Trailer type
vehicle.truck Object Truck information
vehicle.truck.dispatcher_id Int
42026
Dispatcher id
vehicle.truck.id Int
236987
Truck id
vehicle.truck.kind String Bus_van Truck kind
vehicle.truck.registration_plate_number String
DWR9999999
Truck registration plate number
vehicle.truck.type String
Cooler
Truck type

 

Structure of getting single order

Json Type Example Description
additional_terms String Order additional terms
archived_at Timestamp
2021-06-29T10:31:23.398Z
attachments Object Information about attached documents
attachments.description String Example description Document description
attachments.media_id String 73b95cd1-2dfd-40c4-9785-469fb097bf7b Document id
attachments.media_name String File name Document name
attachments.type_id String Waybill Document type one of the following: waybill, transport_order, cession_scan, cargo_photo, invoice_scan, cmr, other
cancellation
Object Cancellation infomation for cancelled orders
cancellation.cancelled_at Timestamp
2021-06-29T10:31:23.398Z
Cancellation date
cancellation.cancelled_by Object Person cancelling order information
cancellation.cancelled_by.company_id Int
1013865
Company Id
cancellation.explanation String Order cancelled because Additional explanation for cancellation
cancellation.reasons Array Possible reasons on shipper’s side: contractor_did_not_obey_arrangements, other, out_of_stock, otherwise_transported, contractor_tried_to_change_arrangement
Possible reasons on carrier’s side: “no_driver”, “contractor_did_not_obey_arrangements”, “contractor_tried_to_change_arrangements”, “other”,“no_car”
cancellation.response String Response to order cancellation Response to order cancellation
cooperation
Object Information about cooperation status between companies
cooperation.status
String ACTIVE Can be active or suspended
created_at Timestamp
2021-06-24T08:31:46.425Z
Order creation date
driver Object Driver information
driver.account_id Int
771476
Driver account id
driver.email String trans@trans.eu Driver e-mail address
driver.employee_id Int 771477 Employee id
driver.family_name String Kowalski Driver last name
driver.full_name String Jan Kowalski Driver full name
driver.given_name String Jan Driver first name
driver.identity_document_number String Null Driver document number
freight Object Description of freight on which created order bases
freight.carrier Object Carrier selected for created order
freight.carrier.assignee Object Freight assignee on carrier’s side
freight.carrier.assignee.account_id Int 749989 Assignee id
freight.carrier.assignee.email String test@trans.eu Assignee email address
freight.carrier.assignee.family_name String Kowalska Assignee last name
freight.carrier.assignee.fax String 11222222222 Assignee fax number
freight.carrier.assignee.given_name String Anna Assignee first name
freight.carrier.assignee.telephone String 11222222222 Assignee telephone number
freight.carrier.assignee.trans_id String 1013865-1 Assignee Trans-Id
freight.carrier.legal_name
String Przewoźnik Test Company name
freight.carrier.vat_id
String PL111111111 Company VAT number
freight.reference_number
String FR/2021/03/11/IETY Freight number
freight.requirements Object Main freight requirements, including truck body and size, adr classes, ways of loading, etc.
freight.requirements.is_ftl Boolean True Determines if freight is a full truck load or less than truckload
freight.requirements.required_truck_bodies Array Curtainsider, Box Allowed vehicle types
freight.requirements.required_ways_of_loading Array Top Allowed ways of loading
freight.requirements.required_adr_classes Array Adr_1 Allowed ADR classes
freight.requirements.other_requirements Array Lift, Hds Array of additional freight requirements
freight.requirements.shipping_remarks String Shipping remarks Additional shipping remarks
freight.requirements.vehicle_size_id String Bus Available vehicle sizes
freight.requirements.temperature Object Can be added for one of following truck bodies: cooler, isotherm, hook truck
freight.requirements.temperature.min Int 10
The input is between ‘-999’ and ‘999’, inclusively”
freight.requirements.temperature.max Int 100 The input is between ‘-999’ and ‘999’, inclusively”
freight.shipper Object Assignee Trans-Id
freight.shipper.assignee Object Freight assignee on shipper’s side
freight.shipper.assignee.account_id Int 749989 Assignee account id
freight.shipper.assignee.email String trans@trans.eu Assignee email address
freight.shipper.assignee.family_name String Kowalski Assignee last name
freight.shipper.assignee.fax String 22111111111 Assignee fax number
freight.shipper.assignee.given_name String Tomasz Assignee first name
freight.shipper.assignee.telephone String 22111111111 Assignee telephone number
freight.shipper.assignee.trans_id String 1007374-1 Assignee Trans-Id
freight.shipper.legal_name String
Firma Testowa
Company name
freight.shipper.vat_id String  PL2222222222 Company VAT number
freight.spots Object Spots for designated route, at least one spot with operation_type loading and one with operation_type unloading are required
freight.spots.name String Magazine 1 Name of the loading or unloading place
freight.spots.description String Example description Description of the loading or unloading place
freight.spots.operations Array of objects Array of operations to be completed in given spot
freight.spots.operations.loads Array of objects Array of loads to be loaded or unloaded during operation
freight.spots.operations.loads.load Array of objects Array of loads
freight.spots.operations.loads.load.load_id String
11xxzz
Load id, which should help identify loads designated to freight
freight.spots.operations.loads.load.name String
Name1
Name of a load
freight.spots.operations.loads.load.type_of_load String
Europalette
Name of supported type of load
freight.spots.operations.loads.load.weight Int or float
15
Load weight
freight.spots.operations.loads.load.height Int or float
1
Load height
freight.spots.operations.loads.load.width Int or float
2
Load width
freight.spots.operations.loads.load.length Int or float
3
Load length
freight.spots.operations.loads.load.volume Int or float
4
Load volume
freight.spots.operations.loads.load.amount Int 5 Amount of load types within given load
freight.spots.operations.loads.load.description String
Description1
Load description
freight.spots.operations.loads.load.loads.is_stackable Boolean
true
Specifies whether the type of load allows stacking
freight.spots.operations.loads.load.loads.is_exchangable Boolean
true
Determines if type of load is available for exchange at unloading place
freight.spots.operations.operation_order Int 1 The order of loading and unloading operations at a given spot.  First operation always has operation_order set to 1
freight.spots.operations.time_window Object Time window information
freight.spots.operations.time_window.reference_number String
DS/206D65
Time slot reference number
freight.spots.operations.time_window_reason String Null

If time window has been created reason will be null, if not reason may be: lack_of_slots, lack_of_warehouse, more_than_one_warehouse, date_scope_exceeded

freight.spots.operations.timespans Object Timespan for selected operation
freight.spots.operations.timespans.begin Timestamp
2021-06-22T11:00:00+0200
Beginning loading or unloading operation
freight.spots.operations.timespans.end Timestamp
2021-06-22T12:00:00+0200
End loading or unloading operation
freight.spots.operations.type String Loading Could be either loading or unloading, at least one of each is required. First operation always has to be loadig, last operation always has to be unloading
freight.spots.place Object Information related to single place on freight’s route
freight.spots.place.address Object Address data
freight.spots.place.address.country String
PL
Country ISO value
freight.spots.place.address.postal_code String
31-001
Postal code
freight.spots.place.address.locality String
Kraków
City name
freight.spots.place.address.street String
Wawel
Street name
freight.spots.place.address.number String 5 Number
freight.spots.place.address.description String
Example description
Spot address description
freight.spots.place.address.coordinates Object Longitude and latitude for selected point
freight.spots.place.address.coordinates.latitude Float
50.06143
Latitude of the point along the freight route
freight.spots.place.address.coordinates.longitude Float
19.93658
Longitude of the point along the freight route
freight.spots.spot_order Int 1 Information about the order of spot places – first spot always has spot_order set to 1
id String
7999470e-43eb-450b-bb83-9a9e07325cc6
Order Id
insurance Object Information about insurance
insurance.load Object Information about load insurance
insurance.load.value Int 1000 Load value
insurance.load.currency String Pln Load value currency
insurance.third_party Object Required driver’s liability insurance information
insurance.third_party.value Int 100 Required driver’s liability insurance value
insurance.third_party.currency String Pln Required driver’s liability insurance currency
invoice String Null Invoice information
is_archived_permanently
Boolean Flase Information about archivization
legacy_freight_id
Int 410610 Freight Id basing on which order was created automatically
monitoring Object Information about monitoring
monitoring.providers String
Trans_task
Monitoring provider information
monitoring.required Boolean True Defines if you demand monitoring from carrier
number String 2021/06/22/2 Transport order number
payment Object Information about payment
payment.days Int 30 Payment due date in callendar days
payment.price Object Price information
payment.price.type String Km Can be either per route or km
payment.price.value Int or float 1500 Price value
payment.price.currency String Pln Price currency
related Object Information about related orders
source String Api Can be either offer or api
status Object Order status information
status.comment String Additional comment Additional comment for order in status cancelled or proposal rejected
status.value String Ready Possible status values: in-preparation, proposal-waiting, waiting-for-vehicle-and-driver, ready , cancelled, proposal-rejected, waiting-for-confirmation
vehicle Object Vehicle information
vehicle.semi_trailer Object Semi trailer information
vehicle.semi_trailer.dispatcher_id Int
42026
Dispatcher id
vehicle.semi_trailer.id Int
236987
Trailer id
vehicle.semi_trailer.kind String Lorry Semi trailer kind
vehicle.semi_trailer.registration_plate_number String
DWR9999999
Semi trailer registration plate number
vehicle.semi_trailer.type String Null Trailer type
vehicle.truck Object Truck information
vehicle.truck.dispatcher_id Int
42026
Dispatcher id
vehicle.truck.id Int
236987
Truck id
vehicle.truck.kind String Bus_van Truck kind
vehicle.truck.registration_plate_number String
DWR9999999
Truck registration plate number
vehicle.truck.type String
Cooler
Truck type

 

Important!
Weight is always represented in tonnes.
Height, length and width are always represented in meters.