Récupérer les données de vos zones RE2020 via l’API Emersus

Vous souhaitez récupérer automatiquement les informations de vos zones RE2020 depuis Emersus, par exemple pour les exploiter dans votre propre outil de reporting, sans passer par l’interface web ?

Emersus met à disposition un point d’entrée API permettant de consulter les données de vos zones. Cet accès est ouvert aux comptes clients actifs, sans option API payante spécifique pour l’endpoint des zones.

Ce guide explique comment vous connecter à l’API, consulter la documentation disponible et récupérer les données de vos zones.

Prérequis

Pour utiliser cet endpoint, vous devez disposer d’un compte Emersus actif.

Vous pouvez utiliser les mêmes identifiants que ceux utilisés pour vous connecter à l’application Emersus : https://app.emersus.io

Aucune activation spécifique n’est nécessaire pour accéder à l’endpoint des zones :

• il n’est pas nécessaire d’être administrateur ;
• il n’est pas nécessaire de disposer d’une option API spécifique ;
• l’accès est possible pour tout utilisateur authentifié.

Vous pouvez tester les appels API avec un outil comme curl, Postman ou Insomnia.

Étape 1 - Se connecter à l’API

L’API fonctionne avec un jeton d’authentification, aussi appelé token.

Ce jeton permet d’identifier l’utilisateur à chaque appel API. Il doit donc être récupéré avant d’appeler les endpoints de données.

Pour récupérer un jeton, utilisez l’appel suivant : curl -X POST https://app.emersus.io/api_client/reporting-stream/login/ \  -H "Content-Type: application/json" \  -d '{"email": "vous@votre-entreprise.com", "password": "VotreMotDePasse"}'

La réponse attendue est de la forme suivante : {  "id": "12345",  "token":"eyJhbGciOiJIUzI1NiIs..." }

Le champ à utiliser pour les appels suivants est le champ token.

Le jeton est valable pendant 3 jours.

Une fois ce délai dépassé, il faut simplement rejouer l’appel de connexion pour obtenir un nouveau jeton.

À noter également : un seul jeton par compte est valable à la fois.

Cela signifie que si vous vous reconnectez à l’application ou à l’API avec le même compte, l’ancien jeton est invalidé.

Pour un usage automatisé, il est donc recommandé de :

• réutiliser le même jeton pendant ses 3 jours de validité ;
• éviter de relancer une connexion à chaque appel API ;
• demander un compte de service à Emersus si vous avez besoin d’un usage automatisé stable.

Utiliser le jeton dans les appels API

Pour tous les appels suivants, le jeton doit être ajouté dans l’en-tête Authorization.

Le format attendu est le suivant : curl https://app.emersus.io/api/results/zones/ \  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIs..."

Point important : le préfixe à utiliser est bien JWT.

Il ne faut pas utiliser le préfixe Bearer, souvent utilisé dans d’autres API.

Format attendu : Authorization: JWT <votre_token>

Étape 2 -Se déconnecter

Il n’existe pas d’appel de déconnexion spécifique pour révoquer le jeton à la demande.

Le jeton s’expire automatiquement au bout de 3 jours.

Pour ne plus l’utiliser, il suffit donc de le supprimer de votre outil, de votre script ou de votre variable d’environnement. Il deviendra automatiquement inactif à l’échéance de sa durée de validité.

Étape 3 - Consulter la documentation interactive de l’API

La documentation de l’API est disponible via Redoc, à partir du schéma OpenAPI.

Deux URLs sont utiles :

La documentation affiche alors le détail des endpoints accessibles à votre compte, avec les paramètres attendus, les formats de réponse et les exemples disponibles.

Données accessibles avec un compte standard

Avec un compte standard, vous avez accès aux endpoints suivants.

Récupérer la liste des zones

Pour récupérer la liste de vos zones, utilisez l’appel suivant : curl https://app.emersus.io/api/results/zones/ \  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIs..."

La liste est paginée.

Par défaut, l’API renvoie 20 résultats. Le maximum est de 100 résultats par appel.

Vous pouvez utiliser les paramètres limit et offset pour naviguer dans les résultats.

Exemple avec une limite de 100 résultats : curl "https://app.emersus.io/api/results/zones/?limit=100" \  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIs..."

Exemple pour récupérer les résultats suivants : curl "https://app.emersus.io/api/results/zones/?limit=100&offset=100" \  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIs..."

Récupérer le détail d’une zone

Une fois l’identifiant d’une zone récupéré dans la liste, vous pouvez consulter le détail de cette zone avec l’endpoint suivant : curl https://app.emersus.io/api/results/zones/{id}/ \  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIs..."

Remplacez {id} par l’identifiant réel de la zone.

Exemple : curl https://app.emersus.io/api/results/zones/12345/ \  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIs..."

Points d’attention

Avant d’intégrer l’API dans un outil automatisé, vérifiez les points suivants :

• le jeton doit être transmis avec le préfixe JWT ;
• le préfixe Bearer ne doit pas être utilisé ;
• le jeton est valable 3 jours ;
• un seul jeton par compte est valable à la fois ;
• une nouvelle connexion avec le même compte invalide l’ancien jeton ;
• la liste des zones est paginée ;
• le nombre maximal de résultats par appel est de 100.

Aller plus loin

Si vous souhaitez accéder à davantage de données pour vos besoins de reporting, vous pouvez contacter votre interlocuteur commercial Emersus ou écrire à : hello@emersus.io

L’équipe Emersus pourra vous orienter sur les possibilités d’accès aux données de reporting via l’API.