Application

Cette méthode est adaptée dans le cadre d'applications (mobile, web ou desktop) exploitées directement par vos utilisateurs détenteurs d'un compte SuiviDeFlotte.net. Ils devront s'identifier avec leur compte utilisateur et bénéficient des mêmes droits et limitations que lorsqu'ils se connectent à nos produits.

L'accès à l'API en mode Application implémente le flux Grant Password (aussi appelé Resource Owner Password Credentials Grant) du protocole OAuth2.

Accès à l'API en mode Application

1. Générer votre clé d'accès.
2. S'identifier auprès du serveur OAuth2 afin de récupérer un access_token :

   curl -X POST "https://api.suivideflotte.net/oauth2" \
   -H "accept: application/json" -H "content-type: application/json" \
   -d '{"client_id":"votre_client_id", "client_secret":"votre_client_secret","username":"identifiant_utilisateur_suivideflotte", "password":"mot_de_passe_utilisateur_suivideflotte"}'

3. L'API vous retourne une réponse JSON au format suivant :

   Status: 200 OK
   {
     "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImZjM2NkMGJmNGY4YjdkZTcxYjNhYWRlNWJlNjU5OTMzMTNhNDU0NzNkNDRiZDcxOTgyOGQyNzFmZWVjMWRlODk0NDgxNTk2YjQyZmNlNWRkIn0.eyJhdWQiOiI2NyIsImp0aSI6ImZjM2NkMGJmNGY4YjdkZTcxYjNhYWRlNWJlNjU5OTMzMTNhNDU0NzNkNDRiZDcxOTgyOGQyNzFmZWVjMWRlODk0NDgxNTk2YjQyZmNlNWRkIiwiaWF0IjoxNDk3Mjc2MDkwLCJuYmYiOjE0OTcyNzYwOTAsImV4cCI6MTQ5NzQ5MjA5MCwic3ViIjoiMTMiLCJzY29wZXMiOlsiKiJdfQ.qOam_2Jf0xFACGBU8yVdkku4DXSyH6dISGY4ZXYtAvKRauQB89BtvtDEK1Mo1PQBoJaX0hvjl2X2Osu3EjwHCy3DwE8NcuFMBdqHbQTAShv23DqOnHRtgKAOz2V_VVs08s-xCxj5yiAQDHankPiDFoHE55GVc6w5E3QgRbHIZuPWDNbqn0lcCbl86xw3J_C7cKGiDiHehxL2cQl2RthPcN3ZevPMWwbAD55DsN0t2RSFpwy3TBl7V5WYRclEECxdZlkkRyu-U_-ec4Vv7o6E8vol_tx-tRBy9yWwfrsUirw-WxCzRrasnU0g0v1ZNsOjeg00UB0dH1HYUFN-GNMygp0nV6UDTOV09P_ligQHLSjf65dKTgV8KF171wuJqDcGbbm0OfvL3sRGU6Nrk8SHd6AHng9hBuxTyQncXnW11gDetbuGUxlbFn_ZCt9DcFgw92MllVqtJqnNAoAaam4rSslXzjivEZ0LR_3MgjkPerzqHeIeCNdWb8cuItnzja0GUBJRAXsiyldAyEY6XV2q0bVWI595lMhfUzsVLwCWtDHlM0ilAMj5Pd-27wrDsc_uvUeIKU_SR-5HkhFdVVGcaDq0dN6Cu7QAfejOZm0aFle9GnrpNjl8R7D9R3oJ3800y8k81hJl1Jzysi-XXnqw6sAtw6P1BwYdmS3gWTQi-qQ",
     "expires_in":86400,
     "refresh_token":"S4SD0HDmZfhQk0fCup6ht7FN6QRjtFfHuHZRt7Tzuv\/k7n++O4TbuJPAGTWEgIpJlYq94O7Cw7MBUh+3gedsQUQCIt89JZYejPilkPk+6yoMMoDkCMCYAkKUEcQ4UgbPE222wvFaZHXzytWNo5O5EmuKdPwl0mqotwuKB2g0729h9njwr30lja6DJWFbOFrNiqPLzzWj+DSNv24nbtUPa9NwtBifna3LoNEU1Szv+BbeDZC1Zk4yQv37MMvINNTutlcIfqKvQPJj8PH9jnYKsK64nzEhJb\/RaynidzciQz5OlMl\/Duki72wOBmMsvM8l+k7BaUWSFrgs0pfdt6kPwINieGL9+4FtVxjAPzYxJpfevcfNfxJKLDgRqcIK\/TSMQ+NB4vR+bWWTh3+KL2wjuAsH6PDg5UyuVt3TgZPe8Ig\/sNudTUYjdUprfbzb6xEAviSfZD388lRL+Z1co4zbbV0NHqD4SkMqYHJh6LCGIrC39QKhd6m2qQyxsxMT0grHX27Kn\/dNfl7jNY+cfsDzEa8aQWNWZK6XYBOHDj2RMEPGC+Cl7NuEa7f4eNFFvGLG0CVF\/oeF3\/DncS9Dv2xR4eOUDaTAVZVRQ7iFwaPK3V4biNhRhlZSikiqCIiJnEUmdt9BoCZxWKW3HQ4UZnmj1h8P36HNdIjVncpc7ekcHlk="
   }

   access_token Token d'identification à utiliser dans vos appels à l'API (header HTTP Authorization).
   expire_in Durée de vie de l'access_token en secondes (1440 minutes).
   refresh_token Token de rafraichissement (valide 10 jours) à utiliser pour obtenir un nouvel access_token lorque celui-ci a expiré.
