# Contrat de donnees site <-> CRM Portail vendeur

Document de coordination a apporter en reunion avec l'equipe du CRM
**Portail vendeur** (CRM interne Biome). Il est autonome : il peut se lire
sans connaitre le code du site.

Contexte en une phrase : le site vitrine Biome Constructions affiche les
biens a vendre (fiches, photos, prix...) qui doivent venir du CRM en
**lecture seule**, et lui transmet en retour certains formulaires remplis
par les visiteurs interesses par un bien (**ecriture**, dans l'autre sens).
Ce sont deux flux distincts, tous les deux a convenir avec vous.

Pour aller plus loin une fois le contrat fixe : `docs/architecture-donnees.md`
(sections 2 bis et 3) contient le detail technique cote site.

---

## Volet 1 — Ce que le site doit LIRE du CRM

Aujourd'hui, en l'absence de contrat CRM fixe, le site utilise des donnees
factices ("fixtures") qui reproduisent fidelement la maquette, le temps que
ce document serve de base de discussion. Rien de ce qui suit n'est donc
definitif : c'est la liste de ce dont le site a besoin.

### 1.1 Liste des biens (page "Acheter" + blocs de la page d'accueil)

Chaque bien affiche en carte (liste "Acheter", carrousel Accueil) a besoin
des champs suivants. Exemple tire d'un bien fictif utilise actuellement par
le site :

| Champ               | Type              | Exemple                          | Obligatoire ? | Usage sur le site |
|----------------------|-------------------|-----------------------------------|----------------|--------------------|
| `id`                 | Identifiant texte | `ach-1`                          | Oui | Cle unique du bien, utilisee dans les URLs et les formulaires de contact |
| `lot`                | Nombre            | `1`                               | Oui | Numero de lot affiche dans le titre de la carte |
| `localite`           | Texte             | `Ciney`                           | Oui | Commune affichee, utilisee pour la recherche/filtre |
| `adresse`            | Texte             | `Rue du Condroz, Ciney, Namur`   | Oui | Adresse indicative (situation du bien) |
| `province`           | Texte (code)      | `namur`                          | Oui | Filtre par province (valeurs actuelles : namur, liege, luxembourg, brabant, hainaut) |
| `type`               | Texte (code)      | `maison`                         | Oui | Filtre type de bien (valeurs actuelles : maison, appartement) |
| `facades`            | Texte             | `Maison 3 facades`               | Oui | Libelle affiche comme "titre" du bien |
| `badge`              | Texte             | `Nouvelle construction`          | Oui | Etiquette affichee sur la carte (ex. "Disponible immediatement") |
| `prix`               | Texte formate     | `375.000 EUR`                    | Oui | Prix tel qu'affiche a l'ecran |
| `prix_valeur`        | Nombre entier     | `375000`                         | Oui | Prix en euros, utilise pour trier/filtrer par budget |
| `surface_habitable`  | Texte formate     | `150 m2`                         | Oui | Surface telle qu'affichee |
| `surface_habitable_valeur` | Nombre entier | `150`                          | Oui | Surface en m2, utilisee pour le tri "plus grande surface" |
| `chambres`           | Nombre entier     | `3`                               | Oui | Nombre de chambres, filtre "au moins X chambres" |
| `salles_de_bain`     | Nombre entier     | `1`                               | Oui | Affiche sur la fiche |
| `terrain`             | Texte formate     | `550 m2` ou `Terrasse 14 m2`     | Oui | Surface de terrain/terrasse telle qu'affichee |
| `terrain_valeur`      | Nombre entier     | `550` (0 si non applicable)      | Oui | Valeur numerique pour le tri "plus grand terrain" |
| `disponibilite`      | Texte (code)      | `immediate` ou `construction`    | Oui | Filtre disponibilite |
| `peb`                | Texte             | `A`                               | Oui | Classe energetique affichee |
| `annee`              | Texte/Nombre      | `2026`                           | Oui | Annee de construction affichee |
| `orientation`        | Texte             | `Sud-Ouest`                      | Oui | Orientation du terrain, affichee sur la fiche |
| `photo_principale`   | URL               | `/images/biens/bien-ciney.jpg`   | Optionnel (le site affiche un visuel neutre si absent) | Photo de couverture sur les cartes |

Note : les cles `_valeur` (numeriques) et les libelles textuels formates
(`prix`, `surface_habitable`, `terrain`) sont doublees aujourd'hui cote site
car les fixtures reproduisent l'affichage exact de la maquette. A voir avec
vous si le CRM peut fournir directement les deux formes, ou si le site doit
composer le texte affiche a partir des seules valeurs numeriques (plus
robuste, mais a valider sur le rendu final).

### 1.2 Detail d'un bien (fiche complete)

En plus des champs de la liste ci-dessus, la fiche detaillee d'un bien a
besoin de :

| Element attendu | Detail | Statut |
|---|---|---|
| Galerie de photos | Liste de photos avec une legende courte par photo (ex. "Facade & carport", "Sejour & salle a manger") | Source unique = CRM, a definir (voir 1.4) |
| Description | Plusieurs paragraphes de texte libre presentant le bien | A fournir par le CRM, absent des fixtures actuelles pour la plupart des biens |
| Informations cles | Reprend les champs de la liste (prix, surfaces, chambres, PEB, annee, orientation...) | Deja couvert par 1.1 |
| Detail du prix | Document PDF telechargeable | Voir 1.4 (document attendu, pas encore fourni) |
| Plans | Image(s) ou PDF (rez-de-chaussee, etage, implantation terrain) | Voir 1.4 (question ouverte) |
| Situation / adresse | Adresse et, idealement, coordonnees pour affichage sur une carte | Voir 1.4 (question ouverte) |
| Arguments "pourquoi cette maison" | Liste de points forts mis en avant sur la fiche | A fournir par le CRM, non modelise dans les fixtures actuelles |
| Biens similaires | Suggestion d'autres biens proches (localite/budget/type) | Peut etre calcule cote site a partir de la liste (1.1) si le CRM ne le fournit pas directement |

### 1.3 Biens d'investissement (page "Investir")

La page "Investir" affiche une selection de biens mis en avant pour
l'investissement locatif, avec des champs specifiques en plus de ceux de
1.1 :

| Champ                     | Type          | Exemple    | Obligatoire ? | Usage |
|----------------------------|---------------|------------|----------------|-------|
| `rendement`                | Texte formate | `4,2 %`    | Oui (pour un bien marque investissement) | Rendement locatif affiche sur la carte |
| `loyer_estime`              | Texte formate | `950 EUR`  | Oui | Loyer mensuel estime, affiche |
| `loyer_estime_valeur`       | Nombre entier | `950`      | Oui | Valeur numerique (tri/calcul eventuel) |
| `type_investissement`      | Texte         | `Appart.`, `Studio`, `Duplex` | Oui | Libelle court affiche sur la carte investisseur |

**Besoin non couvert a ce jour** : la maquette prevoit un titre de carte
synthetique par bien d'investissement (ex. "Appartement 2 chambres", "Studio
neuf meuble"). Aucun champ du contrat actuel ne porte ce titre : le site
reutilise aujourd'hui le champ `facades` (prevu pour l'affichage standard
d'un bien) faute de mieux, ce qui n'est pas totalement satisfaisant
visuellement. **Question pour la reunion** : le CRM peut-il exposer un champ
dedie (ex. `titre_investissement`), ou le site doit-il composer son propre
libelle a partir de `type_investissement` et de la localite ?

Seuls les biens marques comme "mis en avant pour l'investissement" par le
CRM doivent remonter sur cette section — le mecanisme de selection
(flag, critere de calcul...) reste a definir avec vous.

### 1.4 Documents et medias attendus

| Element | Ce que le site attend | Question ouverte |
|---|---|---|
| PDF "detail du prix" | Un document telechargeable par bien, propose depuis la fiche | Le CRM fournira-t-il une URL de telechargement directe par bien ? Le site ne genere aucun PDF lui-meme. |
| Plans (rez-de-chaussee, etage, implantation terrain) | Image(s) ou PDF par bien | Le CRM dispose-t-il de ces plans numerises ? Sous quel format ? |
| Coordonnees / adresse pour la carte de situation | Adresse structuree, idealement latitude/longitude | Le CRM peut-il fournir des coordonnees GPS exploitables, ou seulement une adresse texte ? |
| Photos (galerie + photo principale) | URLs d'images utilisables directement dans les pages du site | Les photos seront-elles servies par une URL publique directe (lien simple), ou faut-il que le site les recopie/mette en cache via un point de passage intermediaire (pour des raisons de performance ou d'acces securise) ? |

