Skip to content

BE OPEN TO OTHER SYSTEMS WITH OUR APIs

écran dev exemple

Mon Appli VTC offers APIs. APIs, which stand for Application Programming Interfaces, allow different systems to interact with each other. For instance, imagine that a local community with a mobility application could offer your services within their app, or a travel agency with an internal management software could request a VTC ride while staying within their interface.

Of course, you will still be able to see the rides within the app, just like before.

This page is primarily intended for developers so that they can integrate with your application.

screen dev right
Prise de commande côté client chez Mon Appli VTC

create an account for the partner

Before handing over to the developer of the mentioned organization, it is necessary to create a client account for them in the application if the organization does not already have one.

Then, go to Settings > API > Add a user > client’s name, and then send the login information to the developer. From now on, they will take control.

Request a price estimate

To obtain a price estimate, you must make a POST request to the URL provided by the fleet manager. This request should be of type « quote, » and you will need to provide information about the starting point, destination, and date. In the case of an ASAP (as soon as possible) ride, you do not need to indicate a date. Please check with the fleet if they accept ASAP rides

Make a POST request to : https://fleet-url.com/api

{
  "client_id":"%CLIENT_ID%",
  "client_secret":"%CLIENT_SECRET%",
  "type":"quote",
  "date":"2021-04-21T12:00:00Z", /*facultatif*/
  "origin":
     {
       "latitude": 43.704142637456805,
       "longitude":7.261011952626623,
       "text":"Gare de Nice Ville, 06100 Nice"
     },
  "destination":
     {
       "latitude": 43.66522829998318,
       "longitude":7.212595874093402,
       "text":"Aéroport Nice Côte d'Azur, 06000 Nice"
     }
}

Response to the estimate request

If your request is correct, you will receive information about the ride, such as the number of kilometers, the estimated time (in seconds), and the price estimate for different vehicles. The price estimates will include the vehicle type name (Sedan, Van, etc.), the price in ISO 4217 format, which means without digits after the decimal point (1234 becomes 12.34€), and a UUID (Universally Unique Identifier) to validate the order later on.

{
  "timeEstimation":900,
  "kmEstimation":"7 km",
  "origin":
     {
       "latitude": 43.704142637456805,
       "longitude":7.261011952626623,
       "text":"Gare de Nice Ville, 06100 Nice"
     },
  "destination":
     {
       "latitude": 43.66522829998318,
       "longitude":7.212595874093402,
       "text":"Aéroport Nice Côte d'Azur, 06000 Nice"
     }
  "quote":[
     {
       "total":16000,
       "currency":"eur",
       "name":"Berline",
       "uuid":"%UUIDESTIMATION1%"
     },
     {
       "total":25000,
       "currency":"eur",
       "name":"Van",
       "uuid":"%UUIDESTIMATION2%"
     },
  ]
}

Validate the creation of a ride

Once you have obtained the price estimate, some additional information is required to complete the booking request. Firstly, you will need to provide us with the UUID of the selected vehicle. For example, %UUIDESTIMATION1% or %UUIDESTIMATION2% if you use the request provided above. You will also need to provide us with an array containing the list of passengers. In case you do not have the names of the other passengers, you can add « passenger_count » with the total number of passengers. Optionally, you can provide a comment or a flight/train number. The API will respond with a trip number (trip_id).

Make a POST request to: https://fleet-url.com/api

{
  "client_id":"%CLIENT_ID%",
  "client_secret":"%CLIENT_SECRET%",
  "type":"book",
  "uuid":"%UUIDESTIMATION1%",
  "passenger_count":2, /*facultatif*/
  "passengers":[
     {
       "first_name":"Jean",
       "last_name":"Martin",
       "phone_number":"06000000000" /*facultatif*/
       "email":"jean@mail.com" /*facultatif*/
     }
  ],
  "comment":"Hello world", /*facultatif*/
  "flight_number":"AF0434", /*facultatif*/
  "train_number":"TGV5423" /*facultatif*/
}

The API will respond :

{
  trip_id:"%TRIPID%"
}

Track the ride

If you wish, you can track the progress of the ride. To do this, use the trip_id provided by the API during the creation of the ride (%TRIPID% in the previous example) with a « getInfo » type request.

As a response, you will first receive the status of the ride:

  • « validate » if the ride has been validated by the dispatch.
  • « driverEnRoute » if the driver is en route to the pickup point.
  • « arrived » if the driver has arrived at the pickup point.
  • « passengerOnBoard » if the passenger(s) are in the vehicle.
  • « completed » if the ride is completed.
  • « cancelled » if the ride has been canceled.

Optionally, you may also receive the name and phone number of the driver, information about the car (make, model, and registration number), as well as the driver’s current geographic position.

Make a POST request to : https://fleet-url.com/api

{
  "client_id":"%CLIENT_ID%",
  "client_secret":"%CLIENT_SECRET%",
  "type":"getInfo",
  "trip_id":"%TRIPID%",
}

The API will respond :

{
  "status":"driverEnRoute",
  "driver":{
     "first_name":"Richard",
     "last_name":"Dupont",
     "phone_number":"0600000000",
  },
  "vehicle":{
     "vehicle_class":"Berline",
     "description":"Peugeot 508",
     "vehicle_registration":"GT-402-AT",
     "position":{
       "latitude":43.66522829998318,
       "longitude":7.261011952626623,
     }
  }
}

Cancel a ride

If you wish to cancel a ride, you need to send a « cancel » type request with the trip_id. The API will respond confirming that the ride has been successfully canceled

Make a POST request to : https://fleet-url.com/api

{
  "client_id":"%CLIENT_ID%",
  "client_secret":"%CLIENT_SECRET%",
  "type":"cancel",
  "trip_id":"%TRIPID%",
}

The API will respond :

{
  cancelled:true
}

Possible errors

Several errors can occur in your requests. In such cases, the API will return a 400 error with an error code and an explanation of the cause of the error. Here are different cases:

{"error":true, "errorCode":1, "errorInfo":"no params"}

Your POST request contains no information. It is necessary to indicate at least the fields client_id, client_secret, and type

{"error":true, "errorCode":2, "errorInfo":"authentification fail"}

Your client_id and/or client_secret are invalid. This could be due to various reasons, such as the deletion of your developer access

{"error":true, "errorCode":3, "errorInfo":"request fail"}

Some elements are missing from your request. For example, you are making a quote request, but you did not specify the destination

{"error":true, "errorCode":4, "errorInfo":"asap unavailable"}

You requested an ASAP (as soon as possible) ride, but the platform does not allow them. Contact the platform to enable ASAP rides or refrain from requesting them

{"error":true, "errorCode":5, "errorInfo":"incorrect time reservation (minimum XXX minutes before"}

The platform requires a reservation XXX minutes in advance, and you have not done so. Similar to error 4, contact the platform

{"error":true, "errorCode":6, "errorInfo":"cancellation error"}

You requested to cancel a ride that cannot be canceled because it has already been billed, for example

{"error":true, "errorCode":7, "errorInfo":"trip not found"}

You requested information about a ride that does not exist