Description of freight elements with the usage and conditions.

Freight allows to search for the best carriers for given shipment. It is possible using previously created groups and automation rules as well as to wide group of carriers present on Trans.eu Platform with the help of Trans.eu matching algorithm.

Creating new freight

With the use of Trans.eu API it is possible to create new own freight, displayed in Trans.eu Platform in Freights Sent module. After the freight is created, it is also possible to update it’s content if it was not yet published.


Freight publication

If a freight was not published, it is not visible to other Trans.eu users. For a freight to be successfully published it has to meet several criteria:

  • the “publish” parameter must be set to “true”
  • if a freight is being published to selected companies, at least one of company id’s must be valid
  • if freight is being published using automation rules, at least one automation rule must be created and active at Platform

Freight price

Depending of method and freight status, there are three different parameters related to freight price:

  • payment  – initial freight price for publication using smart match and groups
  • publication_price – freight price set during publication, it could be equal to payment price if freight was published to groups
  • accepted_price – freight price agreed upon during negotiation process, the final freight price

Components of a single freight

Each freight consists of:

  • summary and requirements
  • publication status
  • carrier information, available to be read after the acceptance of freight
  • list of loads
  • spots, which are divided into:
    • addresses
    • operations

Validation rules

Most important validation rules considering freight publication

  • all dates must be greater or equal today
  • decision date must lower than the date of first operation, if it is not set it will automatically be set to equal first loading date
  • 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 of country, postal code and locality
  • for list of required fields please refer to the summary table below

Freight statuses

  • accepted,
  • in_progress,
  • new,
  • unsuccessful_publication,
  • waiting_for_publication,
  • closed,
  • waiting_for_accept,
  • waiting_for_chain_accept

Diagram

Visualization of freight management process.


 

Structure of posting new freight

