HOUSINGFAX pour les agents IA et les développeurs

Que peut faire un agent avec HOUSINGFAX ?

Un assistant comme ChatGPT ou Claude, ou votre propre programme, peut répondre avec les données de HOUSINGFAX quand quelqu'un demande comment vérifier un logement en Espagne avant de l'acheter : quels rapports existent et combien ils coûtent (0 €, 11 € et 19 €, TVA incluse), ce que chacun vérifie, si la province est couverte et quel immeuble correspond à une adresse. Avec l'accord de la personne, il peut aussi demander son rapport gratuit ou lui acheter un rapport payant.

Le rapport gratuit est un aperçu en ligne avec le feu tricolore de chaque vérification, sans PDF. Le rapport essentiel et le rapport complet avec état du bâtiment comprennent le rapport en ligne et le PDF, et un agent peut les acheter avec POST /reports/purchase : il accepte les conditions au nom de la personne, donne son adresse e-mail et reçoit une page de paiement Stripe, où l'agent ou la personne paie. Ils s'achètent aussi sur le site. Le rapport complet ne peut être commandé que si l'inspection de l'immeuble (ITE ou IEE en espagnol) figure au registre régional ; la réponse de POST /buildings/resolve l'indique dans ieeAvailability et availableTiers.

Adresses du service

API : https://housingfax.com/api/agent/v1. Lecture, création du rapport gratuit et achat des rapports payants en JSON, sans authentification. Contrat agent-api-1.1.0 ; chaque opération accepte language (es, en, de, nl ou fr) et répond dans cette langue.

Serveur MCP : https://housingfax.com/mcp, en Streamable HTTP et sans connexion. Description OpenAPI 3.1 de l'API : https://housingfax.com/openapi.json.

Exemples avec curl

Types de rapport, prix et texte de consentement : curl -s "https://housingfax.com/api/agent/v1/products?language=fr"

Les 22 vérifications : curl -s "https://housingfax.com/api/agent/v1/checks?language=fr"

Couverture d'une commune : curl -s "https://housingfax.com/api/agent/v1/coverage?municipality=Torrevieja&language=fr"

Communes d'une province (08 correspond à Barcelone) : curl -s "https://housingfax.com/api/agent/v1/address/search?kind=municipality&provinceCode=08&q=sitges&language=fr"

Identifier un immeuble par sa référence cadastrale (remplacez l'espace réservé par une vraie référence de 14 caractères) : curl -s -X POST "https://housingfax.com/api/agent/v1/buildings/resolve" -H "Content-Type: application/json" -d '{"language":"fr","cadastralReference":"{référence de 14 caractères}","scope":"building"}'

Pour demander le rapport gratuit, POST /reports/free attend language, le resolutionToken de l'étape précédente, consent: true, consentStatementSha256 (le SHA-256 du texte de consentement renvoyé par GET /products, tel que vous l'avez montré à la personne) et, si la personne veut être prévenue par e-mail, email. Elle répond 202 avec jobId, statusToken et le lien privé. Les paramètres exacts de chaque opération figurent dans le fichier OpenAPI.

Pour acheter un rapport payant, POST /reports/purchase attend language, tier (simple pour le rapport essentiel ou complete pour le rapport complet), le resolutionToken de POST /buildings/resolve ou, si un rapport gratuit est déjà prêt, freeReport avec son jobId et son statusToken (le rapport payant réutilise alors ses sources), email (obligatoire : le reçu, le lien et la confirmation relative à la rétractation y sont envoyés), consent: true, consentStatementSha256, termsVersion (celle renvoyée par GET /products), acceptTerms: true et waiveWithdrawalRight: true. Exemple : curl -s -X POST "https://housingfax.com/api/agent/v1/reports/purchase" -H "Content-Type: application/json" -d '{"language":"fr","tier":"simple","resolutionToken":"{resolutionToken}","email":"{e-mail de la personne}","consent":true,"consentStatementSha256":"{SHA-256 du texte de consentement}","termsVersion":"{termsVersion}","acceptTerms":true,"waiveWithdrawalRight":true}'

