Datacopro API · guide fonctionnel
Comment regrouper, à l'échelle d'un domaine, les fiches contact dupliquées entre copropriétés en un seul dossier de référence, et le rattacher à un fournisseur consolidé avec un rôle.
À propos de ce guide. Ce document décrit uniquement le contrat de l'API : les appels à effectuer, dans quel ordre, avec quels paramètres, et pourquoi. Aucune connaissance d'un logiciel de gestion copropriété en particulier n'est nécessaire pour le suivre — un seul encadré, plus bas, s'appuie sur un logiciel existant à titre d'illustration, clairement signalé comme tel.
Sauf mention contraire, chaque route est relative à la racine de l'API et suppose un jeton d'accès valide transmis en paramètre de requête (access_token), et non dans un en-tête d'autorisation.
Trois niveaux de granularité coexistent, à l'intérieur d'un domaine — le périmètre qui regroupe l'ensemble des copropriétés d'un même portefeuille de gestion. Les comprendre dans l'ordre évite l'erreur la plus fréquente : confondre « la fiche d'une personne dans une copropriété » avec « le dossier consolidé de cette même personne à l'échelle du domaine ».
Trois fiches contact identiques par accident de saisie deviennent un seul super-contact, ensuite rattaché avec un rôle à un fournisseur lui-même consolidé.
Une fiche contact appartient à une copropriété précise. Elle porte l'identité et les coordonnées d'une personne, ainsi qu'une référence — super — vers le super-contact auquel elle est éventuellement déjà rattachée (absente/nulle tant qu'elle ne l'est pas).
Un super-contact reprend exactement les mêmes attributs d'identité et de coordonnées, plus des tags libres, mais n'est rattaché à aucune copropriété : il vit au niveau du domaine et référence la liste des fiches contact qu'il consolide. Il porte son propre identifiant (id), utilisé dans les routes ci-dessous comme {idSuperContact} — à ne pas confondre avec idReference, qui n'existe que sur les fiches contact.
Avant même toute consolidation, une fiche contact peut déjà être rattachée à une fiche fournisseur au sein d'une même copropriété, avec un rôle (fonction) propre à ce rattachement local. La consolidation ajoute l'équivalent au niveau du domaine : un super-contact rattaché à un super-fournisseur, avec sa propre fonction (ex. « Comptable », « Commercial ») et une note interne. Ce rattachement consolidé est un objet à part entière, retourné avec son propre id (utilisé plus loin comme {idRattachement}) — distinct des rattachements locaux par copropriété, mais capable d'agir sur eux (voir parcours 5).
Toutes les routes de ce guide sont scopées au domaine (idDomaine) : le client doit être autorisé sur ce domaine précis, sinon l'appel renvoie 403 Forbidden — y compris quand l'identifiant demandé existe mais appartient à un autre domaine. Il n'existe pas de granularité plus fine (aucun rôle spécifique « gestion des contacts ») : l'autorisation sur le domaine suffit et conditionne tout le reste.
/v2 et servies depuis https://syndic.datacopro.org en production, ou https://preprod-syndic.datacopro.org sur la plateforme de test.
Six enchaînements couvrent le cycle de vie complet : repérer, consolider, faire évoluer, rattacher à un fournisseur, faire évoluer le rôle, puis relire la vue d'ensemble.
Récupère les fiches contact du domaine. Chaque fiche indique dans son champ super si elle est déjà rattachée à un super-contact.
Paramètres utiles : filters, sorts, paginates, displays (voir §6).
Crée le dossier consolidé avec l'identité et les coordonnées de référence (mêmes champs que la fiche contact), plus un objet contacts qui combine deux informations dans une seule structure : une liste d'identifiants de fiches à rattacher immédiatement, et des indicateurs nommés par champ disant lequel doit en plus être répercuté sur ces fiches.
Exemple : contacts[]=4021, contacts[]=4108 (les fiches à rattacher) et, dans le même objet, contacts[nom]=1, contacts[email]=1 (les champs à propager). Les deux cohabitent sous la même clé contacts : n'envoyez que les indicateurs de champs réellement nécessaires, au risque sinon de propager une valeur non voulue.
idReference reste stable d'une version à l'autre — c'est cet identifiant qu'il faut retenir côté intégration si des champs peuvent être propagés, jamais idContact seul.Met à jour l'identité de référence et/ou la liste des fiches rattachées (même objet contacts qu'à la création, avec les mêmes deux usages : identifiants à rattacher et indicateurs de propagation par champ).
contacts est absent de la requête, la liste actuelle est conservée telle quelle. Mais dès qu'il est présent — même vide — il remplace intégralement la liste des fiches rattachées : toute fiche déjà rattachée et non réincluse est détachée. Il faut donc toujours renvoyer la liste complète voulue, jamais seulement l'ajout. Par ailleurs, exactement comme à la création (parcours 2), tout indicateur de propagation activé ici déclenche la même création d'une nouvelle fiche versionnée pour chaque fiche impactée : ce n'est pas propre au POST, cette mise à jour produit le même effet.Crée le rattachement : superContact (identifiant), fonction (rôle libre), note (interne, facultative). La réponse renvoie ce rattachement avec son propre id — c'est cette valeur qu'il faut conserver pour le modifier ensuite (parcours 5), sous le nom {idRattachement}.
Modifie fonction et/ou note du rattachement.
DELETE sur la même URL) mais échoue actuellement à l'exécution avec une erreur serveur. Ne construisez pas de flux de désassociation automatisé sur cet appel tant que ce comportement n'a pas été confirmé corrigé — mieux vaut, pour l'instant, vérifier au cas par cas ou solliciter le support avant de considérer une désassociation comme acquise.La réponse inclut, par défaut, la liste contacts du fournisseur consolidé : chaque entrée porte fonction, note, et le super-contact complet. Aucun appel supplémentaire n'est nécessaire pour afficher les interlocuteurs.
GET /v2/domaines/{idDomaine}/super-contacts (la liste, sans un identifiant précis) ne renvoie pas les fiches contact rattachées à chaque super-contact — cette information n'apparaît que sur la lecture d'un super-contact précis. Pour auditer un grand nombre de super-contacts et leurs fiches, il faut les lire un par un.| Méthode | Route | Rôle |
|---|---|---|
| GET | /v2/domaines/{idDomaine}/contacts | Liste des fiches contact du domaine |
| GET | /v2/domaines/{idDomaine}/contacts/{idContact} | Une fiche contact précise |
| GET | /v2/domaines/{idDomaine}/super-contacts | Liste des super-contacts du domaine (sans leurs fiches rattachées) |
| POST | /v2/domaines/{idDomaine}/super-contacts | Créer un super-contact, éventuellement avec des fiches à rattacher |
| GET | /v2/domaines/{idDomaine}/super-contacts/{idSuperContact} | Un super-contact précis, avec ses fiches rattachées |
| PUT | /v2/domaines/{idDomaine}/super-contacts/{idSuperContact} | Modifier l'identité et/ou la composition d'un super-contact |
| DELETE | /v2/domaines/{idDomaine}/super-contacts/{idSuperContact} | Supprimer — refusé tant qu'une fiche y est rattachée |
| GET | /v2/domaines/{idDomaine}/super-fournisseurs/{idSuperFournisseur} | Fournisseur consolidé, contacts inclus par défaut |
| POST | /v2/domaines/{idDomaine}/super-fournisseurs/{idSuperFournisseur}/contacts | Rattacher un super-contact à ce fournisseur, avec un rôle |
| PUT | /v2/domaines/{idDomaine}/super-fournisseurs/{idSuperFournisseur}/contacts/{idRattachement} | Modifier le rôle/la note du rattachement (propage le rôle en cascade) |
| DELETE | /v2/domaines/{idDomaine}/super-fournisseurs/{idSuperFournisseur}/contacts/{idRattachement} | Déclarée mais échoue actuellement à l'exécution — voir §6 |
Les listes (fiches contact, super-contacts) acceptent les mêmes paramètres génériques que le reste de l'API :
displays ne peut que réduire ou étendre la sélection parmi les champs déjà inclus par défaut pour cet appel précis — il ne peut pas faire réapparaître un champ qui, pour cette route, n'est structurellement jamais renvoyé (c'est le cas, par exemple, d'un éventuel indicateur de version courante d'une fiche contact : il n'est disponible à aucun niveau de ce guide, quels que soient les displays demandés). Ne construisez pas de logique reposant sur un champ absent d'une réponse d'exemple en espérant le faire apparaître via ce paramètre.PUT sur un super-contact avec un champ contacts présent remplace toute la liste des fiches rattachées ; toujours renvoyer la liste complète désirée. Voir parcours 3.idContact par fiche impactée ; seul idReference reste stable. Voir parcours 2.PUT qui n'en réinclut aucune, parcours 3) avant de pouvoir le supprimer. Voir §4 et parcours 3.POST) ou plus tard lors d'une mise à jour (PUT), chaque fiche impactée reçoit un nouvel idContact ; seul idReference reste stable d'une version à l'autre. Rafraîchissez la référence de fiche à partir de la réponse du super-contact plutôt que de garder un idContact figé. Voir parcours 2 et 3, §6.PUT avec contacts contenant la liste complète — les fiches déjà rattachées plus la nouvelle. Omettre les anciennes les détache, ça n'est pas additif. Voir parcours 3.