> ## Documentation Index
> Fetch the complete documentation index at: https://doc.fluximmo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Property vs Advert — bien dédupliqué ou annonce portail

> Comprendre la différence entre Property (bien physique dédupliqué) et Advert (annonce portail) — décision matrix, propertyFlxId pour reconstituer la dédup côté client, anti-patterns.

Fluximmo expose **deux entités** parce que le marché immobilier français est structurellement bruité : un même bien physique apparaît typiquement sur 3 à 8 portails (grands réseaux d'agences, mandataires indépendants, agences locales, etc.) avec des descriptions, des prix et des photos qui divergent. Compter les annonces brutes mène à de la double-comptabilité ; ne regarder que le bien dédupliqué fait perdre la trace fine des publications.

* **Advert** : 1 annonce sur 1 portail = 1 advert. Vue brute, exhaustive, source-par-source. Accessible **uniquement via alerte webhook** (pas de search public).
* **Property** : 1 bien physique unique = N adverts agrégés côté Fluximmo. Vue dédupliquée, accessible via `POST /v2/protected/properties/search` (BAAS API à la demande) + alerte webhook qui livre des IDs.

## Quand choisir lequel — version courte

**Par défaut → PROPERTY.** Si votre besoin est "rechercher des biens sur plusieurs portails sans les compter en double" (BAAS API, marketplace, analytics, scoring, AVM), Property est la primitive simple : une requête, un résultat dédupliqué, payez à l'usage. C'est ce que 90 % des intégrations veulent.

**ADVERTS** est nécessaire si vous voulez :

* répliquer la donnée Fluximmo dans votre propre DB (le seul moyen — il n'y a pas d'export bulk côté property) ;
* recevoir tous les events de cycle de vie en temps réel avec le payload complet self-contained (`PRICE`, `REPUBLISHED`, `UNPUBLISHED`) ;
* tracker l'inventaire d'une agence ou d'un seller portail-par-portail.

## Décision rapide

<Snippet file="/snippets/decision-matrix-property-vs-advert.mdx" />

## Modèle d'agrégation

```mermaid theme={null}
flowchart LR
  A1["Advert · portail A<br/>flxId=adv_aaa<br/>propertyFlxId=adv_aaa"] --> P["Property<br/>flxId=prop_aaa"]
  A2["Advert · portail B<br/>flxId=adv_bbb<br/>propertyFlxId=adv_aaa"] --> P
  A3["Advert · portail C<br/>flxId=adv_ccc<br/>propertyFlxId=adv_aaa"] --> P
  P --> O["1 bien physique<br/>3 publications portail"]
```

Une `Property` est créée (ou enrichie via `MERGED`) dès qu'un advert ingéré est rattaché à un bien physique déjà connu.

## Reconstituer la dédup côté client (propertyFlxId)

Chaque advert porte un champ `propertyFlxId`. **Deux adverts avec le même `propertyFlxId` sont des doublons d'un même bien physique.** La règle d'attribution :

* La première advert non-dupliquée d'une chaîne de dédup a `flxId == propertyFlxId` (l'advert est sa propre racine).
* Chaque advert ingérée ensuite et reconnue comme doublon hérite du `propertyFlxId` de la racine.

Concrètement, si vous recevez deux adverts en webhook :

```json theme={null}
// Advert 1 — racine de la chaîne
{ "flxId": "adv_aaa", "propertyFlxId": "adv_aaa", "source": { "website": "<portail-a>" } }

// Advert 2 — doublon ingéré 12 h plus tard
{ "flxId": "adv_bbb", "propertyFlxId": "adv_aaa", "source": { "website": "<portail-b>" } }
```

Vous savez côté DB que `adv_bbb` est un doublon de `adv_aaa`. Un client ADVERTS-only peut ainsi reconstruire sa propre vue agrégée à la `Property` en groupant par `propertyFlxId` — sans avoir à appeler le côté property de Fluximmo.

## Reproduire la `Property` côté client

Les adverts contiennent **toute l'information** nécessaire pour reconstruire le concept `Property` côté client : il suffit de grouper les adverts par `propertyFlxId` et de maintenir l'agrégat à jour via les événements webhook (`data.created` pour nouveaux adverts, `data.updated` pour les changements de prix/statut).

Voir le playbook [Réplication BDD adverts](/playbooks/replicate-bdd-adverts).

## Cas d'usage

