Docs
Connexion partenaire →

Référence de l’API partenaires

Facturation

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

Lister les avoirs

GET/api/partner/v1/credit-notes#

billing:read

Rend une page des avoirs émis par les sites ouverts à l'application, sans leurs lignes ni leur restitution (à lire au détail). Un avoir ne se modifie pas après émission : sa date de synchronisation est sa date d'émission.

Tri par date d'émission puis identifiant. Les avoirs des 60 dernières secondes n'apparaissent qu'aux appels suivants ; la lecture par identifiant est immédiate. Un client_id ou un invoice_id inconnu rend une liste vide, pas une erreur.

Paramètres

client_idrequête · uuid

Restreint aux avoirs de ce client.

invoice_idrequête · uuid

Restreint aux avoirs de cette facture.

issued_fromrequête · date

Jour d'émission minimal, inclus (AAAA-MM-JJ, heure de Paris).

issued_torequête · date

Jour d'émission maximal, inclus (AAAA-MM-JJ, heure de Paris).

site_idrequête · uuid

Restreint à un site ouvert à l'application (ou passer l'en-tête Treats-Site-Id). Absent : tous les sites ouverts.

updated_sincerequête · date-time

Ne rend que les avoirs émis à cet instant ou après (ISO 8601).

cursorrequête · string

Curseur nextCursor de la page précédente, repassé tel quel. Absent : première page.

limitrequête · integer

Nombre d'avoirs par page, de 1 à 200 (au-delà de 200, ramené à 200).

Défaut : 50
Treats-Site-Iden-tête · uuid

Site visé, à la place du paramètre site_id.

Réponse

200Une page d'avoirs (`lines`, `settlement` et `amountDueToClientCents` à `null`).

Champs de la réponse (2)
itemsCreditNote[]
iduuid

Identifiant de l'avoir.

numberstring

Numéro de l'avoir.

siteIduuid

Site émetteur.

invoiceIduuid

Facture corrigée par l'avoir.

invoiceNumberstring

Numéro de cette facture.

clientIduuid

Client concerné.

typeenum

FULL : avoir sur toute la facture. PARTIAL : sur une partie.

FULLPARTIAL
reasonenum

Motif : erreur de client, doublon, prestation non réalisée, erreur de prix, autre.

CLIENT_ERRORDUPLICATESERVICE_NOT_PROVIDEDPRICING_ERROROTHER
reasonDetailsstring

Précision saisie par la clinique.

peut être null
totalHtCentsinteger

Total hors taxes de l'avoir, en centimes.

totalVatCentsinteger

TVA de l'avoir, en centimes.

totalTtcCentsinteger

Total toutes taxes comprises de l'avoir, en centimes.

currencyenum

Devise des montants, toujours EUR.

EUR
issuedAtdate-time

Date d'émission de l'avoir.

amountDueToClientCentsinteger

Au détail : ce que la clinique doit encore rendre au client au titre de cet avoir (trop-perçu non restitué), en centimes ; 0 une fois restitué ou si rien n'avait été payé en trop. null en liste.

peut être null
settlementCreditNoteSettlement

Au détail : la restitution faite au client. null tant qu'elle n'est pas faite, et toujours null en liste.

peut être null
kindenum

REFUND : remboursé au client. DEPOSIT : porté en acompte sur son compte client.

REFUNDDEPOSIT
methodenum

Moyen du remboursement (voir Payment.method). null pour un acompte.

CARDCARD_CONTACTLESSCASHCHECKTRANSFERCLIENT_ACCOUNTALMAAVOIRCERTIFICATE_UNRECOVERABLECONTENTIOUSONEY_BANKOXANEPAYVETLOSSPROFIT_AND_LOSSFLOApeut être null
amountCentsinteger

Montant restitué, en centimes.

settledAtdate-time

Date de la restitution.

paymentIduuid

Pour un remboursement : le mouvement négatif correspondant dans GET /payments (kind = CREDIT_NOTE_REFUND). null pour un acompte.

peut être null
linesCreditNoteLine[]

Au détail : les lignes de l'avoir. null en liste.

peut être null
iduuid

Identifiant de la ligne.

invoiceLineIduuid

Ligne de la facture d'origine que celle-ci corrige.

peut être null
labelstring

Libellé.

quantitynumber

Quantité.

unitPriceHtCentsinteger

Prix unitaire hors taxes, en centimes.

vatRatePercentnumber

Taux de TVA, en pourcentage.

totalHtCentsinteger

Total hors taxes de la ligne, en centimes.

updatedAtdate-time

