Nedap Ons API uitgelegd: vier requests tegelijk, een certificaat per klant

De Nedap Ons API autoriseert niet op een token maar op een certificaat: een SSL-clientcertificaat per omgeving per zorgorganisatie, ondertekend door Nedaps eigen certificate authority en elk jaar te vernieuwen. Wie vanuit OAuth denkt — client id, secret, refresh-token — ontwerpt het verkeerde ding.

Dat is meteen het patroon van deze API. De techniek is niet ingewikkeld, maar bijna elke aanname die je uit de boekhoud- en CRM-hoek meeneemt klopt hier net niet.

CleverTech AI liep in september 2026 de publieke documentatie op ons-api.nl na en telde de OpenAPI-specificatie die Nedap onder de API-pagina publiceert: 784 endpoints over 266 resources, verdeeld over 33 applicaties. Hieronder staat wat daarin zit, welke limiet Nedap vandaag werkelijk handhaaft en welke zorgspecifieke velden je ontwerp bepalen.

Het bredere kader over bouwen naast een bestaand pakket staat in onze gids over maatwerk software. Dat Nedap als enige Nederlandse ECD-leverancier zijn koppelvlak publiek documenteert, lieten we eerder zien in het overzicht van ECD-leveranciers in Nederland.

Deze pagina gaat over de API zelf.

Het certificaat is het autorisatiemodel#

Elke call wordt ondertekend met het certificaat van je applicatie, en daaruit leidt Nedap af welke connector belt en voor welke klant. Geen bearer-token, geen gebruikerslogin, geen refresh-cyclus.

De certificate signing request moet aan harde eisen voldoen: een sleutellengte van minimaal 4096 bits, en CN, OU, O, L, ST, C en e-mailadres ingevuld (Nedap, Certificaatvereisten, 2026). De Common Name volgt een vast patroon.

# CSR genereren volgens de Ons API-vereisten
openssl req -out connector.csr -new -newkey rsa:4096 -nodes -keyout connector.key

# CN-patroon: {technical_connector_name}-{customer_code}-{identification}
# Voorbeelden uit de documentatie:
#   hr_integration-TE1002-free_text
#   finance_integration-DF0000-production

Lees dat CN-patroon nog eens: de klantcode zit in het certificaat. Eén zorgorganisatie erbij betekent dus geen extra regel configuratie maar een nieuw certificaat, aangevraagd, ondertekend en uitgerold — en een jaar later opnieuw.

Voor een koppeling bij één klant is dat een voetnoot. Voor een SaaS-product dat vijftig zorgorganisaties bedient, is certificaatrotatie een product-feature die je vanaf dag één inbouwt.

Een verlopen of verkeerd ondertekend certificaat levert overigens geen 401 op maar statuscode 495 Invalid certificate (Nedap, API eigenschappen, 2026). Handig om te weten, want generieke HTTP-clients kennen die code niet en loggen hem als onbekende fout.

Rechten zijn van jouw connector, niet van Nedap#

Binnen Ons loopt autorisatie via een hiërarchie: een rol bevat taken, en taken bevatten de rechten die voor die taak nodig zijn. De scope bepaalt met welke cliënten een gebruiker in die rol mag werken.

De beperking die telt: je kunt gebruikers niet autoriseren op rechten die Nedap zelf heeft gedefinieerd. Alleen rechten die specifiek voor jouw externe integratie zijn aangevraagd, kun je bevragen (Nedap, Authorization in Ons, 2026).

Je definieert dus je eigen rechtenset, met de connectornaam als prefix en alleen letters in de identifier — bijvoorbeeld ExternalConnectorClientMedicalNoteView of ExternalIntegrationAccess.

Praktisch betekent dat: je autorisatiemodel is ontwerpwerk vóór de bouw, geen mapping achteraf. Definieer je het te grof, dan krijgt elke gebruiker van je portaal toegang tot elk dossier dat de connector mag zien.

Wat er in de 784 endpoints zit#

De endpoints beginnen allemaal met basispad /v0/, gevolgd door de applicatienaam — met uitzondering van /ping, waarmee je je certificaat test. Drie omgevingen: api-development.ons.io met fictieve data, api-staging.ons.io en api.ons.io op respectievelijk de test- en productieomgeving van een zorgorganisatie.

