1. Trans.eu Api
  2. Use cases
  3. Searching for a carrier without given price

Searching for a carrier without given price

Descrip­tion of adding a freight for select­ed com­pa­nies, with­out declar­ing the freight price.

Scenario

  • car­ri­er is yet to be deter­mined
  • car­ri­er’s Tran­sId is avail­able in exter­nal TMS
  • price was not giv­en
  • car­ri­er is using Trans.eu Plat­form only, with no addi­tion­al freight man­age­ment soft­ware involved
  • both freight for­warder and car­ri­ers have exist­ing and valid Trans.eu account
  • price nego­ti­a­tion process is avail­able from the exter­nal app

Authorize access

Before it is pos­si­ble to send any request, user needs to autho­rize access.

  • client app was reg­is­tered using reg­is­tra­tion form
  • exter­nal app was grant­ed api keys (client_id and client_secret)
  • autho­riza­tion process has been imple­ment­ed in exter­nal app

Create new freight

Each freight must con­sist of:

  • array of car­ri­ers’ ids
  • load­ing loca­tion and time
  • unload­ing loca­tion and time
  • required truck body type
  • sum­ma­ry of freight’s loads weight
  • ftl/ltl para­me­ter

Diagram

Request

To cre­ate new freight for select­ed com­pa­nies, there should be send freight to com­pa­nies pub­li­ca­tion method used.

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

Request example: 

Exam­ple freight post­ing request:

{
  "capacity": 12,
  "requirements": {
    "is_ftl": false,
    "required_truck_bodies": [
      "curtainsider"
    ],
    "loads": []
  },
  "carriers": [
    {
      "company_id": 10
    }
  ],
  "spots": [
    {
      "spot_order": 1,
      "place": {
        "address": {
          "country": "PL",
          "postal_code": "12345",
          "locality": "Wroclaw"
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2021-02-03T13:00:00+0100",
            "end": "2021-02-03T14:00:00+0100"
          },
          "type": "loading",
          "operation_order": 1,
          "loads": []
        }
      ]
    },
    {
      "spot_order": 2,
      "place": {
        "address": {
          "country": "DE",
          "postal_code": "09876",
          "locality": "Nürnberg"
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2021-02-04T08:00:00+0100",
            "end": "2021-02-04T08:00:00+0100"
          },
          "type": "unloading",
          "operation_order": 1,
          "loads": []
        }
      ]
    }
  ],
  "publish": true
}

Response

Each car­ri­er might respond with price con­di­tions accep­tance. Direct­ly after freight pub­li­ca­tion there will be an emp­ty array of offers received using:

https://api.platform.tran.eu/ext/freights-api/v1/freights/:freightId/offers

Once offer is sent by car­ri­er, it will fill out this array, for exam­ple:

[
  {
    "company_id": 1111111,
    "created_at": "2021-07-23T13:25:02+02:00",
    "freight_id": 820262,
    "id": 1892813,
    "legal_name": "Firma Testowa Przewoźnik",
    "price": {
      "currency": "eur",
      "value": 130
    },
    "status": "waiting_for_accept",
    "trans_id": "1111111-1",
    "vat_id": "1111111111",
    "version": 3
  }
]

Conditions:

  • each offer has own unique id
  • each car­ri­er is allowed to send one offer
  • each offer can be respond­ed to