Description of adding a freight which will be visible to all Trans.eu users, without declaring the freight price.

Scenario

  • carrier is yet to be determined from all Trans.eu Platform users
  • carries is supposed to be found as soon as possible, therefore publication is immediately invoked
  • price was not given
  • carrier is using Trans.eu Platform only, with no additional freight management software involved
  • freight forwarding companies are excluded
  • received offers will be negotiated in external app
  • freight acceptance will also be sent from external app

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

To create new freight, which will be visible to all Trans.eu users, the exchange publication method has to 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
  • freight forwarders exclusion parameter

Diagram

Request example

Endpoint:

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

 

Payload:

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