Skip to content

Soyez ouvert aux autres systèmes avec nos api

écran dev exemple

Mon Appli VTC propose des API. Les API pour interfaces de programmation permettent aux différents systèmes d’intéragir ensemble. Par exemple, on peut imaginer qu’une collectivité locale possédant une application de mobilité puisse proposer vos services dans son appli ou encore, une agence de voyages possédant un logiciel de gestion interne puisse commander le VTC en restant dans son interface. 

Bien sûr, vous verrez les courses dans l’application comme avant. 

Cette page est principalement destinée aux développeurs afin qu’ils puissent s’intégrer avec votre application. 

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

Pour commencer : créez un compte pour le partenaire

Avant de passer la main au développeur de la structure en question, il est nécessaire de lui créer un compte client dans l’application si la structure n’en possède pas encore. 

Allez ensuite dans Réglages > API > Ajouter un utilisateur > nom du client et envoyez ensuite les informations de connexion au développeur. A partir de maintenant, c’est lui qui prend la main. 

Demander une estimation du prix

Afin d’obtenir une estimation du prix, vous devez faire une requête POST sur l’URL communiqué par le responsable de la flotte. Cette requête devra être de type « quote » et vous devrez fournir les informations sur le point de départ, de la destination ainsi que la date. Dans le cas d’une course ASAP (dès que possible), vous n’avez pas à indiquer de date. Renseignez-vous auprès de la flotte si elle accepte les courses ASAP. 

 Faire une requête POST sur :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"
     }
}

Réponse à la demande d'estimation

Si votre requête est correcte, vous allez recevoir les informations sur la demande comme le nombre de km, l’estimation du temps (en seconde) ainsi que l’estimation du prix pour les différents véhicules. Dans les estimations du prix, vous aurez le nom du type de véhicule (Berline, Van …), le prix en format ISO 4217, c’est à dire sans chiffre après la virgule (1234 donne 12.34€) ainsi qu’un UUID permettant de valider la commande ultérieurement. 

{
  "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%"
     },
  ]
}

Valider la création d'une course

Une fois que vous avez eu l’estimation du prix, quelques informations supplémentaires sont nécessaires pour terminer la demande de réservation. Tout d’abord, il faudra nous donner l’UUID du véhicule sélectionné. Par exemple %UUIDESTIMATION1% ou %UUIDESTIMATION2% si on prend la requête ci dessus. Vous devrez également nous fournir un tableau avec la liste des passagers. Dans le cas où vous n’auriez pas le nom des autres passagers, vous pouvez rajouter « passager_count » avec le nombre total de passagers. Vous pouvez fournir de manière facultative un commentaire ou un numéro de vol / de train. L’API vous répondra avec un numéro de course (trip_id)

 Faire une requête POST sur :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*/
}

L’API répondra : 

{
  trip_id:"%TRIPID%"
}

Suivre la course

Si vous le souhaitez, vous pouvez suivre le déroulé de la course. Il suffit pour cela d’utiliser le trip_id que l’API vous a fourni lors de la création de la course (%TRIPID% dans l’exemple précédent) avec une requête de type « getInfo ».

Comme réponse, vous aurez tout d’abord le status de la course :

  • validate si la course a été validée par le dispatch
  • driverEnRoute si le chauffeur est en route vers le point de prise en charge
  • arrived si le chauffeur est arrivé au point de prise en charge
  • passengerOnBoard si le ou les voyageurs sont dans le véhicule
  • completed si la course est terminée
  • cancelled si la course a été annulée

Vous pourrez également avoir, de manière optionnelle, le nom et le numéro de téléphone du chauffeur, les informations sur la voiture (marque, modèle et immatriculation) ainsi que la position géographique du chauffeur. 

 Faire une requête POST sur :https://fleet-url.com/api

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

L’API répondra : 

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

Annuler une course

Si vous souhaitez annuler une course, il faut envoyer une requête de type « cancel » avec le trip_id. L’API vous répondra que la course a bien été annulée. 

 Faire une requête POST sur :https://fleet-url.com/api

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

L’API répondra : 

{
  cancelled:true
}

Erreurs possibles

Plusieurs erreurs peuvent intervenir dans vos requêtes. Dans ce cas, l’API vous retournera une erreur 400 avec un code erreur et une explication sur la cause de l’erreur. Voici différents cas : 

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

Votre requête POST ne contient aucune information. Il est nécessaire d’indiquer au minimum les champs client_id, client_secret et type

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

Votre client_id et / ou votre client_secret sont invalides. Cela peut être pour plusieurs raisons comme la suppression de votre accès développeur

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

Il manque certains éléments à votre requête. Par exemple, vous faites une requête quote mais vous ne mettez pas la destination 

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

Vous avez demandé une course ASAP (dès que possible) mais la plateforme ne les autorise pas. Contactez la plateforme pour qu’elle autorise les courses ASAP ou n’en commandez pas

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

La plateforme demande une réservation de XXX minutes à l’avance et vous ne l’avez pas fait. Comme pour l’erreur 4, contactez la plateforme

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

Vous avez demandé à annuler une course qui ne peut pas l’être car elle a déjà été facturée par exemple

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

Vous avez demandé des informations sur une course mais celle-ci n’existe pas