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): een lijst request met aanvragen en paginatie-info page. Eén request is één aanvraag van één kind bij één opvanglocatie. Kiest een ouder voor één kind drie locaties, dan zijn dat drie requests met dezelfde groupId. Requests zijn gesorteerd van nieuw naar oud. Alle velden en mogelijke waarden staan in sectie 5.

{
    "request": [
        {
            "uuid": "3f2c…",
            "groupId": "9a1b…",
            "luwioNumber": "000.123.1",
            "luwioGroupNumber": "000.123",
            "started": "2026-03-01T09:15:00.000Z",
            "state": "Pending",
            "cancellationReason": null,
            "comment": "…",
            "specificNeeds": false,
            "specificNeedsComment": null,
            "urgent": false,
            "urgentComment": null,
            "calculatedSubsidyType": "trap2",
            "monitorContactEmail": null,
            "contacts": [ { "firstName": "…", "lastName": "…", "email": "…", "phoneNumber": "…" } ],
            "subsidyTypes": [ { "group": "workAndOrEducation", "hasSubsidyType": true } ],
            "schedule": {
                "startDate": "2026-09-01",
                "endDate": "2029-09-01",
                "flexible": false,
                "requestedNbOfDaysWeek1": 3,
                "requestedNbOfDaysWeek2": 3,
                "days": [ { "day": 1, "moments": ["voormiddag", "namiddag"] } ]
            },
            "monitor": null,
            "childcare": { "uuid": "…", "name": "…", "establishmentNumber": "12345" },
            "child": {
                "uuid": "9a1b…",
                "firstName": "…",
                "lastName": "…",
                "birthday": "2026-05-12",
                "childRelationType": "parent",
                "fosterChild": false,
                "sibling": null,
                "parent": {
                    "uuid": "…", "firstName": "…", "lastName": "…", "birthday": "1990-01-01",
                    "sex": "F", "phone": "…", "email": "…", "luwioRrn": "…", "notificationType": "email",
                    "address": { "street": "…", "streetNumber": "1", "boxNumber": null, "city": "…", "postcode": "2000", "country": "BE" }
                }
            },
            "luwioState": "in_progress",
            "luwioProposition": null,
            "luwioSchedule": { … },
            "linkedGroups": [ { "groupId": "7c4d…", "type": "multiples" } ]
        }
    ],
    "page": { "current": 1, "pageSize": 100, "rowOffset": 0, "total": 1, "totalRowCount": 1 }
}

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. Betekenis per reden: zie 5.7.

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.

5. Velden van een aanvraag

Betekenis van alle velden die GET /requests teruggeeft (zie 3.1).

5.1 Aanvraag (request)

5.2 Kind en ouder (child, child.parent)

5.3 Schema (schedule, luwioSchedule, luwioProposition)

5.4 Gekoppelde aanvragen (linkedGroups)

Voor een meerling, of voor broers en zussen die samen opvang zoeken, maakt Luwio één aanvraag per kind en koppelt die aan elkaar.

5.5 Paginatie (page)

5.6 Statussen (state, luwioState)

5.7 Annuleringsredenen (cancellationReason)

Dezelfde waarden gelden voor reason bij annuleren (3.4).

5.8 Voorrangscriteria (subsidyTypes.group)