HOUSINGFAX voor AI-agents en ontwikkelaars

Wat kan een agent met HOUSINGFAX?

Een assistent zoals ChatGPT of Claude, of je eigen programma, kan met gegevens van HOUSINGFAX antwoorden wanneer iemand vraagt hoe je een woning in Spanje controleert voordat je koopt: welke rapporten er zijn en wat ze kosten (€ 0, € 11 en € 19, incl. btw), wat elk rapport controleert, of de provincie gedekt is en welk gebouw bij een adres hoort. Met toestemming van de persoon kan hij ook het gratis rapport aanvragen of een betaald rapport voor die persoon kopen.

Het gratis rapport is een voorbeeldweergave op het web met het stoplicht van elke controle, zonder pdf. Het essentiële rapport en het volledige rapport met gebouwstaat bevatten een webrapport en een pdf, en een agent kan ze kopen met POST /reports/purchase: hij aanvaardt de voorwaarden namens de persoon, geeft diens e-mailadres op en krijgt een Stripe-betaalpagina, waar de agent of de persoon betaalt. Op de website kun je ze ook kopen. Het volledige rapport kan alleen worden besteld als de gebouwinspectie (in het Spaans ITE of IEE) in het regionale register staat; het antwoord van POST /buildings/resolve meldt dat in ieeAvailability en availableTiers.

Adressen van de dienst

API: https://housingfax.com/api/agent/v1. Leesbewerkingen, het aanmaken van het gratis rapport en de aankoop van betaalde rapporten in JSON, zonder authenticatie. Contract agent-api-1.1.0; elke bewerking accepteert language (es, en, de, nl of fr) en antwoordt in die taal.

MCP-server: https://housingfax.com/mcp, via Streamable HTTP en zonder inloggen. OpenAPI 3.1-beschrijving van de API: https://housingfax.com/openapi.json.

Voorbeelden met curl

Soorten rapport, prijzen en toestemmingstekst: curl -s "https://housingfax.com/api/agent/v1/products?language=nl"

De 22 controles: curl -s "https://housingfax.com/api/agent/v1/checks?language=nl"

Dekking van een gemeente: curl -s "https://housingfax.com/api/agent/v1/coverage?municipality=Benidorm&language=nl"

Gemeenten van een provincie (03 is Alicante): curl -s "https://housingfax.com/api/agent/v1/address/search?kind=municipality&provinceCode=03&q=torrevieja&language=nl"

Een gebouw bepalen via zijn kadastrale referentie (vervang de plaatshouder door een echte referentie van 14 tekens): curl -s -X POST "https://housingfax.com/api/agent/v1/buildings/resolve" -H "Content-Type: application/json" -d '{"language":"nl","cadastralReference":"{referentie van 14 tekens}","scope":"building"}'

Voor het gratis rapport verwacht POST /reports/free language, het resolutionToken uit de vorige stap, consent: true, consentStatementSha256 (de SHA-256 van de toestemmingstekst uit GET /products, precies zoals je hem aan de persoon liet zien) en, als de persoon een e-mail wil, email. Het antwoord is 202 met jobId, statusToken en de privélink. De precieze parameters van elke bewerking staan in het OpenAPI-bestand.

Om een betaald rapport te kopen, verwacht POST /reports/purchase language, tier (simple voor het essentiële of complete voor het volledige rapport), het resolutionToken uit POST /buildings/resolve of, als er al een gratis rapport klaar is, freeReport met diens jobId en statusToken (het betaalde rapport hergebruikt dan zijn bronnen), email (verplicht: daar komen het betaalbewijs, de link en de bevestiging over het herroepingsrecht), consent: true, consentStatementSha256, termsVersion (die uit GET /products), acceptTerms: true en waiveWithdrawalRight: true. Voorbeeld: curl -s -X POST "https://housingfax.com/api/agent/v1/reports/purchase" -H "Content-Type: application/json" -d '{"language":"nl","tier":"simple","resolutionToken":"{resolutionToken}","email":"{e-mail van de persoon}","consent":true,"consentStatementSha256":"{SHA-256 van de toestemmingstekst}","termsVersion":"{termsVersion}","acceptTerms":true,"waiveWithdrawalRight":true}'

