{"openapi":"3.1.0","info":{"version":"1.0.0","title":"Vastgoedvoordeel Partner API","description":"Programmatic toegang tot de WWS-puntentelling (woningwaarderingsstelsel). Bereken WWS-punten, maximale huur en huursegment — altijd op de meest recente, juridisch geldende regels. Ideaal om te koppelen met je eigen vastgoedbeheer-software.\n\n**Aan de slag:** maak een API-key aan onder Account → API-keys en stuur die mee als `Authorization: Bearer vv_live_…`. De eerste 25 berekeningen per maand zijn gratis; daarboven €0,50 per berekening, maandelijks gebundeld op één factuur.","contact":{"email":"tech@vastgoedvoordeel.com"}},"servers":[{"url":"https://api.vastgoedvoordeel.com","description":"Productie"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"Persoonlijke API-key. Maak er een aan onder Account → API-keys. Stuur als `Authorization: Bearer vv_live_…`."}},"schemas":{"WwsCalculateResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/WwsCalculation"}},"required":["ok","data"]},"WwsCalculation":{"type":"object","properties":{"totalPoints":{"type":"number","example":156},"maxRent":{"type":"number","example":1123.5,"description":"Maximale kale huurprijs per maand in euro."},"segment":{"type":"string","enum":["sociaal","midden","vrij","onzeker"]},"rulesetVersionCode":{"type":"string","example":"ZELFSTANDIG_WWS_2024.01"},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/WwsLineItem"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/WwsWarning"}},"calculatedAt":{"type":"string","example":"2026-06-21T10:00:00.000Z"}},"required":["totalPoints","maxRent","segment","rulesetVersionCode","lineItems","warnings","calculatedAt"]},"WwsLineItem":{"type":"object","properties":{"categoryCode":{"type":"string"},"subcategoryCode":{"type":"string"},"points":{"type":"number"},"amount":{"type":"number"},"explanationNl":{"type":"string"},"certainty":{"type":"string","enum":["certain","probable","missing-evidence"]}},"required":["categoryCode","points","explanationNl","certainty"]},"WwsWarning":{"type":"object","properties":{"code":{"type":"string"},"messageNl":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","messageNl","severity"]},"ErrorResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string"},"code":{"type":"string"},"invalid":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string"}},"required":["key","reason"]}}},"required":["ok","error","code"]},"WwsCalculateRequest":{"type":"object","properties":{"unitKind":{"type":"string","enum":["zelfstandig","onzelfstandig"],"default":"zelfstandig","description":"Zelfstandige of onzelfstandige woonruimte."},"calculationAsOfDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Peildatum (YYYY-MM-DD). Bepaalt welke WWS-versie geldt. Default: vandaag.","example":"2026-06-21"},"contractSignedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Datum huurcontract-ondertekening (YYYY-MM-DD). Default: gelijk aan peildatum."},"isDispute":{"type":"boolean","default":false,"description":"Betreft het een lopend geschil (kwestieus)?"},"facts":{"$ref":"#/components/schemas/Facts"}},"required":["facts"]},"Facts":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"boolean"}]},"description":"WWS-kenmerken als platte key→waarde map. Keys zijn fact-keys uit het woningwaarderingsstelsel (bv. `woonoppervlakte_m2`, `energy_label_class`, `woz_value`). Onbekende keys of foute types geven een 400 met uitleg.","example":{"woonoppervlakte_m2":75,"energy_label_class":"B","woz_value":285000}},"WwsEnrichResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"allOf":[{"$ref":"#/components/schemas/WwsCalculation"},{"type":"object","properties":{"enrichment":{"$ref":"#/components/schemas/Enrichment"}},"required":["enrichment"]}]}},"required":["ok","data"]},"Enrichment":{"type":"object","properties":{"address":{"type":"object","properties":{"matched":{"type":"boolean"},"volledigAdres":{"type":"string"},"bagVerblijfsobjectId":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"}},"required":["matched"]},"energyLabel":{"type":"object","properties":{"applied":{"type":"boolean"},"labelClass":{"type":"string"},"validForWws":{"type":"boolean"},"source":{"type":"string"}},"required":["applied","source"]},"woz":{"type":"object","properties":{"applied":{"type":"boolean"},"value":{"type":"number"},"peildatum":{"type":"string"},"source":{"type":"string"}},"required":["applied","source"]},"notes":{"type":"array","items":{"type":"string"}}},"required":["address","energyLabel","woz","notes"]},"WwsEnrichRequest":{"type":"object","properties":{"postcode":{"type":"string","minLength":6,"description":"Postcode, bv. '1012JS'.","example":"1012JS"},"huisnummer":{"type":"string","minLength":1,"description":"Huisnummer.","example":"34"},"huisletter":{"type":"string","description":"Optionele huisletter."},"toevoeging":{"type":"string","description":"Optionele huisnummertoevoeging."},"includeWoz":{"type":"boolean","default":true,"description":"WOZ-waarde automatisch ophalen (publiek register)."},"unitKind":{"type":"string","enum":["zelfstandig","onzelfstandig"],"default":"zelfstandig"},"calculationAsOfDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"contractSignedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"isDispute":{"type":"boolean","default":false},"facts":{"allOf":[{"$ref":"#/components/schemas/Facts"},{"description":"Aanvullende/overschrijvende kenmerken (klant wint van verrijking)."}]}},"required":["postcode","huisnummer"]}},"parameters":{}},"paths":{"/huurpunten/calculate":{"post":{"tags":["Huurpunten"],"summary":"Bereken WWS-punten en maximale huur","description":"Berekent het aantal WWS-punten, de maximale kale huurprijs en het huursegment (sociaal/midden/vrij) uit de aangeleverde woningkenmerken.\n\nDe berekening is deterministisch en altijd op de meest recente, juridisch geldende WWS-versie voor de opgegeven peildatum. Stuur de kenmerken die je kent mee in `facts`; ontbrekende kenmerken leiden tot waarschuwingen, niet tot een fout.\n\nJe eerste 25 berekeningen zijn gratis; daarboven €0,50 per berekening.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WwsCalculateRequest"}}}},"responses":{"200":{"description":"Berekening geslaagd","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WwsCalculateResponse"}}}},"400":{"description":"Ongeldige invoer of onbekende/foute fact-keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Ontbrekende of ongeldige API-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Geen geldig WWS-stelsel voor deze datum/woningtype","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate-limit overschreden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/huurpunten/enrich":{"post":{"tags":["Huurpunten"],"summary":"Verrijk een adres en bereken WWS-punten","description":"Geeft alleen een adres + de kenmerken die je kent. Wij vullen automatisch het energielabel (EP-Online) en — optioneel — de WOZ-waarde aan, en berekenen dan de WWS-punten. Ideaal om met minimale invoer een complete puntentelling te krijgen.\n\nAangeleverde `facts` overschrijven de automatisch gevulde waarden. Externe lookups zijn best-effort; mislukken ze, dan staat dat in `enrichment.notes` en draait de berekening door.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WwsEnrichRequest"}}}},"responses":{"200":{"description":"Verrijking + berekening geslaagd","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WwsEnrichResponse"}}}},"400":{"description":"Ongeldige invoer of onbekende/foute fact-keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Ontbrekende of ongeldige API-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Adres niet gevonden in het BAG","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Geen geldig WWS-stelsel voor deze datum/woningtype","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate-limit overschreden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}