Guide d'intégration · API Datacopro
Comment récupérer, pour un ensemble de copropriétés, la liste de leurs comptes bancaires, leur solde théorique et leur état de rapprochement comptable.
Ce document décrit uniquement le contrat de l'API Datacopro : quels appels effectuer, dans quel ordre, avec quels paramètres, et pourquoi. Aucune connaissance d'un logiciel de gestion de copropriétés en particulier n'est nécessaire pour le suivre — un tel logiciel n'est cité qu'à titre d'illustration, pour montrer un enchaînement d'appels réellement utilisé en production.
Le sujet met en jeu cinq objets. Chacun est décrit ici par ce que l'API renvoie réellement, pas par sa structure interne.
Un compte bancaire réel rattaché à une copropriété.
Un mouvement brut du relevé bancaire (import comptable, saisie manuelle ou agrégateur bancaire).
Une écriture comptable rattachée à un compte de trésorerie (donc à un compte bancaire), portée par un exercice.
Une période comptable de la copropriété.
Le cumul crédit/débit du compte de trésorerie lié à un compte bancaire, pour un exercice donné et à une date donnée.
Chaque route est bornée à une copropriété (idCopro dans le chemin). Le client doit être autorisé sur cette copropriété précise, sinon la réponse est un 403. Toute ressource imbriquée (un compte, un exercice) est en plus vérifiée comme appartenant réellement à la copropriété passée dans l'URL : un identifiant valide mais rattaché à une autre copropriété est refusé, même si le client y est par ailleurs autorisé.
Toutes les routes de ce guide sont préfixées /v2 et servies depuis https://syndic.datacopro.org en production, ou https://preprod-syndic.datacopro.org sur la plateforme de test.
Cette réponse porte, entre autres, la liste complète des exercices comptables de la copropriété (dates, statut clôturé) — la suite du parcours en a besoin pour savoir sur quels exercices interroger.
Cet appel n'est pas un GET pur : selon la fraîcheur du cache serveur, il peut déclencher en effet de bord la création des exercices comptables à venir manquants et la mise à jour, en base, du statut actif/clôturé de la copropriété. Un appel répété n'est donc pas garanti idempotent au sens strict, même si son intention est la lecture.
date fixe le jour auquel le solde bancaire théorique de chaque compte est calculé — pas seulement un filtre de sélection.
Le solde théorique n'est pas stocké tel quel : il est reconstitué à partir du dernier relevé connu (un montant et sa date), en ajoutant ou retranchant les mouvements bancaires survenus entre ce relevé et la date demandée. Changer date change donc le solde renvoyé, pas seulement l'ensemble de comptes affichés.
Sans nouvel appel : parmi les exercices renvus à l'étape 1, ne garder que ceux non clôturés dont la date de début précède ou égale la date demandée. C'est le socle des étapes 4 et 6.
Renvoie, par défaut, uniquement les écritures pas encore rapprochées de cet exercice.
Cette route ne prend pas de compte bancaire en paramètre : elle renvoie les écritures de trésorerie de tous les comptes bancaires de la copropriété pour cet exercice. Si la copropriété a plusieurs comptes, un filtre supplémentaire côté client est nécessaire pour ne garder que les écritures dont le compte de trésorerie correspond à celui du compte bancaire affiché (le compte de trésorerie lié, renvoyé à l'étape 2). Sans ce filtre, le nombre et le montant affichés mélangent tous les comptes.
Si aucune écriture de trésorerie n'existe pour l'exercice (par ex. un exercice sans mouvement bancaire), la réponse est simplement un tableau vide — pas d'erreur distincte à intercepter.
rapprochees=0 ne garde que les transactions non rapprochées ; rapprochees=1 ne garderait que celles déjà rapprochées ; en l'absence du paramètre, aucun filtre de rapprochement n'est appliqué. date exclut toute transaction postérieure à cette date.
La réponse ne porte aucun champ indiquant si une transaction donnée est rapprochée : le statut sert uniquement à filtrer côté serveur, il n'est pas exposé comme attribut. Pour connaître le détail d'un rapprochement précis (montant rapproché, date), il faut interroger GET /v2/copro/{idCopro}/compte/{idCompte}/transaction/{idTransaction}/rapprochements transaction par transaction.
compte5120 est le nom de champ réel, dans la réponse JSON, du compte de trésorerie lié — hérité du plan comptable belge/français, où la classe 512 désigne les comptes bancaires. C'est ce nom qu'il faut utiliser dans displays, pas un nom fonctionnel de son choix.
cloture=0 exclut les écritures de clôture du cumul crédit/débit renvoyé — utile pour lire un solde "brut", avant l'écriture de clôture de l'exercice. Trier les exercices couvrant la période par date de fin et cumuler leurs crédit/débit donne le solde comptable total.
Le paramètre cloture ne porte pas sur le statut clôturé de l'exercice (utilisé à l'étape 3 pour sélectionner les exercices ouverts) : il indique seulement si les écritures comptables de clôture, elles-mêmes, doivent entrer dans le cumul crédit/débit. Un exercice non clôturé peut très bien contenir de telles écritures (clôture anticipée d'un compte précis), et un exercice clôturé reste interrogeable avec cloture=0.
Passer une liste displays non vide bascule cet appel en mode liste blanche : tout champ de premier niveau absent de la liste est retiré de la réponse, y compris soldeBancaire. Avec la liste ci-dessus, le champ soldeBancaire n'apparaît donc pas du tout dans la réponse (pas de valeur obsolète ni nulle : la clé elle-même est absente) — voir la section Paramètres transverses.
Si le compte bancaire n'a pas de compte de trésorerie lié, cette route ne renvoie aucun solde comptable exploitable — un compte peut donc afficher un solde bancaire sans jamais avoir de contrepartie comptable calculable.
Écart = (solde bancaire théorique, ajusté du montant des transactions non rapprochées) − (solde comptable, ajusté du montant des écritures de trésorerie non rapprochées). Un écart nul ou expliqué entièrement par le rapprochement en attente est normal ; un écart résiduel signale une anomalie à vérifier.
Même séquence que le Parcours 1, répétée pour chaque copropriété et chaque compte bancaire du portefeuille, puis sommée. Deux nuances propres à l'agrégation :
Un compte marqué comme legacy ("ancienne banque") est en général exclu de l'agrégat : il ne reflète plus une activité bancaire réelle et fausserait le solde cumulé si on le laissait entrer dans le calcul.
Sur un grand portefeuille, ce parcours multiplie les appels (fiche copropriété × comptes × exercices × transactions × solde par exercice, pour chaque copropriété). Il n'existe pas de route agrégée côté serveur : la synthèse est entièrement reconstruite côté client, appel après appel.
| Méthode | Route | Rôle |
|---|---|---|
| GET | /v2/copro/{idCopro} | Fiche de la copropriété : porte la liste de ses exercices comptables. |
| GET | /v2/copro/{idCopro}/comptes | Liste des comptes bancaires de la copropriété, avec solde théorique à une date donnée. |
| GET | /v2/copro/{idCopro}/compte/{idCompte}/transactions | Transactions bancaires d'un compte, filtrables par statut de rapprochement et par date. |
| GET | /v2/copro/{idCopro}/compte/{idCompte}/transaction/{idTransaction}/rapprochements | Détail des rapprochements enregistrés pour une transaction précise. |
| GET | /v2/copro/{idCopro}/exercice/{idExercice}/ecrituresbanque | Écritures de trésorerie d'un exercice, en attente de rapprochement par défaut. |
| GET | /v2/copro/{idCopro}/exercice/{idExercice}/compte/{idCompte} | Solde crédit/débit du compte de trésorerie lié, pour un exercice donné. |
Liste de champs à inclure explicitement (ex. displays[]=compte5120.credit) ou à exclure en préfixant par ! (ex. displays[]=!documents). Sans ce paramètre, tous les champs par défaut de la ressource sont renvoyés.
Sur l'appel de solde par exercice, dès qu'une seule inclusion positive est présente dans displays, tout champ non listé est retiré de la réponse — y compris soldeBancaire, qui n'est alors ni recalculé ni renvoyé, sauf s'il figure lui-même explicitement dans la liste. Une liste composée uniquement d'exclusions (!...) ne déclenche pas ce comportement : les champs par défaut restent tous présents, exclusions mises à part. Ne pas passer displays du tout recalcule systématiquement le solde bancaire, ce qui coûte plus cher : un compte avec beaucoup de transactions historiques implique de les parcourir toutes pour reconstituer le solde théorique à la date demandée.
rapprochees=1, une fois avec rapprochees=0), soit demander le détail par transaction.soldeBancaire, la clé est purement et simplement absente du JSON renvoyé — un succès HTTP peut donc masquer l'absence de cette donnée si elle n'a pas été explicitement redemandée.soldeBancaire fait disparaître ce champ de la réponse — la clé est absente, pas seulement non recalculée ou nulle. Si les deux soldes sont nécessaires dans le même flux, soit ajouter soldeBancaire à displays, soit le récupérer séparément via la liste des comptes (Parcours 1, étape 2).