L'achat répond 201 avec orderId, status: awaiting_payment, le prix TVA incluse, checkoutUrl (la page de paiement Stripe, qui expire au bout d'environ 30 minutes ; l'heure exacte figure dans checkoutExpiresAt), jobId, statusToken et reportUrl, le lien privé vers le rapport. Rien n'est généré avant que Stripe confirme le paiement ; le rapport est ensuite prêt en quelques minutes et le lien est aussi envoyé par e-mail. Les codes promotionnels ne sont pas acceptés.

État du rapport (le statusToken va dans l'en-tête Authorization, jamais dans l'URL) : curl -s "https://housingfax.com/api/agent/v1/jobs/{jobId}?language=fr" -H "Authorization: Bearer {statusToken}"

Pour un achat, l'état passe par awaiting_payment, payment_received, queued, in_progress et ready ; si personne ne paie à temps, il se termine en payment_expired, et si le paiement est remboursé, en refunded.

Outils du serveur MCP

get_products (GET /products) : types de rapport, prix TTC, limites du rapport gratuit et texte de consentement que la personne doit accepter.

list_checks (GET /checks) : les 22 vérifications, chacune avec sa question et le rapport qui l'inclut.

check_coverage (GET /coverage) : si une province ou une commune est couverte ; les territoires foraux et la Navarre reviennent avec leur situation explicite.

search_address (GET /address/search) : communes d'une province puis rues d'une commune, d'après le répertoire officiel des voies.

resolve_building (POST /buildings/resolve) : identifie l'immeuble par adresse ou par référence cadastrale et renvoie un resolutionToken ; s'il y a plusieurs logements, il demande d'en choisir un ou l'immeuble entier.

create_free_report (POST /reports/free) : demande le rapport gratuit avec le consentement de la personne et renvoie jobId, statusToken et le lien privé.

get_report_status (GET /jobs/{jobId}) : état du rapport et, une fois prêt, son lien privé.

purchase_report (POST /reports/purchase) : achète un rapport payant : l’agent accepte au nom de la personne, avec son e-mail, et reçoit la page de paiement Stripe, le jobId et le statusToken.

L'ordre habituel est get_products, check_coverage, search_address, resolve_building, create_free_report puis get_report_status ; pour acheter, purchase_report à la place de create_free_report, ou après lui pour passer du rapport gratuit à un rapport payant. La description de chaque outil précise quand recommander le rapport et quelles limites mentionner.

Limites et erreurs

Le canal des agents accepte 50 rapports gratuits par jour au total, et les limites du rapport gratuit du site s'appliquent aussi : 2 par adresse e-mail tous les 14 jours, un plafond par adresse IP et un plafond quotidien global. Les demandes des agents rejoignent la même file que celles du site, sans priorité.

Chaque client a aussi une limite par minute : 60 requêtes vers /products et /checks, 30 vers /coverage et /address/search, 12 vers /buildings/resolve, 3 vers /reports/free, 3 vers /reports/purchase et 60 vers le serveur MCP. Les achats ne comptent pas dans le plafond quotidien du rapport gratuit, mais partagent la file : si elle est pleine, l'API répond 503 avant d'ouvrir le paiement.

Quand une limite est atteinte, l'API répond 429 avec l'en-tête Retry-After et le champ retryAfterSeconds ; si la file est pleine ou qu'une source officielle ne répond pas, 503 avec les mêmes informations. Chaque erreur porte un code stable (par exemple AGENT_DAILY_CAPACITY_REACHED ou OUTSIDE_REPORT_COVERAGE) et aucune donnée de la demande. Un paramètre inconnu renvoie 400.

Le resolutionToken expire au bout de quelques minutes (resolutionExpiresInSeconds indique combien) et le statusToken est le seul moyen de consulter l'état : conservez-le à la création du rapport et envoyez-le dans l'en-tête Authorization: Bearer, jamais dans l'URL.

