Accès et droits

Votre application

Treats enregistre votre application. Elle reçoit :

• un identifiant (client_id, de la forme papp_…) et un secret (client_secret). Le secret n’est montré qu’une fois. Treats n’en garde qu’une empreinte et ne peut pas vous le renvoyer : en cas de perte, demandez-en un nouveau ;
• la liste maximale des droits qu’elle peut demander, choisie avec vous selon votre service ;
• un environnement. Une application de recette (SANDBOX) ne peut être connectée qu’à une organisation de test, qui n’envoie aucun email ni SMS. Une application de production (LIVE) peut être connectée à toute organisation cliente.

Rotation du secret. Treats peut émettre un nouveau secret sans couper l’ancien : les deux fonctionnent pendant 24 heures, le temps de déployer le nouveau. Un secret compromis est retiré tout de suite, et les jetons émis avec lui tombent avec lui.

Suspension. Treats peut suspendre une application (incident, fin de contrat). Ses jetons sont refusés dès l’appel suivant.

L’autorisation d’une organisation

Chaque organisation cliente (une clinique, ou un groupe de cliniques) autorise votre application. Un administrateur de l’organisation choisit :

• les sites ouverts à votre application. « Tous les sites » inclut ceux que l’organisation ouvrira plus tard. Un administrateur ne peut ouvrir que les sites dont il a lui-même la charge ;
• les droits accordés, parmi ceux que Treats a ouverts à votre application.

L’autorisation se donne une fois par organisation. L’organisation peut la modifier ou la retirer quand elle veut : le retrait coupe l’accès immédiatement, jetons compris. Elle voit aussi le journal de vos appels.

À l’autorisation, Treats crée un utilisateur technique « Intégration, nom de votre application ». Il signe chacune de vos écritures dans le logiciel et dans l’historique (« Doctolib a déplacé le RDV »). Personne ne peut s’y connecter et il n’apparaît dans aucune liste d’équipe.

Le jeton

POST /oauth/token échange l’identifiant et le secret contre un jeton, pour une organisation (organization_id). La norme est OAuth 2, flux client_credentials : les bibliothèques OAuth courantes savent le demander. Les identifiants passent dans le corps du formulaire ou en HTTP Basic.

• Le jeton vaut 60 minutes. Réutilisez-le jusqu’à son expiration.
• Il est relu à chaque appel. Un droit retiré, un site retiré, une autorisation retirée ou une application suspendue s’appliquent à l’appel suivant, sans attendre l’expiration.
• Il est lié à une organisation. Pour travailler avec dix cliniques, votre serveur tient dix jetons.
• Il n’ouvre que /api/partner/v1. Un jeton du logiciel ou une clé API de clinique y sont refusés, et votre jeton est refusé partout ailleurs.

GET /me dit ce qu’ouvre le jeton : organisation, sites, droits effectifs.

Les droits

Chaque route exige un droit. Appelée sans lui, elle répond 403 SCOPE_MISSING. La référence liste, droit par droit, toutes les routes qu’il ouvre.

Droit	Ce qu’il ouvre
org:read	Sites, horaires d’ouverture, jours de fermeture, salles, équipe (sans email ni téléphone), espèces et races.
agenda:read	Types et sous-types de rendez-vous, rendez-vous, créneaux libres, motifs d’annulation, salle d’attente, notes d’appel, tâches d’équipe.
agenda:write	Créer, déplacer, annuler (motif obligatoire) un rendez-vous, enregistrer l’arrivée d’un patient ; créer et traiter les notes d’appel et les tâches d’équipe.
clients:read	Lire et rechercher les clients, contrôler un doublon.
clients:write	Créer et modifier un client.
patients:read	Lire et rechercher les animaux, l’historique de leurs poids.
patients:write	Créer et modifier un animal.
consultations:read	Lire les consultations, leurs modules, les définitions des modules et l’historique médical d’un animal.
consultations:write	Ouvrir une consultation, remplir ses modules, y ajouter une note interne.
consultations:notes	Lire les notes internes non confidentielles d’une consultation.
documents:read	Lire et télécharger les documents d’un animal ou d’une consultation.
documents:write	Déposer un document PDF sur la fiche d’un animal.
catalog:read	Lire le catalogue d’actes et de produits, au prix du site.
billing:read	Lire les factures, les avoirs, les règlements, et leurs PDF.
prescriptions:read	Lire les ordonnances signées et leurs PDF.
lab:write	Laboratoire : lire les analyses demandées à votre service, déposer les résultats et leurs comptes rendus.
imaging:write	Imagerie : lire les examens demandés à votre service, déposer les images et les comptes rendus.
webhooks	Déclarer l’adresse des notifications, lire et rejouer les envois.

Ce qu’aucun droit ne permet

Aucun droit ne permet de valider une consultation, de signer une ordonnance, d’émettre, d’annuler ou d’encaisser une facture, de fusionner ou de supprimer une fiche, ou de déclarer un animal décédé. Ces gestes restent à l’équipe de la clinique.

Un service de laboratoire ou d’imagerie est rattaché à son fournisseur chez Treats : il ne voit que les examens demandés à ce fournisseur.

Les sites et ce que vous voyez

Toute lecture se limite aux sites ouverts par l’autorisation. Une ressource d’un autre site répond 404, jamais 403 : l’API ne dit pas qu’elle existe ailleurs.

Quand l’organisation n’a ouvert que certains sites, les clients visibles sont ceux créés sur ces sites, avec leurs animaux. Un client créé sur un autre site du groupe reste invisible, même s’il vient parfois sur un site ouvert. Tout identifiant de client ou d’animal reçu (dans le chemin, un filtre ou un corps) passe par cette règle : hors périmètre, la réponse est 404 CLIENT_NOT_FOUND ou 404 PATIENT_NOT_FOUND.

Quand l’organisation a ouvert plusieurs sites, chaque écriture doit dire sur quel site elle porte : paramètre site_id ou en-tête Treats-Site-Id. Sans eux, l’écriture répond 400 SITE_ID_REQUIRED. Avec un seul site ouvert, il est implicite.