Comment consulter, enregistrer, faire évoluer le statut de validation, comptabiliser et supprimer les règlements reçus des copropriétaires d'une copropriété.
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. Un encaissement appartient toujours à un seul exercice — celui déterminé par sa date de paiement au moment de sa création (voir Parcours C).
Un règlement reçu d'un copropriétaire (ou un remboursement, si son montant est négatif), rattaché à un exercice et à un copropriétaire.
jeuxDecritures liste les écritures comptables déjà générées pour cet encaissement (lecture seule) — un encaissement peut exister sans aucune, si sa comptabilisation n'a pas encore été déclenchée (Parcours C).
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 réappliquées à la modification et à la suppression (dépôt bancaire associé, exercice clôturé — voir Limites & pièges connus). estSupprimable ajoute une condition propre à la suppression seule (rapprochement bancaire partiel ou total), qu'estModifiable ne couvre pas.
planComptable désigne le poste comptable d'imputation ; il n'est facultatif qu'à la création, et seulement pour certains modes de paiement (voir Parcours C). createurContexte identifie l'auteur de la création de l'encaissement (utilisateur humain ou client API) — champ de traçabilité en lecture seule, sans effet sur le comportement des autres routes de ce guide.
Permet de répartir un même règlement entre plusieurs destinations comptables et/ou plusieurs lots plutôt que d'utiliser un montant global unique.
type prend l'une de cinq valeurs : charges, avances, travaux, emprunts, fonds travaux.
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. L'exercice et, selon la route, l'encaissement référencés dans le chemin sont vérifiés comme appartenant réellement à la copropriété — et l'encaissement à l'exercice — passés dans l'URL : un identifiant valide mais rattaché ailleurs est refusé, même si le client est par ailleurs autorisé sur la copropriété. Aucune restriction supplémentaire par rôle n'existe selon le type d'opération réalisée sur un encaissement, y compris pour faire évoluer l'un des trois circuits de validation (Parcours D).
/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'un règlement reçu d'un copropriétaire : de sa consultation à son enregistrement, sa comptabilisation, sa validation, jusqu'à la régénération de ses écritures ou sa suppression.
Cas d'usage : afficher l'historique des règlements reçus par une copropriété sur une période donnée.
Un encaissement appartient à un seul exercice : afficher l'historique complet d'une copropriété suppose de répéter cet appel pour chaque exercice à couvrir — il n'existe pas de route qui liste directement tous les encaissements d'une copropriété tous exercices confondus.
filters n'a pas un coût uniforme selon le champ filtré : un filtre sur un champ directement indexable bénéficie d'une présélection rapide, tandis qu'un filtre sur un champ plus complexe reste correctement appliqué au résultat final, mais après avoir d'abord chargé l'ensemble des encaissements de l'exercice — un coût qui croît avec la taille de l'historique de la copropriété, quel que soit le nombre de résultats effectivement retenus par le filtre.
Cas d'usage : récupérer l'état actuel d'un encaissement avant d'agir dessus — par exemple pour connaître le statut courant de chaque circuit de validation avant de le faire évoluer (Parcours D), ou pour confirmer qu'un encaissement créé plus tôt existe bien (Parcours C).
Cas d'usage : saisir un règlement reçu d'un copropriétaire — par chèque, virement, prélèvement ou tout autre mode de paiement — et déclencher (ou non) la génération immédiate de sa comptabilité.
{
"encaissement": {
"numero": "1234567",
"libelle": "Règlement appel de fonds T3",
"referenceComptable": "",
"date": "2026-09-05 00:00:00",
"coproprietaire": 9931,
"contact": null,
"montant": 45000,
"banque": "BNP Paribas",
"comptabilite": 1
}
}
coproprietaire et un montant non nul (via montant ou via details) sont obligatoires ; les montants s'expriment en centimes. contact permet d'attribuer le paiement à un tiers payeur — par exemple un locataire réglant pour le compte du propriétaire — distinct du copropriétaire bénéficiaire.
planComptable) est facultatif, mais ne se déduit automatiquement que pour deux modes de paiement précis : chèque (identifiant 1) et prélèvement (identifiant 4), sur leur poste d'attente respectif — c'est pourquoi l'exemple ci-dessus, qui enregistre un chèque, ne le fournit pas. Pour tout autre mode de paiement — virement, espèces, carte bancaire, télérèglement… — planComptable: <id> doit être ajouté explicitement dans l'objet encaissement, au même niveau que montant ou banque, sinon la création échoue.
comptabilite: 1 déclenche la génération immédiate des écritures comptables de l'encaissement dans le même appel ; à 0 ou en son absence (valeur par défaut), l'encaissement est enregistré sans aucune écriture — utile pour une saisie en plusieurs temps. Un encaissement resté sans comptabilité se repère à la lecture par un tableau jeuxDecritures vide, et se comptabilise ensuite via un appel séparé (Parcours E).
date doit être comprise entre le début de l'exercice ciblé par la route et aujourd'hui inclus — une date future ou antérieure au début de l'exercice est refusée. Comme alternative (ou en complément) à montant, details permet de répartir le règlement entre plusieurs destinations comptables ou plusieurs lots ; dans ce cas montant peut valoir 0, mais laisser à la fois montant à 0 et details vide fait échouer la création.
comptabilite: 1 — si cette comptabilisation échoue, l'encaissement existe malgré tout. En cas de doute sur le résultat d'un appel, mieux vaut consulter l'encaissement (Parcours B) que retenter sa création.
Cas d'usage : faire progresser un encaissement dans un circuit de validation à plusieurs regards (comptable, administratif, métier) avant qu'il ne soit considéré comme définitivement acquis.
{
"validation": {
"comptable": { "statut": "validé" }
}
}
Le même appel sert aussi à modifier d'autres champs de l'encaissement (voir référence des endpoints) ; seul l'objet validation est représenté ici. 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, ou un nom de circuit inconnu, n'est ni rejeté ni signalé par une erreur : il est silencieusement ignoré, et le statut visé reste inchangé. De même, un champ date soumis dans l'objet de validation est toujours ignoré — la date de validation n'est jamais pilotable par ce biais.
estModifiable (voir Modèle & périmètre).
Cas d'usage : comptabiliser un encaissement resté sans écriture après sa création (Parcours C), ou reconstruire ses écritures après une correction en amont (changement de poste comptable, de mode de paiement…).
La première route génère un jeu d'écritures pour un encaissement qui n'en a encore aucun. La seconde annule le jeu existant puis en régénère un — c'est celle à utiliser si des écritures existent déjà.
Cas d'usage : retirer un règlement saisi par erreur.
estSupprimable à une lecture antérieure — une requête qui ne les respecte pas échoue en 400 avec un message explicite plutôt que de supprimer partiellement.
jeuxDecritures vide) et un autre pour tout encaissement déjà rapproché — ce dernier état n'étant en pratique jamais supprimable (Parcours F). La régénération des écritures (Parcours E) y est réservée à un profil avancé de l'interface, par prudence : l'API elle-même ne restreint pourtant cette action à aucun rôle particulier (voir Contrôle d'accès).
| Méthode | Route | Rôle |
|---|---|---|
| GET | /v2/copro/{idCopro}/exercice/{idExercice}/encaissements.json | Liste des encaissements d'un exercice |
| GET | /v2/copro/{idCopro}/exercice/{idExercice}/encaissement/{idEncaissement}.json | Détail d'un encaissement |
| POST | /v2/copro/{idCopro}/exercice/{idExercice}/encaissement/paiement/{idCstModePaiement}.json | Crée un encaissement |
| PUT | /v2/copro/{idCopro}/exercice/{idExercice}/encaissement/{idEncaissement}.json | Modifie un encaissement (champs et/ou statut de validation) |
| DELETE | /v2/copro/{idCopro}/exercice/{idExercice}/encaissement/{idEncaissement}.json | Supprime un encaissement |
| POST | /v2/copro/{idCopro}/exercice/{idExercice}/ecritures/encaissement/{idEncaissement}.json | Génère les écritures comptables d'un encaissement qui n'en a pas encore |
| POST | /v2/copro/{idCopro}/exercice/{idExercice}/ecritures/encaissement/{idEncaissement}/rejouer.json | Annule puis régénère les écritures comptables existantes |
| GET | /v2/type/mode-paiement.json | Liste des modes de paiement disponibles (fournit idCstModePaiement) |
| GET | /v2/copro/{idCopro}/coproprietaires.json | Liste des copropriétaires pouvant être désignés comme bénéficiaire |
Toutes ces routes attendent une extension de format explicite en fin de chemin (par exemple .json). Les deux routes auxiliaires en bas de tableau ne portent pas de segment exercice : la liste des modes de paiement est globale, et la liste des copropriétaires est propre à la copropriété seule.
La liste des encaissements d'un exercice accepte un paramètre de requête générique, commun à l'ensemble de l'API :
filters — restreint les résultats, avec la même syntaxe que le reste de l'API. Son coût réel dépend du champ filtré : certains bénéficient d'une présélection rapide, d'autres sont appliqués après coup sur l'ensemble des encaissements de l'exercice (voir Parcours A).sorts ni pagination : quel que soit le filtre appliqué, l'ensemble des résultats correspondants est toujours renvoyé en un seul appel — un point à anticiper pour une copropriété à l'historique de règlements volumineux.
comptabilite: 1) dans la même requête ; sans cela, un appel séparé est nécessaire (Parcours C, E).comptabilite: 1 reste sans aucune écriture tant qu'un appel explicite de génération ou de rejeu n'a pas été effectué — un tableau jeuxDecritures vide à la lecture en est le signal. Parcours C, EestSupprimable vaut true au moment où je le lis restera-t-il supprimable si je le supprime juste après ?400 à la suppression même si une lecture antérieure indiquait estSupprimable: true. Parcours F, Modèle & périmètre