Clients

Lire, 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.

Lister les clients

GET/api/partner/v1/clients#

clients:read

Rend les clients de l'organisation que vous pouvez voir (tous si l'organisation vous a ouvert tous ses sites, sinon ceux nés sur les sites ouverts), clients désactivés compris (active: false). Tri par updatedAt puis id, croissant : c'est la liste de synchronisation, à parcourir par cursor et à reprendre par updated_since. Une fiche créée ou modifiée n'y apparaît qu'environ 60 secondes après l'écriture ; sa lecture par GET /clients/{id} est immédiate.

Les filtres q, phone et email sont des recherches : ils se combinent entre eux et rendent aussi une fiche tout juste créée. N'exige que clients:read.

Paramètres

qrequête · string	Texte cherché dans le prénom, le nom ou la raison sociale (contient, casse et accents ignorés), ou dans le téléphone principal tel qu'il a été saisi. 100 caractères au plus. Le téléphone mobile n'est pas cherché ici : utilisez `phone`.
phonerequête · string	Numéro complet, comparé au téléphone principal OU au mobile, quel que soit le format (`06 12 34 56 78`, `0612345678`, `+33 6 12 34 56 78` sont équivalents). 6 chiffres au moins. Pas de recherche partielle.
emailrequête · string	Adresse email exacte, casse ignorée. 255 caractères au plus.
updated_sincerequête · date-time	Ne rend que les fiches dont `updatedAt` est postérieur ou égal à cet instant (ISO 8601, années 1900 à 9999). Pour une synchronisation incrémentale, repartez du plus grand `updatedAt` vu moins 5 minutes et dédoublonnez par `id`.
cursorrequête · string	Curseur opaque rendu par la page précédente (`nextCursor`), à repasser tel quel avec les mêmes filtres. Absent : première page.
limitrequête · integer	Nombre de fiches par page, de 1 à 200. Au-delà de 200, ramené à 200. Défaut : `50`

Réponse

200Une page de clients.

Champs de la réponse (2)

itemsClient[]
iduuid	Identifiant du client.
publicIdstring	Identifiant public partageable (`cli_…`), affiché dans Treats. Peut être nul sur une fiche à qui aucun n'a encore été attribué. peut être null
organizationIduuid	Organisation du client.
siteIduuid	Site d'origine : celui où la fiche a été créée. Le client reste celui de toute l'organisation ; ce site décide de sa visibilité quand l'organisation ne vous a ouvert que certains sites.
typeenum	`INDIVIDUAL` : particulier. `PROFESSIONAL` : éleveur, refuge, entreprise… `INDIVIDUALPROFESSIONAL`peut être null
civilityenum	Civilité : `MR` (Monsieur), `MRS` (Madame), `MS` (Mademoiselle), `DR` (Docteur). `MRMRSMSDR`peut être null
firstNamestring	Prénom. Toujours rempli pour un client créé par l'API ; peut manquer sur une fiche reprise d'un ancien logiciel. peut être null
lastNamestring	Nom.
companyNamestring	Raison sociale. peut être null
sirenstring	Numéro SIREN, en lecture seule (saisi par la clinique). peut être null
emailstring	Adresse email. peut être null
phonestring	Téléphone principal, tel qu'il a été saisi. Unique dans l'organisation. peut être null
mobilePhonestring	Téléphone mobile, tel qu'il a été saisi. peut être null
addressClientAddress	Adresse postale. L'objet est toujours présent ; ses champs sont nuls quand l'adresse n'est pas renseignée.
linestring	Adresse composée sur une ligne, telle qu'elle s'imprime sur les documents. Lecture seule : recomposée à chaque modification des autres champs. peut être null
streetstring	Voie (numéro et rue). peut être null
postalCodestring	Code postal. peut être null
citystring	Ville. peut être null
countrystring	Pays. peut être null
birthDatedate	Date de naissance du client. peut être null
consentsClientConsents	Accords de contact donnés par le client.
emailboolean	Le client accepte d'être contacté par email.
smsboolean	Le client accepte d'être contacté par SMS.
mailboolean	Le client accepte d'être contacté par courrier.
preferredChannelenum	Canal préféré pour les envois manuels de la clinique. `EMAILSMSPHONE`peut être null
activeboolean	`false` : fiche désactivée par la clinique (plus aucune communication).
createdAtdate-time	Date de création de la fiche. Peut être nulle sur une fiche reprise d'un ancien logiciel. peut être null
updatedAtdate-time	Clé de synchronisation, à la microseconde : date de dernière modification, à défaut date de création. C'est la valeur que lit `updated_since` et qui ordonne la liste.
nextCursorstring	Curseur opaque de la page suivante, à repasser tel quel dans `cursor`. `null` : dernière page. peut être null