Dit is de volledige verdeling zoals wij die op 15 september 2026 in de specificatie telden — de negen rijen hieronder dekken tien applicaties en 706 van de 784 paden:

Cliëntdata haal je op met endpoints die je in elke andere API niet zou vinden: GET /v0/administration/clients/by_bsn/{bsn}, /clients/by_skn, /clients/in_care_in_period. Rapportages lees je per zorgplanregel of per periode, met GET /v0/administration/dossier/reports/by_date/{valid_from}...{valid_to} — inclusief die drie punten in het pad.

De zorgvelden waar je ontwerp op vastloopt#

Hier verschilt de Ons API fundamenteel van een boekhoud-API. In de Exact Online API is een klantnummer een string op de relatie; in Ons is het burgerservicenummer een eigen resource met een eigen verificatiegeschiedenis.

De Bsn-resource draagt naast number onder meer sourceVerified, idVerified, idType, idNumber, idValidUntil, widVerified, bsnVerifiedDate, verifiedByEmployeeId en — voor de gevallen waarin het nummer ontbreekt — bsnUnknown met reasonBsnUnknown.

Dat is geen overdaad. De Wet aanvullende bepalingen verwerking persoonsgegevens in de zorg verplicht zorgaanbieders in artikel 4 het BSN te gebruiken om te borgen dat gegevens de juiste cliënt betreffen, en in artikel 5 om bij de eerste zorgvraag de identiteit én het nummer te verifiëren — met een identiteitsdocument, zegt artikel 6.

Het datamodel legt vast wie dat wanneer waarmee deed. Neem je in je maatwerklaag alleen number over, dan kopieer je het nummer zonder de bewijslast eromheen.

Drie andere velden en resources die je ontwerp raken:

• secretClient op de Client-resource markeert een cliënt als geheim. Een dashboard dat dit veld negeert, toont iemand die juist niet getoond mag worden.
• Zorglegitimaties staan per wet apart: /v0/administration/wlz/zorglegitimaties, /wmo/ en /jw/. Eén cliënt kan legitimaties onder meerdere wetten hebben, dus "de indicatie" bestaat niet als enkelvoudig veld.
• Zorgpaden haal je op met GET /v0/zorgpaden/carepath/active/{client_id}. Het actieve zorgpad is een aparte vraag dan de zorgplanregels in het dossier.

Wat dit betekent voor de bouw van een portaal of dashboard naast het ECD, werkten we uit in zorgsoftware laten maken zonder je ECD te vervangen.

De enige limiet die Nedap vandaag afdwingt#

Nedap publiceert drie limieten, maar handhaaft er één (Nedap, API eigenschappen, 2026):

Die laatste is een optelsom over alle requests: 100.000 requests van 100 milliseconden, of één request van 10.000 seconden. Overschrijding geeft HTTP 429.

Nedap schrijft dat het de andere twee limieten in de toekomst kan gaan handhaven, maar eerst onderzoekt of connectors daardoor geraakt worden.

Vier parallelle verbindingen klinkt karig tot je ziet waarvoor het ontworpen is. Nedap limiteert naar eigen zeggen om te voorkomen dat connectors inefficiënte API's gebruiken voor hun use-case.

Vertaald: wie duizend cliënten in een lus opvraagt, gebruikt het verkeerde koppelvlak.

Delta-streams in plaats van pollen#

Het juiste koppelvlak is xstream, beschikbaar op 48 resources. Drie varianten: /data voor de volledige set (47 resources), /updates voor alles wat sinds een tijdstip wijzigde (41) en /deletes voor wat verdween (12).

Die laatste is dus de schaarse. Alleen twaalf resources hebben alle drie — onder meer cliënten, medewerkers, roosterdiensten en teams — terwijl facturen, rapportages, contracten en verzekeringen alleen /data en /updates kennen.

GET /v0/xstream/shifts/updates?since=2026-09-15T00:00:00.000
Accept: application/x-ndjson

