Documenten toevoegen via de API

Dit artikel is bedoeld voor de softwarepartij die een koppeling met Elanza bouwt. Via de REST API kan een bureau documenten van zorgverleners automatisch toevoegen, in plaats van ze handmatig te uploaden in de app.

Het toevoegen gebeurt in twee stappen: eerst meld je een document aan, daarna upload je het bestand naar een adres dat je van Elanza terugkrijgt. Houd er rekening mee dat een document dat via de API binnenkomt nog niet geverifieerd is, en dat niemand automatisch een seintje krijgt om het te controleren.

Verificatie en meldingen

Documenten die via de API binnenkomen, krijgen de status niet geverifieerd. Een zorgorganisatie moet zo'n document eerst verifiëren voordat een zorgverlener kan worden goedgekeurd op een plek waar het document verplicht is. Verifiëren kan alleen in de Elanza-app, niet via de API. Dat gebeurt per zorgorganisatie: hetzelfde document kan bij de ene organisatie geverifieerd zijn en bij de andere nog in behandeling staan.

⚠ Let op
Bij documenten die via de API binnenkomen, wordt er geen taak aangemaakt om ze te controleren. Een bureau dat overstapt op de API moet daarom met de betrokken zorgorganisaties afspreken hoe aangeleverde documenten worden opgepakt. Gebeurt dat niet, dan kunnen documenten onbeperkt ongeverifieerd blijven staan.

Stap 1 — Documenttypes ophalen

Een document hoort altijd bij een bestaand documenttype; je kunt geen eigen label verzinnen. Haal de lijst op met GET /documentTypes. Je krijgt per type een naam, beschrijving en id terug voor de types die gelden voor de eigen pools van het bureau.

De id's verschillen per omgeving, dus leg ze nooit vast in je code. De lijst bevat de types die als verplicht in de pool staan; een type dat wel beschikbaar maar optioneel is, kan ontbreken.

Stap 2 — Document aanmelden

Stuur een POST naar /workerDocuments met vier waarden: de id van de zorgverlener, de id van het documenttype, het aantal bestanden waaruit het document bestaat, en optioneel de verloopdatum. Je krijgt per bestand één upload-adres terug. Elk adres werkt eenmalig en vervalt na 24 uur.

⚠ Let op
Vul altijd een verloopdatum in, ook al is het veld optioneel. Een document zonder verloopdatum valt buiten alle verloop-herinneringen. Het formaat is een gewone datum, bijvoorbeeld 2027-01-01. De datum wordt niet gecontroleerd: een datum in het verleden wordt geaccepteerd, waarna het document meteen als verlopen staat.

Stap 3 — Bestand uploaden

Stuur elk bestand naar het adres dat je terugkreeg. Let op: het bestand gaat mee als de ruwe body van het verzoek, niet als formulier-upload en niet als base64-tekst in een JSON-bericht. Het bestandstype geef je op in de Content-Type-header.

Toegestane types: PDF, JPEG, PNG, GIF, WebP, TIFF, HEIC, HEIF
Maximale grootte: 50 MB
De inhoud van het bestand moet overeenkomen met het type dat je opgeeft, anders wordt het geweigerd
Je kunt geen bestandsnaam kiezen; Elanza genereert die

Voorbeeld

POST https://api.elanza.nl/rest-api/v1/workerDocuments
elanza-api-key-v1: <your key>
Content-Type: application/json

{ "workerUuid": "<worker id>",
  "documentUuid": "<document type id>",
  "numberOfFiles": 1,
  "expiresAt": "2027-01-01" }

→ { "result": "ok",
    "fileUploadUrls": [".../workerDocuments/upload/<id>"] }

POST <the returned upload URL>
elanza-api-key-v1: <your key>
Content-Type: application/pdf

<the PDF file's bytes>

→ { "result": "ok", "uuid": "<file id>" }

Status controleren

Met GET /workerDocuments haal je de geüploade bestanden op. Met GET /workerDocuments/attentionNeeded zie je ontbrekende, verlopen, bijna verlopen en afgekeurde documenten. Een document dat alleen nog niet geverifieerd is, verschijnt niet in die tweede lijst, je kunt die dus niet gebruiken om documenten te vinden die nog op controle wachten.

Belangrijk bij het bouwen van de koppeling

Geverifieerde of afgekeurde documenten zijn vergrendeld. Upload je opnieuw via de API, dan start je een nieuw document in plaats van het oude te vervangen. Wordt een document geverifieerd tussen je twee aanroepen in, dan wordt het uploaden van het bestand geweigerd.
De verloopdatum wijzigen zet verificaties terug. Pas je de verloopdatum aan, dan gaan de verificaties bij andere organisaties terug naar 'in behandeling'. Goed om te weten voordat je in bulk updates gaat sturen.
Geen naam, beschrijving of deel-instelling. Die geef je niet mee. De getoonde naam komt van het documenttype. Of een inlenende zorgorganisatie het document ziet, bepaalt die organisatie zelf met haar documenteisen, niet degene die het aanlevert.

Meer details en alle beschikbare aanroepen vind je in de API-referentie: https://api.elanza.nl/rest-api/v1/documentation.