Werking van de Klasse API

Er is een OpenAPI spec beschikbaar van de API, deze kan geraadpleegd worden via /v3/docs/openapi.

Authenticatie

Om informatie terug te krijgen, moet een geldige API key meegegeven worden in de X-Auth-Key header. Deze API key kan aangevraagd worden bij Klasse.

Manuele controle + werking van API key controleren

Het recht op een kaart kan gecontroleerd worden via de webpagina https://api.klasse.be/v3/lerarenkaart-checker/, met een geldige API key.

Dit kan volstaan voor eenvoudige occasionele checks, maar voor routinematig controleren van het recht op Lerarenkaart, is het geautomatiseerd checken via API calls wellicht handiger.

REST calls

/v3/lerarenkaart/

GET Request met drie specifieke headers:

• X-Auth-Key API key - zie 'Authenticatie'.
• X-Value De waarde die gecheckt moet worden (een Lerarenkaartnummer, INSZ of hash).
• X-Value-Type (optioneel) Het soort waarde. Een van insz, hash of lknr (default).

Respons is altijd Content-type:application/json.

Query parameters

• now timestamp om oudere/latere requests te simuleren. Dit zal gereflecteerd worden in de requested_at waarde in de respons.
• compact (zonder waarde), geeft aan of de API enkel 0/1 moet teruggeven om te checken of een kaart geldig is.

Structuur van de respons.

Dit voorbeeld toont een request voor een actieve kaart, waarbij de gebruiker het recht heeft om op insz te zoeken en om hash, niveau en Lerarenkaartnummer te zien.

De 'insz_hash' waarde in 'detail' zal er ook zijn als er voor een opgegeven insz geen gerechtigde gevonden werd. Dit om in de toekomst opnieuw te kunnen checken zonder het insz te hoeven opslaan.

{
    "authentication": {
        "client_name": "Zorg corp.",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2024-02-23T08:03:30+01:00",
    "provided": "57251564713",
    "provided_type": "insz",
    "message": "Het opgegeven nummer hoort bij een momenteel actieve Lerarenkaart.",
    "status": 200,
    "quality": "valid",
    "found": {
        "hash": "f79ebf1e7d715ca8",
        "lknr": "26602020028",
        "niveau": "110111"
    },
    "detail" : {
        "insz_hash" : "f79ebf1e7d715ca8"
    }
    "version": "v23.10.1-9-gdc67bbf"
}

Mogelijke waarden van authentication.quality

• unauthorized Verzoek zonder key of met onbestaande key. status = 401
• insufficient_rights Onvoldoende rechten voor het request. status = 401
• valid Geldige key en gebruiker heeft voldoende rechten voor het request. status afh. van quality
• unknown 500 error. status = 500

Mogelijke waarden van quality

• notexist Waarde niet gevonden. status = 404
• valid Waarde gevonden. status = 200
• bad_params Ongeldige query parameters. status = 400
• bad_provided_type Ongeldige waarde in X-Value-Type header. status = 400
• badsyntax Ongeldige syntax van X-Value. status = 400
• badchecksum Ongeldige checksum van X-Value (komt enkel voor bij insz). status = 400
• expired Gekende, maar vervallen waarde (recht op LK is vervallen). status = 404
• value_tooshort Opgegeven waarde is te kort. status = 400
• value_toolong Opgegeven waarde is te lang. status = 400
• empty Er is geen of een lege X-Value. status = 400
• unknown 500 error. status = 500
• obsolete (legacy) Nummer van een vorig uitgavejaar. status = 200
• notyetactive (legacy) Nummer van een toekomstig uitgavejaar. status = 200
• tooshort (legacy) Opgegeven Lerarenkaartnummer is te kort. status = 400

Voorbeelden die geen gevonden waarde opleveren (4xx)

De waarde van status zal ook als http response code gezet zijn.

De provided_type key zal alleen aanwezig zijn wanneer de X-Value-Type header een waarde bevat.

Al deze voorbeelden gaan uit van de > 2025 situatie, dus niet van legacy calls.

Verzoek zonder geldige API key

{
    "provided": "67782874419",
    "provided_type" : "lknr",
    "quality": "unauthorized",
    "authentication": {
        "quality": "authfailed",
        "message": "Geen of ongeldige API-key."
    },
    "requested_at": "2021-06-16T12:11:11+0000",
    "status": 401,
    "message": "Deze API is enkel met authorisatie te gebruiken. Check https://www.klasse.be/api voor meer informatie.",
    "version": "v3"
}

Vormelijk fout nr

{
    "provided": "6778287441",
    "provided_type" : "lknr",
    "quality": "badsyntax",
    "authentication": {
        "client_name": "Mijn Onderwijs",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2021-06-16T11:57:26+0000",
    "status": 400,
    "message": "Het opgegeven nummer heeft de foute syntax.",
    "version": "v3"
}

De quality kan hier de waarden tooshort, empty of badsyntax hebben.

Vormelijk correct, maar niet bestaand nummer.

{
    "provided": "67782874419",
    "provided_type" : "lknr",
    "quality": "notexist",
    "authentication": {
        "client_name": "Mijn Onderwijs",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2021-06-16T11:59:15+0000",
    "status": 404,
    "message": "Het opgegeven nummer hoort niet bij een gekende Lerarenkaart.",
    "version": "v3"
}

Geldige respons (2xx)

Of een gebruiker found terugkrijgt, en wat er in found zit, hangt af van diens rechten.

Geldig nummer in het huidige uitgavejaar.

{
    "authentication": {
        "client_name": "Zorg corp.",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2024-02-23T08:03:30+01:00",
    "provided": "57251564713",
    "provided_type": "insz",
    "message": "Het opgegeven nummer hoort bij een momenteel actieve Lerarenkaart.",
    "status": 200,
    "quality": "valid",
    "found": {
        "hash": "f79ebf1e7d715ca8",
        "lknr": "26602020028",
        "niveau": "110111"
    },
    "version": "v23.10.1-9-gdc67bbf"
}

• De provided key is identiek aan X-Value.
• De provided_type key is identiek aan X-Value-Type.

• De status key is de HTTP status.

• De found key kan deze nested waarden bevatten:

• hash Unieke hash van deze gerechtigde
• lknr Lerarenkaartnummer van de gerechtigde
• niveau Onderwijsniveaus waar de gerechtigde actief is.

Of deze waarden aanwezig zijn, hangt af van de rechten van de gebruiker. Een gebruiker die enkel het recht kan checken, krijgt geen found.