De since-parameter is verplicht, en naast JSON accepteert de stream application/x-ndjson: één object per regel, dat je verwerkt terwijl het binnenkomt in plaats van na afloop in het geheugen. Met vier parallelle verbindingen is dat het verschil tussen een synchronisatie die schaalt en een die op zeshonderd cliënten stukloopt.

Gebruik /deletes waar die bestaat. Wie alleen /updates volgt, houdt verwijderde roosterdiensten eindeloos in de eigen database — een fout die pas maanden later opvalt, in een rapportage die niet klopt.

Voor de resources zonder /deletes moet je het verwijderen zelf afleiden, bijvoorbeeld door periodiek /data af te zetten tegen je eigen set. Reken dat in je synchronisatieontwerp in.

Webhooks: snel, maar geen logboek#

Voor gebeurtenissen biedt Nedap webhooks op onder meer cliënten, adressen, medewerkers, locaties, teams, gebruikers, verzekeringen, zorgplannen en contracten, met CREATE, UPDATE en DELETE plus eigen events zoals employee_schedule_changed (Nedap, Webhooks, 2026). Je endpoint valideert de HMAC in de X-Signature-SHA512-header en antwoordt binnen drie seconden met 200.

Twee eigenschappen bepalen je architectuur. Nedap garandeert de volgorde niet — een UPDATE kan vóór de bijbehorende CREATE binnenkomen.

En mislukte bezorgingen worden 24 uur bewaard: ligt je endpoint langer plat, dan zijn die meldingen weg.

Daarom: webhooks voor snelheid, xstream voor waarheid. Een koppeling die alleen op webhooks leunt, mist stilzwijgend data zodra er een dag onderhoud tussen zit.

Wij draaien in zorgprojecten standaard een nachtelijke delta-run naast de webhook-stroom, precies om dat gat te dichten.

Wat er in productie misgaat#

Vier dingen die in de documentatie staan en in vrijwel geen enkele offerte.

Dinsdagavond. Nedap noemt bij de statuscodes 502, 503 en 504 expliciet dat die optreden tijdens updates van achterliggende systemen, "meestal op dinsdagavonden". Plan je eigen batches daar niet overheen, en bouw retry met backoff in plaats van een foutmelding naar de zorgmedewerker.

Veldfiltering werkt maar één kant op. Met de header X-Field-Whitelist beperk je per request welke velden terugkomen, en Nedap filtert daarnaast per model en per CRUD-operatie (Nedap, Dataminimalisatie, 2026).

Maar dat geldt alleen op GET. Een PUT of POST omzeilt de veldbeperking, dus een connector die een record terugschrijft zonder alle velden gezien te hebben, kan data wissen die het nooit mocht lezen.

Er zijn geen versienummers. In plaats daarvan markeert Nedap resources zes maanden vóór verwijdering als deprecated en informeert het de technisch contactpersoon uit het Ons API Dashboard; nieuwe resources verschijnen zonder aankondiging.

Op 19 november 2025 verving een nieuwe set API's de oude, met een aparte migratiehandleiding. Zonder beheerafspraak leest niemand zo'n bericht.

Een goedgekeurde koppeling is niet te wijzigen. Wil je iets aanpassen, dan maak je een nieuwe versie van de connector en doorloopt het proces opnieuw vanaf het ontwikkelstadium — inclusief opnieuw toestemming per zorgorganisatie via Ons Podium.

Dat is geen bureaucratische voetnoot maar een releaseritme: features bundelen loont, losse hotfixes zijn duur. Wat het aansluittraject in doorlooptijd en geld betekent, reken je door in EPD-koppeling kosten.

Wat AVG en NEN 7510 van je maatwerklaag vragen#

Zodra je maatwerklaag dossiergegevens aanraakt, verwerk je bijzondere persoonsgegevens. Artikel 9 lid 1 van de AVG verbiedt de verwerking van onder meer "gegevens over gezondheid" (Verordening (EU) 2016/679); lid 2 sub h maakt daar een uitzondering op voor gezondheidsdoeleinden mits passende waarborgen worden geboden.

Die waarborgen zijn jouw ontwerpwerk, niet dat van Nedap.