Erreurs propres à cette opération

400 INVALID_FIELD

q de plus de 100 caractères, phone de moins de 6 chiffres, email de plus de 255 caractères, updated_since mal formé ou hors des années 1900 à 9999, limit non entier ou inférieur à 1, cursor illisible. details nomme chaque paramètre refusé.

Et les erreurs communes à toutes les opérations : erreurs et limites.

Créer un client

POST/api/partner/v1/clients#

clients:writeIdempotency-Key

Crée un client dans l'organisation, avec pour site d'origine le site désigné par site_id (ou Treats-Site-Id), implicite si l'organisation ne vous a ouvert qu'un site. Le client naît sans aucun accord de contact : c'est la clinique ou le propriétaire qui les donne. Exige clients:write.

Le téléphone principal est unique dans toute l'organisation, sites non ouverts compris : vérifiez d'abord par POST /clients/duplicate-check ou GET /clients?phone=. Tous les champs refusés sont rendus en une seule réponse 400 INVALID_FIELD, et tout champ hors contrat est refusé, y compris dans address et consents. Les textes ne doivent contenir aucune balise HTML.

Paramètres

site_idrequête · uuid	Site d'origine du client. Obligatoire si l'organisation vous a ouvert plusieurs sites (sinon le seul site ouvert). Peut aussi passer en en-tête `Treats-Site-Id`.
Treats-Site-Iden-tête · uuid	Équivalent de `site_id` (le paramètre l'emporte s'il est donné).
Idempotency-Keyen-tête · stringrequis	Clé unique de l'envoi (un UUID). Le même envoi répété avec la même clé n'est appliqué qu'une fois pendant 24 h.

Corps de la requête application/json

firstNamestringrequis	Prénom.
lastNamestringrequis	Nom.
phonestring	Téléphone principal : chiffres, espaces, `+`, `(`, `)`, `.`, `-`, avec 6 chiffres au moins. `phone` ou `email` est obligatoire. Déjà porté par un client de l'organisation : `409 CLIENT_DUPLICATE`.
emailstring	Adresse email (format vérifié). `phone` ou `email` est obligatoire.
mobilePhonestring	Téléphone mobile, même format que `phone`. Ne compte pas comme moyen de contact obligatoire et n'est pas soumis au contrôle de doublon.
typeenum	Type de client (casse ignorée). `INDIVIDUALPROFESSIONAL`défaut "INDIVIDUAL"
civilityenum	Civilité (casse ignorée). `MRMRSMSDR`
companyNamestring	Raison sociale.
addressobject	Adresse postale. Aucun champ n'est obligatoire ; la ligne composée (`address.line`) est calculée par Treats.
streetstring	Voie (numéro et rue).
postalCodestring	Code postal.
citystring	Ville.
countrystring	Pays.
birthDatedate	Date de naissance du client (`AAAA-MM-JJ`), passée ou du jour, pas avant 1900.
consentsobject	Accords de contact. Seul `false` est accepté (`true` ou `null` sont refusés) ; à la création il ne change rien, le client naissant sans aucun accord.
emailboolean	Seul `false` est accepté.
smsboolean	Seul `false` est accepté.
mailboolean	Seul `false` est accepté.
preferredChannelenum	Canal préféré pour les envois manuels (casse ignorée). `EMAILSMSPHONE`

Réponse

201Le client créé.

Champs de la réponse (20)

