Luwio Publieke API voor Lokaal Loket Kinderopvang integratie

Deze API laat externe kinderopvang-software (bv. Deona, Ferm/KOALA, KoningApestaart) aanvragen uit het Lokaal Loket Kinderopvang van Luwio ophalen en erop reageren (aanbod doen, status wijzigen, annuleren, berichten sturen). 

1. Authenticatie (OAuth2 Client Credentials)

Elke partij krijgt een client_id (GUID) en client_secret. Daarmee vraagt men een toegangstoken op.

POST /api/public/v1/token
Content-Type: application/x-www-form-urlencoded

Optie A, via Basic-auth header:

Authorization: Basic base64(client_id:client_secret)

met body:

grant_type=client_credentials

Optie B, alles in de form-body:

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Response (200):

{
    "access_token": "<jwt>",
    "token_type": "Bearer",
    "expires_in": 3600
}

Gebruik dit token op elke volgende call:

Authorization: Bearer <jwt>

Foutresponses:

• 400 unsupported_grant_type: als grant_type niet client_credentials is.
• 400 invalid_request: ontbrekende/ongeldige client_id/client_secret.
• 401: client_id onbekend of secret klopt niet.

2. Autorisatie & toegang

Een client_id/secret is altijd gekoppeld aan één tenant, en krijgt per key een vastgelegde toegang tot specifieke locaties (en/of organisaties). Enkel aanvragen van de locaties waartoe de key toegang heeft, komen terug in de resultaten. Dit wordt serverside afgedwongen, niet clientside gefilterd. 

3. Endpoints

Alle routes hieronder starten met /api/public/integrations/koz-oapi/v1. 

3.1 Aanvragen ophalen

GET /requests/{establishmentNumber}
GET /requests

Query-parameters (optioneel):

Mogelijke waarden voor moments: vroeg, voormiddag, namiddag, avond.

Response (200): lijst van aanvragen met o.a. status, contactpersonen, kind- en oudergegevens, schema (dagen/momenten), en paginatie-info.

Rechten vereist: ApplicationsView.

3.2 Status wijzigen

POST /requests/{applicationForLocationId}/transition/{status}

{status} moet één van volgende waarden zijn:

Idempotentie: receive is idempotent. Als de aanvraag al in status InProgress staat (dus al ontvangen was), geeft dit gewoon 200 OK terug als no-op, zonder de verwerking of automatische berichten opnieuw te starten. Dit vangt retries/races vanuit de integratiepartij op zonder dat die een 400 te zien krijgt voor iets dat al gelukt was.

Response: 200 OK (leeg), 400 bij validatie/business-fout, 404 als de aanvraag niet bestaat.

Rechten vereist: ApplicationsEdit.

3.3 Aanbod (proposition) doorgeven

POST /requests/{applicationForLocationId}/transition/proposition
Content-Type: application/json

Body:

{
    "propositionSchedules": [
        {
            "startDate": "2026-09-01",
            "endDate": "2026-09-14",
            "days": [
                { "day": 1, "early": false, "morning": true, "afternoon": true, "late": false }
            ]
        }
    ]
}

• days moet exact 14 dagen bevatten (2 weken), elke day tussen 1 en 14.
• endDate moet ≥ startDate zijn.

Rechten vereist: ApplicationsEdit.

3.4 Aanvraag annuleren

POST /requests/{applicationForLocationId}/transition/cancel Content-Type: application/json

Body:

{
    "cancelledBy": "daycare",
    "reason": "no_spot"
}

cancelledBy: requestor, daycare, monitor, system.
reason: miscarriage, duplicate_application, school_age_reached, moved, spot_elsewhere, insufficient, no_answer, no_spot, no_spot_end_date, financial, financials_changed, needs_changed, location_changed, other_reason.

Rechten vereist: ApplicationsEdit.

3.5 Bericht toevoegen aan een aanvraag

POST /requests/{applicationForLocationId}/message
Content-Type: application/json

Body:

{
    "message": "Vrije tekst van het bericht",
    "sender": "requestor" 
}

sender: daycare, requestor (de aanvragende ouder), of monitor. 

Rechten vereist: ApplicationsEdit.

4. Algemene foutresponse

Bij 400/401/404 komt telkens een foutmelding terug met validatie- of business-foutdetails.