Naar de inhoud
Heldivo
Inloggen Account aanmaken

API-documentatie

Je leest je leerlingen, lessen en lesboekjes uit met een persoonlijk token. Deze pagina komt rechtstreeks uit het OpenAPI-bestand, dus de documentatie en de API lopen niet uit elkaar.

SysteemAuthenticatieAccountLeerlingenLessenLesboekjeVideo'sExportWachtlijstContact

Basis

Alle paden staan onder /api/v1. Antwoorden zijn application/json. Authenticatie met een persoonlijk Bearer-token of met de sessiecookie (plus de header X-CSRF-Token voor wijzigingen). De volledige specificatie staat in openapi.json. De vorige versie /api/v0 is op 30 juni 2023 uitgezet en antwoordt met 410.

Elke fout heeft dezelfde vorm:

{
  "error": {
    "code": "validation_failed",
    "message": "Een of meer velden kloppen niet.",
    "fields": {
      "wachtwoord": "Minstens 10 tekens."
    }
  },
  "request_id": "req_6f1c2a9b"
}

Systeem

GET/api/v1/health openbaar
Controleert of de database schrijf- en leesbaar is, hoeveel vrije schijfruimte er is en hoe lang geleden de achtergrondtaak liep. Geeft 503 bij degradatie.
Antwoorden: 200 503
GET/api/v1/status openbaar
Status van de componenten op basis van echte metingen: reactietijd van de database, lengte van de wachtrij en schijfgebruik. Aantallen accounts worden niet prijsgegeven.
Antwoorden: 200
GET/api/v1/openapi.json openbaar
Geeft deze OpenAPI 3.1-specificatie terug.
Antwoorden: 200

Authenticatie

POST/api/v1/auth/register openbaar
Maakt direct een account aan met de rol instructeur. Er wordt geen e-mail verstuurd; je kunt meteen inloggen. Het wachtwoord is minstens 10 tekens.
{
  "email": "info@rijschoolnoord.nl",
  "wachtwoord": "een-sterk-wachtwoord",
  "naam": "Rijschool Noord"
}
Antwoorden: 201 400 409 422 429
POST/api/v1/auth/login openbaar
Logt in met e-mail en wachtwoord. Zet een sessiecookie (__Host-prefix, HttpOnly, Secure, SameSite=Lax). Na vijf mislukte pogingen op hetzelfde e-mailadres volgt 15 minuten lang 429.
{
  "email": "info@rijschoolnoord.nl",
  "wachtwoord": "een-sterk-wachtwoord"
}
Antwoorden: 200 401 422 429
POST/api/v1/auth/logout
Beëindigt de huidige sessie en wist de cookie.
Antwoorden: 200

Account

GET/api/v1/me
Geeft je account, je regio (zone) en een CSRF-token voor cookie-sessies.
Antwoorden: 200 401
PATCH/api/v1/me
Wijzigt je naam.
{
  "naam": "Rijschool Noord Utrecht"
}
Antwoorden: 200 401 422
DELETE/api/v1/me
Verwijdert je account en alle gegevens: leerlingen, lessen, lesboekjes en video's. Bevestig met je wachtwoord. Dit kan niet ongedaan worden gemaakt.
{
  "wachtwoord": "een-sterk-wachtwoord"
}
Antwoorden: 200 401 403
POST/api/v1/me/password
Wijzigt je wachtwoord. Je geeft je huidige en je nieuwe wachtwoord op.
{
  "huidig": "een-sterk-wachtwoord",
  "nieuw": "een-nog-sterker-wachtwoord"
}
Antwoorden: 200 401 403 422
GET/api/v1/tokens
Geeft je API-tokens zonder de geheime waarde.
Antwoorden: 200 401
POST/api/v1/tokens
Maakt een persoonlijk Bearer-token. De geheime waarde wordt één keer getoond en daarna alleen als hash bewaard.
{
  "naam": "Koppeling boekhouding"
}
Antwoorden: 201 401 422
DELETE/api/v1/tokens/{id}
Trekt een token in. Verzoeken met dat token worden daarna geweigerd.
Antwoorden: 200 401 404

Leerlingen

GET/api/v1/leerlingen
Geeft je leerlingen, nieuwste eerst.
Antwoorden: 200 401
POST/api/v1/leerlingen
Voegt een leerling toe. Alleen naam is verplicht; e-mail, telefoon en startdatum zijn optioneel. In de gratis bèta kun je tot 25 leerlingen hebben.
{
  "naam": "Sanne de Groot",
  "telefoon": "",
  "email": "",
  "startdatum": "2026-11-01"
}
Antwoorden: 201 401 409 422
GET/api/v1/leerlingen/{id}
Geeft één leerling.
Antwoorden: 200 401 404
PATCH/api/v1/leerlingen/{id}
Wijzigt velden van een leerling.
{
  "telefoon": "",
  "startdatum": "2026-10-01"
}
Antwoorden: 200 401 404 422
DELETE/api/v1/leerlingen/{id}
Verwijdert de leerling, met diens lessen en lesboekje.
Antwoorden: 200 401 404

