Description of adding new transport order to selected carrier for assignment of driver and vehicle.

Scenario

  • carrier is selected and present on Trans.eu Platform
  • carrier’s TransId is stored in external TMS and can be sent via API
  • conditions of cooperation have been agreed upon
  • 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 assign vehicle and driver
  • completed order with vehicle and driver is downloaded from Trans.eu API

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 transport order

Each transport must consist of:

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

Endpoint:

(POST) https://api.platform.trans.eu/ext/orders-api/v1/orders-created

Request example: 

Example of transport order posting request:

{
  "freight": {
    "carrier": {
      "company_id": 317210
    },
    "capacity": 20,
    "loading_meters": 3,
    "requirements": {
      "is_ftl": true,
      "other_requirements": null,
      "required_adr_classes": null,
      "required_ways_of_loading": null,
      "shipping_remarks": null,
      "required_truck_bodies": [
        "41_bde"
      ]
    },
    "publish": "smartmatch",
    "loads": [],
    "spots": [
      {
        "name": null,
        "spot_order": 1,
        "place": {
          "address": {
            "locality": "Дн?про",
            "postal_code": "49000",
            "country": "UA",
            "street": "Каштановая",
            "number": "35"
          }
        },
        "coordinates": {
          "latitude": 48.4977774,
          "longitude": 35.0896543
        },
        "operations": [
          {
            "type": "loading",
            "operation_order": 1,
            "loads": [],
            "timespans": {
              "begin": "2020-04-10T00:00:00",
              "end": "2020-04-10T00:00:00"
            }
          }
        ]
      },
      {
        "name": null,
        "spot_order": 2,
        "place": {
          "address": {
            "locality": "Дн?про",
            "postal_code": "49000",
            "country": "UA",
            "street": "Писаржевкого",
            "number": "1"
          }
        },
        "coordinates": {
          "latitude": 48.4548583,
          "longitude": 35.0549241
        },
        "operations": [
          {
            "type": "unloading",
            "operation_order": 1,
            "loads": [],
            "timespans": {
              "begin": "2020-04-11T00:00:00",
              "end": "2020-04-11T00:00:00"
            }
          }
        ]
      }
    ]
  },
  "additional_terms": "My additional terms",
  "number": "ORDER/123/2019",
  "payment": {
    "days": 365,
    "price": {
      "type": "km",
      "value": 100,
      "currency": "1_eur"
    }
  },
  "monitoring": {
    "required": true,
    "providers": []
  },
  "insurance": {
    "load": {
      "value": 100,
      "currency": "1_eur"
    },
    "third_party": {
      "value": 150,
      "currency": "1_eur"
    }
  }
}

Response:

Confirmation of creating new transport order

{
  "id" : "12312-asdga1-afsfg2",
  "freight": {
    "carrier": {
      "company_id": 317210
    },
    "capacity": 20,
    "loading_meters": 3,
    "requirements": {
      "is_ftl": true,
      "other_requirements": null,
      "required_adr_classes": null,
      "required_ways_of_loading": null,
      "shipping_remarks": null,
      "required_truck_bodies": [
        "41_bde"
      ]
    },
    "publish": "smartmatch",
    "loads": [],
    "spots": [
      {
        "name": null,
        "spot_order": 1,
        "place": {
          "address": {
            "locality": "Днпро",
            "postal_code": "49000",
            "country": "UA",
            "street": "Каштановая",
            "number": "35"
          }
        },
        "coordinates": {
          "latitude": 48.4977774,
          "longitude": 35.0896543
        },
        "operations": [
          {
            "type": "loading",
            "operation_order": 1,
            "loads": [],
            "timespans": {
              "begin": "2020-04-10T00:00:00",
              "end": "2020-04-10T00:00:00"
            }
          }
        ]
      },
      {
        "name": null,
        "spot_order": 2,
        "place": {
          "address": {
            "locality": "Днпро",
            "postal_code": "49000",
            "country": "UA",
            "street": "Писаржевкого",
            "number": "1"
          }
        },
        "coordinates": {
          "latitude": 48.4548583,
          "longitude": 35.0549241
        },
        "operations": [
          {
            "type": "unloading",
            "operation_order": 1,
            "loads": [],
            "timespans": {
              "begin": "2020-04-11T00:00:00",
              "end": "2020-04-11T00:00:00"
            }
          }
        ]
      }
    ]
  },
  "additional_terms": "My additional terms",
  "number": "ORDER/123/2019",
  "payment": {
    "days": 365,
    "price": {
      "type": "km",
      "value": 100,
      "currency": "eur"
    }
  },
  "monitoring": {
    "required": true,
    "providers": []
  },
  "insurance": {
    "load": {
      "value": 100,
      "currency": "eur"
    },
    "third_party": {
      "value": 150,
      "currency": "eur"
    }
  }
}

 

Receiving updated transport order:

(GET) https://api.platform.trans.eu/ext/orders-api/orders-created/12312-asdga1-afsfg2

 

Response example:

{
  "id" : "12312-asdga1-afsfg2",
  "freight": {
    "carrier": {
      "company_id": 317210
    },
    "capacity": 20,
    "loading_meters": 3,
    "requirements": {
      "is_ftl": true,
      "other_requirements": null,
      "required_adr_classes": null,
      "required_ways_of_loading": null,
      "shipping_remarks": null,
      "required_truck_bodies": [
        "41_bde"
      ]
    },
    "publish": "smartmatch",
    "loads": [],
    "spots": [
      {
        "name": null,
        "spot_order": 1,
        "place": {
          "address": {
            "locality": "Днпро",
            "postal_code": "49000",
            "country": "UA",
            "street": "Каштановая",
            "number": "35"
          }
        },
        "coordinates": {
          "latitude": 48.4977774,
          "longitude": 35.0896543
        },
        "operations": [
          {
            "type": "loading",
            "operation_order": 1,
            "loads": [],
            "timespans": {
              "begin": "2020-04-10T00:00:00",
              "end": "2020-04-10T00:00:00"
            }
          }
        ]
      },
      {
        "name": null,
        "spot_order": 2,
        "place": {
          "address": {
            "locality": "Днпро",
            "postal_code": "49000",
            "country": "UA",
            "street": "Писаржевкого",
            "number": "1"
          }
        },
        "coordinates": {
          "latitude": 48.4548583,
          "longitude": 35.0549241
        },
        "operations": [
          {
            "type": "unloading",
            "operation_order": 1,
            "loads": [],
            "timespans": {
              "begin": "2020-04-11T00:00:00",
              "end": "2020-04-11T00:00:00"
            }
          }
        ]
      }
    ]
  },
  "additional_terms": "My additional terms",
  "number": "ORDER/123/2019",
  "payment": {
    "days": 365,
    "price": {
      "type": "km",
      "value": 100,
      "currency": "eur"
    }
  },
  "vehicle": {
    "registration": "NU MB3R"
   }
  }
}