Concreet komen daar drie normen bij kijken die dankzij een afspraak tussen het ministerie van VWS en NEN kosteloos beschikbaar zijn: NEN 7510 voor informatiebeveiliging in de zorg, NEN 7512 voor de vertrouwensbasis bij gegevensuitwisseling, en NEN 7513 voor het vastleggen van acties op elektronische patiëntdossiers (NEN, 2026).

Die laatste is de meest onderschatte. Toont jouw portaal dossierrapportages, dan verplaatst een deel van de toegang tot het dossier zich naar jouw applicatie — en dus ook de logging daarvan.

Nedap logt wat jouw certificaat opvraagt; wie binnen jouw applicatie welk dossier opende, weet alleen jij.

Gebruik daarom het model dat de API je aanreikt in plaats van ernaast te bouwen: eigen rechten per connector, X-Field-Whitelist op elke GET, en alleen de resources aanvragen die je functioneel ontwerp rechtvaardigt. Dataminimalisatie is bij Nedap ook een beoordelingscriterium in het ontwikkelstadium, geen goede bedoeling achteraf.

Isolatie verdient aparte aandacht zodra meerdere zorgorganisaties dezelfde applicatie delen. In ons multi-tenant zorgplatform voor de thuiszorg is tenant-isolatie daarom een constructiedetail dat de database zelf afdwingt, niet een filter in de applicatiecode — juist omdat het weglekken van cliëntgegevens van de ene organisatie naar de andere geen bug is maar een meldingsplichtig datalek.

AI op Ons-data: twee toepassingen die binnen de lijntjes passen#

De rapportagestroom in het dossier is de meest voor de hand liggende plek voor AI, en tegelijk de plek waar het snelst iets misgaat. Twee toepassingen die wij verdedigbaar vinden, en de grens eromheen.

Spraak naar concept-rapportage. Een zorgmedewerker spreekt in, het model maakt er een conceptrapportage van, de medewerker corrigeert en accordeert, en pas daarna gaat de tekst via POST /v0/administration/dossier/reports het dossier in.

Het model schrijft nooit rechtstreeks weg. Die menselijke accordering is geen vormvereiste maar het punt waar de verantwoordelijkheid ligt.

Signalering op wat al gestructureerd is. Openstaande zorgplanacties zonder rapportage, roosterdiensten zonder gekoppelde bezoeken, contracten die aflopen: dat zijn afwijkingen in je eigen gesynchroniseerde data, niet in het dossier. Een signaal daarop is een werkverdelingsvraag, geen zorginhoudelijke uitspraak.

De grens ligt daar waar een model iets over de cliënt gaat vinden. Een systeem dat een gezondheidsverloop voorspelt, risico's inschat of behandeling suggereert, is een ander product met een ander juridisch regime — en dat bouwen we niet als bijvangst van een koppeling.

Verder blijft artikel 9 AVG onverkort gelden: verwerking binnen de EU, alleen de velden die het doel dient, en modellen die niet op je zorgdata trainen. Hoe we die kaders in een implementatie borgen, staat op AI-software laten ontwikkelen.

Bouw je hier zelf op, of niet?#

Nedap Ons is technisch het toegankelijkste ECD van Nederland en tegelijk het minst vrijblijvende. De API is degelijk gedocumenteerd en de specificatie is publiek, maar het traject eromheen — intake, aansluitovereenkomst, ontwikkelstadia, toestemming per zorgorganisatie via Ons Podium, een certificaat per omgeving per klant — bepaalt je planning meer dan de code.

Een aanknopingspunt uit onze projecten: de bouw van een koppeling is zelden de onzekerheid, het toegangstraject wel. Reken de doorlooptijd van dat traject in je planning, en houd er rekening mee dat elke wijziging na goedkeuring opnieuw langs die route gaat.

Heeft Nedap Ons al een kant-en-klare koppeling in de marketplace die jouw scenario precies dekt, gebruik die. Wil je een portaal, een dashboard of een koppeling die er niet is, dan bouw je op deze API — en dan is dit artikel je checklist voor de scoping.

Wat zo'n traject bij CleverTech AI kost en hoe we de certificering begeleiden, staat op Nedap Ons koppeling laten maken.