API REST / Alerts

Alerts

Créez des alertes webhook pour être notifié automatiquement des nouvelles transactions DVF correspondant à vos critères.

Plan Pro ou Enterprise requis

Les alertes webhook sont disponibles uniquement sur les plans Pro et Enterprise. Les appels depuis un plan Free ou Agent retournent HTTP 403. Maximum 20 alertes actives par clé API.

POST/v1/alerts0 crédits

Crée une alerte webhook. Dès qu'une nouvelle transaction DVF correspond aux critères définis, une requête POST est envoyée à l'URL webhook avec le détail de la transaction.

Paramètres

Paramètre	Type	Défaut	Description
webhook_url*	string	—	URL HTTPS vers laquelle les notifications seront envoyées (POST JSON)
code_postal	string	—	Code postal cible. Au moins un filtre de localisation requis.
commune	string	—	Commune en majuscules (ex. PARIS 11, LYON).
code_departement	string	—	Code département (ex. 75, 69).
type_local	enum	—	Maison \| Appartement \| Terrain \| Local commercial \| Dépendance \| Local industriel
prix_min	number	—	Prix minimum en euros (valeur foncière)
prix_max	number	—	Prix maximum en euros
surface_min	number	—	Surface minimum en m²
surface_max	number	—	Surface maximum en m²

Exemple — alerte appartements Paris 11

curl -X POST "https://mcp.normi.fr/v1/alerts" \
  -H "X-API-Key: normi_votre_token" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://votre-app.com/webhooks/dvf",
    "code_postal": "75011",
    "type_local": "Appartement",
    "prix_min": 400000,
    "prix_max": 700000,
    "surface_min": 40
  }'

Réponse (HTTP 201)

{
  "alert": {
    "id": "alert_x9y8z7",
    "api_key_id": "key_xxx",
    "webhook_url": "https://votre-app.com/webhooks/dvf",
    "code_postal": "75011",
    "type_local": "Appartement",
    "prix_min": 400000,
    "prix_max": 700000,
    "surface_min": 40,
    "surface_max": null,
    "is_active": true,
    "created_at": "2026-03-20T14:00:00.000Z",
    "updated_at": "2026-03-20T14:00:00.000Z"
  }
}

GET/v1/alerts0 crédits

Liste toutes les alertes (actives et inactives) associées à cette clé API.

Réponse

{
  "alerts": [
    {
      "id": "alert_x9y8z7",
      "webhook_url": "https://votre-app.com/webhooks/dvf",
      "code_postal": "75011",
      "type_local": "Appartement",
      "is_active": true,
      ...
    }
  ]
}

PUT/v1/alerts/:id0 crédits

Met à jour les critères d'une alerte. Tous les champs sont optionnels. Utilisez is_active: false pour désactiver temporairement une alerte sans la supprimer.

Exemple

curl -X PUT "https://mcp.normi.fr/v1/alerts/alert_x9y8z7" \
  -H "X-API-Key: normi_votre_token" \
  -H "Content-Type: application/json" \
  -d '{ "prix_max": 750000, "is_active": false }'

DELETE/v1/alerts/:id0 crédits

Supprime définitivement une alerte. Retourne HTTP 204 en cas de succès, 404 si l'alerte n'existe pas.

Exemple

curl -X DELETE "https://mcp.normi.fr/v1/alerts/alert_x9y8z7" \
  -H "X-API-Key: normi_votre_token"

Format du payload webhook

Lorsqu'une transaction correspondante est détectée, Normi envoie une requête POST à votre webhook_url avec le corps JSON suivant :

{
  "event": "new_transaction",
  "alert_id": "alert_x9y8z7",
  "transaction": {
    "id": "dvf_abc123",
    "address": "12 RUE DE LA ROQUETTE, 75011, PARIS 11",
    "date_mutation": "2026-03-18",
    "type_local": "Appartement",
    "surface_carrez": 58.5,
    "valeur_fonciere": 545000,
    "prix_m2": 9316
  }
}

Bonnes pratiques

Votre endpoint webhook doit répondre en moins de 10 secondes avec un statut 2xx.
En cas d'échec, Normi retente 3 fois avec un délai exponentiel.
Utilisez is_active: false pour suspendre une alerte temporairement plutôt que de la supprimer.
La limite de 20 alertes actives est par clé API — les alertes inactives ne comptent pas.
DVF est mis à jour semestriellement (avril / octobre) — les alertes se déclenchent à chaque import de nouvelles données.

/v1/portfolio — CRUD

GET /v1/stats/compare