1. Trans.eu Api
  2. Freights
  3. Freight description

Freight description

Descrip­tion of freight ele­ments with the usage and con­di­tions.

Freight allows to search for the best car­ri­ers for giv­en ship­ment. You can use pub­li­ca­tion to select­ed com­pa­nies, automa­tion rules pre­vi­ous­ly cre­at­ed at Plat­form, pub­li­ca­tion to freight exchange or with the help of Trans.eu match­ing algo­rithm — Smart match.

Creating new freight

With the use of Trans.eu API it is pos­si­ble to cre­ate new own freight, dis­played at Trans.eu Plat­form in Freights Sent mod­ule. After the freight is cre­at­ed, it is also pos­si­ble to update it’s con­tent if it was not yet pub­lished.

Freight publication

If a freight was not pub­lished, it is not vis­i­ble to oth­er Trans.eu users. For a freight to be suc­cess­ful­ly pub­lished it has to meet sev­er­al cri­te­ria:

  • the “pub­lish” para­me­ter must be set to “true”
  • if a freight is being pub­lished to select­ed com­pa­nies, at least one of com­pa­ny id’s must be valid
  • if freight is being pub­lished using automa­tion rules, at least one automa­tion rule must be cre­at­ed and active at Plat­form

Freight price

Depend­ing of method and freight sta­tus, there are three dif­fer­ent para­me­ters relat­ed to freight price:

  • pay­ment  — ini­tial freight price for pub­li­ca­tion using freight exchange, smart match and groups
  • publication_price — freight price set dur­ing pub­li­ca­tion
  • accepted_price — freight price agreed upon dur­ing nego­ti­a­tion process, the final freight price

Components of a single freight

Each freight con­sists of:

  • sum­ma­ry and require­ments
  • pub­li­ca­tion sta­tus
  • car­ri­er infor­ma­tion, avail­able to be read after the accep­tance of freight
  • list of loads
  • spots, which are divid­ed into:
    • address­es
    • oper­a­tions

Validation rules

Most impor­tant val­i­da­tion rules con­sid­er­ing freight pub­li­ca­tion

  • all dates must be greater or equal today
  • first oper­a­tion date has to be low­er than last oper­a­tion date
  • first oper­a­tion always has to be load­ing
  • last oper­a­tion always has to be unload­ing
  • each spot has own sequence of oper­a­tions per­formed, there­fore in each spot first oper­a­tion always has operation_order set to 1
  • address must con­sists of coun­try, postal code and local­i­ty
  • for list of required fields please refer to struc­ture of post­ing new freight below

Freight statuses

  • accept­ed,
  • in_progress,
  • new,
  • unsuccessful_publication,
  • waiting_for_publication,
  • closed,
  • waiting_for_accept,
  • waiting_for_chain_accept

Diagram

Visu­al­iza­tion of freight man­age­ment process.

Structure of posting new freight

JsonExam­pleTypeIs requiredDescrip­tion
pub­lishTrueBooleanYesDeter­mines if the freight is auto­mat­i­cal­ly pub­lished or only cre­at­ed
external_sourceapi_transStringNoFreight source iden­ti­fi­er assigned to client_id pro­vid­ed by Trans.eu
send_order_proposal_automaticallytrue/falseBooleanNoSends the order con­di­tions auto­mat­i­cal­ly. This means that when the car­ri­er accepts such freight, an order is cre­at­ed with the terms of the order, and the ship­per does not have to com­plete them man­u­al­ly.
shipment_external_id1/1/1234StringNoExter­nal iden­ti­fi­ca­tion num­ber
mul­ti­stopTrueBooleanNoFreight with more than two stops needs to be declared as mul­ti­stop
publish_date
2021–07-30T13:10:00+0000
Time­stampNoDefines when freight will be pub­lished. Pub­lish date has to be low­er than deci­sion date
decision_date
2021–08-03T13:00:00+0000
Time­stampNoDefines time up to which car­ri­ers can send offers. It can be max:

  • 23:00 on the day of unload­ing for freight exchange pub­li­ca­tion
  • equal load­ing date for smart match pub­li­ca­tion
  • equal unload­ing date for com­pa­nies pub­li­ca­tion
