- 1. Qu'est-ce que la brique API?
- 2. Configurer la connexion API
- 3. Configurer la brique API depuis le formulaire
- 4. Cas pratiques
Une API (Application Programming Interface) est un ensemble de règles et de protocoles qui permettent à différentes applications logicielles de communiquer et d'échanger des données entre elles. En d'autres termes, une API fait office d'intermédiaire entre deux applications ou services. Elle définit comment ces systèmes peuvent interagir et partager des informations de manière sécurisée.
1. Qu'est-ce que la brique API?
La brique Api permet aux administrateurs de créer calls API en cours d’intervention. Vous pourrez ainsi envoyer des informations et en recevoir, afin qu’elles soient affichées dans vos rapports de fin d’intervention.
2. Configurer la connexion API
2.1. Autoriser le rôle utilisateur
- Rendez vous dans section rôle de votre utilisateur. Au niveau de la section “Integration”, activez l’option: Afficher le menu d’intégration.
Une fois cette option est cochée, une nouvelle section sous le nom de “Intégration” apparaitra dans le menu principale d’ermeo.
2.2. Créer une nouvelle connexion
- Cliquez sur le bouton : Nouvelle connexion
- Remplissez les information générales liées à l’API à laquelle vous souhaitez vous connecter (Nom, Base URL).
- Sélectionnez votre authentification.
Vous aurez 4 choix possibles :
- Sans authentification (None): vous pourrez directement valider votre connexion.
- Authentification Basic: Vous devrez renseigner un utilisateur et un mot de passe en deuxième étape.
- Header auth: Vous renseignerez un à plusieurs headers avec leur clé et valeur associée.
- Query Parameters: Comme pour header auth, vous devrez renseigner vos paramètres url, avec leur clé et valeur associée.
- La base url doit terminer avec un “/” à fin, si ce n’est pas le cas, il s’ajoutera automatiquement.
- Si vous avez des query params dans l’url, ces derniers devront être renseignés dans votre path lorsque vous configurerez la requête dans le studio.
2.2. Modifier la connexion
Vous pouvez modifier votre connexion si vous le souhaitez en cliquant sur ”Modifier” sur la connexion choisie.
Dans le cas d’une modification d’une connexion d’authentification Basic, le mot de passe est uniquement à renseigner si vous souhaitez le changer.
- Le type d’authentification n’est pas modifiable.
- Veuillez noter que toute modification d’une connexion déjà utilisée avec des briques API impactera vos formulaires.
2.3. Supprimer la connexion
Vous pouvez supprimer une connexion API créée.
Si cette connexion est utilisée dans la configuration de vos briques API, vous aurez la mention du nombre de brique(s) utilisant cette connexion.
3. Configurer la brique API depuis le formulaire
3.1. Configurer la requête API
- Rendez vous dans le studio d’édition de votre formulaire.
- Glissez puis déposez la brique API qui se trouve dans la section “Workflows”
- Dans le paramétrage de la brique, commencez la configuration de votre requête
- Sélectionnez une connexion configurée dans votre page “Intégrations”.
- Renseignez la méthode choisie : POST, GET, PUT, DELETE
- Vous pourrez ensuite compléter le path de votre url, et y ajouter si besoin des tags présents dans votre formulaire. Si vous avez des query params, ils seront à renseigner dans votre path
- Choisissez le format contenu dans la requête entre JSON et XML
- Vous pouvez renseigner des headers dans votre requête, ainsi qu’un body. La valeur d’un header et le body pourront contenir des tags
- En étape 4, choisissez le format de réponse attendu entre JSON et XML
- Enfin, vous pouvez testez votre requête et sauvegarder sa création :
- Si vous avez mis des tags dans votre requête, et que vous souhaitez la tester, vous devrez renseigner une valeur à chacun des tags en cliquant sur le bouton “Renseigner des tags”
- Vous pouvez également valider la création de votre requête sans la tester. En revanche, nous vous recommandons de tester, afin d’éviter toute erreur de configuration.
- Vous pouvez afficher sur vos rapports les données retournées par l’API en cours d’intervention
- Veuillez noter que pour fonctionner, l’utilisateur ayant une brique API sans son formulaire devra avoir une connexion internet
- Il n’est pas possible d’utiliser les tags suivants dans votre requête api : Photo, Signature, Schéma et Fichier
- Quand le tag d’une brique choix multiple est utilisée dans le path de votre url, seule la première valeur va être récupérée parmi les différents choix retournés par l’api.
3.2. Configurer votre tag API pour afficher la réponse à votre requête dans une autre brique
3.2.1. Le format de votre API path
Le format à renseigner dans une valeur par défaut d’une autre brique afin d’afficher le résultat de votre requête est le suivant : ##api_tag:apipath()##
- api_tag = L’id de votre brique API
- Entre les () : Vous renseignez la réponse souhaitez par l’api
3.2.2. Paramétrer votre tag en fonction de la réponse souhaitée
- Dans une valeur par défaut, un titre, une description, vous pouvez sélectionner le tag de votre brique API
- Une fois sélectionné, cliquez sur le petit crayon à droite sur le tag :
- Une modale de configuration s’ouvre et vous invite à renseigner votre path :
- Vous pouvez ensuite prévisualiser ce que vous avez paramétrer dans le studio et le publier :
- Vous pouvez utiliser ce tag API dans votre valeur par défaut, votre titre et description
- La brique API doit avoir une condition d’affichage si vous souhaitez qu’elle soit masquée et que le click soit automatisé
- Il n’est pas possible d’utiliser un tag API dans la valeur par défaut d’une photo et d’un fichier
4. Cas pratiques
4.1. Collecter des informations externes en cours d’intervention
Cet exemple décrit un scénario où vous allez récupérer le nom d’une commune en se basant sur le code postal qui va être saisi durant l’intervention.
L’objectif de la brique api dans ce cas, est de récupérer le nom de la commune depuis cette source externe.
- Premièrement, créez votre connexion depuis la section “Intégrations”.
Pour ce test, vous pouvez utiliser la connexion: https://geo.api.gouv.fr/ en choisissant le type “Sans authentification” comme type d’authentification.
- Une fois votre formulaire est créé, glissez puis déposez :
- Une brique nombre (qui va servir à définir le code postal)
- La brique API avec le logo HTTP (la brique api qui va récupérer le nom de la commune)
- Une brique texte (qui affichera le nom de la commune)
- Afin de paramétrer la requête de votre brique api, cliquez sur “Configurer la requête”.
- Sélectionnez la connexion que vous avez créé auparavant.
- Choisissez “GET” comme méthode HTTP
- Copiez l’URL suivant: communes?codePostal=tag de la brique nombre.
Par exemple: communescodePostal=##number_jXKVLmOK##
Dans cet exemple, nous n’avons pas besoin de remplir le body de la requête. Vous pouvez passer directement à l’étape de test de la requête.
- Afin de vérifier si la requête fonctionne correctement, saisissez un code postal via le bouton “Renseignez des tags” puis cliquez sur “tester”.
- Si votre test est valide, cliquez sur “Valider”.
- Vous pouvez désormais prévisualiser le résultat de votre paramétrage. La vidéo ci dessous retranscrit les étapes suivies de ce cas pratique.
4.2 Planifier une intervention automatiquement sur Ermeo durant la réalisation d’une autre intervention
4.2.1. Créer votre connexion dans votre page intégration
- L’url que vous allez utiliser est la suivante : https://api.ermeo.com/
- Sélectionner le type d’authentification “None“.
- Pour le moment, l’authentification oauth2 n’est pas disponible, c’est pour cela que nous sélectionnons sans authentification. A termes, vous sélectionnerez “Oauth2” (Disponible en septembre)
4.2.2. Configuration dans le studio
- Configurez votre formulaire et déposez la brique API où vous souhaitez que l’intervention soit créée comme dans la vidéo ci-dessous :
- Masquez votre brique si vous ne souhaitez pas qu’elle soit visible une fois le formulaire publié.
- Sur l’application, la création de l’intervention est transparente pour l’opérateur terrain.
- Dans votre onglet intervention, la nouvelle intervention créée par l’opérateur.
Vous pouvez utiliser l’api souhaitez en fonction de vos cas d’usages. Voici quelques exemples :
- L’api de votre agenda pour créer un événement dans votre propre agenda professionnel
- Une API de météo si vos interventions ne peuvent se faire qu’en fonction de certaines conditions météorologique.
- Une API qui vous génère un identifiant unique d’intervention afin qu’il soit présent dans vos rapports.
- L’api d’une IA pour qu’elle identifie une anomalie…