Guide d'intégration · API Datacopro

Portefeuille de copropriétés d'un cabinet

Comment lister le portefeuille de copropriétés confiées à un cabinet de syndic, le filtrer — par statut, par tag, par utilisateur — et récupérer la fiche complète d'une copropriété.

À propos de ce guide

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.

Modèle & périmètre

Deux objets sont en jeu. Chaque copropriété appartient à un cabinet.

périmètre : un cabinet

Cabinet

Le regroupement de toutes les copropriétés confiées à un même cabinet de syndic.

périmètre : un cabinet

Copropriété

id — identifiant numérique
referenceInterne — le numéro de mandat interne attribué à la copropriété
libelle — le nom de la copropriété
adresse — sous-objet : adresse, complément, code postal, ville, latitude, longitude, paysle sous-objet porte lui-même un champ nommé adresse (la voie), à ne pas confondre avec l'objet englobant
statut — présence dans le portefeuille actif"active" · "cloturée"
statutIntegration — l'étape du cycle de vie commercial/technique de la copropriétévaleurs observées : "Intégration 0" · "A qualifier" · "Intégration administrative terminée" · "Intégration terminée" · "Copro active / Intégration approuvée" — pas une liste fermée garantie
tags — liste de libellés libres (ex. "Prospect")
codeAcces — le code ou les moyens d'accès notés pour la copropriété (digicode, boîte à clé…), un champ texte libre
note — les notes internes associées à la copropriété
collaborateurs — liste des utilisateurs ayant un rôle actif (assistant, comptable ou gestionnaire) sur cette copropriété — id, email, nom, rôle pour chacunrenvoyé uniquement par la fiche complète (parcours 3), pas par le portefeuille de cabinet — voir parcours 2

Contrôle d'accès

Le périmètre autorisé n'est pas le même selon la route :

la route de portefeuille (parcours 1 et 2) est bornée à un cabinet — son identifiant figure dans le chemin, et le client doit être autorisé sur ce cabinet précis ;
la route de fiche complète (parcours 3) est bornée à la copropriété elle-même — son identifiant figure dans le chemin, indépendamment de tout cabinet, et le client doit être autorisé sur cette copropriété précise.

Dans les deux cas, une autorisation manquante renvoie un 403.

Base URL

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.

Parcours 1 — Lister le portefeuille d'un cabinet

Cas d'usage : obtenir la liste des copropriétés gérées par un cabinet, avec la possibilité de restreindre par statut ou par tag.

GET /v2/domaines/{idDomaine}/copros

Sans le paramètre statut, la route restreint systématiquement aux copropriétés actives — même quand un autre filtre (tag, utilisateur…) est fourni par ailleurs. Pour voir les copropriétés clôturées, il faut ajouter explicitement filters[statut], qui remplace alors ce défaut :

GET /v2/domaines/{idDomaine}/copros?filters[statut]=cloturée

Un filtre sur un autre champ (ex. les copropriétés taguées « Prospect ») se combine avec ce défaut plutôt que de le remplacer :

GET /v2/domaines/{idDomaine}/copros?filters[tags]=Prospect

Pourquoi

Le cabinet est le seul point d'entrée qui renvoie « toutes les copropriétés de ce cabinet » en un seul appel.

Limite

Le filtrage est appliqué après récupération de la totalité des copropriétés du cabinet — pas de filtre poussé en base, et pas de pagination disponible sur cette route. Sur un grand portefeuille, le coût de l'appel reste proportionnel à la taille totale du cabinet, pas à la taille du résultat filtré.

Parcours 2 — Restreindre à un utilisateur du cabinet

Cas d'usage : au sein d'un même cabinet, n'afficher que les copropriétés dont un utilisateur précis (gestionnaire, comptable ou assistant) a la charge, plutôt que le portefeuille entier du cabinet.

GET /v2/domaines/{idDomaine}/copros?filters[collaborateurs.id]=<idUtilisateur>