car­ri­ersArray of objectsYesFor pub­li­ca­tion to com­pa­nies only, con­tains of carrier’s com­pa­ny iden­ti­fiers
carriers.company_id{“company_id”: 10}, {“company_id”: 1111111}IntYesCar­ri­er com­pa­nies id’s
contact_employees[“12345–1”, “12345–2”]ArrayNoThe default con­tact per­son is always the pub­lish­er. If the field is sent, the con­tact per­sons will be only the ID’s sent in it
pay­mentObjectNoPub­li­ca­tion price for freight pub­lished using freight exchange, com­pa­nies or auto­mat­ic rules
payment.priceObjectNoFreight price val­ue and cur­ren­cy
payment.price.value1200IntNoVal­ue of freight price (min­i­mum val­ue is 1)
payment.price.currencyEurStringNoCur­ren­cy for freight price
payment.price.periodObjectNoInfor­ma­tion about pay­ment time
payment.price.period.paymentDeferredStringNoAllowed freight pay­ment types
payment.price.period.days5IntYesNum­ber of days for deferred pay­ment only
is_first_buy
TrueBooleanNoFreights with para­me­ter is_first_buy = true can be only accept­ed or reject­ed, they can­not be nego­ti­at­ed (val­ue for pub­li­ca­tion to com­pa­nies only)
capac­i­ty29FloatYesTotal freight capac­i­ty in tonnes. This val­ue is being val­i­dat­ed in com­par­i­son to the sum of all loads weight (range 0.001 – 100000)
loading_meters2FloatNoTotal freight load­ing meters (range: 0,01 — 417)
height4Int or floatNoVehi­cle height (range 0.01–10)
width3Int or floatNoVehi­cle width (range 0.01–10)
length8Int or floatNoVehi­cle length (range 0.01–100)
vol­ume25Int or floatNoVehi­cle vol­ume (range 0.01–10000)
require­mentsObjectYesMain freight require­ments, includ­ing truck body and size, adr class­es, ways of load­ing
requirements.monitoringwithout_monitoringStringNoMon­i­tor­ing require­ment can be select­ed with mon­i­tor­ing require­ment (required) or with­out mon­i­tor­ing require­ment (without_monitoring)
requirements.is_ftlTrueBooleanYesDeter­mines if freight is a full truck load or less than truck­load
requirements.required_truck_bodiesCur­tain­sid­er, cool­erArrayYesAllowed vehi­cle types (array can con­tain max 5 val­ues)
requirements.temperatureObjectNoCan be added for one of fol­low­ing truck bod­ies: cool­er, isotherm, hook truck
requirements.temperature.min3IntNoThe input is between ‘-999’ and ‘999’, inclu­sive­ly”
requirements.temperature.max10IntNoThe input is between ‘-999’ and ‘999’, inclu­sive­ly”
requirements.shipping_remarksShip­ping remarksStringNoAddi­tion­al ship­ping remarks
requirements.vehicle_sizeBusStringNoDefault val­ue is any_size — if you want to use vehi­cle type from beyond the any_size list (Allowed vehi­cle types), you have to give prop­er vehi­cle size
requirements.required_adr_classesAdr_1ArrayNoAllowed ADR class­es
requirements.required_ways_of_loadingTopArrayNoAllowed ways of load­ing
requirements.other_requirementsLift, HdsArrayNoAllowed addi­tion­al require­ments
loadsArray of objectsNoCol­lec­tion of freights’ loads
loads.load_idL123xStringYesLoad id, which should help iden­ti­fy loads des­ig­nat­ed to freight
loads.nameExam­ple nameStringYesName of a load
loads.descriptionDescrip­tionStringNoLoad descrip­tion
loads.weight12Int or floatNoLoad weight (range 0.001 – 100000)
loads.height3Int or floatNoLoad height (range 0.01–10)
loads.width2Int or floatNoLoad width (range 0.01–10)
loads.length8Int or floatNoLoad length (range 0.01–100)
loads.volume21Int or floatNoLoad vol­ume (range 0.01–10000)
loads.amount1Int or floatNoAmount of load types with­in giv­en load
loads.type_of_loadEuropaletteStringYesName of sup­port­ed load types
loads.is_stackableTrueBooleanNoSpec­i­fies whether the type of load allows stack­ing
loads.is_exchangeableTrueBooleanNoDeter­mines if type of load is avail­able for exchange at unload­ing place
spotsArray of objectsYesCol­lec­tion of freights’ spots – at least one load­ing and one unload­ing is required
spots.descriptionExam­ple descrip­tionStringNoDescrip­tion of the load­ing or unload­ing place
spots.nameSpot nameStringNoName of spot
spots.spot_order1IntYesInfor­ma­tion about the order of spot places – first spot always has spot_order set to 1
spots.placeObjectYesInfor­ma­tion relat­ed to sin­gle place on freight’s route
spots.place.addressObjectYesAddress
spots.place.address.countryGBStringYesCoun­try using ISO val­ues
spots.place.address.postal_codeSK7 1StringYesPostal code
spots.place.address.localityLon­donStringYesCity name
spots.place.address.streetThe MallStringNoStreet name
spots.place.address.number1StringNoNum­ber
spots.place.address.descriptionAddress descrip­tionStringNoAddress descrip­tion
spots.place.coordinatesObjectNoLon­gi­tude and lat­i­tude for select­ed point
spots.place.coordinates.latitude53.35801FloatNoLat­i­tude of the point along the freight route
spots.place.coordinates.longitude-2.16539FloatNoLon­gi­tude of the point along the freight route
spots.operationsArray of objectsYesArray of oper­a­tions to be com­plet­ed in giv­en spot
spots.operations.operation_order1IntYesThe order of load­ing and unload­ing oper­a­tions at a giv­en spot – first oper­a­tion always has operation_order set to 1
spots.operations.loadsObjectNoArray of loads to be loaded or unloaded dur­ing oper­a­tion
spots.operations.loads.load_id
L123x
StringNoRef­er­ence to a pre­vi­ous­ly defined load
spots.operations.loads.weight12IntNoWeight of load to be loaded or unloaded in oper­a­tion
spots.operations.timespansObjectYesTimes­pan for select­ed oper­a­tion
spots.operations.timespans.begin
2021–08-03T13:10:00+0000
Time­stampYesBegin­ning of time slot for load­ing or unload­ing oper­a­tion
spots.operations.timespans.end
2021–08-03T15:10:00+0000
Time­stampYesEnd of time slot for load­ing or unload­ing oper­a­tion
spots.operations.typeLoad­ingStringYesCould be either load­ing or unload­ing, at least one of each is required