iduuid	Identifiant du client.
publicIdstring	Identifiant public partageable (`cli_…`), affiché dans Treats. Peut être nul sur une fiche à qui aucun n'a encore été attribué. peut être null
organizationIduuid	Organisation du client.
siteIduuid	Site d'origine : celui où la fiche a été créée. Le client reste celui de toute l'organisation ; ce site décide de sa visibilité quand l'organisation ne vous a ouvert que certains sites.
typeenum	`INDIVIDUAL` : particulier. `PROFESSIONAL` : éleveur, refuge, entreprise… `INDIVIDUALPROFESSIONAL`peut être null
civilityenum	Civilité : `MR` (Monsieur), `MRS` (Madame), `MS` (Mademoiselle), `DR` (Docteur). `MRMRSMSDR`peut être null
firstNamestring	Prénom. Toujours rempli pour un client créé par l'API ; peut manquer sur une fiche reprise d'un ancien logiciel. peut être null
lastNamestring	Nom.
companyNamestring	Raison sociale. peut être null
sirenstring	Numéro SIREN, en lecture seule (saisi par la clinique). peut être null
emailstring	Adresse email. peut être null
phonestring	Téléphone principal, tel qu'il a été saisi. Unique dans l'organisation. peut être null
mobilePhonestring	Téléphone mobile, tel qu'il a été saisi. peut être null
addressClientAddress	Adresse postale. L'objet est toujours présent ; ses champs sont nuls quand l'adresse n'est pas renseignée.
linestring	Adresse composée sur une ligne, telle qu'elle s'imprime sur les documents. Lecture seule : recomposée à chaque modification des autres champs. peut être null
streetstring	Voie (numéro et rue). peut être null
postalCodestring	Code postal. peut être null
citystring	Ville. peut être null
countrystring	Pays. peut être null
birthDatedate	Date de naissance du client. peut être null
consentsClientConsents	Accords de contact donnés par le client.
emailboolean	Le client accepte d'être contacté par email.
smsboolean	Le client accepte d'être contacté par SMS.
mailboolean	Le client accepte d'être contacté par courrier.
preferredChannelenum	Canal préféré pour les envois manuels de la clinique. `EMAILSMSPHONE`peut être null
activeboolean	`false` : fiche désactivée par la clinique (plus aucune communication).
createdAtdate-time	Date de création de la fiche. Peut être nulle sur une fiche reprise d'un ancien logiciel. peut être null
updatedAtdate-time	Clé de synchronisation, à la microseconde : date de dernière modification, à défaut date de création. C'est la valeur que lit `updated_since` et qui ordonne la liste.

Erreurs propres à cette opération

400 INVALID_FIELD	Champ obligatoire absent (`firstName`, `lastName`, ou ni `phone` ni `email`), texte trop long ou contenant une balise HTML, email ou téléphone mal formé, date future ou avant 1900, valeur d'enum inconnue, `consents.*` à `true` ou `null`, `address` ou `consents` qui n'est pas un objet, champ inconnu (`address.ville`). Un détail par champ, chemin compris.
400 SITE_ID_REQUIRED	L'organisation vous a ouvert plusieurs sites et aucun `site_id` n'est donné.
400 INVALID_SITE_ID	`site_id` (ou `Treats-Site-Id`) n'est pas un UUID.
400 INVALID_REQUEST	Refus résiduel de Treats sur une donnée que les contrôles ci-dessus n'ont pas arrêtée (filet de sécurité).
404 SITE_NOT_FOUND	Le site demandé n'est pas un site que l'organisation vous a ouvert.
409 CLIENT_DUPLICATE	Un client de l'organisation porte déjà ce téléphone principal, y compris sur un site qui ne vous est pas ouvert. La réponse ne donne ni l'identifiant ni le site de cette fiche.

Et les erreurs communes à toutes les opérations : erreurs et limites.

Notifications envoyées :client.created

Lire un client

GET/api/partner/v1/clients/{id}#

clients:read

Rend la fiche d'un client visible (organisation entière si tous les sites vous sont ouverts, sinon client né sur un site ouvert). Lecture immédiate, sans le délai de la liste. Un client d'une autre organisation, d'un site non ouvert ou inconnu répond 404 CLIENT_NOT_FOUND. Exige clients:read.

Paramètres