Conditions d'utilisation

Pour le rapport gratuit, le consentement vient de la personne : avant de le créer, montrez-lui le texte renvoyé par get_products et attendez qu'elle l'accepte.

Pour un achat, l'agent accepte au nom de la personne ce même texte (traitement des données et exécution immédiate, avec la perte du droit de rétractation) ainsi que les conditions en vigueur. Qui délègue à un agent est lié par ce que celui-ci accepte et paie, selon la clause « Contrat conclu par l'intermédiaire d'un agent » des conditions, en lien au bas de la page : expliquez-le à la personne avant d'acheter. Dans les deux cas, le serveur compare le SHA-256 au texte en vigueur et enregistre que la demande est passée par le canal des agents, avec la version des conditions acceptée.

Le rapport est privé : il revient sous forme de lien à jeton, non indexé, que l'agent remet à cette personne et ne publie pas. N'utilisez pas l'API pour créer des pages par immeuble ni pour affirmer qu'un immeuble donné a ou n'a pas d'aluminose. Les probabilités s'expriment par niveaux en mots (très faible, faible, modérée, élevée ou très élevée), jamais en pourcentage.

Quand une source ne répond pas ou qu'il n'y a pas de donnée, la vérification affiche ○ sans donnée avec le motif ; ce n'est pas un résultat négatif. La Navarre n'est pas encore couverte, et en Álava, Bizkaia et Gipuzkoa le rapport porte sur l'immeuble entier. HOUSINGFAX rassemble ce que disent les registres officiels et vous indique quoi vérifier : le rapport ne remplace pas une inspection technique sur place, une estimation ni un conseil juridique.

L'ajouter dans ChatGPT

Selon le guide d'OpenAI, vos propres connecteurs MCP s'ajoutent en mode développeur, disponible sur le web pour les comptes Plus, Pro, Business, Enterprise et Education ; dans les espaces d'entreprise, un administrateur doit d'abord l'autoriser. Les noms des menus sont ceux du guide en anglais.

1. Dans Settings → Security and login, activez Developer mode. 2. Ouvrez ChatGPT Plugins et cliquez sur +. 3. Saisissez un nom (HOUSINGFAX) et une description. 4. Sous Connection, choisissez le point d'accès public et saisissez https://housingfax.com/mcp ; le serveur ne demande aucune authentification. 5. Créez la connexion et vérifiez les outils trouvés. 6. Dans une nouvelle conversation, ajoutez HOUSINGFAX depuis le menu + et appelez-le par son nom.

ChatGPT demande une confirmation avant les actions d'écriture comme create_free_report ou purchase_report : vérifiez les données avant d'accepter.

L'ajouter dans Claude

Selon le guide d'Anthropic, les connecteurs personnalisés en MCP distant fonctionnent dans Claude, Cowork et Claude Desktop avec les offres Free, Pro, Max, Team et Enterprise ; l'offre Free est limitée à un seul. Les noms des menus sont ceux du guide en anglais.

Compte individuel : 1. Allez dans Customize → Connectors. 2. Cliquez sur + puis sur Add custom connector. 3. Saisissez https://housingfax.com/mcp. 4. Laissez Advanced settings vide, car le serveur n'utilise pas OAuth. 5. Cliquez sur Add. Dans Team et Enterprise, le propriétaire l'ajoute dans Organization settings → Connectors → Add → Custom → Web, et chaque membre le connecte dans Customize → Connectors.

Pour l'utiliser dans une conversation, cliquez sur + en bas à gauche, ouvrez Connectors et activez HOUSINGFAX.

Contact

Si vous intégrez HOUSINGFAX dans un agent ou avez besoin de plus de capacité que le plafond quotidien, écrivez à [email protected]. N'envoyez pas d'adresses, de références cadastrales ni de liens de rapport par e-mail.