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#
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 ( |
| issued_torequête · date | Jour d'émission maximal, inclus ( |
| site_idrequête · uuid | Restreint à un site ouvert à l'application (ou passer l'en-tête |
| updated_sincerequête · date-time | Ne rend que les avoirs émis à cet instant ou après (ISO 8601). |
| cursorrequête · string | Curseur |
| 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 |
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 |
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 |
| 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. |
| settlementCreditNoteSettlement | Au détail : la restitution faite au client. |
| kindenum |
REFUNDDEPOSIT |
| methodenum | Moyen du remboursement (voir 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 |
| linesCreditNoteLine[] | Au détail : les lignes de l'avoir. |
| 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é à |
| nextCursorstring | Curseur opaque de la page suivante, à repasser tel quel dans |
Erreurs propres à cette opération
| 400 INVALID_FIELD | Date |
| 400 INVALID_SITE_ID |
|
| 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}#
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 |
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 |
| 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. |
| settlementCreditNoteSettlement | Au détail : la restitution faite au client. |
| kindenum |
REFUNDDEPOSIT |
| methodenum | Moyen du remboursement (voir 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 |
| linesCreditNoteLine[] | Au détail : les lignes de l'avoir. |
| 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é à |
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#
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#
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. |
| issued_fromrequête · date | Jour d'émission minimal, inclus ( |
| issued_torequête · date | Jour d'émission maximal, inclus ( |
| site_idrequête · uuid | Restreint à un site ouvert à l'application (ou passer l'en-tête |
| updated_sincerequête · date-time | Ne rend que les factures dont |
| cursorrequête · string | Curseur |
| 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 |
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 |
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, |
| 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 |
| updatedAtdate-time | Date de synchronisation : dernière modification de la facture (règlement, avoir, annulation…), à défaut sa création. Sert de clé à |
| nextCursorstring | Curseur opaque de la page suivante, à repasser tel quel dans |
Erreurs propres à cette opération
| 400 INVALID_FIELD |
|
| 400 INVALID_SITE_ID |
|
| 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}#
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. |
| 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 |
| totalVatCentsinteger | Total de TVA, en centimes. Égal à la somme des TVA de |
| 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 |
| vatBreakdownInvoiceVatLine[] | Ventilation de la TVA par taux : c'est elle qui fait foi. |
| ratePercentnumber | Taux de TVA en pourcentage ( |
| 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 |
ACTPRODUCTSERVICEpeut être null |
| catalogItemIduuid | Article du catalogue facturé (voir |
| 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 |
| 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#
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#
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 ( |
| torequête · date | Jour d'encaissement maximal, inclus ( |
| site_idrequête · uuid | Restreint à un site ouvert à l'application (ou passer l'en-tête |
| updated_sincerequête · date-time | Ne rend que les mouvements dont |
| cursorrequête · string | Curseur |
| 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 |
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 |
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 ( CARDCARD_CONTACTLESSCASHCHECKTRANSFERCLIENT_ACCOUNTALMAAVOIRCERTIFICATE_UNRECOVERABLECONTENTIOUSONEY_BANKOXANEPAYVETLOSSPROFIT_AND_LOSSFLOA |
| amountCentsinteger | Montant en centimes. Négatif pour un remboursement ( |
| refundedCentsinteger | Part de ce paiement déjà rendue au client, en centimes (0 si rien). |
| currencyenum | Devise des montants, toujours EUR |
| receivedAtdate-time | Date d'encaissement. |
| invoiceIduuid | Facture réglée, pour un |
| clientIduuid | Client payeur (à défaut, celui de la facture réglée). peut être null |
| creditNoteIduuid | Avoir remboursé, pour un |
| 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é à |
| nextCursorstring | Curseur opaque de la page suivante, à repasser tel quel dans |
Erreurs propres à cette opération
| 400 INVALID_FIELD | Date |
| 400 INVALID_SITE_ID |
|
| 404 SITE_NOT_FOUND | Le site demandé n'est pas ouvert à l'application. |
Et les erreurs communes à toutes les opérations : erreurs et limites.