Json example (publication to companies)

{
  "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
    }
  ],
  "contact_employees": [
    "12345-1",
    "12345-2"
  ],
  "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": {
    "monitoring": "without_monitoring",
    "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

JsonExam­pleTypeDescrip­tion
accepted_priceObjectFinal price for freight accept­ed dur­ing pub­li­ca­tion and nego­ti­a­tion process
accepted_price.currencyEurStringFinal price cur­ren­cy
accepted_price.value110IntFinal price val­ue
capac­i­ty29FloatTotal freight capac­i­ty in tonnes. This val­ue is being val­i­dat­ed in com­par­i­son to the sum of all loads weight.
Range: 0,001 – 100000
car­ri­erObjectCar­ri­er select­ed dur­ing pub­li­ca­tion and nego­ti­a­tion process
carrier.addressObjectCar­ri­er address infor­ma­tion
carrier.address.countryPLStringCoun­try ISO val­ue
carrier.address.localityWar­sawStringTown
carrier.address.postal_code00–111StringPostal code
carrier.address.streetStreet nameStringStreet
carrier.emailabc@trans.euStringE‑mail address
carrier.id1111111IntCom­pa­ny ofice id
carrier.nameExam­ple nameStringCom­pa­ny name
carrier.telephone0048 111111111Num­berTele­phone num­ber
carrier.vat_id11111111111StringCom­pa­ny tax iden­ti­fi­ca­tion num­ber
dis­tance1234IntDis­tance from the point of load­ing to the point of unload­ing
end_reasonnullStringPub­li­ca­tion end rea­son (can be one from the fol­low­ing: null, time­out, reject­ed, accept­ed,

can­celed, fail­ure, exchange_limit)
heightnullFloatVehi­cle height (range 0.01–10)
id820283IntFreight iden­ti­fi­ca­tion num­ber, assigned auto­mat­i­cal­ly dur­ing cre­ation of a new freight
lengthnullFloatVehi­cle length (range 0.01–100)
loading_meters2FloatTotal freight load­ing meters
Range: 0,01 — 417
loadsObjectCol­lec­tion of freights’ loads. It is pos­si­ble to send emp­ty array of loads, nev­er­the­less an array has to be set
loads.load_idL123xStringLoad id, which should help iden­ti­fy loads des­ig­nat­ed to freight
loads.nameExam­ple nameStringName of a load
loads.descriptionNoStringLoad descrip­tion
loads.weight12Int or floatLoad weight (range 0.001 – 100000)
loads.height3Int or floatLoad height (range 0.01–10)
loads.width2Int or floatLoad width (range 0.01–10)
loads.length8Int or floatLoad length (range 0.01–100)
loads.volume21Int or floatLoad vol­ume (range 0.01–10000)
loads.amount1Int or floatAmount of load types with­in giv­en load
loads.type_of_loadEuropaletteStringName of sup­port­ed type of load
loads.is_stackableTrueBooleanSpec­i­fies whether the type of load allows stack­ing
loads.is_exchangeableTrueBooleanDeter­mines if type of load is avail­able for exchange at unload­ing place
publication_priceObjectPub­li­ca­tion price infor­ma­tion
cur­ren­cyEurStringPub­li­ca­tion price cur­ren­cy
val­ue110IntPub­li­ca­tion price val­ue
publication_statusactiveStringCan be null, active or fin­ished
reference_numberFR/2021/07/23/TLUHStringFreight ref­er­ence num­ber
require­mentsObjectMain freight require­ments, includ­ing truck body and size, adr class­es, ways of load­ing
requirements.is_ftlTrueBooleanDeter­mines if freight is a full truck load or less than truck­load
requirements.required_truck_bodiesCur­tain­sid­er, cool­erArrayAllowed vehi­cle types
requirements.temperatureObjectCan be added for one of fol­low­ing truck bod­ies: cool­er, isotherm, hook truck
requirements.temperature.min3IntThe input is between ‘-999’ and ‘999’, inclu­sive­ly”
requirements.temperature.max10IntThe input is between ‘-999’ and ‘999’, inclu­sive­ly”
requirements.shipping_remarksShip­ping remarksStringAddi­tion­al ship­ping remarks
requirements.vehicle_sizeBusStringDefault val­ue is any_size — if you want to use vehi­cle type from beyond the any_size list (Allowed vehi­cle types), you have to give prop­er vehi­cle size
requirements.required_adr_classesAdr_1ArrayAllowed ADR class­es
requirements.required_ways_of_loadingTopArrayAllowed ways of load­ing
requirements.other_requirementsLift, HdsArrayAllowed addi­tion­al require­ments
shipment_external_id
nullStringExter­nal iden­ti­fi­ca­tion num­ber
spotsArray of objectsCol­lec­tion of freights’ spots – at least one load­ing and one unload­ing is required
spots.descriptionExam­ple descrip­tionStringDescrip­tion of the load­ing or unload­ing place
spots.nameSpot nameStringName of spot
spots.operationsArray of objectsArray of oper­a­tions to be com­plet­ed in giv­en spot
spots.operations.operation_order1IntThe order of load­ing and unload­ing oper­a­tions at a giv­en spot – first oper­a­tion always has operation_order set to 1
spots.operations.loadsObjectArray of loads to be loaded in unloaded dur­ing oper­a­tion
spots.operations.loads.load_id279606StringRef­er­ence to a pre­vi­ous­ly defined load
spots.operations.loads.weight10IntWeight of load to be loaded or unloaded in this oper­a­tion
spots.operations.timespansObjectTimes­pan for select­ed oper­a­tion
spots.operations.timespans.begin2021–01-23T18:00:00+01:00Time­stampBegin­ning of time slot for load­ing or unload­ing oper­a­tion
spots.operations.timespans.end2021–01-23T18:30:00+01:00Time­stampEnd of time slot for load­ing or unload­ing oper­a­tion
spots.operations.typeLoad­ingStringCould be either load­ing or unload­ing, at least one of each is required
spots.placeObjectInfor­ma­tion relat­ed to sin­gle place on freight’s route
spots.place.addressObjectAddress
spots.place.address.countryGBStringCoun­try using ISO val­ues
spots.place.address.postal_codeSK7 1StringPostal code
spots.place.address.localityLon­donStringCity name
spots.place.address.streetThe MallStringStreet name
spots.place.address.number1StringNum­ber
spots.place.address.descriptionAddress descrip­tionStringDescrip­tion of load­ing point
spots.place.coordinatesObjectLon­gi­tude and lat­i­tude for select­ed point
spots.place.coordinates.latitude53.35801FloatLat­i­tude of the point along the freight route
spots.place.coordinates.longitude-2.16539FloatLon­gi­tude of the point along the freight route
spots.spot_order1IntInfor­ma­tion about the order of oper­a­tions at this loca­tion
sta­tusAccept­edStringFreight sta­tus
vol­umenullFloatVehi­cle vol­ume (range 0.01–10000)
widthnullFloatVehi­cle width (range 0.01–10)