### 1.5 Questions techniques ouvertes (a trancher avec vous)

- **Mode d'acces** : API HTTP (REST/JSON) ? Export de fichier a intervalle
  regulier ? Autre mecanisme deja en place cote CRM ?
- **Authentification** : cle API, jeton, adresse IP autorisee, ou autre
  methode deja standard chez vous ?
- **Frequence de rafraichissement** : le site prevoit par defaut de garder
  les donnees en cache 15 minutes avant de les redemander au CRM (valeur
  ajustable). Ce delai est-il compatible avec vos mises a jour de biens
  (nouveau bien, changement de prix, bien vendu retire de la vente) ?
- **Format des reponses** : JSON attendu cote site. A confirmer que c'est
  bien ce que le CRM peut produire.
- **Pagination** : la liste des biens sera-t-elle fournie en une seule fois,
  ou faut-il prevoir une pagination cote CRM (nombre de biens par page,
  numero de page, etc.) ? Combien de biens sont actuellement disponibles a
  la vente en moyenne ?
- **Biens retires de la vente** : comment le site sait-il qu'un bien vendu
  ne doit plus apparaitre (statut explicite, disparition de la reponse,
  autre) ?

---

## Volet 2 — Ce que le site va ENVOYER au CRM (leads acheteurs)

### Perimetre confirme avec le client (2026-07-03)