Date de synchronisation : la date d'émission (un avoir ne se modifie pas). Sert de clé à updated_since et au curseur.

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

Date issued_from / issued_to mal formée ou hors des années 1900 à 9999, client_id, invoice_id ou updated_since mal formé, limit inférieur à 1 ou non entier, curseur illisible. Un détail par champ.

400 INVALID_SITE_ID

site_id (ou Treats-Site-Id) n'est pas un identifiant valide.

404 SITE_NOT_FOUND

Le site demandé n'est pas ouvert à l'application.

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

Lire un avoir

GET/api/partner/v1/credit-notes/{id}#

billing:read

Rend le détail d'un avoir émis par un site ouvert à l'application : ses lignes, la ligne de facture que chacune corrige, ce qui reste à rendre au client et la restitution faite (remboursement ou acompte). Un avoir d'un site non ouvert répond 404.

Paramètres

idchemin · uuidrequis

Identifiant de l'avoir.

Réponse

200L'avoir, avec ses lignes.

Champs de la réponse (18)
iduuid

Identifiant de l'avoir.

numberstring

Numéro de l'avoir.

siteIduuid

Site émetteur.

invoiceIduuid

Facture corrigée par l'avoir.

invoiceNumberstring

Numéro de cette facture.

clientIduuid

Client concerné.

typeenum

FULL : avoir sur toute la facture. PARTIAL : sur une partie.

FULLPARTIAL
reasonenum

Motif : erreur de client, doublon, prestation non réalisée, erreur de prix, autre.

CLIENT_ERRORDUPLICATESERVICE_NOT_PROVIDEDPRICING_ERROROTHER
reasonDetailsstring

Précision saisie par la clinique.

peut être null
totalHtCentsinteger

Total hors taxes de l'avoir, en centimes.

totalVatCentsinteger

TVA de l'avoir, en centimes.

totalTtcCentsinteger

Total toutes taxes comprises de l'avoir, en centimes.

currencyenum

Devise des montants, toujours EUR.

EUR
issuedAtdate-time

Date d'émission de l'avoir.

amountDueToClientCentsinteger

Au détail : ce que la clinique doit encore rendre au client au titre de cet avoir (trop-perçu non restitué), en centimes ; 0 une fois restitué ou si rien n'avait été payé en trop. null en liste.

peut être null
settlementCreditNoteSettlement

Au détail : la restitution faite au client. null tant qu'elle n'est pas faite, et toujours null en liste.

peut être null
kindenum

REFUND : remboursé au client. DEPOSIT : porté en acompte sur son compte client.

REFUNDDEPOSIT
methodenum

Moyen du remboursement (voir Payment.method). null pour un acompte.

CARDCARD_CONTACTLESSCASHCHECKTRANSFERCLIENT_ACCOUNTALMAAVOIRCERTIFICATE_UNRECOVERABLECONTENTIOUSONEY_BANKOXANEPAYVETLOSSPROFIT_AND_LOSSFLOApeut être null
amountCentsinteger

Montant restitué, en centimes.

settledAtdate-time

Date de la restitution.

paymentIduuid

Pour un remboursement : le mouvement négatif correspondant dans GET /payments (kind = CREDIT_NOTE_REFUND). null pour un acompte.

peut être null
linesCreditNoteLine[]

Au détail : les lignes de l'avoir. null en liste.

peut être null
iduuid

Identifiant de la ligne.

invoiceLineIduuid

Ligne de la facture d'origine que celle-ci corrige.

peut être null
labelstring

Libellé.

quantitynumber

Quantité.

unitPriceHtCentsinteger

Prix unitaire hors taxes, en centimes.

vatRatePercentnumber

Taux de TVA, en pourcentage.

totalHtCentsinteger

Total hors taxes de la ligne, en centimes.

updatedAtdate-time

Date de synchronisation : la date d'émission (un avoir ne se modifie pas). Sert de clé à updated_since et au curseur.

Erreurs propres à cette opération

404 CREDIT_NOTE_NOT_FOUND

Aucun avoir de ce périmètre ne porte cet identifiant.

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

Télécharger le PDF d'un avoir

GET/api/partner/v1/credit-notes/{id}/pdf#

billing:read

Rend le PDF officiel de l'avoir, avec l'en-tête du site émetteur. Même périmètre que GET /credit-notes/{id}. Le fichier est servi avec Content-Disposition: inline; filename="avoir-<id>.pdf".

Paramètres

idchemin · uuidrequis

Identifiant de l'avoir.

Réponse

200Le PDF de l'avoir. · fichier application/pdf

Erreurs propres à cette opération

404 CREDIT_NOTE_NOT_FOUND