Json Example Type Is required Description
publish True Boolean Yes Determines if the freight is automatically published or only created
external_source api_trans String No Freight source identifier assigned to client_id provided by Trans.eu
shipment_external_id 1/1/1234 String No External identification number
multistop True Boolean No Freight with more than two stops needs to be declared as multistop
publish_date
2021-07-30T13:10:00+0000
Timestamp No Defines when freight will be published. Publish date has to be lower than decision date
decision_date
2021-08-03T13:00:00+0000
Timestamp No Defines time up to which carriers can send offers. Decision date has to be smaller or equals than loading date
carriers Array of objects Yes For publication to companies only, contains of carrier’s company identifiers
carriers.company_id {“company_id”: 10}, {“company_id”: 1111111} Int Yes Carrier companies id’s
payment Object No Publication price for freight published using companies or smart match only
payment.price Object No Freight publication price value and currency
payment.price.value 1200 Int No Value of freight publication price (minimum value is 1)
payment.price.currency Eur String No Currency for freight publication price
payment.price.period Object No Information about payment time
payment.price.period.payment Deferred String No Allowed freight payment types
payment.price.period.days 5 Int Yes Number of days for deferred payment only
is_first_buy
True Boolean No Freights with parameter is_first_buy = true can be only accepted or rejected, they cannot be negotiated
capacity 29 Float No Total freight capacity in tonnes. This value is being validated in comparison to the sum of all loads weight (range 0.001 – 100000)
loading_meters 2 Float Yes Total freight loading meters (range: 0,01 – 417)
height 4 Int or float No Vehicle height (range 0.01-10)
width 3 Int or float No Vehicle width (range 0.01-10)
length 8 Int or float No Vehicle length (range 0.01-100)
volume 25 Int or float No Vehicle volume (range 0.01-10000)
requirements Object Yes Main freight requirements, including truck body and size adr classes, ways of loading
requirements.is_ftl True Boolean Yes Determines if freight is a full truck load or less than truckload
requirements.required_truck_bodies Curtainsider, cooler Array Yes Allowed vehicle types
requirements.temperature Object No Can be added for one of following truck bodies: cooler, isotherm, hook truck
requirements.temperature.min 3 Int No The input is between ‘-999’ and ‘999’, inclusively”
requirements.temperature.max 10 Int No The input is between ‘-999’ and ‘999’, inclusively”
requirements.shipping_remarks Shipping remarks String No Additional shipping remarks
requirements.vehicle_size Bus String No Default value is any_size – if you want to use vehicle type from beyond the any_size list (Allowed vehicle types), you have to give proper vehicle size
requirements.required_adr_classes Adr_1 Array No Allowed ADR classes
requirements.required_ways_of_loading Top Array No Allowed ways of loading
requirements.other_requirements Lift, Hds Array No Allowed additional requirements
loads Object Yes Collection of freights’ loads. It is possible to send empty array of loads, nevertheless an array has to be set
loads.load_id L123x String Yes Load id, which should help identify loads designated to freight
loads.name Example name String Yes Name of a load
loads.description Description String No Load description
loads.weight 12 Int or float No Load weight (range 0.001 – 100000)
loads.height 3 Int or float No Load height (range 0.01-10)
loads.width 2 Int or float No Load width (range 0.01-10)
loads.length 8 Int or float No Load length (range 0.01-100)
loads.volume 21 Int or float No Load volume (range 0.01-10000)
loads.amount 1 Int or float No Amount of load types within given load
loads.type_of_load Europalette String Yes Name of supported load types
loads.is_stackable True Boolean No Specifies whether the type of load allows stacking
loads.is_exchangeable True Boolean No Determines if type of load is available for exchange at unloading place
spots Array of objects Yes Collection of freights’ spots – at least one loading and one unloading is required
spots.description Example description String No Description of the loading or unloading place
spots.name Spot name String No Name of spot
spots.spot_order 1 Int Yes Information about the order of spot places – first spot always has spot_order set to 1
spots.place Object Yes Information related to single place on freight’s route
spots.place.address Object Yes Address
spots.place.address.country GB String Yes Country using ISO values
spots.place.address.postal_code SK7 1 String Yes Postal code
spots.place.address.locality London String Yes City name
spots.place.address.street The Mall String No Street name
spots.place.address.number 1 String No Number
spots.place.address.description Address description String No Address description
spots.place.coordinates Object No Longitude and latitude for selected point
spots.place.coordinates.latitude 53.35801 Float No Latitude of the point along the freight route
spots.place.coordinates.longitude -2.16539 Float No Longitude of the point along the freight route
spots.operations Array of objects Yes Array of operations to be completed in given spot
spots.operations.operation_order 1 Int Yes The order of loading and unloading operations at a given spot – first operation always has operation_order set to 1
spots.operations.loads Object No Array of loads to be loaded or unloaded during operation
spots.operations.loads.load_id
L123x
String No Reference to a previously defined load
spots.operations.loads.weight 12 Int No Weight of load to be loaded or unloaded in operation
spots.operations.timespans Object Yes Timespan for selected operation
spots.operations.timespans.begin
2021-08-03T13:10:00+0000
Timestamp Yes Beginning of time slot for loading or unloading operation
spots.operations.timespans.end
2021-08-03T15:10:00+0000
Timestamp Yes End of time slot for loading or unloading operation
spots.operations.type Loading String Yes Could be either loading or unloading, at least one of each is required

 

Json example

