Rapprocher les transactions bancaires avec l'API Datacopro

Cadrage

Modèle & périmètre

Le rapprochement bancaire met en relation deux objets qui existent indépendamment l'un de l'autre dans Datacopro, puis les relie par un troisième objet, le lien de rapprochement lui-même.

Tout ce périmètre est rattaché à une copropriété (idCopro), elle-même optionnellement regroupée dans un domaine (idDomaine) lorsqu'un même mandataire gère plusieurs copropriétés — c'est ce regroupement qui permet de traiter un portefeuille entier en une seule boucle plutôt que copropriété par copropriété. Les écritures, elles, sont en plus rattachées à un exercice comptable précis (une période datée), déterminé par la date du mouvement bancaire — un même compte bancaire peut donc voir ses écritures se répartir sur deux exercices si l'un vient d'être ouvert. Cet exercice n'apparaît pas comme un champ de l'écriture elle-même : c'est l'URL de l'appel (/exercice/{idExercice}/) qui porte ce rattachement.

Deux champs de la transaction se ressemblent mais répondent à des questions différentes : type décrit l'instrument bancaire tel que rapporté par le relevé (par exemple un virement, un chèque, un ordre permanent), tandis que typeTransaction décrit le canal par lequel la transaction est entrée dans Datacopro (voir parcours 3) — c'est ce second champ, et lui seul, qu'il faut renvoyer tel quel lors d'un rapprochement.

Les routes de ce guide se terminent par .{_format} : à ce jour, seule la valeur json est utilisée en pratique (/v2/copro/42/transactions.json).

Cadrage

Contrôle d'accès

Chaque appel qui porte sur une copropriété ou un domaine vérifie que le client authentifié est autorisé sur ce périmètre précis ; dans le cas contraire l'API répond 403, avant même de regarder si la ressource demandée existe.

Ce contrôle est vérifié deux fois de suite sur les appels qui traversent deux niveaux d'imbrication : par exemple, pour rapprocher une écriture, l'API vérifie d'abord que le client est autorisé sur la copropriété de l'URL, puis que l'écriture visée appartient bien à cette même copropriété — un identifiant d'écriture syntaxiquement valide mais rattaché à une autre copropriété est également refusé en 403, même si le client est par ailleurs autorisé sur sa propre copropriété.

Une fois ce contrôle passé, deux autres codes distinguent les refus qui suivent : un 404 pour un identifiant syntaxiquement valide mais qui ne désigne aucune ressource réelle, et un 400 pour toutes les règles de validation métier détaillées dans les parcours ci-dessous (transaction déjà rapprochée, montant incohérent, clé de répartition manquante…).

Parcours 1 / 7

01Repérer le périmètre à traiter

Avant de traiter la banque d'une copropriété, il faut d'abord savoir laquelle traiter. Pour un mandataire qui gère un portefeuille, cela part du domaine plutôt que d'une copropriété isolée.

Parcours 2 / 7

02Rassembler les données d'une copropriété

Pour chaque copropriété active, le traitement a besoin de trois familles de données avant de pouvoir commencer à apparier quoi que ce soit : les mouvements bancaires bruts, les écritures comptables qui attendent d'être rapprochées, et le contexte qui permettra d'identifier ce que chaque mouvement représente.

Selon ce que la suite du parcours doit faire avec un mouvement non apparié (parcours 4 à 6), deux appels complémentaires sont utiles à ce stade :

Si le traitement doit aussi couvrir les frais bancaires ou les intérêts créditeurs (parcours 7), il faut en plus la clé de répartition générale de la copropriété :

La clé de type general répartit un montant sur l'ensemble des lots de la copropriété — c'est celle qu'attend une écriture dont le poste de destination est réparti plutôt qu'imputé sur un compte précis (voir parcours 7).

Parcours 3 / 7

03Rapprocher une transaction et une écriture

C'est le cas central : une écriture comptable existe déjà (elle a été saisie ou importée par ailleurs) et un mouvement bancaire lui correspond. Il reste à poser le lien entre les deux.

{
  "idTransaction": 48213,
  "idEcriture": 102938,
  "typeTransaction": "budgetinsight"
}

Deux autres cas sont refusés systématiquement, quel que soit le sens et l'origine : une écriture qui appartient à une annulation (elle-même annulée, ou étant l'origine d'une annulation) ne peut pas être rapprochée, et une écriture dont le compte de destination n'est pas un compte de type banque n'est pas éligible — même si son montant correspond par coïncidence à celui d'une transaction.