4. Vous pouvez accéder aux endpoints de l'API grâce à votre access_token.

Token persistant

Cette méthode est destiné à une utilisation dans le cadre d'applications serveur gérant des traitements automatisés (machine to machine). Le token fourni a plusieurs particularités qu'il est important de connaître:

• Il permet d'exploiter l'intégralité de l'API avec le même niveau de permission qu'un Super Administrateur. Il existe donc un système de permission (appelé Scopes) que vous décidez d'accorder ou non au moment de la génération du token.
• Contrairement à la méthode Application, il n'est pas nécessaire de rafraîchir ce type de token.
• En contrepartie, sa durée de vie est importante : 5 ans.

Important. Ce type de token est comparable à un mot de passe, vous devez donc prendre les même précautions : ne pas le divulguer, ne pas le stocker en clair dans votre application, etc.

Accès à l'API en mode Token persistant

1. Générer votre clé d'accès.
   • Lors de la procédure de génération, précisez les Scopes (permissions) que vous souhaitez accorder à ce token.
   • Nous vous conseillons de n'autoriser que le "minimum vital" nécessaire au bon fonctionnement de votre application. Par exemple, si vous n'avez besoin de faire que du reporting, n'accorder pas de droits d'écriture qui autoriserait la modification de ressources.
2. Une fois votre token généré, vous pouvez vous en servir dans le header HTTP Authorization afin d'accéder aux endpoints de l'API. Consultez Autorisations pour plus de détails.

Autorisations

L'accès aux endpoint n'est possible que si vous avez un access_token valide (voir Authentification pour obtenir un access_token). Toutes vos requêtes doivent à minima comporter dans l'en-tête HTTP :

• Authorization avec la valeur Bearer votre_access_token
• Accept avec la valeur application/json.
• X-Version Indique la version de l'API sur laquelle vous voulez faire votre requête. Ce paramètre est optionnel, si il n'est pas spécifié c'est la version courante de l'API qui est utilisée (actuellement version 1). Nous vous conseillons vivement de préciser ce paramètre afin de vous assurer que votre application continue de fonctionner à l'identique si un endpoint que vous exploitez est remanié dans une version ultérieure.

Exemple d'appel en GET, sans paramètre particulier :

curl -X GET "https://api.suivideflotte.net/url_du_endpoint" \
-H "Authorization:Bearer votre_access_token" -H "Accept:application/json" \
-H "X-Version:1

Rafraîchissement de l'access_token

Pour des raisons de sécurité, la durée de vie de l'access_token de type Application est limitée à 1440 minutes. Passé ce délai, vous recevez une erreur HTTP 401 et devez alors effectuer une opération de rafraîchissement pour pouvoir continuer à communiquer avec l'API. La réponse retournée a le même format que lors de l'authentification.

Deux méthode de rafraîchissement sont possibles :

