Search for carrier using appropriately selected and recommended companies

Descrip­tion of adding a freight to com­pa­nies cho­sen by rec­om­men­da­tion algo­rithm, with declar­ing the freight price.

Scenario

• car­ri­er is yet to be deter­mined
• price and cur­ren­cy was giv­en
• car­ri­er is using Trans.eu Plat­form only, with no addi­tion­al freight man­age­ment soft­ware involved
• both freight for­warder and car­ri­ers have exist­ing and valid Trans.eu account
• car­ri­er has to meet spec­i­fied cri­te­ria
• the car­ri­er does not yet belong to the group of con­trac­tors

Diagram

Authorize access

Before it is pos­si­ble to send any request, user needs to autho­rize access.

• client app was reg­is­tered using reg­is­tra­tion form
• exter­nal app was grant­ed api keys (client_id and client_secret)
• autho­riza­tion process has been imple­ment­ed in exter­nal app

Create new freight

In order to send freight pro­pos­als to car­ri­ers tai­lored to its cri­te­ria, the pub­li­ca­tion method using the smart­match algo­rithm must be used.

Each freight must consist of:

• load­ing loca­tion and time
• unload­ing loca­tion and time
• required truck body type
• sum­ma­ry of freight’s loads weight
• ftl/ltl para­me­ter
• price and cur­ren­cy

Endpoint:

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

Request example: 

Exam­ple of smart match freight post­ing request:

{
  "capacity": 12,
  "requirements": {
    "is_ftl": false,
    "required_truck_bodies": [
      "curtainsider"
    ],
    "loads": []
  },
  "spots": [
    {
      "spot_order": 1,
      "place": {
        "address": {
          "country": "PL",
          "postal_code": "12345",
          "locality": "Wroclaw"
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2021-02-03T13:00:00+0100",
            "end": "2021-02-03T14:00:00+0100"
          },
          "type": "loading",
          "operation_order": 1,
          "loads": []
        }
      ]
    },
    {
      "spot_order": 2,
      "place": {
        "address": {
          "country": "DE",
          "postal_code": "09876",
          "locality": "Nürnberg"
        }
      },
      "operations": [
        {
          "timespans": {
            "begin": "2021-02-04T08:00:00+0100",
            "end": "2021-02-04T08:00:00+0100"
          },
          "type": "unloading",
          "operation_order": 1,
          "loads": []
        }
      ]
    }
  ],
  "publish": true
}

Response example:

{
    "accepted_price": null,
    "capacity": 12,
    "carrier": null,
    "id": 592018,
    "loading_meters": null,
    "loads": [],
    "publication_price": null,
    "reference_number": "FR/2021/02/03/X64K",
    "requirements": {
        "is_ftl": false,
        "other_requirements": [],
        "required_adr_classes": [],
        "required_truck_bodies": [
            "curtainsider"
        ],
        "required_ways_of_loading": [],
        "shipping_remarks": null,
        "temperature": {
            "max": null,
            "min": null
        },
        "vehicle_size": "any_size"
    },
    "shipment_external_id": null,
    "spots": [
        {
            "description": null,
            "name": null,
            "operations": [
                {
                    "loads": [],
                    "operation_order": 1,
                    "timespans": {
                        "begin": "2021-02-03T13:00:00+01:00",
                        "end": "2021-02-03T14:00:00+01:00"
                    },
                    "type": "loading"
                }
            ],
            "place": {
                "address": {
                    "country": "PL",
                    "description": null,
                    "locality": "Wroclaw",
                    "number": null,
                    "postal_code": "12345",
                    "street": null
                },
                "coordinates": {
                    "latitude": null,
                    "longitude": null
                }
            },
            "spot_order": 1
        },
        {
            "description": null,
            "name": null,
            "operations": [
                {
                    "loads": [],
                    "operation_order": 1,
                    "timespans": {
                        "begin": "2021-02-04T08:00:00+01:00",
                        "end": "2021-02-04T08:00:00+01:00"
                    },
                    "type": "unloading"
                }
            ],
            "place": {
                "address": {
                    "country": "DE",
                    "description": null,
                    "locality": "Nürnberg",
                    "number": null,
                    "postal_code": "09876",
                    "street": null
                },
                "coordinates": {
                    "latitude": null,
                    "longitude": null
                }
            },
            "spot_order": 2
        }
    ],
    "status": "new"
}

Receive offers

Each response for freight pub­li­ca­tion can be accessed using API. To find out which car­ri­ers respond­ed send the request below:

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

If there is no response, you will receive an emp­ty array.

If respons­es have been sent, there will be an array, which con­sists of each response.

How to get freight offers is described here.

Negotiation

It pos­si­ble to accept, reject or nego­ti­ate received price con­di­tions

Accept:

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

Pay­load for freight accep­tance:

{ "version" : 3}

Reject:

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

Negotiate:

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

Payload for freight negotiation:

{
    "payment": {
        "price": {
            "value": 150
        }
    },
    "version": 2
}