API partenaires · v1
Référence de l’API partenaires
Toutes les opérations de /api/partner/v1, par domaine. Pour chacune : le droit exigé, les paramètres, le corps, la réponse champ par champ, les erreurs possibles et un exemple d’appel réel. La liste des routes et leurs droits sont lus sur le serveur ; chaque description est vérifiée contre de vraies réponses.
Opérations
84
72 chemins
Domaines
14
Droits
18
accordés par la clinique
Exemples réels
82
sur 84 opérations
Appeler l’API.Un jeton par organisation, valable 60 minutes.
- Production :
https://app.treats.vet/api/partner/v1· recette :https://preprod.treats.vet/api/partner/v1 - Identifiants UUID, instants ISO 8601 UTC, montants en centimes, listes
{items, nextCursor}: conventions Idempotency-Keyobligatoire sur tout POST, erreurs en français dans une enveloppe unique : erreurs et limites
Domaines.Ce que l’API permet, domaine par domaine.
Accès2 opérationsObtenir un jeton pour une organisation qui a connecté l'application, puis lire ce que ce jeton ouvre : l'organisation, les sites et les droits effectifs. Le jeton vaut 60 minutes ; réutilisez-le jusqu'à son expiration plutôt que d'en demander un à chaque appel.Organisation8 opérationsLire les référentiels de l'organisation connectée : ses sites (coordonnées, horaires d'ouverture, jours fériés), son équipe, ses salles, les espèces et races qu'elle propose. Toutes ces routes exigent le droit `org:read` et sont en lecture seule. Ce sont des listes courtes, rendues en une seule réponse : `nextCursor` vaut toujours `null`. Elles ne voient que les sites que l'organisation a ouverts à l'application ; un autre site répond `404 SITE_NOT_FOUND`, jamais `403`.Clients5 opérationsLire, rechercher, créer et modifier les clients (propriétaires) d'une organisation, et vérifier un doublon avant une création. Un client appartient à l'organisation entière, pas à un site ; il garde son site d'origine (`siteId`), le site où sa fiche a été créée.
Règle de visibilité, commune à toute l'API : une organisation qui a ouvert tous ses sites vous montre tous ses clients. Une organisation qui ne vous a ouvert que certains sites vous montre seulement les clients nés sur ces sites (et leurs animaux), même si un client né ailleurs vient se faire soigner sur un site ouvert. Hors de ce périmètre, tout répond `404 CLIENT_NOT_FOUND`, jamais `403`.
Brouillon seulement : l'API ne fusionne, ne désactive ni ne supprime aucun client, et ne donne jamais d'accord de contact (email, SMS, courrier) ; ces gestes restent à la clinique.Animaux5 opérationsLire, rechercher, créer et modifier l'identité des animaux (patients) d'une organisation, et lire leurs pesées. Un animal suit la visibilité de son propriétaire : vous le voyez si vous voyez son client (organisation entière si tous les sites vous sont ouverts, sinon client né sur un site ouvert) ; sinon `404 PATIENT_NOT_FOUND`.
Identité seulement : le dossier médical n'est pas exposé ici. L'API ne déclare pas de décès, ne transfère pas un animal à un autre propriétaire, ne fusionne ni ne supprime d'animal ; ces gestes restent à la clinique.Agenda12 opérationsLire et synchroniser l'agenda des sites ouverts à l'application, chercher des créneaux libres, prendre, déplacer, annuler un rendez-vous et pointer l'arrivée d'un animal. Lectures : droit `agenda:read` ; écritures : `agenda:write`. Toute prise ou tout déplacement de rendez-vous est jugé en politique stricte : la moindre contrainte non respectée (site fermé, vétérinaire hors planning ou absent, créneau pris, date passée…) refuse l'appel en `409 SLOT_CONFLICT`, même si la clinique accepte ce cas en simple avertissement dans son propre agenda. Une clinique qui n'a renseigné ni les horaires de ses sites ni le planning de ses vétérinaires ne peut donc recevoir aucun rendez-vous par l'API. L'application agit sous un utilisateur d'intégration à son nom : il apparaît comme créateur du rendez-vous, auteur de sa note, de son annulation et de l'arrivée.Notes d'appel et tâches7 opérationsConsigner un appel d'un client (demande de rendez-vous, question médicale, réclamation…) pour que l'accueil le traite, et créer des tâches pour l'équipe d'un site. Lectures : droit `agenda:read` ; écritures : `agenda:write`. L'application agit sous son utilisateur d'intégration, auteur des notes et des tâches qu'elle crée. Une tâche créée par l'API est toujours une tâche d'équipe ; les tâches personnelles des membres de l'équipe ne sont jamais visibles. Aucune note d'appel ni tâche ne se supprime par l'API, et ces écritures n'émettent pas de notification.Consultations10 opérationsOuvrir une consultation en brouillon, remplir ses modules cliniques (anamnèse, commémoratifs, examen général, diagnostic, comportement), ajouter une note d'équipe et lire l'historique clinique d'un animal. Un partenaire ne valide jamais une consultation, ne la déverrouille ni ne la supprime, et n'écrit ni acte, ni produit, ni ordonnance : ces gestes restent au vétérinaire, dans Treats. Les modules d'actes, la vaccination et les mesures (température, pression, glycémie) se lisent en texte seulement. Une consultation d'un site non ouvert à l'application répond `404`, jamais `403`.Documents6 opérationsLire les documents du dossier d'un animal ou d'une consultation (comptes rendus, ordonnances, certificats, fichiers déposés…), les télécharger, et déposer un PDF (compte rendu de laboratoire, d'imagerie…) dans le dossier d'un animal. Un document déposé par l'API naît interne : c'est la clinique qui décide de le montrer au propriétaire. Seuls les documents des sites ouverts à l'application sont visibles ; un autre répond `404`, jamais `403`. Aucun antivirus n'analyse les fichiers déposés : seuls le type déclaré et la signature PDF des octets sont vérifiés.Catalogue4 opérationsLire le catalogue de la clinique (actes et produits, appelés Treats dans l'application) avec le prix pratiqué par un site, l'arbre des catégories, et chercher un acte ou un produit par son nom. Lecture seule : aucune route ne crée ni ne modifie un article, une catégorie ou un prix. Seul le catalogue propre à l'organisation est visible, jamais le référentiel des centrales. Droit exigé : `catalog:read`.Facturation7 opérationsLire les factures émises, les avoirs et les encaissements des sites ouverts à l'application, avec leur PDF officiel. Lecture seule : un partenaire ne crée, ne modifie, n'émet, n'annule ni n'encaisse aucune facture, et ne crée aucun avoir ni paiement ; tout cela se fait dans l'application de la clinique. Les brouillons de facture et les pièces reprises d'un ancien logiciel qui ne sont pas des factures (devis, bons de livraison, factures provisoires) ne sont jamais exposés. Montants en centimes entiers, toujours avec leur devise ; les totaux d'une pièce sont ceux du document émis, jamais recalculés. Droit exigé : `billing:read`. Notifications associées : `invoice.issued`, `invoice.paid`, `payment.recorded`, `credit_note.issued`.Ordonnances3 opérationsLire les ordonnances signées par les vétérinaires des sites ouverts à l'application, leurs lignes et leur PDF officiel. Seules les ordonnances signées sont exposées, y compris celles annulées après signature ; un brouillon n'est pas une ordonnance tant que le vétérinaire ne l'a pas signée (article R.5141-111 du code de la santé publique), même s'il a été préparé ou validé par l'équipe. Lecture seule : l'API ne crée, ne modifie, ne signe ni n'annule aucune ordonnance. Droit exigé : `prescriptions:read`. Notification associée : `prescription.signed`.Laboratoire5 opérationsPour un laboratoire d'analyses : lire les commandes que les cliniques lui adressent, puis déposer les résultats structurés (lignes d'analyses, valeurs, unités, bornes, drapeaux) et leur compte rendu PDF. Treats rattache le résultat à la commande ou à l'animal par un identifiant sûr (commande, identifiant de l'animal, puce), jamais par le nom ; en cas de doute, le résultat attend dans la file « Résultats à rattacher » de la clinique. L'application doit avoir été rattachée par Treats au laboratoire qu'elle représente (droit `lab:write`) : elle ne voit que les commandes et les résultats de ce laboratoire, sur les sites ouverts par l'organisation.Imagerie3 opérationsPour un fournisseur d'imagerie (radiographie, échographie, PACS) : lire les demandes d'examen que les cliniques lui adressent, puis déposer les résultats (images JPEG ou PNG, compte rendu PDF, lien vers l'étude). Les fichiers entrent dans le dossier de l'animal et la consultation est prévenue. L'application doit avoir été rattachée par Treats au fournisseur qu'elle représente (droit `imaging:write`) : elle ne voit que les demandes adressées à ce fournisseur, sur les sites ouverts par l'organisation. L'API ne crée ni n'annule de demande : c'est la clinique qui les émet.Notifications7 opérationsRecevoir un appel signé (webhook) dès qu'une ressource que l'application a le droit de lire change, au lieu d'interroger l'API en boucle. Chaque application a UN point de réception (endpoint), commun à toutes les organisations qui l'ont connectée ; l'organisation de chaque événement est dans son corps. Le corps est mince (type, organisation, site, identifiant de la ressource) et ne porte aucune donnée personnelle : relisez la ressource sur l'API avec vos droits du moment. Toutes les routes de ce domaine exigent le droit `webhooks` ; recevoir un type exige en plus le droit de lecture de sa ressource.
Droits.Ce que chaque droit ouvre.
Treats fixe les droits qu’une application peut demander ; chaque organisation choisit ceux qu’elle accorde, et les sites. Une route appelée sans son droit répond 403 SCOPE_MISSING.