> ## 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.

# Match types & cycle de vie d'une alerte

> Comprendre les types de matches (CREATED, MERGED, ADVERT_EVENT) et pourquoi recréer une alerte fait perdre l'historique.

Un **match** est l'événement métier qu'émet Fluximmo lorsqu'une advert ou une property satisfait les critères d'une alerte. Chaque match est livré au webhook de l'alerte. Le **type** de match indique la nature de l'événement : nouveau bien découvert, fusion, ou événement sur un bien déjà matché.

## Match types — Adverts

| Type (souscription `match[]`) | Quand                                                                                                   | Branche du webhook canonique                                                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ALERT_MATCH_CREATED`         | Une nouvelle advert vient d'être ingérée et qualifiée par l'alerte. Émis **une seule fois** par advert. | `data.created[]` — `AdvertDto` complet.                                                                                                                              |
| `ALERT_MATCH_ADVERT_EVENT`    | Une advert **historiquement matchée par cette alerte** a évolué (prix, status).                         | `data.updated[]` — DTO réduit (`flxId`, `currentPrice`, `isOnline`). Type d'event (PRICE / REPUBLISHED / UNPUBLISHED) **dérivé côté client** par diff vs état local. |

## Match types — Properties

| Type                  | Quand                                                                                                                                                    | Payload (webhook)         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `ALERT_MATCH_CREATED` | Une property vient d'être créée et qualifiée par l'alerte.                                                                                               | IDs uniquement → refetch. |
| `ALERT_MATCH_MERGED`  | Une nouvelle advert vient d'être fusionnée dans une property **déjà matchée**. Émis uniquement à la fusion (pas à la création de la property elle-même). | IDs uniquement → refetch. |

## Comparatif Adverts vs Properties

|                                      | Adverts                                                                                                   | Properties                               |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `CREATED`                            | Oui                                                                                                       | Oui                                      |
| `MERGED`                             | Non par nature (chaque advert reste distincte) — mais `propertyFlxId` permet la déduplication côté client | **Oui** — fusion = nouveau matching      |
| Events post-création (`PRICE`, etc.) | **Oui** via `ADVERT_EVENT`                                                                                | **Non** — pas d'event natif sur Property |

Si vous avez besoin d'événements granulaires (variation de prix, online/offline), **utilisez les alertes Adverts**. Les alertes Properties ne livrent que des notifications de découverte/fusion.

## Events ADVERT — à dériver côté client

Le webhook ADVERT pousse les advert evolved dans `data.updated[]` avec un DTO minimal (`flxId`, `currentPrice {value, valuePerArea}`, `isOnline`). Il n'y a **pas de champ `event_type`** côté serveur — vous reconstituez l'événement par comparaison avec votre état stocké local :

| Event dérivé  | Règle de détection (côté client)                          | Note                                                                                                                  |
| ------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `PRICE`       | `advert.currentPrice.value` ≠ valeur précédemment stockée | Toute variation, **même 1 €**. Pas de seuil serveur. Filtrez côté client si vous voulez ignorer les micro-variations. |
| `REPUBLISHED` | `advert.isOnline` passe de `false` à `true`               | Annonce remise en ligne.                                                                                              |
| `UNPUBLISHED` | `advert.isOnline` passe de `true` à `false`               | Annonce retirée.                                                                                                      |

<Note>
  **Pré-requis** : maintenez localement (`flxId` → `{ price, isOnline }`) à jour à chaque webhook (`data.created` ET `data.updated`) pour pouvoir comparer au prochain. Sans état local, impossible de dériver les events.

  **`CHECK` non émis.** Les vérifications périodiques sans changement réel ne déclenchent aucun webhook — pas de bruit.
</Note>

<Snippet file="/snippets/warning-cycle-vie-alerte.mdx" />

## Pas de backfill à la création

Une alerte ne match **que** les annonces ingérées **après** sa création (`createdAt`). Les annonces déjà présentes dans le catalogue qui rempliraient les critères ne déclencheront pas de match.

```mermaid theme={null}
sequenceDiagram
  participant Fluximmo
  participant Alerte
  participant Webhook

  Note over Fluximmo: t = -2 j<br/>advert A1 ingerée (qualifiante)
  Note over Alerte: t = 0<br/>création de l'alerte
  Note right of Alerte: A1 jamais matchée<br/>(antérieure)
  Fluximmo->>Webhook: t = 1 → A2 ingérée → ALERT_MATCH_CREATED
  Fluximmo->>Webhook: t = 2 → A2 changement de prix → ALERT_MATCH_ADVERT_EVENT (PRICE)
  Fluximmo->>Webhook: t = 3 → A2 passe offline → ALERT_MATCH_ADVERT_EVENT (UNPUBLISHED)
  Note over Alerte: t = 4<br/>DELETE + recréation alerte
  Note right of Alerte: ⚠️ historique A2 perdu<br/>plus aucun event sur A2
```

**Pattern recommandé pour couvrir passé + futur** :

1. **Côté PROPERTIES** : `POST /v2/protected/properties/search` one-shot avec vos critères pour récupérer les biens déjà ingérés ; en parallèle, créez une alerte property pour le flux continu.
2. **Côté ADVERTS** : créez l'alerte ADVERT pour le flux continu, et **demandez par mail** à [contact@fluximmo.com](mailto:contact@fluximmo.com) la réception du backfill historique sur votre webhook (volume + dates précisés).
3. **Dédupliquez** côté client : un même `flxId` peut réapparaître si ingéré à nouveau (rare). Utilisez `flxId` comme clé d'idempotence.

## Pour aller plus loin

* [Webhooks — architecture, retry, sécurité](/concepts/webhooks)
* [Property vs Advert](/concepts/property-vs-advert)
* Endpoints alertes : `PUT /v2/protected/properties/search/alerts`, `PUT /v2/protected/adverts/search/alerts`, `PATCH /v2/protected/{adverts,properties}/search/alerts/{flxId}`.

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