Search for carrier using appropriately selected and recommended companies

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

Scenario

  • carrier is yet to be determined
  • 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
  • carrier has to meet specified criteria
  • the carrier does not yet belong to the group of contractors

Diagram

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
  • price and currency

Endpoint:

(POST) https://api.platform.trans.eu/ext/freights-api/v1/freight-smartmatch

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

Payload for freight acceptance:

{ "version" : 3}

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 for freight negotiation:

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