Search for carriers with user defined pubication

Description of adding a freight to companies chosen by recommendation algorithm, with declaring the freight price.

Scenario

carrier is yet to be determined
price was not 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
carrier has to meet specified criteria
the carrier does not belong to the group of contractors
there are corresponding automation rules set on Trans.eu Platform

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

In order to send freight proposals to carriers tailored to its criteria, the publication method using the smartmatch algorithm must be used.

Each freight must consist of:

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

Diagram

Endpoint:

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

Request example:

Example of transport order posting request:

{
  "payment": {
    "price": {
      "value": 123,
      "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 example:

{
  "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
}

Receive offers

Each response for freight publication can e accessed using APi. To find out which carriers responded send the request below:

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

If there is no response, you will receive empty array.

If responses have been sent, there will be array, which consists of each response:

Negotiation

It possible to accept, reject or negotiate received price conditions

Accept:

https://api.platform.trans.eu/ext/freights/v1/{offer-id}/accept

Reject:

https://api.platform.trans.eu/ext/freights/v1/{offer-id}/reject

Negotiate:

https://api.platform.trans.eu/ext/freights/v1/{offer-id}/negotiate

Payload:

{
  "payment": {
    "price": {
      "value": 100,
      "currency": "pln"
    }
  },
  "requirements": "requirements description",
  "version": 3,
  "carrier_decision_date": "2020-05-20T12:00:00+02:00"
}

Accepted freight

{
  "payment": {
    "price": {
      "value": 100,
      "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
}