Trois formulaires remplis par les visiteurs du site seront transmis au CRM.
Tous les autres formulaires du site restent strictement internes (consultes
uniquement dans l'administration du site, jamais envoyes au CRM).

| Transmis au CRM | Reste local uniquement |
|---|---|
| Demande de visite d'un bien | Formulaire "vendre mon terrain" |
| Demande d'infos / brochure / prix / rappel sur un bien | Formulaire "Contact" branche question |
| Formulaire "Contact" branche maison | Candidatures (offres d'emploi) |
| | Devenir partenaire / sous-traitant |

### 2.1 Payload par type de lead

Chaque envoi partage un socle commun, puis une partie de donnees propre au
formulaire.

**Socle commun a tous les envois :**

| Champ | Type | Exemple | Description |
|---|---|---|---|
| `type` | Texte (code) | `visite` | Un des 3 codes : `visite`, `info_bien`, `contact_maison` |
| `id_local` | Nombre entier | `142` | Identifiant interne du site (sert uniquement a faire le lien avec l'accuse de reception, jamais a utiliser comme identifiant cote CRM) |
| `bien_id` | Texte ou vide | `parcelle:6062` | Cle canonique du bien cote CRM, au format `type:id` (exactement la cle `id_hfsql` que le CRM pousse au site : nous la stockons et la renvoyons telle quelle, sans table de correspondance). Vide (`null`) pour une demande generique sans bien precis. En environnement de recette non branche au miroir (fixtures), les leads partent avec des ids de demonstration (`ach-3`...) a ignorer/filtrer cote CRM |
| `date_soumission` | Date/heure (format standard ISO 8601) | `2026-07-03T14:32:00+02:00` | Date et heure de soumission du formulaire par le visiteur |
| `donnees` | Groupe de champs | — | Contenu specifique au formulaire, detaille ci-dessous |

**a) Demande de visite d'un bien** (`type = visite`)

| Champ (`donnees`) | Type | Obligatoire ? | Format / regle |
|---|---|---|---|
| `nom` | Texte | Oui | Max. 255 caracteres |
| `prenom` | Texte | Oui | Max. 255 caracteres |
| `telephone` | Texte | Oui | Max. 30 caracteres |
| `email` | E-mail | Oui | Doit etre une adresse valide |
| `date_souhaitee` | Date | Oui | Format `AAAA-MM-JJ`, ne peut pas etre dans le passe |
| `message` | Texte libre | Optionnel | Max. 5000 caracteres |

**b) Demande d'infos / brochure / prix / rappel sur un bien** (`type = info_bien`)

| Champ (`donnees`) | Type | Obligatoire ? | Format / regle |
|---|---|---|---|
| `type_demande` | Texte (code) | Oui | Une valeur parmi : `infos`, `brochure`, `prix`, `rappel` |
| `nom` | Texte | Oui | Max. 255 caracteres |
| `prenom` | Texte | Obligatoire seulement si `type_demande` = infos, brochure ou prix (optionnel pour un rappel) | Max. 255 caracteres |
| `email` | E-mail | Obligatoire seulement si `type_demande` = infos, brochure ou prix (optionnel pour un rappel) | Doit etre une adresse valide |
| `telephone` | Texte | Oui | Max. 30 caracteres |
| `souhaits` | Liste de codes ou vide | Optionnel | Valeurs possibles : `rappel`, `brochure`, `visite` (cases cochees en plus du motif principal) |
| `message` | Texte libre | Obligatoire seulement si `type_demande` = infos (optionnel sinon) | Max. 5000 caracteres |

Note : ce formulaire peut aussi correspondre a un "rappel generique" sans
bien precis (ex. depuis la page Contact ou Acheter) : dans ce cas `bien_id`
(dans le socle commun) est vide.

**c) Formulaire "Contact", branche maison** (`type = contact_maison`)