Via un endpoint

Le rafraîchissement par endpoint (/oauth2/refresh) vous permet de demander le rafraîchissement de votre access_token dans toutes les situations.

curl -X POST "https://api.suivideflotte.net/oauth2/refresh" \
-H "Accept:application/json" -H "X-Version:1 \
-d '{"client_id":"votre_client_id", "client_secret":"votre_client_secret", "refresh_token":"votre_refresh_token"}

Si vous recevez une erreur HTTP 400, celà signifie que votre refresh_token est invalide. Nous vous conseillons alors de rediriger vos utilisateurs vers votre écran de login afin qu'ils s'identifient à nouveau.

Exemples de réponses possibles :

Status: 400 Bad Request
{"error":"invalid_request", "message":"The refresh token is invalid.", "hint":"Token has been revoked"}

Status: 400 Bad Request
{"error":"invalid_request", "message":"The refresh token is invalid.", "hint":"Cannot decrypt the refresh token"}

Via un cookie

Si votre application fonctionne dans un navigateur internet acceptant les cookies (application en mode SPA par exemple), un cookie contenant le refresh_token a été positionné pour vous. Vous pouvez donc demander le rafraîchissement de l'access_token en appelant directement https://api.suivideflotte.net/oauth2/refresh.

Endpoints

Requêtes HTTP

L'API est composée de plusieurs endpoints. Un endpoint est une URL à laquelle vous vous adressez via les méthodes HTTP suivantes :

• GET. Pour une opération de récupération de données.
• POST. Pour une opération de création (si l'utilisateur connecté bénéficie des droits suffisants).
• PUT. Pour une opération d'édition (si l'utilisateur connecté bénéficie des droits suffisants).
• DELETE. Pour une opération de suppression (si l'utilisateur connecté bénéficie des droits suffisants).

L'ensemble des endpoints, leurs paramètres et les formats de retour sont consultables via la documentation dédiée au format Swagger.

Réponses HTTP

Chaque requête que vous envoyez à l'API vous gratifie d'une réponse. Cette dernière est composée d'un code de statut HTTP et du contenu de la réponse en elle-même.

Codes de statut

Un code de statut HTTP est un code numérique standardisé (consulter la liste des codes HTTP) indiquant comment votre requête a été intéprétée par le serveur.

Contenu de la réponse

Le contenu des réponses est formaté en JSON (Content-Type: application/json). D'une manière générale, on peut considérer que les opérations de consultation (GET) retournent une structure qui leur est propre (vous comprendrez aisément que la consultation d'un Véhicule et d'un Point d'intérêt retournent des informations structurées différemment). Le détail peut être consulté ici.

Concernant les opérations d'écriture (création via POST, modification via PUT, suppression via DELETE) et les retours d'erreur, Les réponses respectent le format suivant :

{
  "code": code_HTTP,
  "message": Message standard ou précision sur l'erreur recontrée.
}

code Code numérique identique au code de statut HTTP.
message Une chaîne de caractères apportant des précisions sur le retour ou la nature de l'erreur.

Réponses courantes

Vous trouverez dans cette section les réponses les plus courantes que vous pourriez être ammené à rencontrer en exploitant l'API SuiviDeFlotte.net.

Succès (codes 2xx)

Les codes HTTP 200 indiquent une opération réalisée avec succès.

• 200 "OK". Réponse indiquant que votre requête s'est déroulée normalement. Selon le contexte, le retour peut être un message générique ou une structure spécifique.
• 201 "Created". La demande de création (POST) s'est bien passée. La partie message contient l'identifiant de la ressource fraîchement créée.

Erreur du client web (codes 4xx)

Les codes HTTP 400 indiquent que les informations que vous avez transmises ne permettent pas de réaliser l'opération demandée.

