FAQ

Pour un assistant (claude.ai sur le web, mobile ou Cowork, ChatGPT, Claude Code), utilisez la connexion OAuth : collez https://mcp.normi.fr/mcp, connectez-vous à Normi et autorisez, sans clé à copier. Pour l'API REST, un script, la CI, Cursor ou le paquet STDIO @normi/mcp-dvf, utilisez une clé API normi_…. La connexion OAuth ne fonctionne que sur le serveur MCP, pas sur l'API REST.

Oui, exactement comme une clé API : chaque appel d'outil est débité sur la clé API active de votre compte, au même tarif. Une application connectée n'a pas de solde séparé. Si vous n'aviez pas encore de clé, la première autorisation en crée une avec 500 crédits gratuits ; sinon votre solde et votre plan restent inchangés.

C'est voulu. Une application OAuth utilise la clé active de votre compte ; sans clé active, ses appels échouent avec « no active API key » (403 no_active_key). Créez une nouvelle clé depuis le tableau de bord : l'application reprend dès l'appel suivant, sans reconnexion. Une simple rotation (nouvelle clé qui remplace l'ancienne) ne coupe rien.

Tableau de bord → Tokens → Applications connectées → Révoquer. L'application est coupée dès son appel suivant et devra redemander l'autorisation. Se déconnecter de normi.fr, en revanche, ne déconnecte pas vos applications.

Oui. Les URL /mcp/claude/… et /mcp/chatgpt/… restent prises en charge pour les clients qui ne gèrent pas OAuth. Pour claude.ai et ChatGPT, la connexion OAuth est plus sûre : rien de secret dans l'URL, et chaque application se révoque séparément.

ChatGPT garde en cache la configuration du connecteur et « Reconnecter » ne la relit pas. Supprimez le connecteur dans ChatGPT puis recréez-le avec https://mcp.normi.fr/mcp ; la connexion OAuth se relance normalement.

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. Sur le serveur MCP, un 401 sans identifiant porte un en-tête WWW-Authenticate : c'est lui qui déclenche la connexion OAuth dans les clients compatibles.

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

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

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. Le message donne le lien d'achat (https://www.normi.fr/dashboard/credits) et, pour un compte gratuit, la date de la prochaine remise à 500 crédits. En REST, la même information est dans le champ message, ainsi que dans upgrade_url et free_credits_reset_at.

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 500 crédits le 1er de chaque mois via un cron automatique. Suffisant pour ~100 appels à search_property_transactions ou analyze_market_statistics.

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 / Indie / Agent / Scale = 60 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). Ce filtre est activé par défaut pour garantir des statistiques représentatives. exclude_outliers est obsolète et sans effet : les prix aberrants (moins de 500 €/m² ou plus de 100 000 €/m² sur du bâti) sont retirés dès l'ingestion, donc aucune transaction publiée n'en est un. Le paramètre reste accepté pour ne pas casser les appels existants, mais il est ignoré.

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.

Commencez à 500 m et 12 mois. Pour les transactions, un rayon supérieur à 1000 m sans date explicite est limité aux 12 derniers mois et signalé par notice. Pour les comparables et l'estimation, les paramètres explicites sont conservés : utilisez 2 km seulement en zone rare, jusqu'à 36 mois pour les comparables et 24 mois pour l'estimation, puis découpez une zone dense par périodes. Un notice conserve des données partielles ; dense_query_timeout signifie qu'aucun résultat exploitable n'a été obtenu et que les crédits sont remboursés.

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 et ChatGPT : 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_property_transactions = 5 crédits, GET /v1/stats/market = analyze_market_statistics = 5 crédits, etc.

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