De aankoop antwoordt met 201 en orderId, status: awaiting_payment, de prijs incl. btw, checkoutUrl (de Stripe-betaalpagina, die na ongeveer 30 minuten verloopt; het precieze tijdstip staat in checkoutExpiresAt), jobId, statusToken en reportUrl, de privélink naar het rapport. Er wordt niets opgesteld voordat Stripe de betaling bevestigt; daarna is het rapport binnen enkele minuten klaar en komt de link ook per e-mail. Kortingscodes worden niet geaccepteerd.

Status van het rapport (het statusToken gaat in de header Authorization, nooit in de URL): curl -s "https://housingfax.com/api/agent/v1/jobs/{jobId}?language=nl" -H "Authorization: Bearer {statusToken}"

Bij een aankoop doorloopt de status awaiting_payment, payment_received, queued, in_progress en ready; betaalt niemand op tijd, dan eindigt hij als payment_expired, en wordt de betaling terugbetaald, als refunded.

Tools van de MCP-server

get_products (GET /products): soorten rapport, prijzen incl. btw, grenzen van het gratis rapport en de toestemmingstekst die de persoon moet accepteren.

list_checks (GET /checks): de 22 controles, elk met zijn vraag en het rapport waar hij in zit.

check_coverage (GET /coverage): of een provincie of gemeente gedekt is; de forale gebieden en Navarra krijgen hun status expliciet terug.

search_address (GET /address/search): gemeenten van een provincie en daarna straten van een gemeente, uit het officiële stratenregister.

resolve_building (POST /buildings/resolve): bepaalt het gebouw via adres of kadastrale referentie en geeft een resolutionToken terug; zijn er meerdere woningen, dan vraagt het om er één te kiezen of het hele gebouw.

create_free_report (POST /reports/free): vraagt met toestemming van de persoon het gratis rapport aan en geeft jobId, statusToken en de privélink terug.

get_report_status (GET /jobs/{jobId}): status van het rapport en, zodra het klaar is, de privélink.

purchase_report (POST /reports/purchase): koopt een betaald rapport: de agent aanvaardt namens de persoon, met diens e-mail, en krijgt de Stripe-betaalpagina, de jobId en het statusToken.

De gebruikelijke volgorde is get_products, check_coverage, search_address, resolve_building, create_free_report en get_report_status; om te kopen purchase_report in plaats van create_free_report, of erna om van het gratis naar een betaald rapport over te stappen. De beschrijving van elke tool zegt wanneer het rapport aan te raden is en welke grenzen je noemt.

Grenzen en fouten

Het agentkanaal staat in totaal 50 gratis rapporten per dag toe, en daarnaast gelden de grenzen van het gratis rapport op de website: 2 per e-mailadres per 14 dagen, een grens per IP-adres en een algemene dagelijkse grens. Aanvragen van agents gaan in dezelfde wachtrij als die van de website, zonder voorrang.

Daarnaast heeft elke client een grens per minuut: 60 aanvragen naar /products en /checks, 30 naar /coverage en /address/search, 12 naar /buildings/resolve, 3 naar /reports/free, 3 naar /reports/purchase en 60 naar de MCP-server. Aankopen tellen niet mee voor de daggrens van het gratis rapport, maar delen wel de wachtrij: is die vol, dan antwoordt de API met 503 voordat de betaling wordt geopend.

Is een grens bereikt, dan antwoordt de API met 429, de header Retry-After en het veld retryAfterSeconds; is de wachtrij vol of antwoordt een officiële bron niet, dan met 503 en dezelfde gegevens. Elke fout heeft een vaste code (bijvoorbeeld AGENT_DAILY_CAPACITY_REACHED of OUTSIDE_REPORT_COVERAGE) en bevat geen gegevens uit de aanvraag. Een onbekende parameter geeft 400.