ou, si seul l'email de l'utilisateur est connu côté client (comparaison exacte, via l'opérateur __eq — voir Paramètres transverses) :

GET /v2/domaines/{idDomaine}/copros?filters[collaborateurs.email__eq]=<email>

Pourquoi ça marche

collaborateurs est un champ standard de la copropriété. Le mécanisme de filtre de l'API sait descendre dans un champ imbriqué (champ.sousChamp) et, quand ce champ est une liste, retient la copropriété dès qu'un élément de la liste correspond — ce n'est pas un paramètre dédié à la notion de « portefeuille utilisateur », c'est une conséquence du filtrage générique appliqué à un champ qui existe déjà. Il fonctionne même si collaborateurs ne fait pas partie des champs renvoyés par cette route (voir limite ci-dessous) : un champ peut servir de critère de filtre sans figurer dans la réponse.

Limite

collaborateurs ne recense que les utilisateurs ayant un rôle assistant, comptable ou gestionnaire sur la copropriété — un utilisateur avec un autre type de rôle n'y apparaît pas.
pour isoler un rôle précis (ex. uniquement « gestionnaire »), un filtre séparé filters[collaborateurs.role]=gestionnaire ne se combine pas de façon fiable avec filters[collaborateurs.id] : chaque filtre est vérifié indépendamment sur l'ensemble des collaborateurs de la copropriété, pas sur la même personne — une copropriété peut donc être retenue à tort si l'utilisateur visé y est comptable pendant qu'un autre y est gestionnaire. Pour confirmer le rôle exact d'une personne précise, il faut consulter la fiche complète de la copropriété (parcours 3), qui renvoie le rôle de chaque collaborateur.
cette route (portefeuille) ne renvoie pas elle-même le champ collaborateurs dans sa réponse : le filtre agit, mais pour voir qui sont les collaborateurs il faut consulter la fiche complète de chaque copropriété (parcours 3).

Parcours 3 — Fiche complète d'une copropriété

Cas d'usage : une fois une copropriété identifiée (parcours 1 ou 2), récupérer sa fiche complète.

GET /v2/copro/{idCopro}

Renvoie l'ensemble des champs listés en Modèle & périmètre (identifiant, référence de mandat, libellé, adresse, statut, étape d'intégration, tags, code/moyens d'accès, notes internes, collaborateurs), sans paramètre supplémentaire à fournir.

Référence des endpoints

Méthode	Route	Rôle
GET	/v2/domaines/{idDomaine}/copros	Portefeuille de copropriétés d'un cabinet, filtrable par statut, tag ou utilisateur.
GET	/v2/copro/{idCopro}	Fiche complète d'une copropriété.

Paramètres transverses

filters

filters[champ]=valeur — champ peut être un chemin imbriqué séparé par un point (ex. collaborateurs.id). Comportement par défaut selon le type :

champ texte → recherche « contient », insensible à la casse
champ nombre ou date → égalité stricte, ou préfixe >, >=, <, <=, != directement dans la valeur
champ liste → la copropriété est retenue dès qu'un élément de la liste correspond

Un opérateur explicite peut être ajouté en suffixant le nom du champ par __ :

__eqégal

__diffdifférent

__containscontient

__ncontainsne contient pas

__gt / __gtesupérieur (ou égal)

__lt / __lteinférieur (ou égal)

__empty / __nemptyvide / non vide

Plusieurs filtres passés ensemble (filters[statut]=active&filters[tags]=Prospect) sont combinés en ET — chacun est cependant vérifié indépendamment sur l'ensemble des éléments d'un champ liste (voir la limite du Parcours 2 pour le cas où cela compte).

displays

displays[]=champ restreint les champs renvoyés à ceux listés (ou les exclut si préfixés par !, ex. displays[]=!note pour tout renvoyer sauf les notes internes). Sans ce paramètre, tous les champs par défaut de la fiche sont renvoyés — il n'est donc pas nécessaire pour obtenir les champs cités en Modèle & périmètre, déjà présents par défaut.

Limite

displays ne peut pas faire apparaître un champ qui n'est pas déjà servi par la route (ex. collaborateurs sur le portefeuille de cabinet, voir Parcours 2).

Limites & pièges connus

Pas de filtre poussé en base, ni de pagination sur la route de portefeuille : le filtre par statut, tag ou utilisateur est reconstruit après coup, sans réduction du volume transféré côté base pour un grand cabinet.
Le contrôle d'accès change de périmètre selon la route — cabinet pour le portefeuille, copropriété elle-même pour la fiche complète (voir Contrôle d'accès).
Pas de notion de « portefeuille utilisateur » en tant que ressource dédiée : elle se déduit du champ collaborateurs de chaque copropriété, qui ne couvre que trois rôles (assistant, comptable, gestionnaire), et qui n'est renvoyé que par la fiche complète — pas par le portefeuille de cabinet, même quand on filtre dessus.
Combiner un filtre sur l'identité d'un collaborateur et un filtre sur son rôle (deux clés filters[collaborateurs.*] séparées) ne garantit pas qu'ils portent sur la même personne : chaque filtre est vérifié indépendamment sur la liste des collaborateurs.
statut et statutIntegration répondent à deux questions différentes : une copropriété peut être « active » (statut) tout en étant encore à une étape antérieure à « Copro active / Intégration approuvée » (statutIntegration).

Questions de validation

1. Comment obtenir uniquement les copropriétés d'un cabinet où un utilisateur précis intervient ?

Parcours 2 : filters[collaborateurs.id]=<id> sur la route du portefeuille de cabinet — cela couvre les trois rôles assistant/comptable/gestionnaire confondus. Pour confirmer que cette personne y intervient précisément comme gestionnaire (et pas seulement comptable ou assistant), il faut vérifier le rôle sur la fiche complète de chaque copropriété obtenue (Parcours 3) : un filtre combiné sur l'identité et sur le rôle n'apporte pas cette garantie à lui seul.

2. Le numéro de mandat, le statut, les tags, le code d'accès et les notes internes sont-ils déjà dans la réponse, ou faut-il un paramètre en plus ?

Oui, tous déjà présents par défaut, dans chaque élément du portefeuille (Parcours 1) comme dans la fiche complète (Parcours 3) — displays n'est pas nécessaire pour les obtenir. Seul collaborateurs fait exception : présent uniquement sur la fiche complète.

3. Que renvoie l'API si aucun filtre de statut n'est précisé sur la liste d'un cabinet ?

Uniquement les copropriétés au statut actif, et ce même si un autre filtre (tag, utilisateur…) est fourni par ailleurs sans préciser statut (voir Parcours 1). Les clôturées doivent être demandées explicitement via filters[statut]=cloturée, qui remplace alors ce défaut.