idchemin · uuidrequis

Identifiant du client (id, pas publicId).

Réponse

200La fiche du client.

Champs de la réponse (20)

iduuid	Identifiant du client.
publicIdstring	Identifiant public partageable (`cli_…`), affiché dans Treats. Peut être nul sur une fiche à qui aucun n'a encore été attribué. peut être null
organizationIduuid	Organisation du client.
siteIduuid	Site d'origine : celui où la fiche a été créée. Le client reste celui de toute l'organisation ; ce site décide de sa visibilité quand l'organisation ne vous a ouvert que certains sites.
typeenum	`INDIVIDUAL` : particulier. `PROFESSIONAL` : éleveur, refuge, entreprise… `INDIVIDUALPROFESSIONAL`peut être null
civilityenum	Civilité : `MR` (Monsieur), `MRS` (Madame), `MS` (Mademoiselle), `DR` (Docteur). `MRMRSMSDR`peut être null
firstNamestring	Prénom. Toujours rempli pour un client créé par l'API ; peut manquer sur une fiche reprise d'un ancien logiciel. peut être null
lastNamestring	Nom.
companyNamestring	Raison sociale. peut être null
sirenstring	Numéro SIREN, en lecture seule (saisi par la clinique). peut être null
emailstring	Adresse email. peut être null
phonestring	Téléphone principal, tel qu'il a été saisi. Unique dans l'organisation. peut être null
mobilePhonestring	Téléphone mobile, tel qu'il a été saisi. peut être null
addressClientAddress	Adresse postale. L'objet est toujours présent ; ses champs sont nuls quand l'adresse n'est pas renseignée.
linestring	Adresse composée sur une ligne, telle qu'elle s'imprime sur les documents. Lecture seule : recomposée à chaque modification des autres champs. peut être null
streetstring	Voie (numéro et rue). peut être null
postalCodestring	Code postal. peut être null
citystring	Ville. peut être null
countrystring	Pays. peut être null
birthDatedate	Date de naissance du client. peut être null
consentsClientConsents	Accords de contact donnés par le client.
emailboolean	Le client accepte d'être contacté par email.
smsboolean	Le client accepte d'être contacté par SMS.
mailboolean	Le client accepte d'être contacté par courrier.
preferredChannelenum	Canal préféré pour les envois manuels de la clinique. `EMAILSMSPHONE`peut être null
activeboolean	`false` : fiche désactivée par la clinique (plus aucune communication).
createdAtdate-time	Date de création de la fiche. Peut être nulle sur une fiche reprise d'un ancien logiciel. peut être null
updatedAtdate-time	Clé de synchronisation, à la microseconde : date de dernière modification, à défaut date de création. C'est la valeur que lit `updated_since` et qui ordonne la liste.

Erreurs propres à cette opération

404 CLIENT_NOT_FOUND	Client inconnu, d'une autre organisation, ou né sur un site qui ne vous est pas ouvert.
404 NOT_FOUND	`id` n'est pas un UUID.

Et les erreurs communes à toutes les opérations : erreurs et limites.

Modifier un client

PATCH/api/partner/v1/clients/{id}#

clients:write

Modifie les champs envoyés : champ absent = inchangé, champ à null = vidé. Se vident : email, mobilePhone, companyName, chaque champ d'address, et address: null (toute l'adresse). Ne se vident pas (400 INVALID_FIELD, « ne peut pas être vidé ») : firstName, lastName, type, civility, phone (le remplacer), birthDate, preferredChannel, consents.*. Un corps vide {} ne change rien et rend la fiche.

Le client doit garder un téléphone principal ou un email : vider l'email d'un client sans téléphone est refusé. Un accord de contact peut être retiré (false, à la demande du client), jamais donné (true refusé). Un nouveau téléphone déjà porté par un autre client de l'organisation répond 409 CLIENT_DUPLICATE. Exige clients:write.

Paramètres

idchemin · uuidrequis	Identifiant du client.
site_idrequête · uuid	Site au nom duquel l'écriture est faite (journal). Facultatif : à défaut, le site d'origine du client s'il vous est ouvert, sinon le seul site ouvert. La fiche reste celle de l'organisation.
Treats-Site-Iden-tête · uuid	Équivalent de `site_id`.