Aucun avoir de ce périmètre ne porte cet identifiant.

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

Lister les factures émises

GET/api/partner/v1/invoices#

billing:read

Rend une page des factures émises par les sites ouverts à l'application, tous clients confondus. Les brouillons n'existent pas pour l'API : ni numéro légal, ni montant définitif. Les pièces reprises d'un ancien logiciel qui ne sont pas des factures (devis, bons de livraison, provisoires) sont exclues, même payées.

Tri par date de synchronisation (updatedAt) puis identifiant : une facture réglée, créditée ou annulée revient dans updated_since. Les modifications des 60 dernières secondes n'apparaissent qu'aux appels suivants ; la lecture par identifiant est immédiate. Un client_id inconnu rend une liste vide, pas une erreur.

Paramètres

client_idrequête · uuid

Restreint aux factures de ce client.

statusrequête · enum

Restreint à ce statut. Insensible à la casse. DRAFT est refusé.

issued_fromrequête · date

Jour d'émission minimal, inclus (AAAA-MM-JJ, heure de Paris).

issued_torequête · date

Jour d'émission maximal, inclus (AAAA-MM-JJ, heure de Paris).

site_idrequête · uuid

Restreint à un site ouvert à l'application (ou passer l'en-tête Treats-Site-Id). Absent : tous les sites ouverts.

updated_sincerequête · date-time

Ne rend que les factures dont updatedAt est postérieur ou égal à cet instant (ISO 8601).

cursorrequête · string

Curseur nextCursor de la page précédente, repassé tel quel. Absent : première page.

limitrequête · integer

Nombre de factures par page, de 1 à 200 (au-delà de 200, ramené à 200).

Défaut : 50
Treats-Site-Iden-tête · uuid

Site visé, à la place du paramètre site_id.

Réponse

200Une page de factures émises.

Champs de la réponse (2)
itemsInvoiceSummary[]
iduuid

Identifiant de la facture.

numberstring

Numéro de la facture (numérotation légale de la clinique).

siteIduuid

Site émetteur.

clientIduuid

Client facturé.

statusenum

PENDING : à régler. PARTIAL : réglée en partie. PAID : soldée. CANCELLED : annulée. Une facture réglée puis créditée garde PAID : creditedCents égal à totalTtcCents dit qu'elle est annulée par avoir.

PENDINGPARTIALPAIDCANCELLED
issuedAtdate-time

Date d'émission (validation). Pour une facture reprise d'un ancien logiciel sans date de validation : sa date de création.

dueDatedate

Date d'échéance.

peut être null
totalHtCentsinteger

Total hors taxes, en centimes.

totalVatCentsinteger

Total de TVA, en centimes.

totalTtcCentsinteger

Total toutes taxes comprises, en centimes : ce que le client doit payer. Sur quelques factures anciennes, totalHtCents + totalVatCents en diffère d'un centime ; les montants sont rendus tels qu'émis.

paidCentsinteger

Montant déjà encaissé, en centimes.

creditedCentsinteger

Somme TTC des avoirs émis sur cette facture, en centimes.

balanceDueCentsinteger

Reste à payer, en centimes : TTC moins avoirs moins encaissé, jamais négatif.

currencyenum

Devise des montants, toujours EUR.

EUR
updatedAtdate-time

Date de synchronisation : dernière modification de la facture (règlement, avoir, annulation…), à défaut sa création. Sert de clé à updated_since et au curseur.

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

status hors liste (dont DRAFT : les brouillons ne sont pas exposés), date issued_from / issued_to mal formée ou hors des années 1900 à 9999, client_id ou updated_since mal formé, limit inférieur à 1 ou non entier, curseur illisible. Un détail par champ.

400 INVALID_SITE_ID

site_id (ou Treats-Site-Id) n'est pas un identifiant valide.

404 SITE_NOT_FOUND

Le site demandé n'est pas ouvert à l'application.

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

Lire une facture émise

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

billing:read

Rend le détail d'une facture émise par un site ouvert à l'application : lignes imprimées, ventilation de TVA, totaux, encaissé, avoirs et reste à payer. Les totaux sont ceux du document émis ; la ventilation de TVA leur est égale au centime. Un brouillon, une pièce reprise qui n'est pas une facture, ou une facture d'un site non ouvert répond 404.

Paramètres

idchemin · uuidrequis

Identifiant de la facture.

Réponse

200La facture.

Champs de la réponse (25)
iduuid

Identifiant de la facture.

numberstring

Numéro de la facture.

siteIduuid

Site émetteur.

clientIduuid

Client facturé.

statusenum

Statut, comme en liste.

