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

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

Diagram

Visualization of freight management process.


Summary

Description and accepted values for main freight structure.

Json Example Type Is required Description
id 12 Int No Freight identification number, assigned automatically during creation of a new freight.
Important: this value is only received (GET)
shipment_external_id 2020/ABC/1/1 String No External identification number
external_source 1_api String No Freight source identifier assigned to client_id
capacity 12 Float Yes 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 8 Float No Total freight loading meters
Range: 0,01 – 417
publish True Boolean Yes Determines if the freight is automatically published or only created
payment Object No Payment conditions for publication using groups or smart match
carriers 1111, 2222 Array Yes For publication to group, contains of carrier’s company identifiers
publication_price 111 Int No Price value given at freight publication. Not available for freights published using automation rules.
Important: this value is only received after successful freight publication (GET)
accepted_price Object No Final price for freight accepted during publication and negotiation process
publication_price.currency eur String No Currency  for freight price accepted during publication and negotiation process
requirements Object Yes Main freight requirements, including truck body and size adr classes, ways of loading
carrier Object No Carrier selected during publication and negotiation process
Important: this value is only received after successful freight publication (GET)
loads Array No Collection of freights’ loads. It is possible to send empty array of loads, nevertheless an array has to be set
spots Object Yes Spots for freight route, at least one loading and one unloading is required
status String No Freight status
Important: this value is only received (GET)


Json example

{
    "accepted_price": {
        "currency": "eur",
        "value": 111
    },
    "capacity": 25,
    "carrier": { 
        "address": {
            "country": "PL",
            "locality": "Warsaw",
            "postal_code": "11-111",
            "street": "AAAABBB"
        },
        "email": "abc@trans.eu",
        "id": 11111,
        "name": "Firma Testowa",
        "telephone": "0048 111111111",
        "vat_id": "11111111111"
    },
    "id": 543792,
    "loading_meters": 13,
    "loads": [],
    "publication_price": {
        "currency": "eur",
        "value": 111
    },
    "reference_number": "FR/2021/01/18/VH3V",
    "requirements": {
        "is_ftl": true,
        "required_truck_bodies": [
            "cooler"
        ],
        "vehicle_size": "solo"
    },
    "shipment_external_id": "XYZ123456789",
    "spots": [],
    "status": "accepted"
}


Requirements and pricing

Description and accepted values for freight summary and requirements.

 

Json Example Type Is required Description
payment Object No* Publication price for freight published using group or smart match
payment.price Object No Freight publication price value and currency
payment.price.value 12 Int No Value of freight publication price
payment.price.currency Eur String No Currency for freight publication price
publication_price.period Object No Information about payment time
publication_price.period.payment Deferred String No Allowed freight payment types
publication_price.period.days 5 Int Yes Number of days for deferred payment
accepted_price Object No Price value
accepted_price.currency Eur String No Currency for freight price accepted during publication and negotiation process.
accepted_price.value 123.22 Float No Price value for freight accepted during publication and negotiation process.
requirements Object Yes Main freight requirements, ftl/ltl and truck body are required
requirements.is_ftl True Bool Yes Determines if freight is a full truck load or less than truckload
requirements.required_truck_bodies Curtainsider, Box Array Yes Allowed vehicle types
requirements.shipping_remarks Shipping remarks String No Additional shipping remarks
requirements.vehicle_size Bus String No Available vehicle sizes
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

 

Json example

{
  "payment": {
    "price: {
       "currency": "eur",
       "value": 123 },
    }
  "id": "111111",
  "shipment_external_id": "2020/01/abcdef123",
  "external_source": "1_system",
  "capacity": 12,
  "requirements": {
    "is_ftl": true,
    "required_truck_bodies": [
      "curtainsider"
    ],
  "required_adr_classes" : [ "adr_8","adr_9"],
  },
  "publish": "true",
  "publication_price": {
    "currency": "eur",
    "value": 123,
    "period": {
            "payment": "deferred",
            "days": 5
  }
        }
    }
  },
 "accepted_price": {
    "currency": "eur",
    "value": 123
  },
  "loads": [],
  "spots": [],
  "carrier": [],
  "status": "accepted"
}

Carrier

Details of carrier chosen during freight publication and negotiation. Those details are available after the fright has been fully accepted and are not possible to be given during new freight creation.

