API REST / Portfolio

Portfolio

Gérez un portefeuille de biens immobiliers avec estimations automatiques basées sur les données DVF.

POST/v1/portfolio10 crédits

Ajoute un bien au portefeuille. Pour les types Maison et Appartement, une estimation DVF est automatiquement calculée au moment de l'ajout (10 crédits). Pour les autres types (Terrain, Local commercial, Dépendance), seules les métadonnées sont enregistrées (2 crédits).

Corps de la requête (JSON)

Envoyez les données en JSON avec le header Content-Type: application/json.

Paramètres

Paramètre	Type	Défaut	Description
latitude*	number	—	Latitude GPS du bien
longitude*	number	—	Longitude GPS du bien
type_local*	enum	—	Maison \| Appartement \| Terrain \| Local commercial \| Dépendance
surface*	number	—	Surface en m² (valeur positive)
label	string	—	Libellé personnalisé (max 255 caractères)
address	string	—	Adresse textuelle (max 500 caractères)
code_postal	string	—	Code postal du bien
commune	string	—	Commune du bien
pieces	number	—	Nombre de pièces (entier positif)
purchase_price	number	—	Prix d'achat en euros (pour suivi de plus-value)

Exemple — ajouter un appartement

curl -X POST "https://mcp.normi.fr/v1/portfolio" \
  -H "X-API-Key: normi_votre_token" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Appart Paris 11",
    "latitude": 48.8581,
    "longitude": 2.3790,
    "type_local": "Appartement",
    "surface": 65,
    "pieces": 3,
    "code_postal": "75011",
    "commune": "PARIS 11",
    "purchase_price": 580000
  }'

Réponse (HTTP 201)

{
  "property": {
    "id": "prop_a1b2c3d4",
    "api_key_id": "key_xxx",
    "label": "Appart Paris 11",
    "latitude": 48.8581,
    "longitude": 2.379,
    "type_local": "Appartement",
    "surface": 65,
    "pieces": 3,
    "code_postal": "75011",
    "commune": "PARIS 11",
    "purchase_price": 580000,
    "estimate_low": 572000,
    "estimate_mid": 614500,
    "estimate_high": 668000,
    "estimate_pm2": 9454,
    "estimate_confidence": 0.87,
    "estimate_based_on": 11,
    "estimate_computed_at": "2026-03-20T14:32:10.000Z",
    "created_at": "2026-03-20T14:32:10.000Z",
    "updated_at": "2026-03-20T14:32:10.000Z"
  },
  "_credits": { "used": 10, "remaining": 75 }
}

GET/v1/portfolio0 crédits

Liste tous les biens du portefeuille associés à cette clé API. Retourne les estimations en cache — aucun crédit déduit.

Réponse

{
  "properties": [
    {
      "id": "prop_a1b2c3d4",
      "label": "Appart Paris 11",
      "type_local": "Appartement",
      "surface": 65,
      "estimate_mid": 614500,
      "estimate_computed_at": "2026-03-20T14:32:10.000Z",
      ...
    }
  ]
}

GET/v1/portfolio/:id0 crédits

Retourne un bien par son identifiant. Si l'estimation date de plus de 30 jours, elle est recalculée automatiquement (10 crédits supplémentaires). Le champ estimate_refreshed indique si un recalcul a eu lieu.

Rafraîchissement automatique

Le recalcul est déclenché uniquement pour les types Maison et Appartement dont l'estimation a plus de 30 jours. 10 crédits sont alors déduits.

Réponse

{
  "property": { ... },
  "estimate_refreshed": false,
  "_credits": { "used": 0, "remaining": 75 }
}

PUT/v1/portfolio/:id0 crédits

Met à jour les métadonnées d'un bien. Si la position GPS (latitude/longitude), la surface ou le type_local changent, l'estimation en cache est invalidée — elle sera recalculée au prochain GET /portfolio/:id.

Exemple

curl -X PUT "https://mcp.normi.fr/v1/portfolio/prop_a1b2c3d4" \
  -H "X-API-Key: normi_votre_token" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Résidence principale", "purchase_price": 595000 }'

DELETE/v1/portfolio/:id0 crédits

Supprime définitivement un bien du portefeuille. Retourne HTTP 204 (sans corps) en cas de succès, 404 si le bien n'existe pas ou n'appartient pas à cette clé.

Exemple

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

Cycle de vie des estimations

L'estimation est calculée à la création (POST) pour Maison / Appartement.
Modifier la position, la surface ou le type invalide l'estimation en cache.
Après 30 jours, le prochain GET /portfolio/:id recalcule automatiquement (10 crédits).
Utilisez GET /v1/estimate pour une estimation ponctuelle sans stocker le bien.

GET /v1/market-score

/v1/alerts — CRUD