PENDINGPARTIALPAIDCANCELLED
issuedAtdate-time

Date d'émission (validation) ; à défaut, date de création.

dueDatedate

Date d'échéance.

peut être null
patientIdsuuid[]

Animaux concernés : celui de l'en-tête puis ceux des lignes (encaissement groupé de plusieurs animaux). Liste vide pour une vente au comptoir.

consultationIdsuuid[]

Consultations liées à la facture (en-tête et lignes). Liste vide si aucune.

globalDiscountPercentnumber

Remise globale de la facture, en pourcentage. null s'il n'y en a pas.

peut être null
subtotalHtCentsinteger

Total hors taxes des lignes avant toute remise, en centimes.

discountHtCentsinteger

Total des remises (remises de ligne et remise globale), hors taxes, en centimes.

totalHtCentsinteger

Total hors taxes, en centimes. Égal à la somme des bases de vatBreakdown.

totalVatCentsinteger

Total de TVA, en centimes. Égal à la somme des TVA de vatBreakdown.

totalTtcCentsinteger

Total toutes taxes comprises, en centimes.

paidCentsinteger

Montant déjà encaissé, en centimes.

creditedCentsinteger

Somme TTC des avoirs émis sur cette facture, en centimes.

balanceDueCentsinteger

Reste à payer, en centimes, jamais négatif.

currencyenum

Devise des montants, toujours EUR.

EUR
vatBreakdownInvoiceVatLine[]

Ventilation de la TVA par taux : c'est elle qui fait foi.

ratePercentnumber

Taux de TVA en pourcentage (20.00, 5.50…).

baseHtCentsinteger

Base hors taxes nette (après remises) à ce taux, en centimes.

vatCentsinteger

TVA à ce taux, en centimes.

linesInvoiceLine[]

Lignes telles qu'imprimées sur la facture remise au client. Les lignes internes ou incluses masquées n'y figurent pas.

iduuid

Identifiant de la ligne.

labelstring

Libellé imprimé sur la facture.

typeenum

ACT : acte médical. PRODUCT : produit vendu. SERVICE : autre prestation.

ACTPRODUCTSERVICEpeut être null
catalogItemIduuid

Article du catalogue facturé (voir GET /catalog/items/{id}). null pour une ligne libre.

peut être null
quantitynumber

Quantité.

unitstring

Unité de vente (comprimé, boîte…).

peut être null
unitPriceHtCentsinteger

Prix unitaire hors taxes, arrondi au centime (le prix saisi peut porter quatre décimales). Pour recompter, partir des totaux de ligne, pas de ce prix.

peut être null
unitPriceTtcCentsinteger

Prix unitaire toutes taxes comprises, en centimes.

peut être null
vatRatePercentnumber

Taux de TVA de la ligne, en pourcentage.

peut être null
discountPercentnumber

Remise de la ligne, en pourcentage.

peut être null
totalHtCentsinteger

Total hors taxes de la ligne après sa remise, en centimes.

peut être null
totalVatCentsinteger

TVA de la ligne, en centimes.

peut être null
totalTtcCentsinteger

Total toutes taxes comprises de la ligne tel qu'il se lit sur la facture. Sans remise globale, la somme des lignes égale totalTtcCents de la facture au centime ; avec une remise globale, les lignes sont rendues avant elle et leur somme dépasse le total du montant de la remise. Sur une ligne, totalHtCents + totalVatCents peut différer d'un centime de ce montant.

peut être null
patientIduuid

Animal concerné par la ligne.

peut être null
consultationIduuid

Consultation d'où vient la ligne.

peut être null
cancelledAtdate-time

Date d'annulation, pour une facture annulée.

peut être null
replacedByInvoiceIduuid

Facture qui remplace celle-ci, quand elle a été annulée puis refaite.

peut être null
replacesInvoiceIduuid

Facture annulée que celle-ci remplace.

peut être null
updatedAtdate-time

Date de synchronisation, comme en liste.

Erreurs propres à cette opération

404 INVOICE_NOT_FOUND

