Démarrage rapide

Ce parcours suppose une application de recette déjà connectée à une organisation de test (voir Recette et mise en production). Vous avez reçu de Treats trois valeurs : l’identifiant de l’application, son secret et l’identifiant de l’organisation de test.

export TREATS="https://preprod.treats.vet/api/partner/v1"
export TREATS_CLIENT_ID="papp_…"
export TREATS_CLIENT_SECRET="…"
export ORGANIZATION_ID="…"

Le secret ne quitte jamais votre serveur. Il ne va ni dans une application mobile, ni dans un navigateur, ni dans un dépôt de code.

1. Obtenir un jeton

curl -X POST "$TREATS/oauth/token" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode "client_id=$TREATS_CLIENT_ID" \
  --data-urlencode "client_secret=$TREATS_CLIENT_SECRET" \
  --data-urlencode "organization_id=$ORGANIZATION_ID"

{
  "access_token": "QUPrqmoitOUZbzI-50Jk…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "agenda:read agenda:write clients:read org:read patients:read",
  "organization_id": "…"
}

Le jeton vaut 60 minutes. Gardez-le en mémoire et réutilisez-le jusqu’à son expiration ; les demandes de jeton sont limitées (60 par minute et par adresse IP). Une réponse 401 sur un appel veut dire que le jeton a expiré ou que l’organisation a retiré son autorisation : redemandez un jeton une fois, et si la demande répond unauthorized_client, l’organisation vous a déconnecté.

export TREATS_TOKEN="…"

2. Lire ce que le jeton ouvre

curl "$TREATS/me" -H "Authorization: Bearer $TREATS_TOKEN"

La réponse donne l’organisation, les sites ouverts à votre application et les droits accordés. Gardez les identifiants de sites : quand l’organisation en a ouvert plusieurs, chaque écriture doit dire sur quel site elle porte (site_id). Les droits peuvent changer d’un jour à l’autre si la clinique modifie son autorisation ; relisez GET /me après chaque nouveau jeton plutôt que de les mémoriser.

3. Trouver un créneau libre

Les types de rendez-vous du site, puis les créneaux libres d’un type sur une période :

curl "$TREATS/appointment-types?site_id=$SITE_ID" -H "Authorization: Bearer $TREATS_TOKEN"

curl "$TREATS/availability/slots?site_id=$SITE_ID&type_id=$TYPE_ID&from=2026-10-20T07:00:00Z&to=2026-10-21T19:00:00Z" \
  -H "Authorization: Bearer $TREATS_TOKEN"

Chaque créneau rendu porte le vétérinaire libre (vetId), le début, la fin et la durée. Les créneaux tiennent compte des horaires du site, des absences, des rendez-vous déjà posés et des règles de la clinique : un créneau rendu est un créneau que la création acceptera, sauf s’il a été pris entre-temps.

4. Créer le rendez-vous

Un rendez-vous porte sur un client et un animal existants. Cherchez-les (GET /clients?phone=…, GET /patients?client_id=…), ou créez-les (POST /clients, POST /patients). Puis :

curl -X POST "$TREATS/appointments?site_id=$SITE_ID" \
  -H "Authorization: Bearer $TREATS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "…",
    "patientId": "…",
    "appointmentTypeId": "…",
    "vetId": "…",
    "startAt": "2026-10-20T08:30:00Z",
    "note": "Pris en ligne : boiterie depuis deux jours"
  }'

La réponse 201 rend le rendez-vous créé, avec son identifiant. Trois points à retenir.

• Idempotency-Key est obligatoire sur tout POST. Générez une clé par opération et gardez-la jusqu’à la réponse. Si le réseau coupe, renvoyez le même appel avec la même clé : il ne sera appliqué qu’une fois et vous recevrez la réponse d’origine.
• Le créneau est revérifié. S’il a été pris entre-temps, la création répond 409 SLOT_CONFLICT. Le message dit pourquoi, en français, et meta.reason le dit en code (VET_BUSY : le vétérinaire a déjà un rendez-vous). Reproposez un autre créneau.
• Le rendez-vous est signé de votre application. Dans l’agenda de la clinique, il apparaît créé par « Intégration, nom de votre application ».

5. Rester à jour

Le rendez-vous peut ensuite être déplacé ou annulé par la clinique. Deux façons de le savoir, à combiner.

• Les notifications. Déclarez l’adresse de votre serveur (PUT /webhooks/endpoint) : Treats y envoie appointment.updated, appointment.cancelled… avec l’identifiant concerné. Votre serveur relit alors le rendez-vous par GET /appointments/{id}. Voir Notifications.
• La synchronisation. Relisez périodiquement GET /appointments?updated_since=… pour rattraper une notification perdue. Voir Synchronisation.

Et ensuite

• Accès et droits : ce que chaque droit ouvre, ce que voit une autorisation limitée à certains sites.
• Conventions : identifiants, dates, montants, listes, modification partielle.
• Erreurs et limites : l’enveloppe d’erreur, les codes communs, le quota d’appels.
• Référence : chaque route, avec un exemple d’appel réel.