<CardGroup cols={2}>
  <Card title="Recherche multi-portail (BAAS API)" icon="magnifying-glass">
    **Property** — Cas d'usage **principal** côté API : `POST /v2/protected/properties/search` retourne directement les biens dédupliqués multi-portails. Une requête, un résultat propre, facturé à l'appel.
  </Card>

  <Card title="Marketplace / agrégateur" icon="store">
    **Property** — Affichez un bien unique avec ses N sources en bas de fiche. Évitez les doublons visuels qui dégradent l'UX.
  </Card>

  <Card title="Analytics / market intel" icon="chart-line">
    **Property** — Comptez des biens, pas des publications. Les KPIs (stock, durée moyenne en ligne, prix médian) doivent être basés sur la déduplication serveur.
  </Card>

  <Card title="Fintech / scoring crédit" icon="building-columns">
    **Property** — Estimer la valeur d'un bien suppose un objet unique. Utilisez `Property` + `estimatedPrice` pour la valorisation.
  </Card>

  <Card title="Réplication BDD locale" icon="database">
    **Advert** — Seule option pour avoir un stream complet de la donnée Fluximmo en local. Le webhook livre le payload entier et tous les events de cycle de vie.
  </Card>

  <Card title="Tracking concurrentiel par agence" icon="user-tie">
    **Advert** — `seller.flxId` + `source.website` permettent de suivre l'inventaire d'un acteur sur un portail donné, et de mesurer la durée de vie de chaque annonce.
  </Card>
</CardGroup>

## Coût / perf

| Axe                    | ADVERTS (alerte webhook)                                      | PROPERTIES (search API + alerte)                        |
| ---------------------- | ------------------------------------------------------------- | ------------------------------------------------------- |
| Mode                   | Push continu, payload complet, doublons inclus                | Pull à la demande (search) + push allégé (alerte = IDs) |
| Volume webhook         | Élevé : toutes les annonces matching, doublons inter-portails | Faible côté alerte (IDs uniquement, refetch optionnel)  |
| Ownership de la donnée | Fort — vous pouvez tout répliquer en local                    | Moindre — pas de stream continu côté client             |
| Quand c'est gagnant    | Réplication DB, market intel temps réel, analytics interne    | Recherche BAAS, scoring à la demande, UI temps réel     |

<Note>
  **Volume webhook ADVERTS** — c'est un mode haut débit. Sur des filtres larges (un département, plusieurs régions), prévoyez la capacité receiver en conséquence avant d'activer l'alerte. Côté PROPERTIES, l'alerte `MERGED` ne se déclenche **que** quand une nouvelle advert est fusionnée dans une property déjà matchée — pas à chaque check de fraîcheur.
</Note>

## Anti-patterns

<Warning>
  **Stocker en DB les résultats d'un search PROPERTIES — KO.** L'API properties n'est pas conçue pour ce cas. Aucun event `UNPUBLISHED` n'est émis côté property : si un bien est retiré du marché, votre cache local va dériver sans signal. Pour répliquer Fluximmo en local, utilisez **ADVERTS** (alerte webhook avec payload complet + events `UNPUBLISHED`).
</Warning>

<Warning>
  **Faire de l'analytics agrégé sur Adverts sans grouper par `propertyFlxId` — KO.** Un même bien physique compté 5 fois (une fois par portail) gonfle le stock, fausse les médianes prix/m² et biaise les durées en ligne. Si vous répliquez les adverts en DB, groupez par `propertyFlxId` au moment du calcul KPI pour retrouver la vue dédupliquée — ou utilisez directement l'API PROPERTIES côté Fluximmo.
</Warning>

<Warning>
  **Recréer une advert pour "rafraîchir" une property — KO.** Les adverts sont fusionnées automatiquement par le moteur de matching. Ne cherchez pas à recréer ou dupliquer manuellement : la déduplication est un service de Fluximmo.
</Warning>

## Pour aller plus loin

* [Match types & cycle de vie d'une alerte](/concepts/match-types-cycle-alerte) — quand vous recevez `CREATED`, `MERGED`, `ADVERT_EVENT`.
* [Property — modèle complet](/api-v2-reference/_api-models/property)
* [Advert — modèle complet](/api-v2-reference/_api-models/advert)
* [Search Properties](/api-v2-reference/properties-search/search-properties)

<Snippet file="/snippets/cta-cle-test-gratuite.mdx" />