Comment consulter, créer, faire évoluer et solder les factures fournisseurs d'une copropriété, et quelles contraintes régissent leur suppression.
Tous les appels de ce guide sont adressés à une copropriété précise (idCopro) et à un exercice comptable précis (idExercice) de cette copropriété : c'est le périmètre racine de chaque route. Une facture appartient toujours à un seul exercice — celui qui couvre sa date — mais cette appartenance peut changer après coup si la date de la facture est modifiée (voir Parcours C).
Une facture fournisseur (ou un avoir, qui est une facture au montant négatif) rattachée à un exercice et un fournisseur.
jeuxDecritures liste les écritures comptables déjà générées pour cette facture (lecture seule).
estSupprimable et estModifiable ne sont pas des indicateurs stockés : ils reflètent, au moment de la lecture, le résultat des mêmes règles générales que celles appliquées à la modification et à la suppression (exercice clôturé, ou écritures comptables ventilées sur un exercice antérieur clôturé — voir Limites & pièges connus). Ils ne couvrent pas la contrainte additionnelle propre au changement de fournisseur (Parcours C) : un estModifiable à true ne garantit donc pas que ce changement précis réussira.
Une ligne d'imputation, avec sa quotité de TVA et son rattachement comptable.
* rattachements optionnels, mutuellement indépendants. mutation n'est accepté que si la mutation visée a le statut « ouverte ».
Trois circuits de validation indépendants, chacun avec son propre statut : comptable, administrative, metier.
* date est renvoyée en lecture mais ignorée si elle est soumise en écriture — voir Parcours D.
Chaque appel nécessite un jeton d'accès OAuth2, et le client doit être explicitement autorisé sur la copropriété visée par idCopro, sinon la réponse est un 403. Toute ressource imbriquée dans l'URL (l'exercice, la facture, un document) est en plus vérifiée comme appartenant réellement à la copropriété — et, pour une facture, à l'exercice — passés dans le chemin : un identifiant valide mais rattaché ailleurs est refusé, même si le client est par ailleurs autorisé sur la copropriété.
/v2 et servies depuis https://syndic.datacopro.org en production, ou https://preprod-syndic.datacopro.org sur la plateforme de test.
Ces six parcours suivent le cycle de vie réel d'une facture : de sa consultation à sa saisie, son évolution, sa validation, son rapprochement bancaire, jusqu'à sa suppression.
Cas d'usage : afficher l'ensemble des factures et avoirs fournisseurs d'une copropriété, paginé, avec un compteur total fiable pour la pagination côté client.
Une facture appartient à un seul exercice : afficher toutes les factures d'une copropriété suppose de répéter cet appel pour chaque exercice à couvrir — il n'existe pas de route qui liste directement toutes les factures d'une copropriété tous exercices confondus.
displays=[id] seul, sans filtre ni pagination et trié par id, bascule sur un chemin plus léger qui ne renvoie que les identifiants — pratique pour connaître le nombre total de factures avant de paginer l'affichage détaillé.
fournisseur.id (opérateur égalité, une seule valeur) est appliqué directement à la constitution de la réponse plutôt qu'après coup : c'est la seule combinaison de filtre optimisée à ce niveau. Tout autre filtre est appliqué en mémoire sur l'ensemble déjà mis en cache pour l'exercice — ce qui reste correct, mais sans le même bénéfice de sélectivité.
Cas d'usage : saisir une facture reçue d'un fournisseur, avec une ou plusieurs lignes d'imputation, et déclencher (ou non) la génération immédiate des écritures comptables.
{
"facture": {
"montant": 128000,
"libelle": "Entretien ascenseur - T3",
"referenceUnique": "F-2026-00412",
"date": "2026-09-05 00:00:00",
"dateLimite": "2026-10-05 00:00:00",
"fournisseur": 4821,
"note": "",
"comptabilite": 1,
"details": [
{
"quantite": 1,
"libelle": "Contrat entretien T3",
"montant": 128000,
"tva": 21,
"dateDebut": "2026-07-01 00:00:00",
"dateFin": "2026-09-30 00:00:00",
"planComptable": 55310,
"contrat": 9012
}
]
}
}
fournisseur et details sont obligatoires ; les montants s'expriment en centimes.
montant n'est pas une valeur libre : elle doit être strictement égale à la somme des montant de chaque ligne de details, sans quoi la création échoue avec un message explicite. C'est un garde-fou de cohérence, pas une simple recopie — le total n'est jamais recalculé automatiquement à partir des lignes.
comptabilite: 1 déclenche la génération immédiate des écritures comptables de la facture ; à 0, la facture est enregistrée sans aucune écriture (utile pour une saisie en plusieurs temps, avant validation). Chaque ligne peut en plus être rattachée, indépendamment, à un contrat, une intervention, un coproprietaire, ou une mutation — mais seulement si cette mutation a le statut « ouverte » : une mutation déjà clôturée est silencieusement ignorée comme rattachement possible.
date doit tomber dans les bornes de l'exercice ciblé par la route (entre sa date de début et sa date de fin) au moment de la création — contrairement à la modification, où changer la date peut faire basculer la facture vers un autre exercice (Parcours C). referenceUnique est facultative et, malgré son nom, aucune vérification d'unicité n'est appliquée dessus : deux factures, y compris du même fournisseur, peuvent parfaitement partager la même référence.
Cas d'usage : corriger le libellé, la date, la référence ou le fournisseur d'une facture déjà saisie.
Seuls les champs présents dans la requête sont modifiés — pas de remplacement complet de l'objet. Champs modifiables : referenceUnique, libelle, note, referenceComptable, fournisseur, date, datePiece, dateLimite, validation (voir Parcours D).
date recalcule l'exercice de rattachement de la facture à partir de la nouvelle date — la facture peut donc changer d'exercice suite à cette modification, sans appel supplémentaire. Un changement de libelle ou de date régénère aussi les écritures comptables existantes de la facture pour rester cohérentes.
datePiece ne peut pas être postérieure à aujourd'hui, et dateLimite ne peut pas être antérieure à la date de la facture — deux contraintes vérifiées à chaque modification, pas seulement à la création. Changer fournisseur est bloqué si la facture n'est pas modifiable (voir Limites & pièges connus), ou si un règlement déjà associé à la facture couvre aussi d'autres factures : dans ce cas, le fournisseur ne peut pas être changé sans d'abord dissocier ce règlement partagé.
Cas d'usage : faire progresser une facture dans un circuit de validation à plusieurs regards (comptable, administratif, métier) avant qu'elle ne soit considérée comme définitivement acquise.
{
"validation": {
"comptable": { "statut": "validé" }
}
}
Le même appel que le Parcours C, avec uniquement l'objet validation. Les trois circuits (comptable, administrative, metier) sont indépendants et se mettent à jour séparément — modifier l'un ne touche pas le statut des deux autres.
statut sont acceptées : à valider, indéfini, validé. Une valeur hors de cette liste n'est ni rejetée ni signalée par une erreur : elle est silencieusement ignorée, et le statut du circuit visé reste inchangé. De même, un champ date soumis dans l'objet de validation est toujours ignoré, y compris s'il est présent — la date de validation n'est jamais pilotable par ce biais.
Cas d'usage : marquer manuellement une facture comme soldée dans le cadre d'un rapprochement bancaire, ou revenir sur ce marquage.
GET alors qu'elles modifient l'état de la facture (estSoldee) — une lecture n'est donc pas ici, contrairement à l'usage HTTP habituel, une opération sans effet de bord. Solder n'a aucune condition bloquante ; désolder, en revanche, échoue en 400 si la facture est déjà réglée (un règlement bancaire lui est effectivement associé) — le désoldage ne peut porter que sur un rapprochement manuel, pas défaire un règlement réel.
Cas d'usage : retirer une facture saisie par erreur, ou une seule de ses lignes d'imputation.
| Méthode | Route | Rôle |
|---|---|---|
| GET | /v2/copro/{idCopro}/exercice/{idExercice}/factures.json | Liste des factures d'un exercice |
| POST | /v2/copro/{idCopro}/exercice/{idExercice}/facture.json | Crée une facture |
| GET | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}.json | Détail d'une facture |
| PUT | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}.json | Modifie une facture (champs et/ou statut de validation) |
| DELETE | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}.json | Supprime une facture |
| POST | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}/detail.json | Ajoute une ligne à une facture existante |
| PUT | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}/detail/{idDetail}.json | Modifie une ligne de facture |
| DELETE | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}/detail/{idDetail}.json | Supprime une ligne de facture |
| POST | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}/facture-detail/{idDetail}/consommation.json | Enregistre un volume de consommation sur une ligne |
| GET | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}/solder.json | Marque la facture comme soldée |
| GET | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}/desolder.json | Annule le marquage soldée (refusé si réglée) |
| POST | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}/document/{idDocument}.json | Associe un document justificatif à la facture |
| PUT | /v2/copro/{idCopro}/exercice/{idExercice}/facture/{idFacture}/delier-document.json | Retire le document associé (refusé selon état de la facture) |
Toutes ces routes attendent une extension de format explicite en fin de chemin (par exemple .json). Une facture ne peut porter qu'un seul document justificatif à la fois : y associer un nouveau document tant qu'un autre y est déjà lié n'ajoute pas un second justificatif.
La liste des factures d'un exercice accepte trois familles de paramètres de requête génériques, communs à l'ensemble de l'API :
filters — restreint les résultats, par exemple filters[fournisseur.id]==4821.sorts / pagination — ordonnancement et découpage en pages de la liste.displays — restreint ou ouvre l'ensemble des champs renvoyés, parmi ceux déjà présents dans la réponse de la route appelée.displays=[id] seul, sans filtre ni pagination, trié par id, bascule sur un chemin de réponse allégé qui ne renvoie que les identifiants (voir Parcours A) — le moyen le plus léger de connaître le nombre total de factures d'un exercice avant de paginer un affichage détaillé.
referenceUnique n'est ni obligatoire ni vérifiée comme unique, malgré son nom : deux factures peuvent librement partager la même référence (Parcours B).montant doit être strictement égal à la somme des montants des lignes de details à la création, sinon la requête échoue (Parcours B).GET alors qu'ils modifient son état — ne pas supposer qu'un appel GET est ici sans effet de bord (Parcours E).400 : le désoldage ne défait qu'un rapprochement manuel, jamais un règlement bancaire réel (Parcours E).date d'une facture peut la faire changer d'exercice de rattachement, sans appel supplémentaire ni confirmation (Parcours C)..../facture/{id}/detail/{id} pour la lecture, la modification et la suppression d'une ligne, mais .../facture/{id}/facture-detail/{id}/consommation pour y enregistrer un volume de consommation. Ce n'est pas une coquille de ce guide : c'est ainsi que l'API expose réellement ces deux routes (référence des endpoints, §04).montant et la somme des details[].montant doivent déjà correspondre exactement dans la requête envoyée. Si ce n'est pas le cas, la création échoue avec un message d'erreur explicite plutôt que de recalculer l'un à partir de l'autre ou d'accepter l'incohérence. Parcours BestModifiable ne suffit toutefois pas à l'anticiper avec certitude, voir Modèle & périmètre). Ensuite, même une facture par ailleurs modifiable reste bloquée si son règlement est partagé avec d'autres factures — le fournisseur du règlement ne pourrait alors plus correspondre à toutes les factures qu'il couvre. Dans ce second cas, il faut d'abord dissocier ce partage (ou traiter les factures concernées séparément) avant de pouvoir changer le fournisseur de celle-ci. Parcours C