Het resolutionToken verloopt na enkele minuten (resolutionExpiresInSeconds zegt hoeveel) en het statusToken is de enige manier om de status op te vragen: bewaar het als je het rapport aanmaakt en stuur het in de header Authorization: Bearer, nooit in de URL.

Gebruiksvoorwaarden

Bij het gratis rapport geeft de persoon de toestemming: laat hem of haar vóór het aanmaken de tekst uit get_products zien en wacht tot die geaccepteerd is.

Bij een aankoop aanvaardt de agent namens de persoon dezelfde tekst (verwerking van de gegevens en onmiddellijke uitvoering, met verlies van het herroepingsrecht) en de geldende voorwaarden. Wie een agent inschakelt, is gebonden aan wat die aanvaardt en betaalt, volgens de clausule ‘Contracteren via een agent’ van de voorwaarden, onderaan gelinkt: leg dat de persoon uit voordat je koopt. In beide gevallen vergelijkt de server de SHA-256 met de geldende tekst en legt hij vast dat de aanvraag via het agentkanaal kwam, met de aanvaarde versie van de voorwaarden.

Het rapport is privé: het komt terug als een niet-geïndexeerde link met token, die de agent aan die persoon geeft en niet publiceert. Gebruik de API niet om pagina's per gebouw te maken of om te beweren dat een bepaald gebouw wel of geen aluminose heeft. Kansen worden in woorden gegeven (zeer laag, laag, gemiddeld, hoog of zeer hoog), nooit als percentage.

Antwoordt een bron niet of zijn er geen gegevens, dan toont de controle ○ geen gegevens met de reden; dat is geen negatief resultaat. Navarra is nog niet gedekt, en in Álava, Bizkaia en Gipuzkoa gaat het rapport over het hele gebouw. HOUSINGFAX brengt samen wat de officiële registers zeggen en vertelt je wat je moet nagaan: het rapport vervangt geen technische inspectie ter plaatse, taxatie of juridisch advies.

Zo voeg je het toe in ChatGPT

Volgens de handleiding van OpenAI voeg je eigen MCP-connectoren toe in de ontwikkelaarsmodus, beschikbaar op het web voor Plus-, Pro-, Business-, Enterprise- en Education-accounts; in bedrijfsworkspaces moet een beheerder die eerst toestaan. De menunamen komen uit de Engelse handleiding.

1. Zet onder Settings → Security and login Developer mode aan. 2. Open ChatGPT Plugins en klik op +. 3. Vul een naam (HOUSINGFAX) en een beschrijving in. 4. Kies onder Connection het openbare eindpunt en vul https://housingfax.com/mcp in; de server vraagt geen authenticatie. 5. Maak de verbinding aan en bekijk de gevonden tools. 6. Voeg in een nieuw gesprek HOUSINGFAX toe via het menu + en noem het bij naam.

ChatGPT vraagt om bevestiging vóór schrijfacties zoals create_free_report of purchase_report: controleer de gegevens voordat je akkoord gaat.

Zo voeg je het toe in Claude

Volgens de handleiding van Anthropic werken aangepaste connectoren met remote MCP in Claude, Cowork en Claude Desktop op de abonnementen Free, Pro, Max, Team en Enterprise; op Free is er één mogelijk. De menunamen komen uit de Engelse handleiding.

Individueel account: 1. Ga naar Customize → Connectors. 2. Klik op + en daarna op Add custom connector. 3. Vul https://housingfax.com/mcp in. 4. Laat Advanced settings leeg, want de server gebruikt geen OAuth. 5. Klik op Add. Bij Team en Enterprise voegt de eigenaar hem toe via Organization settings → Connectors → Add → Custom → Web, en elk lid koppelt hem via Customize → Connectors.

Om hem in een gesprek te gebruiken klik je linksonder op +, open je Connectors en zet je HOUSINGFAX aan.

Contact

Bouw je HOUSINGFAX in een agent in of heb je meer capaciteit nodig dan de daggrens, schrijf dan naar [email protected]. Stuur geen adressen, kadastrale referenties of rapportlinks per e-mail.