Pour vérifier les liens déjà posés sur un exercice avant d'en créer un nouveau, ou pour un audit :

Pour défaire un lien créé par erreur :

Parcours 4 / 7

04Comptabiliser un règlement identifié dans le libellé

Une transaction bancaire n'a pas toujours d'écriture qui l'attend déjà : c'est le cas d'un paiement fournisseur qui n'a pas encore été saisi. Si son libellé bancaire contient une référence de facture reconnaissable, l'API permet de créer directement le règlement — et donc l'écriture comptable qui va avec — à partir de la seule transaction.

Relit le règlement créé pour en extraire l'écriture générée, en vue du second appel de rapprochement décrit ci-dessus.

Parcours 5 / 7

05Comptabiliser un transfert interne entre deux comptes

Un virement d'un compte de la copropriété vers un autre compte de la même copropriété (par exemple du compte courant vers un compte rémunéré) apparaît côté banque comme deux transactions symétriques, une sur chaque compte, au même montant et à la même date.

Comme pour le règlement (parcours 4), créer le transfert ne rapproche aucune des deux transactions bancaires : chacune des deux jambes doit être rapprochée séparément via l'endpoint du parcours 3, à partir des deux écritures que le transfert a générées.

Parcours 6 / 7

06Comptabiliser un encaissement copropriétaire

Un versement reçu d'un copropriétaire peut être identifié de deux façons, à tenter dans cet ordre : par une référence structurée présente dans le libellé bancaire, ou, à défaut, par une correspondance de montant avec le solde d'un copropriétaire.

Comme pour le règlement (parcours 4), créer l'encaissement ne rapproche pas la transaction bancaire d'origine : c'est, là aussi, un second appel explicite vers l'endpoint du parcours 3.

Parcours 7 / 7

07Comptabiliser des frais bancaires ou des intérêts créditeurs

Certains mouvements ne correspondent ni à un règlement, ni à un encaissement, ni à un transfert : ce sont des frais prélevés par la banque, ou des intérêts créditeurs versés sur un compte rémunéré. Ils se comptabilisent par une écriture libre équilibrée plutôt que par un des endpoints métier précédents.

{
  "libelle": "Frais de tenue de compte",
  "date": "2026-03-14 00:00:00",
  "ecritures": [
    { "debit": 1200, "credit": 0,
      "repartition": { "type": "{idPosteFraisBancaires}", "cle": "{idCleGenerale}" } },
    { "debit": 0, "credit": 1200,
      "repartition": { "planComptable": "{idCompteBanque}" } }
  ]
}

Comme pour le règlement (parcours 4), créer cette écriture ne rapproche pas la transaction par elle-même : le lien avec la transaction bancaire d'origine se pose ensuite via l'endpoint du parcours 3.

Référence

Endpoints utilisés dans ce guide

Identifiants de mode de paiement

Requis par les endpoints de règlement, encaissement et transfert. Ensemble actuellement défini par l'API :

Référence

Paramètres transverses

Référence

Limites & pièges connus

• Pas d'unicité stricte transaction ↔ écriture. Seul un doublon exact (même transaction, même écriture, même montant, même origine) est refusé par l'API — vérifier l'absence de lien existant reste à la charge du client (parcours 3).
• typeTransaction n'est pas une valeur libre. Elle doit reproduire exactement celle portée par la transaction visée, faute de quoi le rapprochement est refusé (parcours 3).
• Créer un règlement, un transfert, un encaissement ou une écriture libre ne rapproche pas la transaction. C'est toujours un second appel explicite vers l'endpoint de rapprochement du parcours 3 (parcours 4, 5, 6, 7).
• Hors autorisation (403), les refus de ce guide sont des 400. Toutes les règles de validation métier décrites ci-dessus — transaction déjà rapprochée, sens incohérent, écriture d'annulation, clé de répartition manquante… — sont renvoyées avec ce code, à charge pour le client de lire le message pour distinguer le cas précis (parcours 3, 7 ; « Contrôle d'accès »).
• Un transfert entre deux comptes n'est détectable automatiquement que si les deux jambes bancaires partagent exactement la même date — une date de valeur décalée casse l'appariement (parcours 5).
• L'identification d'un encaissement par solde échoue silencieusement en cas de solde partagé par plusieurs copropriétaires — aucune erreur explicite, simplement aucun encaissement créé (parcours 6).
• Chaque écriture appartient à un exercice comptable précis, déterminé par la date du mouvement ; sur l'écriture libre du parcours 7, un exercice clôturé refuse explicitement toute nouvelle écriture.

Vérifications

Questions de validation