{
  "publish": true,
  "external_source": "api_trans",
  "shipment_external_id": "1/1/1234",
  "multistop": true,
  "publish_date": "2021-07-30T13:10:00+0000",
  "decision_date": "2021-08-03T13:00:00+0000",
  "carriers": [
    {
      "company_id": 10
    },
    {
      "company_id": 1111111
    }
  ],
  "payment": {
    "price": {
      "value": 1200,
      "currency": "eur",
      "period": {
        "payment": "deferred",
        "days": 5
      }
    }
  },
  "is_first_buy": true,
  "capacity": 29,
  "loading_meters": 2,
  "height": 4, 
  "width": 3, 
  "length": 8, 
  "volume": 25,
  "requirements": {
    "is_ftl": true,
    "required_truck_bodies": [
      "curtainsider",
      "cooler"
    ],
    "temperature": {
      "min": 3,
      "max": 10
    },
    "shipping_remarks": "shipping remarks",
    "vehicle_size": "bus",
    "required_adr_classes": [
      "adr_1"
    ],
    "required_ways_of_loading": [
      "top"
    ],
    "other_requirements": [
      "lift",
      "hds"
    ]
  },
  "loads": [
    {
      "load_id": "L123x",
      "name": "example name",
      "description": "Description",
      "weight": 12,
      "height": 3,
      "width": 2,
      "length": 8,
      "volume": 21,
      "amount": 1,
      "type_of_load": "europalette",
      "is_stackable": true,
      "is_exchangeable": true
    }
  ],
  "spots": [
    {
      "description": "Example description",
      "name": "Spot name",
      "spot_order": 1,
      "place": {
        "address": {
          "country": "GB",
          "postal_code": "SK7 1",
          "locality": "London",
          "street": "The Mall",
          "number": "1",
          "description": "Address description"
        },
        "coordinates": {
          "latitude": 53.35801,
          "longitude": -2.16539
        }
      },
      "operations": [
        {
          "operation_order": 1,
          "loads": [
            {
              "load_id": "L123x",
              "weight": 12
            }
          ],
          "timespans": {
            "begin": "2021-08-03T13:10:00+0000",
            "end": "2021-08-03T15:10:00+0000"
          },
          "type": "loading"
        }
      ]
    },
    {
      "name": "Spot name 2",
      "description": "Description2",
      "spot_order": 2,
      "place": {
        "address": {
          "country": "PL",
          "postal_code": "61-625",
          "locality": "Poznań",
          "street": "Rynek",
          "number": "1",
          "description": "Address 2"
        },
        "coordinates": {
          "latitude": 52.43457,
          "longitude": 16.95141
        }
      },
      "operations": [
        {
          "operation_order": 1,
          "loads": [
            {
              "load_id": "L123x",
              "weight": 10
            }
          ],
          "type": "unloading",
          "timespans": {
            "begin": "2021-08-04T13:00:00+0000",
            "end": "2021-08-04T14:00:00+0000"
          }
        }
      ]
    },
    {
      "name": "Spot name 3",
      "description": "Description3",
      "spot_order": 3,
      "place": {
        "address": {
          "country": "DE",
          "postal_code": "09000",
          "locality": "Brieselang",
          "street": "Strasse",
          "number": "3",
          "description": "Address 3"
        },
        "coordinates": {
          "latitude": 52.58216,
          "longitude": 12.99756
        }
      },
      "operations": [
        {
          "operation_order": 1,
          "loads": [
            {
              "load_id": "L123x",
              "weight": 2
            }
          ],
          "type": "unloading",
          "timespans": {
            "begin": "2021-08-05T01:00:00+0000",
            "end": "2021-08-05T01:00:00+0000"
          }
        }
      ]
    }
  ]
}

 

Structure of response, structure of getting single freight

