HOUSINGFAX para agentes y desarrolladores

¿Qué puede hacer un agente con HOUSINGFAX?

Un asistente como ChatGPT o Claude, o un programa tuyo, puede contestar con datos de HOUSINGFAX cuando alguien pregunta cómo revisar una vivienda antes de comprarla: qué informes hay y cuánto cuestan (0 €, 11 € y 19 €, IVA incluido), qué comprueba cada uno, si la provincia tiene cobertura y cuál es el edificio de una dirección. Con permiso de la persona, también puede pedir su informe gratuito o comprarle uno de pago.

El informe gratuito es una vista previa en la web con el semáforo de cada comprobación, sin PDF. El informe esencial y el informe completo con estado del edificio tienen informe web y PDF, y el agente puede comprarlos con POST /reports/purchase: acepta los términos en nombre de la persona, da su correo y recibe la página de pago de Stripe, donde paga él o la persona. También se compran en la web. El completo solo se puede pedir cuando consta la inspección del edificio (ITE o IEE) en el registro autonómico; la respuesta de POST /buildings/resolve lo indica en ieeAvailability y availableTiers.

Direcciones del servicio

API: https://housingfax.com/api/agent/v1. Lectura, creación del informe gratuito y compra de los de pago en JSON, sin autenticación. Contrato agent-api-1.1.0; todas las operaciones aceptan language (es, en, de, nl o fr) y responden en ese idioma.

Servidor MCP: https://housingfax.com/mcp, con transporte Streamable HTTP y sin inicio de sesión. Descripción OpenAPI 3.1 de la API: https://housingfax.com/openapi.json.

Ejemplos con curl

Tipos de informe, precios y texto de consentimiento: curl -s "https://housingfax.com/api/agent/v1/products?language=es"

Las 22 comprobaciones: curl -s "https://housingfax.com/api/agent/v1/checks?language=es"

Cobertura de un municipio: curl -s "https://housingfax.com/api/agent/v1/coverage?municipality=Getafe&language=es"

Municipios de una provincia (46 es Valencia): curl -s "https://housingfax.com/api/agent/v1/address/search?kind=municipality&provinceCode=46&q=gandia"

Identificar un edificio por su referencia catastral (sustituye el marcador por una referencia real de 14 caracteres): curl -s -X POST "https://housingfax.com/api/agent/v1/buildings/resolve" -H "Content-Type: application/json" -d '{"language":"es","cadastralReference":"{referencia de 14 caracteres}","scope":"building"}'

Para pedir el informe gratuito, POST /reports/free recibe language, el resolutionToken del paso anterior, consent: true, consentStatementSha256 (el SHA-256 del texto de consentimiento que devolvió GET /products, tal como se lo enseñaste a la persona) y, si la persona quiere el aviso por correo, email. Responde 202 con jobId, statusToken y el enlace privado. Los parámetros exactos de cada operación están en el OpenAPI.

Para comprar un informe de pago, POST /reports/purchase recibe language, tier (simple para el esencial o complete para el completo), el resolutionToken de POST /buildings/resolve o, si ya hay un gratuito listo, freeReport con su jobId y su statusToken (entonces el de pago reutiliza sus fuentes), email (obligatorio: allí llegan el recibo, el enlace y la confirmación del desistimiento), consent: true, consentStatementSha256, termsVersion (la que devolvió GET /products), acceptTerms: true y waiveWithdrawalRight: true. Ejemplo: curl -s -X POST "https://housingfax.com/api/agent/v1/reports/purchase" -H "Content-Type: application/json" -d '{"language":"es","tier":"simple","resolutionToken":"{resolutionToken}","email":"{correo de la persona}","consent":true,"consentStatementSha256":"{SHA-256 del texto de consentimiento}","termsVersion":"{termsVersion}","acceptTerms":true,"waiveWithdrawalRight":true}'

La compra responde 201 con orderId, status: awaiting_payment, el precio con IVA, checkoutUrl (la página de pago de Stripe, que caduca en unos 30 minutos; la hora exacta va en checkoutExpiresAt), jobId, statusToken y reportUrl, el enlace privado del informe. No se genera nada hasta que Stripe confirma el pago; después, el informe está listo en unos minutos y el enlace llega también por correo. No admite códigos promocionales.

Estado del informe (el statusToken va en la cabecera Authorization, nunca en la URL): curl -s "https://housingfax.com/api/agent/v1/jobs/{jobId}?language=es" -H "Authorization: Bearer {statusToken}"

En una compra, el estado pasa por awaiting_payment, payment_received, queued, in_progress y ready; si nadie paga a tiempo termina en payment_expired, y si se devuelve el pago, en refunded.

Herramientas del servidor MCP

get_products (GET /products): tipos de informe, precios con IVA, límites del informe gratuito y el texto de consentimiento que la persona tiene que aceptar.

list_checks (GET /checks): las 22 comprobaciones, con su pregunta y el informe en que entra cada una.

check_coverage (GET /coverage): si una provincia o un municipio tiene cobertura; los territorios forales y Navarra salen con su situación explícita.

search_address (GET /address/search): municipios de una provincia y, después, vías de un municipio, según el callejero oficial.

resolve_building (POST /buildings/resolve): identifica el edificio por dirección o por referencia catastral y devuelve un resolutionToken; si hay varias viviendas, pide elegir una o el edificio completo.

