Creating new freight in Trans.eu Platform and sending it to Freight exchange.

Url parameters and connection settings

  • URL: https://api.platform.trans.eu
  • Endpoint: /freights-api/v1/freight-exchange
  • Method: POST

Headers:

  • Content-type: application/json
  • Accept: application/json
  • Authorization: Bearer {access_token}
  • Api-key: {unique_app_api_key}

Authorization

Authorization process is described here.

 

Description and example values

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
exchange_recipents carriers String No Can be either carriers or all.
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
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
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

 

Example

Sample Json for creating new freight using required data only

{
  "publish": true,
  "external_source": "api_trans",
  "shipment_external_id": "1/1/1234",
  "multistop": true,
  "publish_date": "2021-08-24T10:10:00+0000",
  "decision_date": "2021-08-30T13:00:00+0000",
  "exchange_recipents" : "carriers",
  "payment": {
    "price": {
      "value": 1200,
      "currency": "eur",
      "period": {
        "payment": "deferred",
        "days": 5
      }
    }
  },
  "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-30T13:10:00+0000",
            "end": "2021-08-30T15: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-31T13:00:00+0000",
            "end": "2021-08-31T14: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-09-01T01:00:00+0000",
            "end": "2021-09-01T01:00:00+0000"
          }
        }
      ]
    }
  ]
}

Response

{
    "accepted_price": null,
    "capacity": 29,
    "carrier": null,
    "id": 862241,
    "loading_meters": 2,
    "loads": [
        {
            "amount": 1,
            "description": "Description",
            "height": 3,
            "id": 849998,
            "is_exchangeable": true,
            "is_stackable": true,
            "length": 8,
            "load_id": "849998",
            "name": "example name",
            "type_of_load": "europalette",
            "volume": 21,
            "weight": 12,
            "width": 2
        }
    ],
    "publication_price": {
        "currency": "eur",
        "value": 1200
    },
    "reference_number": "FR/2021/09/07/SC50",
    "requirements": {
        "is_ftl": true,
        "monitoring": "expected",
        "other_requirements": [
            "lift",
            "hds",
            "adr"
        ],
        "required_adr_classes": [
            "adr_1"
        ],
        "required_truck_bodies": [
            "curtainsider",
            "cooler"
        ],
        "required_ways_of_loading": [
            "top"
        ],
        "shipping_remarks": "shipping remarks",
        "temperature": {
            "max": 10,
            "min": 3
        },
        "vehicle_size": "bus"
    },
    "shipment_external_id": "1/1/1234",
    "spots": [
        {
            "description": null,
            "name": "Spot name",
            "operations": [
                {
                    "loads": [
                        {
                            "load_id": "849998",
                            "weight": 12
                        }
                    ],
                    "operation_order": 1,
                    "timespans": {
                        "begin": "2021-09-08T15:10:00+02:00",
                        "end": "2021-09-08T17:10:00+02:00"
                    },
                    "type": "loading"
                }
            ],
            "place": {
                "address": {
                    "country": "gb",
                    "description": "Address description",
                    "locality": "London",
                    "number": "1",
                    "postal_code": "SK7 1",
                    "street": "The Mall"
                },
                "coordinates": {
                    "latitude": 53.35801,
                    "longitude": -2.16539
                }
            },
            "spot_order": 1
        },
        {
            "description": null,
            "name": "Spot name 2",
            "operations": [
                {
                    "loads": [
                        {
                            "load_id": "849998",
                            "weight": 10
                        }
                    ],
                    "operation_order": 1,
                    "timespans": {
                        "begin": "2021-09-09T15:00:00+02:00",
                        "end": "2021-09-09T16:00:00+02:00"
                    },
                    "type": "unloading"
                }
            ],
            "place": {
                "address": {
                    "country": "pl",
                    "description": "Address 2",
                    "locality": "Poznań",
                    "number": "1",
                    "postal_code": "61-625",
                    "street": "Rynek"
                },
                "coordinates": {
                    "latitude": 52.43457,
                    "longitude": 16.95141
                }
            },
            "spot_order": 2
        },
        {
            "description": null,
            "name": "Spot name 3",
            "operations": [
                {
                    "loads": [
                        {
                            "load_id": "849998",
                            "weight": 2
                        }
                    ],
                    "operation_order": 1,
                    "timespans": {
                        "begin": "2021-09-10T03:00:00+02:00",
                        "end": "2021-09-10T03:00:00+02:00"
                    },
                    "type": "unloading"
                }
            ],
            "place": {
                "address": {
                    "country": "de",
                    "description": "Address 3",
                    "locality": "Brieselang",
                    "number": "3",
                    "postal_code": "09000",
                    "street": "Strasse"
                },
                "coordinates": {
                    "latitude": 52.58216,
                    "longitude": 12.99756
                }
            },
            "spot_order": 3
        }
    ],
    "status": "new"
}