FAQ

Votre token est manquant, invalide ou révoqué. Vérifiez que le header est bien formaté : X-API-Key: normi_votre_token pour l'API REST, ou Authorization: Bearer normi_votre_token pour le MCP. Régénérez un token depuis le tableau de bord si nécessaire.

Non. Chaque compte peut avoir un seul token actif. Créer un nouveau token révoque silencieusement l'ancien. Mettez à jour vos applications immédiatement après rotation.

Non. Seul le SHA-256 de votre token est stocké en base. La comparaison utilise timingSafeEqual pour éviter les attaques par timing. Le token en clair n'est visible qu'une seule fois lors de sa création.

Ajoutez le header X-API-Key: normi_votre_token à chaque requête. Exemple : curl -H "X-API-Key: normi_votre_token" https://mcp.normi.fr/v1/transactions?code_postal=75001

Les sessions MCP ont un TTL de 15 minutes. Après expiration, le serveur retourne 409. Réinitialisez la connexion en relançant Claude Desktop ou en exécutant à nouveau la commande claude mcp add. Les sessions sont aussi perdues lors d'un redéploiement Railway.

15 minutes est un compromis entre sécurité et ergonomie. Les sessions MCP sont stockées en mémoire sur Railway (pas en base), donc elles ne survivent pas aux redéploiements. Une session est réinitialisée instantanément — ce n'est pas une friction significative.

Vérifiez que la commande claude mcp add a bien été exécutée. Sur Claude Desktop, redémarrez l'application après édition du fichier de config. Si vous utilisez un autre client, vérifiez que l'URL https://mcp.normi.fr/mcp et le header Authorization: Bearer VOTRE_TOKEN sont corrects.

Les crédits sont déduits après exécution réussie de chaque outil (fire-and-forget). Si un outil échoue (erreur DB, timeout), les crédits ne sont pas déduits. Les appels avec crédits insuffisants retournent un message d'erreur en texte — pas un HTTP 402.

L'erreur apparaît dans le corps de la réponse MCP (content[0].text), pas comme code HTTP 402. Achetez des crédits depuis le tableau de bord. Si vous utilisez l'API REST, l'erreur est dans le champ message du JSON.

L'abonnement recharge automatiquement vos crédits le 1er de chaque mois. Entre deux recharges, vous pouvez acheter des packs one-time depuis le tableau de bord. Vos crédits mensuels ne sont pas reportés — ils sont réinitialisés à chaque recharge.

Oui. Les comptes Free reçoivent 100 crédits le 1er de chaque mois via un cron automatique. Suffisant pour ~20 appels à search_properties ou get_market_stats.

Le solde restant est retourné dans chaque réponse dans le champ _credits.remaining. Vous pouvez aussi le consulter dans le tableau de bord sous Usage.

Vous dépassez la limite de requêtes par minute de votre plan : Free/Pro = 60 req/min, Agent = 30 req/min, Enterprise = 120 req/min. Attendez quelques secondes et réessayez. Implémentez un backoff exponentiel dans vos scripts.

Maximum 200 résultats par requête (paramètre limit). Utilisez offset pour paginer. Pour les grandes zones (75015–75020), ajoutez date_debut pour éviter les timeouts.

Oui. Toutes les requêtes sont limitées à 8 secondes (timeout PostgREST sur le rôle authenticator). Les requêtes sur de grandes zones sans date_debut peuvent dépasser ce timeout — toujours spécifier date_debut pour les zones denses.

Les données DVF stockent Paris par arrondissement : PARIS 01, PARIS 02, … PARIS 20. Pour requêter tout Paris, utilisez commune=PARIS (notre API utilise commune_base en interne pour matcher les variantes). Évitez code_postal=75000 qui n'existe pas.

exclude_bulk_sales=true exclut les ventes en lot (plusieurs biens dans une seule transaction). exclude_outliers=true exclut les prix aberrants détectés par méthode IQR (quartiles Q1/Q3 ± 3×IQR). Ces filtres sont activés par défaut pour garantir des statistiques représentatives.

DVF est publié deux fois par an par la DGFiP (en mai et octobre). Normi intègre chaque publication sous 48h. Les transactions récentes (moins de 6 mois) peuvent donc manquer selon la période de l'année.

Pour les rayons supérieurs à 1000m, l'API restreint automatiquement les résultats aux 12 derniers mois pour éviter les timeouts sur de grandes zones. La réponse inclut un champ notice expliquant la limitation appliquée.

score = 1.0 représente un comparable parfait. Le score est calculé sur deux critères : distance géographique (plus proche = meilleur score) et écart de surface par rapport au bien cible. Un score > 0.8 indique un excellent comparable.

surface_reelle_bati est la surface déclarée totale du bâti (peut inclure caves, parkings). surface_carrez_lot1 est la surface loi Carrez (surface habitable nette, hors combles < 1.80m, caves, garages). Pour les estimations au m², préférez surface_carrez_lot1 quand disponible.

L'API REST (mcp.normi.fr/v1/...) est une API HTTP classique — utilisez-la dans vos scripts, applications web, ou outils d'analyse. Le serveur MCP (mcp.normi.fr/mcp) est conçu pour les assistants IA comme Claude : il expose les mêmes données via le protocole MCP pour que l'IA les appelle automatiquement.

Oui. Les mêmes opérations coûtent les mêmes crédits quelle que soit l'interface : GET /v1/transactions = search_properties = 5 crédits, GET /v1/stats/market = get_market_stats = 5 crédits, etc.

Oui. Le même token fonctionne pour REST et MCP. Les crédits sont mutualisés sur votre compte.