Json Example Type Description
accepted_price Object Final price for freight accepted during publication and negotiation process
accepted_price.currency Eur String Final price currency
accepted_price.value 110 Int Final price value
capacity 29 Float Total freight capacity in tonnes. This value is being validated in comparison to the sum of all loads weight.
Range: 0,001 – 100000
carrier Object Carrier selected during publication and negotiation process
carrier.address Object Carrier address information
carrier.address.country PL String Country ISO value
carrier.address.locality Warsaw String Town
carrier.address.postal_code 00-111 String Postal code
carrier.address.street Street name String Street
carrier.email abc@trans.eu String E-mail address
carrier.id 1111111 Int Company ofice id
carrier.name Example name String Company name
carrier.telephone 0048 111111111 Number Telephone number
carrier.vat_id 11111111111 String Company tax identification number
id 820283 Int Freight identification number, assigned automatically during creation of a new freight.
loading_meters 2 Float Total freight loading meters
Range: 0,01 – 417
loads Object Collection of freights’ loads. It is possible to send empty array of loads, nevertheless an array has to be set
loads.load_id L123x String Load id, which should help identify loads designated to freight
loads.name Example name String Name of a load
loads.description No String Load description
loads.weight 12 Int or float Load weight (range 0.001 – 100000)
loads.height 3 Int or float Load height (range 0.01-10)
loads.width 2 Int or float Load width (range 0.01-10)
loads.length 8 Int or float Load length (range 0.01-100)
loads.volume 21 Int or float Load volume (range 0.01-10000)
loads.amount 1 Int or float Amount of load types within given load
loads.type_of_load Europalette String Name of supported type of load
loads.is_stackable True Boolean Specifies whether the type of load allows stacking
loads.is_exchangeable True Boolean Determines if type of load is available for exchange at unloading place
publication_price Object Publication price information
currency Eur String Publication price currency
value 110 Int Publication price value
reference_number FR/2021/07/23/TLUH, String Freight reference number
requirements Object Main freight requirements, including truck body and size adr classes, ways of loading
requirements.is_ftl True Boolean Determines if freight is a full truck load or less than truckload
requirements.required_truck_bodies Curtainsider, cooler Array Allowed vehicle types
requirements.temperature Object Can be added for one of following truck bodies: cooler, isotherm, hook truck
requirements.temperature.min 3 Int The input is between ‘-999’ and ‘999’, inclusively”
requirements.temperature.max 10 Int The input is between ‘-999’ and ‘999’, inclusively”
requirements.shipping_remarks Shipping remarks String Additional shipping remarks
requirements.vehicle_size Bus String Default value is any_size – if you want to use vehicle type from beyond the any_size list (Allowed vehicle types), you have to give proper vehicle size
requirements.required_adr_classes Adr_1 Array Allowed ADR classes
requirements.required_ways_of_loading Top Array Allowed ways of loading
requirements.other_requirements Lift, Hds Array Allowed additional requirements
spots Array of objects Collection of freights’ spots – at least one loading and one unloading is required
spots.description Example description String Description of the loading or unloading place
spots.name Spot name String Name of spot
spots.operations Array of objects Array of operations to be completed in given spot
spots.operations.operation_order 1 Int The order of loading and unloading operations at a given spot – first operation always has operation_order set to 1
spots.operations.loads Object Array of loads to be loaded in unloaded during operation
spots.operations.loads.load_id 279606 String Reference to a previously defined load
spots.operations.loads.weight 10 Int Weight of load to be loaded or unloaded in this operation.
spots.operations.timespans Object Timespan for selected operation
spots.operations.timespans.begin 2021-01-23T18:00:00+01:00 Timestamp Beginning of time slot for loading or unloading operation
spots.operations.timespans.end 2021-01-23T18:30:00+01:00 Timestamp End of time slot for loading or unloading operation
spots.operations.type Loading String Could be either loading or unloading, at least one of each is required
spots.place Object Information related to single place on freight’s route
spots.place.address Object Address
spots.place.address.country GB String Country using ISO values
spots.place.address.postal_code SK7 1 String Postal code
spots.place.address.locality London String City name
spots.place.address.street The Mall String Street name
spots.place.address.number 1 String Number
spots.place.address.description Address description String Description of loading point
spots.place.coordinates Object Longitude and latitude for selected point
spots.place.coordinates.latitude 53.35801 Float Latitude of the point along the freight route
spots.place.coordinates.longitude -2.16539 Float Longitude of the point along the freight route
spots.spot_order 1 Int Information about the order of operations at this location
status Accepted String Freight status