| Champ (`donnees`) | Type | Obligatoire ? | Format / regle |
|---|---|---|---|
| `nom` | Texte | Oui | Max. 255 caracteres |
| `email` | E-mail | Oui | Doit etre une adresse valide |
| `telephone` | Texte | Oui | Max. 30 caracteres |
| `budget` | Texte | Oui | Max. 100 caracteres (budget selectionne par le visiteur) |
| `localisation` | Texte | Optionnel | Max. 255 caracteres |
| `message` | Texte libre | Optionnel | Max. 5000 caracteres |

Pour ce type, `bien_id` (socle commun) est toujours vide : ce formulaire
n'est jamais rattache a un bien precis.

### 2.2 Mecanisme cote site (deja en place)

Le fonctionnement suivant est deja implemente et actif cote site (avec un
"bouchon" qui journalise sans encore rien envoyer, en attendant ce contrat) :

- **Envoi différe, pas en temps reel.** Le visiteur remplit un formulaire,
  le lead est enregistre immediatement sur le site. La transmission vers le
  CRM se fait ensuite via une tache planifiee qui tourne **toutes les 15
  minutes** (contrainte d'hebergement : pas d'envoi immediat possible dans
  la requete du visiteur).
- **Retentatives automatiques limitees a 5 essais.** Si l'envoi echoue, le
  site retente automatiquement lors des passages suivants de la tache
  planifiee, jusqu'a 5 tentatives. Au-dela, l'envoi n'est plus retente
  automatiquement (le lead reste consultable dans l'administration du site
  pour un traitement manuel).
- **Suivi d'un accuse de reception.** Chaque lead garde en memoire la date a
  laquelle le CRM l'a accepte (une fois recu avec succes), visible dans
  l'administration du site pour l'equipe Biome.

**Ce qui est attendu cote CRM pour rendre ce mecanisme fonctionnel :**

| Besoin | Detail |
|---|---|
| Un point de reception | Une adresse/API a laquelle le site peut envoyer ces 3 types de leads |
| Une authentification | Cle API, jeton ou autre mecanisme pour securiser l'envoi |
| Un accuse de reception clair | Une reponse permettant au site de distinguer sans ambiguite un succes (le lead a bien ete recu par le CRM) d'un echec a retenter |
| Idempotence (souhaitable) | Le site envoie `id_local` a chaque tentative : si un envoi reussit cote CRM mais que la reponse se perd avant d'arriver au site (le site retente alors inutilement), pouvoir reconnaitre grace a `id_local` qu'il s'agit du meme lead evite les doublons cote CRM |

### 2.3 Questions ouvertes

- **Au-dela de 5 echecs** : quel comportement souhaitez-vous ? Simple
  consultation manuelle cote site (statu quo actuel), notification
  automatique a une personne dediee, tableau de bord specifique ?
- **Notification d'erreur** : souhaitez-vous etre informes (email, alerte)
  en cas d'echecs repetes d'envoi, ou la responsabilite de surveillance
  reste-t-elle cote equipe Biome ?
- **Environnement de test** : le CRM dispose-t-il d'un environnement de
  recette/bac a sable pour que l'equipe du site puisse tester les envois
  sans polluer les donnees reelles du CRM ?

---

## Prochaines etapes proposees

1. **Convenir du contrat** avec l'equipe CRM a partir de ce document : valider
   ou ajuster les champs des volets 1 et 2, repondre aux questions ouvertes
   (mode d'acces, authentification, format, comportement en cas d'echec).
2. **Implementer cote site** une fois le contrat fixe :
   - un client CRM en lecture reelle (remplace l'implementation actuelle a
     base de donnees factices, sans changement pour le reste du site) ;
   - un transmetteur de leads reel vers le CRM (remplace le bouchon qui
     journalise sans envoyer).
3. **Recette croisee site <-> CRM** : verifier ensemble, sur un environnement
   de test, que les biens s'affichent correctement sur le site et que les 3
   types de leads sont bien recus et acquittes par le CRM.