Json Example Type Is required Description
id 123456 String No Trans.eu company identifier
name Example name String No Company name
vat_id 11111111111 String No Company tax identification number
address Object No Address
address.country PL String No Country ISO value
address.postal_code 00-111 String No Postal code
address.locality Warsaw String No Town
address.street Street name String No Street
address.number 1 String No Number
email abc@trans.eu String No E-mail address
telephone 0048 111111111 Number No Telephone number

Json example

"carrier": { 
        "address": {
            "country": "PL",
            "locality": "Warsaw",
            "postal_code": "00-111",
            "street": "Street name"
        },
        "email": "abc@trans.eu",
        "id": 123456,
        "name": "Example name",
        "telephone": "0048 111111111",
        "vat_id": "11111111111"
    }

Loads

Array of loads. Freight can be created without any load definition, but at least an empty array has to be sent.

Json Example Type Is required Description
load_id L123x String Yes Load id, which should help identify loads designated to freight
name Example name String Yes Name of a load
type_of_load Europalette String Yes Name of supported type of load
weight 12 Int or float No Load weight
height 3 Int or float No Load height
width 2 Int or float No Load width
length 8 Int or float No Load length
volume 21 Int or float No Load volume
amount 1 Int or float No Amount of load types within given load
description Example description String No Load description
is_stackable True Boolean Yes Specifies whether the type of load allows stacking – required only for palette and europalette
is_exchangable False Boolean Yes Determines if type of load is available for exchange at unloading place – required only for palette and europalette

Json example

  "loads": [{
      "load_id": L123x,
      "name": "Example name",
      "type_of_load": "europalette",
      "weight": 12,
      "height": 3,
      "width": 2,
      "length": 8,
      "volume": 21,
      "amount": 1,
      "description": "Example description",
      "is_stackable": true,
      "is_exchangeable": false
   }]

Spots

Spots for designated route, at least one spot with operation_type loading and one with operation_type unloading are required.

Json Example Type Is required Description
name Magazine 1 String No Name of the loading or unloading place
description Example description String No Description of the loading or unloading place
spot_order 1 Int Yes Information about the order of operations at this location
place Object Yes Information related to single place on freight’s route
operations [] Array Yes Array of operations to be completed in given spot

Json example

"spots": [
      {
            "description": "Example description",
            "name": "Magazine 1",
            "operations": [],
            "place": {},
            "spot_order": 1
         },
      {
            "description": "Example description",
            "name": "Magazine 2",
            "operations": [],
            "place": {},
            "spot_order": 2
         }
     ]

Spots place

Address data

Json Example Type Is required Description
address Object Yes Address
address.country GB String Yes Country code ISO value
address.postal_code SK7 1 String Yes Postal code
address.locality Londyn String Yes City name
address.street The Mall String No Street name
address.number 1 String No Number
address.description Address desc String No Spot address description
address.coordinates Object No Longitude and latitude for selected point
address.coordinates.latitude 53.35801 Float No Latitude of the point along the freight route
address.coordinates.longitude -2.16539 Float No Longitude of the point along the freight route

Json example

"place": {
                "address": {
                    "country": "GB",
                    "description": "Address desc",
                    "locality": "Londyn",
                    "number": "1",
                    "postal_code": "SK7 1",
                    "street": "The Mall"
                },
                "coordinates": {
                    "latitude": 53.35801,
                    "longitude": -2.16539
                }
            },

Spots operations

Array of operations to be completed in given spot

Json Example Type Is required Description
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
loads Object No Array of loads to be loaded in unloaded during operation
loads.load_id L123x String No Reference to a previously defined load
loads.weight 10 Int Yes Weight of load to be loaded or unloaded in this operation.
type Loading String Yes Could be either loading or unloading, at least one of each is required
timespans Object Yes Timespan for selected operation
timespans.begin 2021-01-23T18:00:00+01:00 Timestamp Yes Beginning of time slot for loading or unloading operation
timespans.end 2021-01-23T18:30:00+01:00 Timestamp Yes End of time slot for loading or unloading operation

Json example

"operations": [
                {
                    "loads": [{
                              "load_id": "L123x",
                              "weight": 10
                             }],
                    "operation_order": 1,
                    "timespans": {
                        "begin": "2021-01-23T18:00:00+01:00",
                        "end": "2021-01-23T18:30:00+01:00"
                    },
                    "type": "unloading"
                }
              ]