Diffusion de courrier

Une diffusion de courrier ne s'adresse jamais à un « copropriétaire » directement : elle s'adresse à des contacts, rattachés à un copropriétaire via les lots qu'il détient. Un même copropriétaire peut avoir plusieurs contacts (un mandataire, un usufruitier, un locataire...), et un même contact peut être rattaché à plusieurs lots. C'est cette structure imbriquée — copropriétaire → lots → contacts par lot — qui porte l'essentiel des règles de ce guide.

La fenêtre dateDebut/dateFin d'un lot-contact est déterminante : sans précision de date, seuls les rattachements valides aujourd'hui sont retournés (voir Parcours A). Un contact peut aussi être historisé : une fiche contact obsolète (fusionnée avec une plus récente) n'a alors plus de rattachement de lot valide et disparaît donc des lotContacts actuels de coproprietaires — mais elle reste présente, avec une référence vers le contact qui l'a remplacée, dans la liste à plat des contacts de la copropriété (voir Limites & pièges).

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, sans détail sur l'autorisation manquante. Sur les appels d'écriture (journalisation d'un envoi), référencer un contact, un document ou un regroupement d'envoi qui n'appartient pas à cette même copropriété renvoie également un 403.

Ces quatre parcours couvrent la diffusion de bout en bout : constituer l'audience, éventuellement la restreindre, vérifier l'historique avant d'envoyer, puis tracer l'envoi une fois qu'il a réellement eu lieu.

{
  "libelle": "Diffusion #128 - Travaux toiture - Bât. A",
  "mode": "courrier",
  "urlContenu": "https://mon-domaine.example/archives/diffusion-128.html",
  "idsContacts": [55231, 55240],
  "idsDocuments": [4821],
  "idGroupe": 9017
}

La route attend une extension de format explicite en fin de chemin (par exemple .json).

Ces familles de paramètres sont communes à l'ensemble des routes de liste de ce guide (coproprietaires, cles, contacts, envois) :

• filters[champ]=valeur — sur un champ texte, en l'absence d'opérateur explicite le filtre teste une sous-chaîne (insensible à la casse), pas une égalité stricte ; pour une égalité stricte utiliser filters[champ__eq]=valeur (ou préfixer la valeur d'un =, comme dans filters[id]==12 au Parcours B). Sur un champ numérique ou une date, un opérateur est obligatoire — soit en suffixe du nom (filters[champ__gt]=...), soit en préfixe de la valeur (<, >, <=, >=, !=) — son absence renvoie une erreur explicite plutôt qu'un résultat vide. Un chemin imbriqué se filtre par point, comme documents.tags.
• displays[] — un nom de champ l'inclut explicitement, le même préfixé de ! l'exclut. Sur la plupart des routes il ne fait que réduire la taille de la réponse, une fois celle-ci déjà entièrement construite côté serveur ; sur cles, en revanche, il conditionne si tantiemesParLot est effectivement récupéré (Parcours B) — dans ce cas précis il change aussi le travail réellement effectué, pas seulement la forme de la réponse.
• sorts[champ]=ASC|DESC — tri appliqué après coup sur le résultat déjà chargé ; sans effet sur le coût de l'appel.
• paginates[page]=N&paginates[nb]=N — découpage en pages (1-indexé), lui aussi appliqué après coup : il réduit la taille de la réponse transmise, jamais le travail effectué pour la construire.

Sur envois spécifiquement, voir la nuance de performance détaillée au Parcours C : deux filtres seulement (documents.id, documents.url) et les bornes de date sont réellement économes, tous les autres filtres imbriqués s'appliquent après chargement complet de la période demandée.