woz-api-nl Proef API

openapi: 3.2.0
info:
  title: Wozapi Proef API
  description: 'De WOZ API die je zelf regelt. WOZ-waarden, BAG-adresgegevens met bouwjaar en oppervlakte, WOZ-object en kadastrale percelen uit 1 endpoint. Met `energielabel=true` ook het geregistreerde energielabel (EP-Online van RVO), zonder extra credit.


    **Base URL:** `https://woz-api.nl`


    **Authenticatie:** stuur je key mee als header `X-Api-Key: {key}` of als `Authorization: ApiKey {key}`. Een key maak je aan onder API sleutels. Een sleutel hoort in een header, nooit in een URL.


    **Voor softwareleveranciers (OAuth-koppeling):** laat je klant zijn eigen Wozapi-account koppelen via OAuth 2.0 (authorization code met PKCE) en stuur diens access token mee als `Authorization: Bearer {token}`. De credits gaan dan van het account van je klant af. Scopes: `woz.lookup` en `account.saldo`. Discovery: `/.well-known/openid-configuration`. Uitleg en aanvraag: woz-api.nl/woz-api-koppeling.


    **Credits:** 1 credit is 1 uniek adres. Hetzelfde adres binnen 7 dagen opnieuw opvragen kost geen extra credit; dat is een kortingsregel en geen cache, de request wordt wel echt uitgevoerd. Een opvraging die op een fout eindigt (4xx of 5xx) kost niets, en een antwoord zonder WOZ-waarden (een lege `woz`) ook niet. Een nieuw account krijgt 10 gratis credits. Het resterende saldo staat in de response-header `X-Credits-Remaining` en is ook op te vragen via `GET /Api/Credits`. Is het saldo op, dan volgt 402 met code `InsufficientCredits`.


    **Zonder account:** vraag een gratis proefsleutel aan met `POST /Api/Proef` (5 unieke adressen, 10 met het e-mailadres van de gebruiker) en stuur hem mee als `X-Api-Key`. Zonder sleutel geeft de API 401 met code `SleutelOntbreekt`; een verbruikte proef geeft 402 met code `ProefVerbruikt`.


    **Een hele lijst:** `POST /Api/Lijst` met de adressen geeft een gratis proef van 5 adressen, de prijs voor de hele lijst en een betaalpagina voor de gebruiker; na betaling de rijen en het bestand.


    **AI-assistenten:** een MCP-server op `https://woz-api.nl/Api/Mcp`, en uitleg voor agents op woz-api.nl/voor-ai-agents.


    **Foutvorm:** elke fout geeft `{ fout, code, status, detail, traceId }` terug, zie het schema ApiFoutResponse. Dat geldt ook voor een 400 door modelvalidatie; `detail` bevat dan per veld de meldingen. Match in code op `code`, niet op de tekst in `fout`. Veelvoorkomende codes: `InvalidInput` (400), `Unauthorized` (401), `InsufficientCredits` (402), `AddressNotFound` (404), `PdokLookupFailed` (502) en `UpstreamUnavailable` (503). Een 502 of 503 kost niets; probeer het opnieuw, bij een 503 na het aantal seconden uit de header `Retry-After`, en sla het adres niet over.


    **Geen WOZ-waarde:** alleen van woningen is de WOZ-waarde openbaar. Bestaat het adres maar is er geen openbare waarde, bijvoorbeeld bij een kantoor of kerk, dan krijg je een 200 met een lege `woz`, `huidigeWaarde: null` en in `wozStatus` de reden: `geen_woning` als het pand volgens de BAG geen woonfunctie heeft, anders `geen_waarde`. Dat is een antwoord en geen storing: opnieuw proberen verandert niets, en het kost geen credit. Een storing geeft altijd een 502 of 503.


    **Voorbeeld:**


    ```

    curl "https://woz-api.nl/Api/Adres?adres=Spuistraat%2036C,%201012TT%20Amsterdam" \

    -H "X-Api-Key: JOUW_API_KEY"

    ```'
  termsOfService: https://woz-api.nl/terms
  contact:
    name: Wozapi
    url: https://woz-api.nl/
    email: info@woz-api.nl
  version: v1
servers:
- url: https://woz-api.nl
  description: Productie
security:
- ApiKey: []
tags:
- name: Proef
  description: 'Starten zonder account: een gratis proefsleutel, het e-mailadres van de gebruiker, en een betaallink voor credits. Voor AI-assistenten en scripts.'