Lessen

GET/api/v1/lessen
Geeft lessen, optioneel voor één week (maandag als startdatum via de parameter week).
Antwoorden: 200 401
POST/api/v1/lessen
Plant een les van 30, 45, 60 of 90 minuten. Als de les in tijd overlapt met een bestaande les, krijg je 409 en wordt er niets opgeslagen.
{
  "leerling_id": "leer_xxxxxxxx",
  "datum": "2026-11-10",
  "start": "09:00",
  "duur": 60,
  "locatie": "Station Utrecht Centraal",
  "notitie": "Rotondes"
}
Antwoorden: 201 401 404 409 422
GET/api/v1/lessen/{id}
Geeft één les.
Antwoorden: 200 401 404
PATCH/api/v1/lessen/{id}
Wijzigt tijd, duur, locatie, notitie of status. Overlapcontrole geldt opnieuw.
{
  "start": "10:30",
  "duur": 90,
  "status": "afgerond"
}
Antwoorden: 200 401 404 409 422
DELETE/api/v1/lessen/{id}
Verwijdert een les.
Antwoorden: 200 401 404

Lesboekje

GET/api/v1/leerlingen/{id}/lesboekje
Geeft alle onderdelen met het huidige niveau (0–4) voor deze leerling.
Antwoorden: 200 401 404
PUT/api/v1/leerlingen/{id}/lesboekje/{onderdeel}
Zet het niveau van één onderdeel (0 t/m 4). De vorige waarde wordt met datum in de geschiedenis bewaard.
{
  "niveau": 3
}
Antwoorden: 200 401 404 422
GET/api/v1/leerlingen/{id}/lesboekje/{onderdeel}/historie
Geeft de niveauwijzigingen van één onderdeel met datum en tijd.
Antwoorden: 200 401 404

Video's

GET/api/v1/videos
Geeft je instructievideo's met de publieke link.
Antwoorden: 200 401
POST/api/v1/videos
Uploadt een mp4- of webm-bestand tot 50 MB als multipart/form-data (veld 'bestand', optioneel 'titel'). Tot 12 video's en 200 MB per account in de bèta.

multipart/form-data met het veld bestand.

Antwoorden: 201 401 409 413 415
GET/api/v1/videos/{id}
Geeft de gegevens van één video.
Antwoorden: 200 401 404
DELETE/api/v1/videos/{id}
Verwijdert de video en het bestand van de schijf.
Antwoorden: 200 401 404
GET/v/{token} openbaar
Openbare HTML-pagina met de video voor de leerling, zonder account. De bijbehorende mediastroom staat op /v/{token}/media en ondersteunt Range.
Antwoorden: 200 404
GET/v/{token}/media openbaar
Levert de videobytes met het juiste Content-Type en ondersteuning voor Range (206). Het eerste verzoek markeert de video als bekeken.
Antwoorden: 200 206 404 416

Export

GET/api/v1/export.zip
Levert een zip met je leerlingen, lessen en lesboekjes als CSV, plus een overzicht van je video's.
Antwoorden: 200 401
GET/api/v1/export/leerlingen.csv
Levert je leerlingen als CSV.
Antwoorden: 200 401
GET/api/v1/export/lessen.csv
Levert je lessen als CSV.
Antwoorden: 200 401

Wachtlijst

POST/api/v1/waitlist openbaar
Zet je op de wachtlijst voor een betaald pakket. Er wordt niets afgeschreven; we nemen contact op via het contactformulier zodra het pakket opengaat.
{
  "email": "info@rijschoolnoord.nl",
  "plan": "rijschool",
  "rijschool": "Rijschool Noord",
  "plaats": "Utrecht",
  "aantal": "3",
  "bericht": ""
}
Antwoorden: 201 422 429

Contact

POST/api/v1/contact openbaar
Stuurt een bericht naar Heldivo. Je krijgt een referentienummer terug. Maximaal drie berichten per uur per e-mailadres.
{
  "naam": "Sanne de Groot",
  "email": "sanne@example.nl",
  "onderwerp": "Vraag over de bèta",
  "bericht": "Graag meer informatie."
}
Antwoorden: 201 422 429