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/v1/freights/freight-companies

 

Payload:

{
  "payment": {
    "price": {
      "value" : 1234,
      "currency": "eur"
    }
  },
  "capacity": 12,
  "exchange_recipients": "carriers",
  "requirements": {
    "is_ftl": false,
    "required_truck_bodies": [
      "cooler"
    ]
  },
  "spots": [
    {
      "spot_order": 1,
      "place": {
        "address": {
          "country": "fr",
          "postal_code": "11111",
          "locality": "null"
        },
        "coordinates": {
          "latitude": 49.8056,
          "longitude": 12.1881
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2020-06-25T09:00:00+01:00",
            "end": "2020-06-25T09:00:00+01:00"
          },
          "type": "loading",
          "operation_order": 1,
          "loads": []
        }
      ]
    },
    {
      "spot_order": 2,
      "place": {
        "address": {
          "country": "lt",
          "postal_code": "22222",
          "locality": "City"
        },
        "coordinates": {
          "latitude": null,
          "longitude": null
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2020-06-26T09:00:00+01:00",
            "end": "2020-06-26T09:00:00+01:00"
          },
          "type": "unloading",
          "operation_order": 1,
          "loads": []
        }
      ]
    }
  ],
  "loads": [
    {
      "name": "example",
      "description": "Example description",
      "load_id": "1",
      "type_of_load": "palette",
      "weight": 1,
      "height": 1,
      "length": 1,
      "volume": 1,
      "amount": 1,
      "is_stackable": false,
      "is_exchangeable": false
    }
  ],
  "publish": true
}

 

Response:

{
  "payment": {
    "price": {
      "value": null,
      "currency": "eur"
    }
  },
  "capacity": 12,
  "exchange_recipients": "carriers"
  "requirements": {
    "is_ftl": false,
    "required_truck_bodies": [
      "cooler"
    ]
  },
  "spots": [
    {
      "spot_order": 1,
      "place": {
        "address": {
          "country": "fr",
          "postal_code": "11111",
          "locality": "null"
        },
        "coordinates": {
          "latitude": 49.8056,
          "longitude": 12.1881
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2020-06-25T09:00:00+01:00",
            "end": "2020-06-25T09:00:00+01:00"
          },
          "type": "loading",
          "operation_order": 1,
          "loads": []
        }
      ]
    },
    {
      "spot_order": 2,
      "place": {
        "address": {
          "country": "lt",
          "postal_code": "22222",
          "locality": "City"
        },
        "coordinates": {
          "latitude": null,
          "longitude": null
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2020-06-26T09:00:00+01:00",
            "end": "2020-06-26T09:00:00+01:00"
          },
          "type": "unloading",
          "operation_order": 1,
          "loads": []
        }
      ]
    }
  ],
  "loads": [
    {
      "name": "example",
      "description": "Example description",
      "load_id": "1",
      "type_of_load": "palette",
      "weight": 1,
      "height": 1,
      "length": 1,
      "volume": 1,
      "amount": 1,
      "is_stackable": false,
      "is_exchangeable": false
    }
  ],
  "publish": true
}

 

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.


Accepted freight

{
  "payment": {
    "price": {
      "value": 2,
      "currency": "eur"
    }
  },
  "capacity": 12,
  "requirements": {
    "is_ftl": false,
    "required_truck_bodies": [
      "cooler"
    ]
  },
  "spots": [
    {
      "spot_order": 1,
      "place": {
        "address": {
          "country": "fr",
          "postal_code": "11111",
          "locality": "null"
        },
        "coordinates": {
          "latitude": 49.8056,
          "longitude": 12.1881
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2020-06-25T09:00:00+01:00",
            "end": "2020-06-25T09:00:00+01:00"
          },
          "type": "loading",
          "operation_order": 1,
          "loads": []
        }
      ]
    },
    {
      "spot_order": 2,
      "place": {
        "address": {
          "country": "lt",
          "postal_code": "22222",
          "locality": "City"
        },
        "coordinates": {
          "latitude": null,
          "longitude": null
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2020-06-26T09:00:00+01:00",
            "end": "2020-06-26T09:00:00+01:00"
          },
          "type": "unloading",
          "operation_order": 1,
          "loads": []
        }
      ]
    }
  ],
  "loads": [
    {
      "name": "example",
      "description": "Example description",
      "load_id": "1",
      "type_of_load": "palette",
      "weight": 1,
      "height": 1,
      "length": 1,
      "volume": 1,
      "amount": 1,
      "is_stackable": false,
      "is_exchangeable": false
    }
  ],
  "publish": true
}