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
}