Corps de la requête application/json

firstNamestring	Prénom. Non vidable, ni à `null` ni à vide.
lastNamestring	Nom. Non vidable, ni à `null` ni à vide.
phonestring	Téléphone principal (même format qu'à la création). Non vidable : le remplacer. Déjà porté par un autre client : `409 CLIENT_DUPLICATE`.
emailstring	Adresse email. `null` la vide, si le client garde un téléphone principal. peut être null
mobilePhonestring	Téléphone mobile. `null` le vide. peut être null
typeenum	Type de client. Non vidable. `INDIVIDUALPROFESSIONAL`
civilityenum	Civilité. Non vidable. `MRMRSMSDR`
companyNamestring	Raison sociale. `null` la vide. peut être null
addressobject	Adresse : seuls les champs envoyés changent, un champ à `null` est vidé ; `address: null` vide toute l'adresse. La ligne composée suit. peut être null
streetstring	Voie. `null` la vide. peut être null
postalCodestring	Code postal. `null` le vide. peut être null
citystring	Ville. `null` la vide. peut être null
countrystring	Pays. `null` le vide. peut être null
birthDatedate	Date de naissance, passée ou du jour, pas avant 1900. Non vidable.
consentsobject	Retrait d'accords de contact : seul `false` est accepté, `true` et `null` sont refusés.
emailboolean	`false` : retire l'accord email.
smsboolean	`false` : retire l'accord SMS.
mailboolean	`false` : retire l'accord courrier.
preferredChannelenum	Canal préféré. Non vidable. `EMAILSMSPHONE`

Réponse

200La fiche modifiée.

Champs de la réponse (20)

iduuid	Identifiant du client.
publicIdstring	Identifiant public partageable (`cli_…`), affiché dans Treats. Peut être nul sur une fiche à qui aucun n'a encore été attribué. peut être null
organizationIduuid	Organisation du client.
siteIduuid	Site d'origine : celui où la fiche a été créée. Le client reste celui de toute l'organisation ; ce site décide de sa visibilité quand l'organisation ne vous a ouvert que certains sites.
typeenum	`INDIVIDUAL` : particulier. `PROFESSIONAL` : éleveur, refuge, entreprise… `INDIVIDUALPROFESSIONAL`peut être null
civilityenum	Civilité : `MR` (Monsieur), `MRS` (Madame), `MS` (Mademoiselle), `DR` (Docteur). `MRMRSMSDR`peut être null
firstNamestring	Prénom. Toujours rempli pour un client créé par l'API ; peut manquer sur une fiche reprise d'un ancien logiciel. peut être null
lastNamestring	Nom.
companyNamestring	Raison sociale. peut être null
sirenstring	Numéro SIREN, en lecture seule (saisi par la clinique). peut être null
emailstring	Adresse email. peut être null
phonestring	Téléphone principal, tel qu'il a été saisi. Unique dans l'organisation. peut être null
mobilePhonestring	Téléphone mobile, tel qu'il a été saisi. peut être null
addressClientAddress	Adresse postale. L'objet est toujours présent ; ses champs sont nuls quand l'adresse n'est pas renseignée.
linestring	Adresse composée sur une ligne, telle qu'elle s'imprime sur les documents. Lecture seule : recomposée à chaque modification des autres champs. peut être null
streetstring	Voie (numéro et rue). peut être null
postalCodestring	Code postal. peut être null
citystring	Ville. peut être null
countrystring	Pays. peut être null
birthDatedate	Date de naissance du client. peut être null
consentsClientConsents	Accords de contact donnés par le client.
emailboolean	Le client accepte d'être contacté par email.
smsboolean	Le client accepte d'être contacté par SMS.
mailboolean	Le client accepte d'être contacté par courrier.
preferredChannelenum	Canal préféré pour les envois manuels de la clinique. `EMAILSMSPHONE`peut être null
activeboolean	`false` : fiche désactivée par la clinique (plus aucune communication).
createdAtdate-time	Date de création de la fiche. Peut être nulle sur une fiche reprise d'un ancien logiciel. peut être null
updatedAtdate-time	Clé de synchronisation, à la microseconde : date de dernière modification, à défaut date de création. C'est la valeur que lit `updated_since` et qui ordonne la liste.

Erreurs propres à cette opération

400 INVALID_FIELD	Champ non vidable envoyé à `null` (ou prénom, nom, téléphone vide), email vidé sur un client sans téléphone principal, `consents.*` à `true`, format ou longueur refusés, valeur d'enum inconnue, champ hors contrat. Un détail par champ.
400 SITE_ID_REQUIRED	Aucun `site_id`, le site d'origine du client ne vous est pas ouvert, et l'organisation vous a ouvert plusieurs sites.
400 INVALID_SITE_ID	`site_id` (ou `Treats-Site-Id`) n'est pas un UUID.
400 INVALID_REQUEST	Refus résiduel de Treats sur une donnée que les contrôles ci-dessus n'ont pas arrêtée (filet de sécurité).
404 CLIENT_NOT_FOUND	Client inconnu, d'une autre organisation, ou né sur un site qui ne vous est pas ouvert.
404 NOT_FOUND	`id` n'est pas un UUID.
404 SITE_NOT_FOUND	Le site demandé n'est pas un site que l'organisation vous a ouvert.
409 CLIENT_DUPLICATE	Le nouveau téléphone principal est déjà porté par un autre client de l'organisation, y compris sur un site qui ne vous est pas ouvert. Ni l'identifiant ni le site de cette fiche ne sont rendus.

Et les erreurs communes à toutes les opérations : erreurs et limites.

Vérifier un doublon avant création

POST/api/partner/v1/clients/duplicate-check#

clients:read

Dit si POST /clients accepterait ce téléphone, et rend les fiches proches que vous pouvez voir (même téléphone principal, ou même nom et prénom). La recherche porte sur toute l'organisation ; une fiche d'un site qui ne vous est pas ouvert fait passer phoneAvailable à false mais n'apparaît jamais dans candidates. Ne crée et ne modifie rien. Exige clients:read. Route de lecture malgré la méthode POST : pas d'en-tête Idempotency-Key.

Corps de la requête application/json

phonestring	Téléphone à vérifier, même format que pour `POST /clients`. Obligatoire si `firstName` et `lastName` ne sont pas donnés tous les deux.
firstNamestring	Prénom. Pris en compte seulement avec `lastName`.
lastNamestring	Nom. Pris en compte seulement avec `firstName`.

Réponse

200Disponibilité du téléphone et fiches proches visibles.

Champs de la réponse (2)

phoneAvailableboolean	`false` : un client de l'organisation porte déjà ce téléphone principal, et `POST /clients` le refuserait (`409 CLIENT_DUPLICATE`). Vaut aussi `false` quand cette fiche est sur un site qui ne vous est pas ouvert, sans rien en dire de plus. `true` : téléphone libre. `null` : aucun téléphone demandé. peut être null
candidatesClientDuplicateCandidate[]	Fiches proches que vous pouvez voir, d'abord celles au même téléphone puis celles au même nom. Une fiche d'un site qui ne vous est pas ouvert n'y figure jamais. Liste vide si aucune.
clientIduuid	Identifiant du client existant (à lire par `GET /clients/{id}`).
publicIdstring	Identifiant public (`cli_…`). peut être null
siteIduuid	Site d'origine du client existant.
firstNamestring	Prénom du client existant. peut être null
lastNamestring	Nom du client existant.
matchenum	`PHONE` : même téléphone principal. `NAME` : même nom et même prénom, casse et accents ignorés. Une fiche qui correspond aux deux n'apparaît qu'une fois, en `PHONE`. `PHONENAME`

Erreurs propres à cette opération

400 INVALID_FIELD	Ni `phone`, ni le couple `firstName` et `lastName` (le refus porte sur `phone`) ; téléphone mal formé, texte trop long ou contenant une balise HTML ; champ hors de `phone`, `firstName`, `lastName`.
404 CLIENT_NOT_FOUND	L'organisation ne vous ouvre plus aucun site.

Et les erreurs communes à toutes les opérations : erreurs et limites.