Documentation API Optibilan
L’API REST v1 donne accès aux clients, bilans, nutrition, sport et santé, avec des webhooks signés pour réagir en temps réel. Ce document présente ce qui est public et vérifiable. Le schéma OpenAPI complet, les signatures d’authentification détaillées et les quotas exacts sont communiqués avec l’accès API.
Authentification et permissions
L’authentification repose sur des clés API scopées : chaque clé porte une liste explicite de permissions, et les requêtes sont refusées si l’action demandée n’y figure pas. Ce modèle évite qu’une intégration de lecture obtienne un accès en écriture par simple erreur de configuration.
Créer une clé API scopée
Les clés sont générées dans votre espace et limitées aux permissions nécessaires à votre usage. Une clé de lecture seule ne peut pas écrire, même si l’endpoint le permet.
Appeler l’API REST v1
Une seule base, des ressources REST classiques, des réponses en JSON. Le schéma complet est décrit en OpenAPI 3.1 et communiqué avec l’accès API.
Recevoir les webhooks
Huit événements signés couvrent la vie d’un dossier : création, bilan, nutrition, badges et appels. Chaque requête reçue est signée et horodatée.
Ressources disponibles
L’API v1 couvre les sept familles de ressources suivantes. Les permissions indiquées sont celles utilisées le plus souvent par les intégrations ; la liste exacte est attachée à chaque clé.
| Ressource | Contenu | Permissions typiques |
|---|---|---|
| Clients | Création, lecture, mise à jour et recherche de clients, avec les permissions de l’utilisateur authentifié. | clients:read, clients:write |
| Bilans | Bilan de suivi, mesures et évolution des indicateurs et historique des points d’étape. | bilans:read, bilans:write |
| Nutrition | Plans, listes de courses, habitudes et compléments documentés. | nutrition:read, nutrition:write |
| Sport | Programmes, séances, progression et données d’entraînement. | sport:read, sport:write |
| Santé | Biomarqueurs, habitudes de vie et remontée de données depuis un appareil tiers. | sante:read, sante:write |
| Webhooks | Abonnement aux événements, configuration des URLs de réception et rejeu d’événements. | webhooks:read, webhooks:write |
| Administration | Utilisateurs, rôles, permissions granulaires et audit, sur les offres Studio et Cabinet. | admin:read, admin:write |
Remontée de données de santé
Les applications tierces qui disposent déjà de données mesurées (Apple Health, Oura, Garmin) les
transmettent au point d’entrée de synchronisation
POST /api/health-sync. Ce point
d’entrée est le point d’ancrage des automatisations n8n, Make et Zapier : récupération côté
partenaire, puis envoi vers Optibilan.
Webhooks signés
Huit événements couvrent la vie d’un dossier. Chaque notification est signée et horodatée, ce qui permet de rejeter toute requête qui ne proviendrait pas d’Optibilan. Parmi les plus utilisés :
- Client créé
- Bilan soumis
- Badge obtenu
- Nutrition mise à jour
- Appel en retard
- + + 3 autres événements
Environnement sandbox
L’environnement de test fournit des clés API de test, des données factices et un playground de navigation pour explorer la spec sans toucher aux dossiers réels. C’est l’espace recommandé pour valider une intégration avant sa mise en production, et pour tester la reprise sur erreur d’un webhook.
Clés de test
Des clés distinctes de celles de production, avec les mêmes scopes. Un test de permission se fait donc dans les mêmes conditions qu’en production.
Données factices
Des dossiers fictifs préchargés, sans donnée de santé réelle. Les parcours de bilan, de nutrition et de suivi sont identiques à ceux du produit.
Playground Swagger / Redoc
La spec OpenAPI 3.1 est explorable directement dans le navigateur : listes d’endpoints, schémas et exemples de charge utile.
Obtenir l’accès API
L’accès API s’active depuis votre espace, sur les offres Studio et Cabinet. L’activation ouvre l’espace développeur : clés scopées, spec OpenAPI 3.1, sandbox et journal des appels.