paths:
  /Api/Proef:
    post:
      tags:
      - Proef
      summary: Een gratis proefsleutel, zonder account
      description: 'Geeft een sleutel voor 5 unieke adressen. Met het e-mailadres van de gebruiker worden het er

        10 in totaal en ontstaat er een WozApi-account zonder wachtwoord; de gebruiker krijgt daar een

        mail over. De proef telt unieke adressen: hetzelfde adres opnieuw is gratis, en een fout of een

        adres zonder WOZ-waarde kost niets.


        Vraag per gesprek hoogstens een proefsleutel aan, en geen nieuwe als de proef op is.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProefAanvraag'
          text/json:
            schema:
              $ref: '#/components/schemas/ProefAanvraag'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ProefAanvraag'
      responses:
        '200':
          description: De sleutel en het tegoed. De sleutel is alleen in dit antwoord te zien.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProefSleutelAntwoord'
        '400':
          description: Het e-mailadres is onbruikbaar (EmailOngeldig).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
        '429':
          description: Te veel sleutels vanaf dit netwerk (TeVeelProefsleutels) of te snel achter elkaar (TeVeelVerzoeken).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
      operationId: postApiProef
      x-operation-id-source: derived
  /Api/Proef/Email:
    post:
      tags:
      - Proef
      summary: Het e-mailadres van de gebruiker bij een proefsleutel
      description: 'Met het eigen e-mailadres van de gebruiker worden het 10 adressen in totaal. Er ontstaat een

        account zonder wachtwoord, en de gebruiker krijgt een mail met uitleg; daarna koopt hij credits

        via een betaallink. Heeft dit adres al een account, dan koppelen we de sleutel daar niet aan:

        dat gebeurt pas als de gebruiker zelf inlogt. Het antwoord is in beide gevallen hetzelfde.

        Verzin nooit een e-mailadres.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProefEmailAanvraag'
          text/json:
            schema:
              $ref: '#/components/schemas/ProefEmailAanvraag'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ProefEmailAanvraag'
      responses:
        '200':
          description: Het nieuwe tegoed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProefEmailAntwoord'
        '400':
          description: Het e-mailadres is onbruikbaar (EmailOngeldig).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
        '401':
          description: Geen sleutel, of een verlopen sleutel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
        '409':
          description: Aan deze sleutel hangt al een ander e-mailadres (SleutelHeeftAlEmail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
      operationId: postApiProefEmail
      x-operation-id-source: derived
  /Api/Opwaarderen:
    post:
      tags:
      - Proef
      summary: Een betaallink voor credits
      description: 'Geeft een link die je aan de gebruiker geeft. Hij ziet daar eerst wat hij koopt en betaalt

        daarna zelf met iDEAL; openen start nog geen betaling. De credits staan direct na betaling

        op het account en de factuur komt per mail. Een proefsleutel zonder e-mailadres heeft nog

        geen account: stuur eerst het e-mailadres met POST /Api/Proef/Email.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpwaardeerAanvraag'
          text/json:
            schema:
              $ref: '#/components/schemas/OpwaardeerAanvraag'
          application/*+json:
            schema:
              $ref: '#/components/schemas/OpwaardeerAanvraag'
      responses:
        '200':
          description: De betaallink met het bedrag.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaalLinkAntwoord'
        '400':
          description: Geen geldig aantal credits; detail.geldigeAantallen noemt ze.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
        '401':
          description: Geen sleutel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
        '403':
          description: Betalen staat tijdelijk uit (PaymentsDisabled).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
        '409':
          description: Eerst het e-mailadres van de gebruiker (EmailNodig).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
      operationId: postApiOpwaarderen
      x-operation-id-source: derived
components:
  schemas:
    BetaalBedragInfo:
      type: object
      properties:
        prijsPerCreditExclBtw:
          type: number
          format: double
        exclBtw:
          type: number
          format: double
        btw:
          type: number
          format: double
        inclBtw:
          type: number
          format: double
        valuta:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: Een bedrag in euro's, met en zonder 21% btw.
    ProefSleutelAntwoord:
      type: object
      properties:
        sleutel:
          type:
          - string
          - 'null'
          description: De sleutel. Stuur hem mee als header X-Api-Key, nooit in een URL.
          example: woz_Qm9BvX1kLp7Zt3YwR8sHn2JcF6gDaE4uVo5iKq0yTbM
        tegoed:
          $ref: '#/components/schemas/TegoedInfo'
        email:
          type:
          - string
          - 'null'
          description: '"ontvangen" als er een e-mailadres meekwam, anders leeg.'
        gebruik:
          type:
          - string
          - 'null'
          description: Hoe je de sleutel gebruikt.
        regels:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Regels voor wie namens een gebruiker opvraagt.
      additionalProperties: false
      description: Een nieuwe proefsleutel. De sleutel is alleen in dit antwoord te zien.
    ProefEmailAanvraag:
      type: object
      properties:
        email:
          type:
          - string
          - 'null'
          description: Het eigen e-mailadres van de gebruiker. Verzin er nooit een.
      additionalProperties: false
      description: Het e-mailadres van de gebruiker bij een proefsleutel.
    TegoedInfo:
      type: object
      properties:
        soort:
          type:
          - string
          - 'null'
          description: '"proef" zolang de sleutel aan geen account hangt, "credits" als hij van een account is.'
          example: proef
        limiet:
          type:
          - integer
          - 'null'
          description: Unieke adressen die deze proef in totaal mag; leeg bij credits.
          format: int32
          example: 5
        gebruikt:
          type:
          - integer
          - 'null'
          description: Unieke adressen die al gebruikt zijn; leeg bij credits.
          format: int32
          example: 1
        resterend:
          type: integer
          description: 'Wat er nog kan: adressen in de proef, of credits op het account.'
          format: int32
          example: 4
        verlooptOp:
          type:
          - string
          - 'null'
          description: Wanneer een proefsleutel zonder account vervalt.
          format: date-time
      additionalProperties: false
      description: Het tegoed van een proefsleutel of van een account dat een AI-assistent aanmaakte.
    OpwaardeerAanvraag:
      type: object
      properties:
        credits:
          type:
          - integer
          - 'null'
          description: Aantal credits; leeg is het kleinste pakket. Zie geldigeAantallen.
          format: int32
          example: 100
      additionalProperties: false
      description: Verzoek om een betaallink voor credits.
    ProefEmailAntwoord:
      type: object
      properties:
        tegoed:
          $ref: '#/components/schemas/TegoedInfo'
        melding:
          type:
          - string
          - 'null'
          description: Wat er met het e-mailadres gebeurt.
      additionalProperties: false
      description: 'Antwoord op de e-mailstap: het nieuwe tegoed.'
    BetaalLinkAntwoord:
      type: object
      properties:
        betaalUrl:
          type:
          - string
          - 'null'
          description: De link voor de gebruiker. Openen start nog geen betaling.
        credits:
          type: integer
          format: int32
        bedrag:
          $ref: '#/components/schemas/BetaalBedragInfo'
        geldigTot:
          type: string
          description: Tot wanneer de link werkt.
          format: date-time
        geldigeAantallen:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int32
          description: De aantallen credits die je kunt kopen.
        uitleg:
          type:
          - string
          - 'null'
          description: Wat de gebruiker ziet en wat er daarna gebeurt.
      additionalProperties: false
      description: Een betaallink voor credits. De gebruiker betaalt zelf, in zijn browser.
    ProefAanvraag:
      type: object
      properties:
        email:
          type:
          - string
          - 'null'
          description: 'Het eigen e-mailadres van de gebruiker, alleen als hij het zelf voor dit doel gaf. Met een

            e-mailadres worden het 10 adressen in totaal en ontstaat er een account zonder wachtwoord.

            Verzin er nooit een.'
        kanaal:
          type:
          - string
          - 'null'
          description: 'Waar de aanvraag vandaan komt: "api" (standaard), "demo" of "mcp".'
      additionalProperties: false
      description: Verzoek om een gratis proefsleutel. Beide velden zijn optioneel; een lege body mag.
    ApiFoutResponse:
      type: object
      properties:
        fout:
          type:
          - string
          - 'null'
          description: Foutmelding in het Nederlands, bedoeld om te tonen aan een eindgebruiker.
          example: Ongeldige API-key.
        code:
          type:
          - string
          - 'null'
          description: 'Stabiele foutcode om in code op te matchen. Niet elke fout heeft er een; bij een

            onverwachte fout is dit veld null.'
          example: Unauthorized
        status:
          type: integer
          description: De HTTP-statuscode, ook in de body zodat loggen zonder response-object werkt.
          format: int32
          example: 401
        detail:
          description: 'Extra toelichting waar die bestaat, anders null. Dit is soms een tekst en soms een

            object (bijvoorbeeld met de gezochte term en een hint), dus lees het als vrije JSON.'
        traceId:
          type:
          - string
          - 'null'
          description: Correlatie-id van de request. Vermeld dit bij een supportvraag.
          example: 0HN7GK2P3QJ1M:00000003
      additionalProperties: false
      description: 'De foutrespons die de API werkelijk teruggeeft. Bestaat omdat de OpenAPI-spec bij 400, 401,

        402 en 404 naar ProblemDetails verwees, terwijl

        WozApi.Middleware.ErrorHandlingMiddleware een heel andere vorm stuurt. Wie op de

        documentatie bouwde, parseerde dus elke fout verkeerd.'
  securitySchemes:
    ApiKey:
      type: apiKey
      description: 'Gebruik je API key via header: X-Api-Key: {key} of Authorization: ApiKey {key}'
      name: X-Api-Key
      in: header
    OAuth2:
      type: oauth2
      description: 'OAuth-koppeling voor softwareleveranciers: authorization code met PKCE. Je klant koppelt zijn eigen Wozapi-account; credits gaan van diens saldo af.'
      flows:
        authorizationCode:
          authorizationUrl: https://woz-api.nl/connect/authorize
          tokenUrl: https://woz-api.nl/connect/token
          scopes:
            woz.lookup: WOZ-gegevens opvragen op de credits van de gekoppelde klant
            account.saldo: Creditsaldo van de gekoppelde klant lezen