1. Trans.eu Api
  2. Freights section
  3. Publish to Trans.eu Freight Exchange

Publish to Trans.eu Freight Exchange

Cre­at­ing a new freight and pub­lish­ing it to the Trans.eu Freight Exchange.

After suc­cess­ful­ly exe­cut­ing the method, you receive in response the freight details with the unique freight iden­ti­fi­ca­tion num­ber id assigned when cre­at­ing the new freight.

This method can also be used to sim­ply cre­ate a work­ing copy of the freight for sub­se­quent man­u­al pub­li­ca­tion using any method on the Plat­form.
See more infor­ma­tion about freight pub­li­ca­tion.

POST
/ext/freights-api/v1/freight-exchange
Request Authorization

Every request MUST include a valid access token obtained dur­ing the user autho­riza­tion process, pro­vid­ed using the Bear­er token scheme in the Autho­riza­tion head­er.

Request

Request Head­er

Request Para­me­ters

Request Body

Successful Response

Response Fields

Response Body

Error Response

Clients errors (400)

Gen­er­al API errors

Request Header
POST /ext/freights-api/v1/freight-exchange HTTP/1.1 
Host: api.platform.trans.eu 
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token) 
Api-key: {unique_app_api-key}
Request Parameters
AttributeTypeExam­pleManda­to­ryDescrip­tion
callback_urlStringhttp://example.com/msgNoThe return address pro­vid­ed by the client to receive freight and pub­li­ca­tion event sta­tus­es. See list of avail­able event sta­tus­es.
capac­i­tyFloat24YesTotal 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)
contact_employeesArray of String[“13443–1”,“13443–2”]NoThe 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.
decision_dateTime­stamp2025–08–03T13:00:00+0000NoDefines time up to which car­ri­ers can send offers. Cal­cu­lat­ed auto­mat­i­cal­ly for freight-exchange pub­li­ca­tion — it can be max 23:00 on the day of unload­ing.
Required con­di­tion: decision_date > publish_date
heightInt or Float3.2NoExpected/required vehi­cle height (range: 0.01–10)
lengthInt or Float5NoExpected/required vehi­cle length (range: 0.01–100)
loading_metersFloat13.6NoTotal freight load­ing meters (range: 0,01 — 417)
loads (see details)Array of ObjectsNoCol­lec­tion of freight loads.
pay­ment (see details)ObjectNoPay­ment con­di­tions for pub­li­ca­tion
pub­lishBooleanTrueYesDeter­mines if the freight is auto­mat­i­cal­ly pub­lished (True) or only cre­at­ed (False)
publish_dateTime­stamp2025–08–03T13:00:00+0000NoPub­li­ca­tion (acti­va­tion) date — must be greater or equal today, NULL — imme­di­ate pub­li­ca­tion
require­ments (see details)ObjectYesMain freight require­ments
send_order_proposal_
auto­mat­i­cal­ly		BooleanFalseNoSends 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_idString2023/NWX/1/3NoExter­nal iden­ti­fi­ca­tion num­ber
spots (see details)Array of ObjectsYesCol­lec­tion of freights’ spots – at least one load­ing and one unload­ing is required
transit_timeInt or Float280NoTime expressed in min­utes (pos­i­tive inte­ger) for trans­port. Must be less than the dif­fer­ence between the last unload­ing and the first load­ing.
vol­umeInt or Float21NoExpected/required vehi­cle vol­ume (range: 0.01–10000)
widthInt or Float3.1NoExpected/required vehi­cle width (range: 0.01–10)
Example Request Body
{
  "callback_url": "http://example.com/msg",  
  "capacity": 16.1,
  "contact_employees" : [
    "1007374-5","1007374-2"
  ],
  "decision_date": "2026-02-23T16:55:00+0100",
  "height":4.3,
  "length":5.8,
  "loading_meters": 10.1,
  "loads": [ {
      "type_of_load": "europalette",
      "name": "Load nr 1",
      "load_id": "1123dfd121_1",
      "amount":2,
      "is_exchangeable": true
  }],
  "payment": {
    "price": {
        "value": 332,
        "currency": "eur",
        "period": { 
            "payment": "deferred", 
            "days": 14
        }
    }
  },
  "publish": true,
  "publish_date": null,
  "requirements": {
    "is_ftl": true,
    "required_truck_bodies": [
      "gas-tanker"
    ],
    "required_ways_of_loading": [ 
        "side" 
    ],
    "vehicle_size": "solo"
  },
  "send_order_proposal_automatically": true,
  "shipment_external_id": "1123dfd121",
  "spots": [
    {
      "spot_order": 1,
      "operations": [
        {
          "operation_order": 1,
          "type": "loading",
          "timespans": {
            "begin": "2026-02-23T10:30:58+01:00",
            "end": "2026-02-23T12:30:58+01:00"
          }
        }
      ],
      "place": {
        "address": {
          "country": "PL",
          "postal_code": "54-128",
          "locality": "Wroclaw"
        }
      }
    },
    {
      "spot_order": 2,
      "operations": [
        {
          "operation_order": 1,
          "type": "unloading",
          "timespans": {
            "begin": "2026-02-26T10:30:58+01:00",
            "end": "2026-02-26T12:30:58+01:00"
          }
        }
      ],
      "place": {
        "address": {
          "country": "IT",
          "postal_code": "20097",
          "locality": "Milan"
        }
      }
    }
  ],
  "volume":12.6,
  "width": 3.1
}
Response Fields
AttributeTypeExam­pleDescrip­tion
accepted_priceObjectnullFinal price for freight accept­ed dur­ing pub­li­ca­tion and nego­ti­a­tion process. The val­ue is always null in this request.
capac­i­tyFloat22.1Total freight capac­i­ty in tonnes.
car­ri­erObjectnullCar­ri­er select­ed dur­ing nego­ti­a­tion process. The val­ue is always null in this request.
contact_employeesArray of ObjectsList of employ­ees assigned to freight nego­ti­a­tion. Default is pub­lish­er.
contact_employees.last_nameStringNowakSur­name of assigned employ­ee
contact_employees.nameStringJanFirst name of assigned employ­ee
contact_employees.trans_idString13443–1Tran­sId of assigned employ­ee
dis­tanceInt34000Dis­tance in meters from the point of load­ing to the point of unload­ing.
end_reasonStringnullPub­li­ca­tion end rea­son.
For cor­rect pub­li­ca­tion or freight cre­ation only null is returned.
heightFloat3.1Vehi­cle height (range: 0.01–10)
idInt234923Freight iden­ti­fi­ca­tion num­ber, assigned auto­mat­i­cal­ly dur­ing cre­ation of a new freight.
is_first_buyBooleanFalseDefines if price will be nego­ti­at­ed or only accept­ed by car­ri­er. The val­ue is always False in this request.
lengthFloat12Vehi­cle length (range: 0.01–100)
loading_metersFloat23Total freight load­ing meters (range: 0,01 — 417)
loads (see details)Array of ObjectsCol­lec­tion of freight loads.
publication_priceObjectPub­li­ca­tion price infor­ma­tion
publication_price.currencyStringeurPub­li­ca­tion price cur­ren­cy. See cur­ren­cy dic­tio­nary.
publication_price.valueInt560Pub­li­ca­tion price val­ue. The val­ue is Null if was not spec­i­fied.
publication_statusStringactiveSta­tus of the pub­li­ca­tion — always null in pub­lish­ing request
reference_numberStringFR/2025/12/30/2NNQFreight ref­er­ence num­ber — a unique, auto­mat­i­cal­ly assigned busi­ness iden­ti­fi­er of the freight
require­ments (see details)ObjectMain freight require­ments
shipment_external_idString2023/NWX/1/3Exter­nal iden­ti­fi­ca­tion num­ber
spots (see details)Array of ObjectsCol­lec­tion of freights’ spots. At least one load­ing and one unload­ing will occur.
sta­tusStringnewFreight sta­tus. The val­ue is always new in this request. See for oth­er pos­si­ble sta­tus­es.
sur­chagesObjectnullSur­chages for fixed routes. The val­ue is always null in this request.
transit_timeInt460Time expressed in min­utes (pos­i­tive inte­ger) for trans­port, if spec­i­fied.
vol­umeFloat21Vehi­cle vol­ume (range 0.01–10000).
widthFloat3.1Vehi­cle width (range 0.01–10).
Response Body
{
    "accepted_price": null,
    "capacity": 16.1,
    "carrier": null,
    "contact_employees": [
        {
            "last_name": "Nowak",
            "name": "Jan",
            "trans_id": "1007374-1"
        }
    ],
    "distance": 1185000,
    "end_reason": null,
    "height": 4.3,
    "id": 3829554,
    "is_first_buy": false,
    "length": 5.8,
    "loading_meters": 10.1,
    "loads": [
        {
            "amount": 2,
            "description": null,
            "height": null,
            "id": 3765461,
            "is_exchangeable": true,
            "is_stackable": false,
            "length": null,
            "load_id": "3765461",
            "name": "Load nr 1",
            "type_of_load": "europalette",
            "volume": null,
            "weight": null,
            "width": null
        }
    ],
    "publication_price": {
        "currency": "eur",
        "value": 332
    },
    "publication_status": null,
    "reference_number": "FR/2026/02/23/2NNW",
    "requirements": {
        "exemption_from_adr": false,
        "is_ftl": true,
        "monitoring": "required",
        "other_requirements": [],
        "required_adr_classes": [],
        "required_door_types": [],
        "required_tipper_trailer_additional_equipment": [],
        "required_truck_bodies": [
            "gas-tanker"
        ],
        "required_ways_of_loading": [
            "side"
        ],
        "shipping_remarks": null,
        "temperature": {
            "max": null,
            "min": null
        },
        "transport": {
            "count": null,
            "schedule_type": null,
            "settlement": "route",
            "settlement_basis": null,
            "total_weight": null,
            "type": "ftl"
        },
        "vehicle_size": "solo"
    },
    "shipment_external_id": "1123dfd121",
    "spots": [
        {
            "description": "",
            "name": null,
            "operations": [
                {
                    "loads": [
                        {
                            "load_id": "3765461",
                            "weight": null
                        }
                    ],
                    "operation_order": 1,
                    "operation_time": null,
                    "timespans": {
                        "begin": "2026-02-23T10:30:58+01:00",
                        "begin_local": "2026-02-23T10:30:58+01:00",
                        "end": "2026-02-23T12:30:58+01:00",
                        "end_local": "2026-02-23T12:30:58+01:00",
                        "timezone": "Europe/Warsaw"
                    },
                    "type": "loading"
                }
            ],
            "place": {
                "address": {
                    "country": "pl",
                    "description": null,
                    "locality": "Wroclaw",
                    "number": null,
                    "postal_code": "54-128",
                    "street": null
                },
                "coordinates": {
                    "latitude": 51.142329074,
                    "longitude": 16.937462521
                }
            },
            "spot_order": 1
        },
        {
            "description": "",
            "name": null,
            "operations": [
                {
                    "loads": [
                        {
                            "load_id": "3765461",
                            "weight": null
                        }
                    ],
                    "operation_order": 1,
                    "operation_time": null,
                    "timespans": {
                        "begin": "2026-02-26T10:30:58+01:00",
                        "begin_local": "2026-02-26T10:30:58+01:00",
                        "end": "2026-02-26T12:30:58+01:00",
                        "end_local": "2026-02-26T12:30:58+01:00",
                        "timezone": "Europe/San_Marino"
                    },
                    "type": "unloading"
                }
            ],
            "place": {
                "address": {
                    "country": "it",
                    "description": null,
                    "locality": "Milan",
                    "number": null,
                    "postal_code": "20097",
                    "street": null
                },
                "coordinates": {
                    "latitude": 45.397205283,
                    "longitude": 9.21659417
                }
            },
            "spot_order": 2
        }
    ],
    "status": "new",
    "surcharges": [],
    "transit_time": null,
    "volume": 12.6,
    "width": 3.1
}

Clients errors (code 422)

HTTP 4xx sta­tus codes indi­cate client errors, mean­ing that the request could not be processed due to an issue on the client side. Below is a list of request-spe­cif­ic errors.

Example error 1

No manda­to­ry val­ue in capac­i­ty field

{
    "detail": "Failed Validation",
    "status": 422,
    "title": "Unprocessable Entity",
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "validation_messages": {
        "capacity": {
            "value": {
                "isEmpty": "Value is required and can't be empty"
            }
        }
    }
}
Example error 2

Incor­rect date in spot oper­a­tion

"validation_messages": {
        "spot_operation": {
            "validation_error": "In one of spot.operation begin or end date is lower or equal today (UTC)"
        }
    }
Example error 3

Vehi­cle type not allowed for vehi­cle size

"validation_messages": {
            "vehicle_size_id": {
                "invalid": "['7_silos'] is not valid for vehicle size: '1_bus'"
            }
        }
    }