Search for carrier with given price and buy now option

Description of adding new freight for selected companies, with given price, without the possibility of freight price negotiations.

Scenario

carrier is yet to be determined
carrier’s TransId is available in external TMS
price and currency was given
carrier is using Trans.eu Platform only, with no additional freight management software involved
both freight forwarder and carriers have existing and valid Trans.eu account
freight is published immediately after creation
first carrier which accepts freight conditions and price is selected
after first acceptance carrier details are attached to freight entity

Authorize access

Before it is possible to send any request, user needs to authorize access.

client app was registered using registration form
external app was granted api keys (client_id and client_secret)
authorization process has been implemented in external app

Create new freight

Each freight must consist of:

array of carriers’ ids
loading location and time
unloading location and time
required truck body type
summary of freight’s loads weight
ftl/ltl parameter
price an currency

Diagram

Request example:

Endpoint:

POST https://api.platform.trans.eu/ext/freights-api/v1/freight-companies

Payload:

{
  "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
    }
  ],
  "payment": {
    "price": {
      "value": 1200,
      "currency": "eur",
      "period": {
        "payment": "deferred",
        "days": 5
      }
    }
  },
  "is_first_buy": true,
  "capacity": 29,
  "loading_meters": 2,
  "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-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"
          }
        }
      ]
    }
  ]
}

Verify freight status

Immediately after freight creation it is possible do access current freight status and details:

GET https://api.platform.trans.eu/ext/freights-api/v1/freights/{freight-id}

If there is a carrier’s acceptance, carrier details will be filled out, in other case there will be empty collection.