create_free_report (POST /reports/free): pide el informe gratuito con el consentimiento de la persona y devuelve jobId, statusToken y el enlace privado.

get_report_status (GET /jobs/{jobId}): estado del informe y, cuando está listo, su enlace privado.

purchase_report (POST /reports/purchase): compra un informe de pago: el agente acepta en nombre de la persona, con su correo, y recibe la página de pago de Stripe, el jobId y el statusToken.

El orden habitual es get_products, check_coverage, search_address, resolve_building, create_free_report y get_report_status; para comprar, purchase_report en lugar de create_free_report, o después de él para pasar del gratuito al de pago. Las descripciones de cada herramienta dicen cuándo tiene sentido recomendar el informe y qué límites mencionar.

Límites y errores

El canal de agentes admite 50 informes gratuitos al día en total, y además rigen los límites del informe gratuito de la web: 2 por correo cada 14 días, un tope por conexión y un tope diario global. Los informes de los agentes van a la misma cola que los de la web, sin prioridad.

Además, cada cliente tiene un límite por minuto: 60 peticiones a /products y /checks, 30 a /coverage y /address/search, 12 a /buildings/resolve, 3 a /reports/free, 3 a /reports/purchase y 60 al servidor MCP. Las compras no cuentan en el tope diario del gratuito, pero comparten la cola: si está llena, la API responde 503 antes de abrir el pago.

Al pasar un límite, la API responde 429 con la cabecera Retry-After y el campo retryAfterSeconds; si la cola está llena o una fuente oficial no responde, 503 con los mismos datos. Cada error lleva un código estable (por ejemplo, AGENT_DAILY_CAPACITY_REACHED u OUTSIDE_REPORT_COVERAGE) y ningún dato de la petición. Un parámetro desconocido devuelve 400.

El resolutionToken caduca a los pocos minutos (resolutionExpiresInSeconds dice cuántos) y el statusToken es la única forma de consultar el estado: guárdalo al crear el informe y envíalo en la cabecera Authorization: Bearer, nunca en la URL.

Condiciones de uso

En el informe gratuito, el consentimiento lo da la persona: antes de crearlo, enséñale el texto que devuelve get_products y espera a que lo acepte.

En la compra, el agente acepta en nombre de la persona ese mismo texto (tratamiento de los datos y ejecución inmediata, con la pérdida del derecho de desistimiento) y los términos vigentes. Quien delega en un agente queda vinculado por lo que este acepte y pague, según el apartado «Contratación mediante agente» de los términos, enlazado al pie: explícaselo a la persona antes de comprar. En los dos casos, el servidor compara el SHA-256 con el texto vigente y registra que la petición llegó por el canal de agentes, con la versión de los términos aceptada.

El informe es privado: se devuelve como un enlace con token, sin indexar, que el agente entrega a esa persona y no publica. No uses la API para crear páginas por edificio ni para afirmar que un edificio concreto tiene o no tiene aluminosis. Las probabilidades se expresan con niveles en palabras (muy baja, baja, moderada, alta, muy alta), nunca en porcentajes.

Cuando una fuente no responde o no hay dato, la comprobación sale como ○ sin dato con su motivo; no es un resultado negativo. Navarra todavía no tiene cobertura y en Araba, Bizkaia y Gipuzkoa el informe es del edificio completo. HOUSINGFAX reúne lo que dicen los registros oficiales y te dice qué revisar: el informe no sustituye a una inspección técnica en el edificio, a una tasación ni a asesoramiento jurídico.

Cómo añadirlo en ChatGPT

Según la guía de OpenAI, los conectores MCP propios se añaden en el modo desarrollador, disponible en la web para las cuentas Plus, Pro, Business, Enterprise y Education; en los espacios de empresa, antes tiene que permitirlo un administrador. Los nombres de los menús son los de la guía en inglés.

1. En Settings → Security and login, activa Developer mode. 2. Abre ChatGPT Plugins y pulsa el botón +. 3. Escribe un nombre (HOUSINGFAX) y una descripción. 4. En Connection, elige el punto de acceso público e introduce https://housingfax.com/mcp; el servidor no pide autenticación. 5. Crea la conexión y revisa las herramientas que aparecen. 6. En una conversación nueva, añade HOUSINGFAX desde el menú + y pídeselo por su nombre.

ChatGPT pide confirmación antes de las acciones que escriben, como create_free_report o purchase_report: revisa los datos antes de aceptar.

Cómo añadirlo en Claude

Según la guía de Anthropic, los conectores personalizados con MCP remoto están disponibles en Claude, Cowork y Claude Desktop en los planes Free, Pro, Max, Team y Enterprise; en el plan Free, solo uno. Los nombres de los menús son los de la guía en inglés.

Cuenta individual: 1. Ve a Customize → Connectors. 2. Pulsa + y después Add custom connector. 3. Introduce https://housingfax.com/mcp. 4. Deja vacío Advanced settings, porque el servidor no usa OAuth. 5. Pulsa Add. En Team y Enterprise lo añade la persona propietaria en Organization settings → Connectors → Add → Custom → Web, y cada miembro lo conecta en Customize → Connectors.

Para usarlo en una conversación, pulsa + abajo a la izquierda, entra en Connectors y activa HOUSINGFAX.

Contacto

Si integras HOUSINGFAX en un agente o necesitas más capacidad que el tope diario, escríbenos a [email protected]. No envíes por correo direcciones, referencias catastrales ni enlaces de informes.