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 also 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 freight exchange, smart match and groups
  • publication_price – freight price set during publication, it could be equal to payment price if freight was published to freight exchange or groups. If freight is published using automation rules, publication price is set in the rule parameters
  • 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 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 Yes Freight identification number, assigned during creation of a new freight
external_shipment_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 int 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 int 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 and freight exchange.
Important: this is value is being used during freight creation (POST)
carriers Array 1,2,3 For publication to group, contains of carrier’s company identifiers
publication_price 123.22 float 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 123.22 float No Currency  for freight price accepted during publication and negotiation process.
requirements Object No Main freight requirements, including truck body and size adr classes, ways of loading
carrier Object No Carrier selected during publication and negotiation process
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

 

Json example

{
  "id": "12345-abcd-123567",
  "external_shipment_id": "2020/01/abcdef123",
  "external_source": "1_system_name",
  "capacity": 12,
  "loading_meters": 8,
  "multistop": false,
  "requirements": {
    "is_ftl": true,
    "required_truck_bodies": [
      "curtainsider"
    ]
  },
  "publish": "auto",
  "payment": {
    "price": {
      "currency": "eur",
      "value": 123
    },
  "period": {
    "payment": "deferred",
    "days": 5
  },
 }
 "accepted_price": {
    "currency": "eur",
    "value": 123
  },
 "publication_price": {
  "currency": "eur",
  "value": 123
  },
  "loads": [],
  "spots": [],
  "carrier": []
}


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 on freight exchange or using group
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
payment.price.period eur string No Currency for freight publication price
payment.price.period.payment deferred string No Payment type: available values: deferred, payment_on_unloading, payment_in_advance
payment.price.period.days 5 int No Number of days for deferred payment
accepted_price Object No Price value. Not available for freights published using automation rules.
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 it is a full truck load freight
requirements.required_truck_bodies curtainsider array Yes List of allowed truck bodies
requirements.shipping_remarks Shipping remarks string No Additional shipping remarks
requirements.vehicle_size bus string No Vehicle size: bus, lorry, double_trailer
requirements.required_adr_classes 1 array No Array of ADR Classes
requirements.required_ways_of_loading top array Yes Allowed ways of loading: top, back, side
requirements.other_requirements array array Yes Array of additional requirements: “hds”, “gps”, “lift”,”custom_rope”, “pallet_basket”, “goods_to_declare”,
“adr”, “carnet_tir”, “carnet_ata”, “xl_certificate”, “a-sign”, “doppel_decker”, “gmp_certificate”

 

Json example

{
  "payment": {
    "price: {
       "currency": "eur",
       "value": 123 },
    }
  "id": "12345-abcd-123567",
  "external_shipment_id": "2020/01/abcdef123",
  "external_source": "1_system",
  "capacity": 12,
  "loading_meters": 8,
  "multistop": false,
  "requirements": {
    "is_ftl": true,
    "required_truck_bodies": [
      "curtainsider"
    ],
  "required_adr_classes" : [ "adr_8","adr_9"],
  },
  "publish": "auto",
  "publication_price": {
    "currency": "eur",
    "value": 123,
    "period": {
            "payment": "deferred",
            "days": 5
  }
        }
    }
  },
 "accepted_price": {
    "currency": "eur",
    "value": 123
  },
  "loads": [],
  "spots": [],
  "carrier": []
}

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 987654321 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

Json example

  "carrier" : {
      "id" : "123",  
      "name" : "Example company name",
      "vat" : "PL123456789",
      "address" : {
          "country" : "pl",
          "locality" : "Sopot",
          "postal_code" : "12-345",
          "street" : "Example street",
          "number" : "13a"
      }

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
id L123x string No Load id, which should help identify loads designated to freight
name Example name string No Name of a load
type_of_load europalette string No Type of cargo, also understood as a way of packing or transporting goods
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 No Specifies whether the type of load allows stacking
is_exchangable false boolean No Determines if there are palettes available for exchange at unloading place

Json example

  "loads": [{
      "id": 279606,
      "name": "Example load no 1",
      "type_of_load": "europalette",
      "weight": 2,
      "height": 1,
      "width": 2,
      "length": 9,
      "volume": 20,
      "amount": 3,
      "description": null,
      "load_id": null,
      "is_stackable": false,
      "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 L123x 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": [
    {
      "name": "string",
      "description": "string",
      "spot_order": 0,
      "place": {
        "address": {
        },
        "coordinates": {
        }
      },
      "operations": [
      ]
    }
  ]

Spots place

Address data

Json Example Type Is required Description
address Object Yes
address.country DE Yes Country code ISO value
address.postal_code 52-200 Yes Postal code
address.locality Paris Yes City name
address.street Champs elysees No Street name
address.number 44 No Number
address.description Address desc No Spot address description
address.coordinates Object No Longitude and latitude for selected point
address.coordinates.latitude 51.8338 float No Latitude of the point along the freight route
address.coordinates.longitude 16.5792 float No Longitude of the point along the freight route

Json example

"place": {
        "address": {
          "country": "pl",
          "street": "Racławicka",
          "number": "2-4",
          "locality": "Wrocław",
          "postal_code": "53-146",
          "description": "Trans.eu office"
        },
        "coordinates": {
          "latitude": 51.085615,
          "longitude": 17.0105
        }
      },

Spots operations

Array of operations to be completed in given spot

Json Example Type Is required Description
operations_order 1 int Yes The order of loading and unloading operations at a given spot.
loads L123x string No Array of loads to be loaded in unloaded during operation
loads.id L123x string No Reference to a previously defined load that is to be partially or completely unloaded or loaded at a given location.
loads.weight L123x string No 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 2018-07-18T14:30:00+0200 timestamp Yes Beginning of time slot for loading or unloading operation
timespans.end 2018-07-18T15:30:00+0200 timestamp Yes End of time slot for loading or unloading operation

Json example

      "operations": {[
        "operation_order": 0,
        "loads": [{
           "id" : "L123X",
           "weight: 12
        }],
        "timespans": {
          "end": "2018-07-18T14:30:00+0200",
          "begin": "2018-07-18T15:30:00+0200"
        },
        "type": "loading"
      ]}