Observatoire National Ventilation
Guide d’utilisation pour l’accès éditeur

Création de compte éditeur
API Reference

L’Observatoire National Ventilation propose une API permettant l’intégration avec des logiciels tiers.

1. Création de compte éditeur

Pour pouvoir utiliser l’API de l’Observatoire, il est nécessaire de créer un compte Editeur.

Pour créer votre compte Editeur, rendez-vous sur l’Observatoire National Ventilation, cliquez sur le bouton “Connexion”, puis en bas de la page, cliquez sur le bouton “Créer un compte éditeur”.

Remplissez ensuite le formulaire en renseignant toutes les informations demandées. Vous recevrez alors un email généré automatiquement par l’Observatoire National Ventilation pour valider la création de votre compte éditeur et choisir votre mot de passe pour sécuriser l’accès à votre compte.

2. API Reference

L’API de l’Observatoire National Ventilation est une API REST.

i. Authentification logiciel – Observatoire National Ventilation

L’API de l’Observatoire National Ventilation utilise des clés secrètes pour authentifier les requêtes provenant des logiciels.

Pour obtenir votre clé secrète, connectez-vous à votre compte éditeur sur l’Observatoire et rendez-vous dans le menu Compte > Mon application

Cliquez alors sur le bouton “Générer la clé secrète” pour obtenir la clé secrète de votre application.

Attention: c’est la seule fois où votre clé secrète sera affichée. Veillez à la sauvegarder immédiatement de manière sécurisée. Il ne sera ensuite plus possible de l’afficher.

L’authentification est réalisée via HTTP Basic Auth. Dans les requêtes envoyées à l’API, spécifiez votre nom de logiciel comme nom d’utilisateur Basic Auth et votre clé secrète comme mot de passe.

ii. Comptes opérateurs

Vous devez spécifier le compte de l’opérateur qualifié pour lequel les requêtes sont effectuées. Ajoutez le Header Account à vos requêtes en spécifiant l’identifiant du compte.

Nota : Pour l’obtention de l’identifiant du compte, se rapprocher de l’opérateur reconnu. L’utilisateur doit avoir activé son compte sur l’Observatoire.

Vous devez spécifier la “authorization-key”, la clé utilisée pour identifier l’opérateur et le logiciel qu’il utilise en ajoutant le header authorization-key à vos requêtes. Cette clé est générée par l’ONV lors de l’autorisation et doit être sauvegardée sur le logiciel utilisé.

Nota : Si le logiciel ne dispose pas encore d’autorisation pour cet utilisateur, ce header doit quand même être présent avec la valeur “”. Si une nouvelle demande est réalisée pour un même utilisateur, son authorization-key sera différente

Vous pouvez utiliser la route /ext/ventilation-reports/test-access pour vérifier l’autorisation d’accès de votre logiciel à un compte utilisateur.

curl --location "https://www.observatoire-national-ventilation.developpement-durable.gouv.fr/ext/ventilation-reports/test-access" -u "nom_logiciel:cle_secrete" --header "Account: user" --header "Accept-Language: fr" --header "SoftwareVersion: 1.0" --header "authorization-key;" --header "Accept: application/json" -v

L’utilisateur (opérateur reconnu) doit avoir autorisé votre logiciel à effectuer des actions sur son compte.

Lors de la première requête pour un compte, l’API retourne une réponse 401 et fournit un header GrantAccessUrl qui contient comme valeur une URL à présenter à l’opérateur pour lui permettre d’autoriser l’accès de votre application à son compte. Vous pouvez également trouver l’en-tête authorization-key, qui doit être enregistrée par le logiciel utilisant l’API et envoyée dans l’en-tête pour toutes les demandes ultérieures de l’opérateur.

Exemple :

curl --location "https://www.observatoire-national-ventilation.developpement-durable.gouv.fr/ext/ventilation-reports/test-access" -u "nom_logiciel:cle_secrete" --header "Account: user" --header "Accept-Language: fr" --header "SoftwareVersion: 1.0" --header "authorization-key;" --header "Accept: application/json" -v
HTTP/1.1 401 Unauthorized`
Server: nginx/1.21.3`
Date: Thu, 07 Jul 2022 10:28:04 GMT`
Content-Length: 0`
Connection: keep-alive`
Expires: 0`
GrantAccessUrl: http://www.observatoire-national-ventilation.developpement-durable.gouv.fr/software-authorization/259/grant-access`
authorization-key: dsWYDvnkvU8jHOD2yClv`

{
  "timestamp" : "2024-07-11T12:57:48.807+00:00",
  "status" : 401,
  "error" : "Unauthorized",
  "path" : "/ext/ventilation-reports/test-access"
}

En ouvrant l’url GrantAccessUrl dans son navigateur, l’opérateur s’authentifie et peut ensuite valider ou refuser la demande d’accès du logiciel à son compte.

Après validation de l’accès, votre application peut effectuer des requêtes pour le compte de cet opérateur :

curl --location "https://www.observatoire-national-ventilation.developpement-durable.gouv.fr/ext/ventilation-reports/test-access" -u "nom_logiciel:cle_secrete" --header "Account: user" --header "Accept-Language: fr" --header "SoftwareVersion: 1.0" --header "authorization-key: dsWYDvnkvU8jHOD2yClv" --header "Accept: application/json" -v
HTTP/1.1 200 OK

iii. Environnement de test

Pour tester l’intégration de votre logiciel avec l’Observatoire National Ventilation, trois utilisateurs de test ont automatiquement été créés lors de la création de votre compte éditeur.

Login
nomDuLogiciel_test_pending	utilisateur n’ayant ni validé ni approuvé l’accès de votre logiciel à son compte
nomDuLogiciel_test_accepted	utilisateur ayant accepté l’accès de votre logiciel à son compte
nomDuLogiciel_test_refused	utilisateur ayant refusé l’accès de votre logiciel à son compte

nomDuLogiciel est à remplacer par le nom de votre logiciel renseigné lors de la création de votre compte.

Exemple : si votre logiciel s’appelle “MyVentilationSoftware”, l’utilisateur de test ayant accepté l’accès de votre logiciel à son compte a pour login “MyVentilationSoftware_test_accepted”.

Nota : Vous devez définir la valeur de authorization-key : MO9jxDxlqYWbVERjprkg dans toutes les requêtes pour ces trois comptes de test.

Vous pouvez tester l’intégration de votre logiciel en utilisant les routes de l’API avec ces trois utilisateurs. Les éventuelles données publiées pour ces utilisateurs n’auront pas d’impact sur les données utilisées pour les statistiques de l’Observatoire National Ventilation.

curl https://www.observatoire-national-ventilation.developpement-durable.gouv.fr/ext/test-access -u MyVentilationSoftware:cle_secrete -H "Account:MyVentilationSoftware_test_accepted" -H "authorization-key:MO9jxDxlqYWbVERjprkg" --header "Accept-Language: fr" --header "SoftwareVersion: 1.0" --header "Accept: application/json" -v
HTTP/1.1 200 OK

iv. API

La documentation détaillée des actions disponibles via l’API est disponible sur cette page de l’Observatoire National Ventilation.

HAUT DE PAGE

Observatoire National Ventilation Guide d’utilisation pour l’accès éditeur