• 400 "Bad Request". La syntaxe de votre requête est erronée.
• 401 "Unauthorized". Une authentification est nécessaire pour accéder à la ressource. Voir Authentification.
• 403 "Forbidden". Le serveur a compris la requête, mais refuse de l'exécuter. Contrairement à l'erreur 401, s'authentifier ne fera aucune différence. Sur les serveurs où l'authentification est requise, cela signifie généralement que l'authentification a été acceptée mais que les droits d'accès ne permettent pas au client d'accéder à la ressource.
• 404 "Not Found". La ressource que vous cherchez à manipuler n'existe pas ou vous interrogez un Endpoint qui n'éxiste pas.
• 405 "Method Not Allowed". Vous vous addressez à un Endpoint en n'utilisant pas la bonne méthode HTTP.
• 422 "Unprocessable Entity". Les paramètres fournis ne sont pas interprétables. Celà indique typiquement lors d'opérations de création ou d'édition que les données transmises ne respectent pas le format imposé (par exemple, on atttend un email et la chaine fournie ne respecte pas ce format). Dans ce cas, le message est structuré de la manière suivante :
  

  Status: 422 Unprocessable Entity
  {
    "code": 422,
    "message": {
      "name" : ["The name field is required."],
      "email" : ["The email must be a valid email address.", "The email may not be greater than 100 characters."],
      ...
    }
  }

  Dans cet exemple, le champ name n'a pas été spécifié alors qu'il est obligatoire et le champ email n'a pas un format valide et dépasse 100 caractères alors qu'il ne devrait pas.

Erreur du serveur (code 5xx)

Les codes HTTP 500 indiquent que l'API n'est pas parvenu à réaliser l'opération demandée.

• 500 "Internal Server Error". Une erreur interne s'est produite, vous n'êtes pas supposé rencontrer ce type d'erreur.

Filtrage des résultats

La plupart des opérations de lecture (GET) faisant référence à une ressource (par exemple, récupérer la liste de POI, des véhicules, des alertes, etc.) peuvent être filtrés grâce à des paramètres supplémentaires passés dans l'URL (Query String).

Nous attirons votre attention sur le fait qu'il sagit d'un système de filtrage simple et en aucun cas d'un système complet de requêtage. L'objectif est de vous proposer des outils facile d'utilisation vous permettant d'alléger les réponses de l'API : pourquoi récupérer les 10 champs d'une ressource si vous n'en avez besoin que de 3 dans votre application ?

Query string	Détails
fields=field1,field2,...	Limite les champs retournés à ceux spécifiés (SELECT field1, field2).
equals=field:value,...	Recherche (de manière stricte) les ressources répondant au(x) critère(s) : WHERE field=value.
like=field:value,...	Recherche (de manière souple) les ressources répondant au(x) critère(s) : WHERE field LIKE "%value%".
sort=field2,-field2	Tri le résultat sur les champs spécifiés. Un nom de champ préfixé par "-" (le signe moins) est trié en DESC et un nom de champ sans préfixe est trié en ASC : ORDER BY field ASC|DESC.
page=int	Lorsque la réponse est une liste et qu'elle est paginée, ce paramètre permet de demander une page spécifique.
perpage=int	Nombre d'éléments à afficher par page (15 par défaut).

Remarques

• Si ces paramètres sont spécifiés mais invalides (champ n’existant pas pour la ressource demandée, numéro de page erroné, etc. une erreur HTTP 422 (Unprocessable Entity) est renvoyée.
• Si les paramètres equals et like sont utilisés conjointements, un ET logique est appliqué.
• Il n'est pas possible de spécifier plusieurs fois le même champs (ex: ...?equals=name:jean,name:jacques). Les filtrages de type ET ou OU ne sont pas gérés.
• Les paramètres décrits dans le tableau ci-dessus sont considérés comme réservés, cela signifie que fields, equals, like, sort, page et perpage ne peuvent pas être utilisés comme paramètres que ce soit en GET, en POST ou dans un message JSON dans le corps de la requête.

Limitations

Afin de conserver un temps de réponse optimal et pour éviter les abus, vous êtes limité à 60 appels par minute et par utilisateur. Vous trouverez dans les réponses émise par l'API les en-têtes HTTP X-RateLimit-Limit et X-RateLimit-Remaining qui vous indiquent repectivement la limitation par minutes (en l'occurence 60) et le nombre d'appels restants.

Si jamais vous dépassez la limite fixée (X-RateLimit-Remaining = 0), vous recevez une erreur HTTP 429 "Too Many Attempts" accompagné d'un en-tête HTTP X-RateLimit-Reset contenant un timestamp unix indiquant quand vous pourrez à nouveau exploiter l'API.