Comment obtenir la liste des copropriétaires d'une copropriété, comprendre la fenêtre temporelle qui détermine qui y figure, et maîtriser le coût réel de l'appel selon les champs demandés.
Tous les appels de ce guide sont adressés à une copropriété précise (idCopro) : c'est le périmètre racine de la route. Un copropriétaire appartient toujours à une seule copropriété, mais son appartenance à la liste renvoyée n'est pas un simple statut binaire actif/inactif — elle dépend de la fenêtre temporelle de l'appel, parce qu'elle est déterminée par les lots qu'il détenait pendant cette fenêtre (voir Parcours fonctionnels).
Une fiche copropriétaire, avec le ou les lots qu'elle détient sur la fenêtre demandée.
type distingue notamment propriété pleine, démembrement, personne morale, communauté de biens et indivision. dateAcquisition / dateCession ne sont renseignées que si la fiche correspond à un seul mouvement global ; un copropriétaire dont les lots ont été acquis ou cédés à des dates différentes n'a pas de date unique fiable à ce niveau — il faut alors regarder chaque lot de lots[] individuellement.
Les champs iban, bic, modeDePaiement, delaiReglement, documents, referenceInterne, libelleComplement et super apparaissent toujours dans la réponse mais sont systématiquement vides pour un copropriétaire : ce sont des champs communs à d'autres types de tiers exposés par la même famille d'API (fournisseurs notamment), sans usage ici.
Un lot détenu par le copropriétaire, avec son propre cycle de vie.
estPrincipal distingue un lot principal (habitation, local commercial...) d'un lot secondaire (cave, parking...) — c'est cette distinction qui sépare les deux dans un affichage groupé par copropriétaire. C'est au niveau du lot, pas du copropriétaire, que se joue réellement la présence dans la liste sur une fenêtre donnée : un copropriétaire y figure dès qu'au moins un de ses lots a été détenu à un instant quelconque de cette fenêtre.
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.
/v2 et servies depuis https://syndic.datacopro.org en production, ou https://preprod-syndic.datacopro.org sur la plateforme de test.
Ces trois parcours couvrent la même route sous trois angles : la vue « aujourd'hui », la vue historique complète, et la variante allégée pour un affichage qui n'a pas besoin du détail comptable.
Cas d'usage : afficher, pour la copropriété, la liste des copropriétaires actifs aujourd'hui, avec leurs lots et leur solde.
Sans aucun paramètre de date, l'appel ne renvoie que les copropriétaires détenant au moins un lot à la date du jour — ni ceux qui n'ont encore acquis aucun lot, ni ceux ayant déjà cédé la totalité des leurs.
filters appliqué, et le fait que solde ait été exclu ou non de displays — cette seule information est extraite de displays avant la mise en cache, car elle décide si le calcul comptable doit avoir lieu (voir Parcours C). En dehors de ce cas précis, ni displays (le choix des champs à renvoyer), ni sorts, ni la pagination ne font partie de la clé de cache : ils sont appliqués après coup sur le résultat déjà en cache, donc changer le tri ou restreindre l'affichage à certains champs (sans en retirer solde) ne recalcule rien côté serveur.
Cas d'usage : produire un registre couvrant tout un exercice, où doivent figurer aussi bien les copropriétaires toujours en place que ceux ayant cédé leurs lots en cours de période.
Passer dateDebut seul, sans dateFin, ouvre la fenêtre sans limite supérieure : elle couvre alors tout copropriétaire ayant détenu un lot à un instant quelconque depuis cette date, y compris ceux qui ont depuis cédé la totalité de leurs lots. Symétriquement, passer dateFin seul, sans dateDebut, ouvre la fenêtre sans limite inférieure : elle couvre alors tout l'historique jusqu'à cette date, aussi loin que des lots existent. Passer les deux bornes ensemble restreint la fenêtre à une période précise (par exemple l'exercice de référence d'une assemblée). Passer date seul équivaut à fixer dateDebut et dateFin à cette même valeur — un instantané à une date donnée plutôt qu'une fenêtre.
dateFin ne plafonne pas non plus dans le futur : un lot dont l'acquisition est déjà enregistrée à une date future apparaîtra donc, même si cette date n'est pas encore passée. Ce n'est pertinent que pour des situations déjà saisies par avance dans Datacopro — mais ce n'est pas filtré automatiquement par la route.
Cas d'usage : afficher une liste ou un sélecteur de copropriétaires qui n'a pas besoin du détail comptable — seulement l'identité et les lots.
solde de chaque copropriétaire n'est pas une valeur stockée : c'est le résultat d'une requête comptable dédiée, exécutée pour chacun d'eux au moment de l'appel — la charge la plus significative de cette route. Exclure explicitement solde (ou ne demander qu'un sous-ensemble de champs qui ne l'inclut pas) désactive entièrement ce calcul pour toute la liste, pas seulement son affichage. Ce calcul a lieu avant l'application d'un éventuel filters : filtrer sur solde (par exemple filters[solde__lt]=0) porte donc bien sur le montant réel, à condition que le calcul n'ait pas justement été désactivé de cette façon.
| Méthode | Route | Rôle |
|---|---|---|
| GET | /v2/copro/{idCopro}/coproprietaires.json | Liste des copropriétaires ayant détenu au moins un lot sur la fenêtre temporelle demandée (aujourd'hui par défaut), avec leurs lots et, sauf exclusion, leur solde |
La route attend une extension de format explicite en fin de chemin (par exemple .json).
Au-delà des paramètres de date propres à cette route (Parcours B), la liste accepte les familles de paramètres génériques communes à l'ensemble de l'API :
filters[champ__eq]=valeur — restreint les résultats. Pour d'autres types de filtrage utiliser (__gt, __nempty, __diff).sorts[champ]=ASC|DESC — ordonnancement de la liste. Sans ce paramètre, l'ordre par défaut est l'identifiant croissant ; passer sorts vide restitue l'ordre alphabétique par libelle que le serveur construit en interne avant mise en cache.displays[] — restreint ou exclut des champs de la réponse, parmi ceux déjà présents dans le contrat de la route : un nom de champ l'inclut explicitement, le même nom préfixé de ! (par exemple displays[]=!solde) l'exclut ; voir Parcours C pour son effet sur le coût réel de l'appel.paginates — découpage en pages de la liste.solde (filters[solde]=...) ne porte sur la valeur réelle que si le solde est effectivement calculé pour cet appel : si displays[]=!solde désactive ce calcul (Parcours C), un filtre sur solde n'a plus rien de réel à comparer.dateFin, un dateDebut seul ouvre la fenêtre sans limite, y compris vers le futur : un lot déjà enregistré avec une date d'acquisition future apparaît dans le résultat (Parcours B).dateAcquisition / dateCession fiable au niveau de la fiche racine — seules les dates portées par chaque lot de lots[] le sont (Modèle & périmètre).libelle que le serveur construit pourtant en interne avant mise en cache ; pour obtenir ce second ordre, il faut explicitement envoyer sorts vide (référence, §05).iban, bic, modeDePaiement, delaiReglement, documents, referenceInterne, libelleComplement et super sont toujours présents dans la réponse mais toujours vides pour un copropriétaire — ne pas s'appuyer dessus (Modèle & périmètre).dateDebut. Parcours A & Bfilters[solde]=<0 par exemple : le solde de chaque copropriétaire est calculé avant que les filtres ne soient évalués, donc le filtre porte bien sur le montant réel. La seule condition est que ce calcul ait effectivement lieu pour cet appel — s'il est désactivé via displays[]=!solde (Parcours C), un filtre sur solde n'a alors plus de valeur réelle à comparer. Parcours C, Limites & pièges connusdateDebut sans dateFin, jusqu'à quand va la fenêtre couverte ?dateDebut, sans limite vers le futur — y compris un lot dont l'acquisition est déjà enregistrée à une date qui n'est pas encore passée. Pour borner précisément la période (un exercice donné, par exemple), il faut passer dateFin explicitement. Parcours B