Shipment of multiple load in multiple locations

Shipment of one load from point A to point B

Scenario

many defined loads with multiple loadings and unloadings:
- load L1 — weight: 8 tonnes
- load L2 — weight 3 tonnes
- load L3 — weight 10 tonnes
multiple operations in more than two locations
- first spot — loading L1 and L2
- second spot — loading L3
- third spot — unloading L3 and loading L1
- fourth spot — unloading L1 and unloading L2

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:

loads definition
loading locations and time
unloading locations and time
load reference in loading and unloading points
required truck body type
summary of freight’s loads weight
ftl/ltl parameter

Request

This type of freight parameters can be used with all types of publication methods. Some conditions apply.

POST https://api.platform.tran.eu/ext/freights-api/v1/freights-{publication method}

Request example:

Example of freight request:

{
  "payment": {
    "price": {
      "value": 123,
      "currency": "eur"
    }
  },
  "capacity": 21,
  "exchange_recipients": "carriers",
  "requirements": {
    "is_ftl": false,
    "required_truck_bodies": [
      "cooler"
    ]
  },
  "loads": [
    {
      "name": "example",
      "description": "Example description of first load",
      "load_id": "L1",
      "type_of_load": "palette",
      "weight": 8,
      "height": 1,
      "length": 1,
      "volume": 1,
      "amount": 1,
      "is_stackable": false,
      "is_exchangeable": false
    },
    {
      "name": "example",
      "description": "Example description of second load",
      "load_id": "L2",
      "type_of_load": "palette",
      "weight": 3,
      "height": 1,
      "length": 1,
      "volume": 1,
      "amount": 1,
      "is_stackable": false,
      "is_exchangeable": false
    },
    {
      "name": "example",
      "description": "Example description of third load",
      "load_id": "L3",
      "type_of_load": "palette",
      "weight": 10,
      "height": 1,
      "length": 1,
      "volume": 1,
      "amount": 1,
      "is_stackable": false,
      "is_exchangeable": false
    }
  ],
  "carriers": [
    {
      "company_id": 1111111
    }
  ],
  "spots": [
    {
      "spot_order": 1,
      "place": {
        "address": {
          "country": "fr",
          "postal_code": "11111",
          "locality": "null"
        },
        "coordinates": {
          "latitude": 49.8056,
          "longitude": 12.1881
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2021-07-25T09:00:00+01:00",
            "end": "2021-07-25T09:00:00+01:00"
          },
          "type": "loading",
          "operation_order": 1,
          "loads": [
            {
              "load_id": "L1",
              "weight": 8
            },
            {
              "load_id": "L2",
              "weight": 3
            }
          ]
        }
      ]
    },
    {
      "spot_order": 2,
      "place": {
        "address": {
          "country": "lt",
          "postal_code": "22222",
          "locality": "City"
        },
        "coordinates": {
          "latitude": null,
          "longitude": null
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2021-07-27T09:00:00+01:00",
            "end": "2021-07-27T09:00:00+01:00"
          },
          "type": "loading",
          "operation_order": 1,
          "loads": [
            {
              "load_id": "L3",
              "weight": 10
            }
          ]
        }
      ]
    },
    {
      "spot_order": 3,
      "place": {
        "address": {
          "country": "fr",
          "postal_code": "11111",
          "locality": "null"
        },
        "coordinates": {
          "latitude": 49.8056,
          "longitude": 12.1881
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2021-07-28T09:00:00+01:00",
            "end": "2021-07-28T09:00:00+01:00"
          },
          "type": "unloading",
          "operation_order": 1,
          "loads": [
            {
              "load_id": "L3",
              "weight": 10
            }
          ]
        },
        {
          "timespans": {
            "begin": "2021-07-29T09:00:00+01:00",
            "end": "2021-07-29T09:00:00+01:00"
          },
          "type": "unloading",
          "operation_order": 2,
          "loads": [
            {
              "load_id": "L1",
              "weight": 4
            }
          ]
        }
      ]
    },
    {
      "spot_order": 4,
      "place": {
        "address": {
          "country": "fr",
          "postal_code": "11111",
          "locality": "null"
        },
        "coordinates": {
          "latitude": 49.8056,
          "longitude": 12.1881
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2021-07-30T09:00:00+01:00",
            "end": "2021-07-30T09:00:00+01:00"
          },
          "type": "unloading",
          "operation_order": 1,
          "loads": [
            {
              "load_id": "L1",
              "weight": 4
            },
            {
              "load_id": "L2",
              "weight": 3
            }
          ]
        }
      ]
    }
  ],
  "publish": true
}

Response

Each carrier might respond with price conditions acceptance. Directly after freight publication there will be an empty array of offers received using:

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

Once offer is sent by carrier, it will fill out this array, for example:

[
  {
    "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 carrier is allowed to send one offer
each offer can be responded to