Synchronisation

Beaucoup de services gardent une copie de ce qu’ils lisent chez Treats : un agenda en ligne, un outil comptable, un tableau de bord de groupe. Les listes de l’API sont faites pour ça. Suivez les quatre règles ci-dessous et vous ne perdrez aucune modification.

Listes synchronisables : /appointments, /call-notes, /tasks, /clients, /patients, /consultations, /invoices, /credit-notes, /payments, /prescriptions, /catalog/items, /lab/orders, /imaging/exams.

1. Le premier parcours

Lisez la liste page par page, sans updated_since, en suivant nextCursor jusqu’à null. Les lignes arrivent dans l’ordre de leur dernière modification, puis de leur identifiant ; une ligne modifiée pendant le parcours repasse plus loin, elle n’est jamais sautée.

curl "$TREATS/appointments?limit=200" -H "Authorization: Bearer $TREATS_TOKEN"
curl "$TREATS/appointments?limit=200&cursor=$NEXT" -H "Authorization: Bearer $TREATS_TOKEN"

Retenez le plus grand updatedAt vu.

2. Les passages suivants : repartir avec un recouvrement

À chaque passage, repartez de updated_since = le plus grand updatedAt vu moins 5 minutes, puis suivez les pages jusqu’au bout.

curl "$TREATS/appointments?updated_since=2026-10-15T09:25:00Z&limit=200" -H "Authorization: Bearer $TREATS_TOKEN"

Les 5 minutes de recouvrement couvrent les écarts d’horloge et les écritures longues. Vous relirez quelques lignes déjà vues : c’est voulu.

3. Dédoublonner par identifiant

Rangez chaque ligne par son id. Une ligne déjà connue remplace l’ancienne si son updatedAt est plus récent ou égal. Ne comptez jamais les lignes reçues comme des nouveautés.

4. Ce que « au plus 60 secondes » veut dire

Une liste ne rend une ligne que 60 secondes après sa dernière modification. Ce délai garantit qu’une écriture encore en cours chez Treats ne passe pas derrière votre curseur : sans lui, une modification validée juste après votre passage porterait une date que vous avez déjà dépassée, et vous ne la verriez jamais.

En pratique :

• une écriture apparaît dans les listes au plus une minute après ;
• la lecture par identifiant (GET /appointments/{id}) est immédiate, de même que les recherches par identité (/clients?phone=, /clients?email=, /clients?q=, /patients?microchip=) ;
• après avoir créé un rendez-vous, relisez-le par son identifiant, pas en relisant la liste.

Combiner avec les notifications

Les notifications préviennent en quelques secondes qu’une ressource a changé, avec son identifiant. Relisez alors la ressource par GET /…/{id}. Gardez quand même un passage de synchronisation régulier (toutes les 5 à 15 minutes) : une notification peut arriver en retard, en double ou dans le désordre, et un passage rattrape tout.

Volumes

• Une page compte au plus 200 lignes. Visez limit=200 pour une synchronisation, une valeur plus petite pour un affichage.
• Le quota est de 300 appels par minute et par organisation (voir Erreurs et limites). Un premier parcours de 50 000 rendez-vous prend 250 appels.
• Ne relancez pas un parcours complet à chaque passage : le passage incrémental lit seulement ce qui a changé.
• Si Treats reprend les données d’une clinique (changement de logiciel, correction en masse), l’équipe Treats vous prévient : refaites alors un parcours complet de l’organisation concernée.