Aucune facture émise de ce périmètre ne porte cet identifiant (brouillon, autre organisation, site non ouvert, pièce qui n'est pas une facture).

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

Télécharger le PDF d'une facture émise

GET/api/partner/v1/invoices/{id}/pdf#

billing:read

Rend le PDF officiel de la facture, le même que celui remis au client, avec l'en-tête du site émetteur. Même périmètre que GET /invoices/{id}. Le fichier est servi avec Content-Disposition: inline; filename="facture-<id>.pdf".

Paramètres

idchemin · uuidrequis

Identifiant de la facture.

Réponse

200Le PDF de la facture. · fichier application/pdf

Erreurs propres à cette opération

404 INVOICE_NOT_FOUND

Aucune facture émise de ce périmètre ne porte cet identifiant.

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

Lister les encaissements

GET/api/partner/v1/payments#

billing:read

Rend une page des mouvements d'encaissement des sites ouverts à l'application : règlements de factures, acomptes et remboursements (montants négatifs). Un paiement enregistré sans site est rattaché au site de la facture qu'il règle. Les règlements de pièces reprises qui ne sont pas des factures sont exclus : un paiement ne pointe jamais vers une facture introuvable par l'API.

Tri par date de synchronisation (updatedAt) puis identifiant. Les modifications des 60 dernières secondes n'apparaissent qu'aux appels suivants. Aucune route ne lit un paiement par son identifiant.

Paramètres

fromrequête · date

Jour d'encaissement minimal, inclus (AAAA-MM-JJ, heure de Paris).

torequête · date

Jour d'encaissement maximal, inclus (AAAA-MM-JJ, heure de Paris).

site_idrequête · uuid

Restreint à un site ouvert à l'application (ou passer l'en-tête Treats-Site-Id). Absent : tous les sites ouverts.

updated_sincerequête · date-time

Ne rend que les mouvements dont updatedAt est postérieur ou égal à cet instant (ISO 8601).

cursorrequête · string

Curseur nextCursor de la page précédente, repassé tel quel. Absent : première page.

limitrequête · integer

Nombre de mouvements par page, de 1 à 200 (au-delà de 200, ramené à 200).

Défaut : 50
Treats-Site-Iden-tête · uuid

Site visé, à la place du paramètre site_id.

Réponse

200Une page de mouvements d'encaissement.

Champs de la réponse (2)
itemsPayment[]
iduuid

Identifiant du mouvement.

siteIduuid

Site de l'encaissement (celui de la facture réglée quand le paiement n'en porte pas).

kindenum

INVOICE : règlement d'une facture (invoiceId renseigné). DEPOSIT : acompte versé au compte client. DEPOSIT_REFUND : remboursement d'un acompte. CREDIT_NOTE_REFUND : remboursement d'un avoir (creditNoteId renseigné). Les remboursements ont un montant négatif.

INVOICEDEPOSITDEPOSIT_REFUNDCREDIT_NOTE_REFUND
methodenum

Moyen de paiement : carte, carte sans contact, espèces, chèque, virement, prélèvement sur le compte client (acompte), avoir, organismes de paiement ou de financement (ALMA, FLOA, ONEY_BANK, OXANE, PAYVET), et soldes comptables d'une créance (CERTIFICATE_UNRECOVERABLE : certificat d'irrécouvrabilité, CONTENTIOUS : contentieux, LOSS et PROFIT_AND_LOSS : passage en perte).

CARDCARD_CONTACTLESSCASHCHECKTRANSFERCLIENT_ACCOUNTALMAAVOIRCERTIFICATE_UNRECOVERABLECONTENTIOUSONEY_BANKOXANEPAYVETLOSSPROFIT_AND_LOSSFLOA
amountCentsinteger

Montant en centimes. Négatif pour un remboursement (DEPOSIT_REFUND, CREDIT_NOTE_REFUND).

refundedCentsinteger

Part de ce paiement déjà rendue au client, en centimes (0 si rien).

currencyenum

Devise des montants, toujours EUR.

EUR
receivedAtdate-time

Date d'encaissement.

invoiceIduuid

Facture réglée, pour un INVOICE.

peut être null
clientIduuid

Client payeur (à défaut, celui de la facture réglée).

peut être null
creditNoteIduuid

Avoir remboursé, pour un CREDIT_NOTE_REFUND.

peut être null
referencestring

Référence saisie avec le paiement (numéro de chèque, de transaction…).

peut être null
groupIduuid

Identifiant commun aux mouvements d'un même encaissement réparti sur plusieurs factures.

peut être null
updatedAtdate-time

Date de synchronisation : dernière modification du paiement (remboursement partiel…), à défaut sa date d'encaissement. Sert de clé à updated_since et au curseur.

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

Date from / to mal formée ou hors des années 1900 à 9999, updated_since mal formé, limit inférieur à 1 ou non entier, curseur illisible. Un détail par champ.

400 INVALID_SITE_ID

site_id (ou Treats-Site-Id) n'est pas un identifiant valide.

404 SITE_NOT_FOUND

Le site demandé n'est pas ouvert à l'application.

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

esc
↵ ouvrir↑↓ naviguerrésultats limités à ce site