v23.10.1 | Timestamp: 2023-10-13T13:06:22.775393

Structuur van de API

/v3/docs

Deze documentatie

/v3/templates

Een overzicht van de beschikbare output-templates die de data in de parameters key van de individuele responses gebruiken.

/v3/lerarenkaart/

GET Request met twee specifieke headers:

X-Auth-Key API key - zie 'Authenticatie'.
X-Value Het stamnummer/Lerarenkaartnummer dat gecheckt moet worden.

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.

Authenticatie

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

Voorbeelden voor alle gebruikers

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

Verzoek zonder geldige API key

{
    "provided": "24609100060",
    "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": "2761119004",
    "quality": "tooshort",
    "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 is te kort.",
    "version": "v3"
}

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

Vormelijk correct, maar niet bestaand nummer.

{
    "provided": "47810230168",
    "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"
}

Voorbeelden voor gebruikers met enkel toegang tot eenvoudige gegevens.

De meeste gebruikers hebben enkel toegang tot eenvoudige gegevens over een Lerarenkaart, en krijgen geen naam of andere gegevens terug.

Geldig nummer in het huidige uitgavejaar.

{
    "authentication": {
        "client_name": "Mijn Onderwijs",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2021-06-16T12:02:29+0000",
    "provided": "19604150038",
    "message": "Het opgegeven nummer hoort bij een momenteel actieve Lerarenkaart.",
    "status": 200,
    "quality": "valid",
    "found": {
        "stamnummer": "19604150038",
        "niveau": "000000",
        "lerarenkaartnummer": "19604150038-000000",
        "year": "2021"
    },
    "version": "v3"
}

Lerarenkaart die enkel vorig uitgavejaar bestaat.

{
    "authentication": {
        "client_name": "Mijn Onderwijs",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2021-06-16T12:02:29+0000",
    "provided": "19604150038",
    "message": "Het opgegeven nummer hoort bij een Lerarenkaart die niet meer actief is.",
    "status": 200,
    "quality": "obsolete",
    "found": {
        "stamnummer": "19604150038",
        "niveau": "000000",
        "lerarenkaartnummer": "19604150038-000000",
        "year": "2021"
    },
    "version": "v3"
}

Voorbeelden voor gebruikers met toegang tot uitgebreide gegevens.

Lerarenkaart die enkel vorig uitgavejaar bestaat.

{
    "provided": "19604150038",
    "quality": "obsolete",
    "authentication": {
        "client_name": "Mijn Onderwijs",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2021-06-16T12:02:29+0000",
    "found": {
        "stamnummer": "19604150038",
        "niveau": "000000",
        "lerarenkaartnummer": "19604150038-000000",
        "year": "2019",
        "batch": {
            "date": "2019-03-13",
            "nr": "15",
            "name": "Klasse magazine maart 2019",
            "published": true
        }
    },
    "detail": {
        "type": "unavailable",
        "parameters": {
            "support_email": "secretariaat@klasse.be",
            "issue_year": 2020
        },
        "template": "unavailable"
    },
    "status": 200,
    "message": "Het opgegeven nummer hoort bij een Lerarenkaart die niet meer actief is.",
    "version": "v3"
}

Lerarenkaart waarvoor contact moet opgenomen worden met Klasse.

{
    "quality": "valid",
    "status": 200,
    "provided": "23503210033",
    "authentication": {
        "client_name": "Mijn Onderwijs",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2020-03-15T10:52:00+0100",
    "found": {
        "stamnummer": "23503210033",
        "niveau": "100100",
        "lerarenkaartnummer": "23503210033-100100",
        "year": "2020",
        "name": "Kelsy H",
        "batch": {
            "date": "2019-12-16",
            "nr": "18",
            "name": "Klasse magazine december 2019",
            "published": true
        }
    },
    "detail": {
        "type": "klasse",
        "parameters": {
            "support_email": "secretariaat@klasse.be",
            "issue_year": "2020",
            "support_link": "https://www.klasse.be?pagina=abonnement&stamnummer=23503210033",
            "date": "4 januari"
        },
        "template": "klasse"
    },
    "message": "Het opgegeven nummer hoort bij een momenteel actieve Lerarenkaart.",
    "version": "v3"
}

Dit algemene patroon, waarbij in detail (Waar Is Mijn Lerarenkaart) de keys type, parameters en template zijn voorzien, keert algemeen terug bij alle kaarten waar gegevens voor gevonden worden. Binnen parameters variëren de keys naargelang de template key.

Lerarenkaart die bij een abonnement hoort.

{
    "quality": "valid",
    "status": 200,
    "provided": "29201040048",
    "authentication": {
        "client_name": "Mijn Onderwijs",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2020-03-15T10:52:00+0100",
    "found": {
        "stamnummer": "29201040048",
        "niveau": "110010",
        "lerarenkaartnummer": "29201040048-110010",
        "year": "2020",
        "name": "Anneleen D",
        "batch": {
            "date": "2020-03-19",
            "nr": "19",
            "name": "Klasse magazine maart 2020",
            "published": true
        }
    },
    "detail": {
        "type": "abo",
        "parameters": {
            "support_email": "secretariaat@klasse.be",
            "issue_year": "2020",
            "support_link": "https://www.klasse.be?pagina=abonnement&stamnummer=29201040048",
            "magazine": "maart 2020",
            "abo_id": 997047
        },
        "template": "abo"
    },
    "message": "Het opgegeven nummer hoort bij een momenteel actieve Lerarenkaart.",
    "version": "v3"
}

Hierbij is het ID van het abonnement als extra waarde (abo_id) toegevoegd aan wiml.

Lerarenkaart die bij een afhaalpunt moet opgehaald worden.

{
    "quality": "valid",
    "status": 200,
    "provided": "19308070066",
    "authentication": {
        "client_name": "Mijn Onderwijs",
        "quality": "valid",
        "message": "Geldige API-key."
    },
    "requested_at": "2020-03-15T10:52:00+0100",
    "found": {
        "stamnummer": "19308070066",
        "niveau": "001111",
        "lerarenkaartnummer": "19308070066-001111",
        "year": "2020",
        "name": "Saskia V".
        "batch": {
            "date": "2019-12-16",
            "nr": "18",
            "name": "Klasse magazine december 2019",
            "published": true
        }
    },
    "detail": {
        "type": "ap",
        "parameters": {
            "support_email": "secretariaat@klasse.be",
            "notices": [
                {
                    "level": "notice",
                    "message": "Leraren die in de deelgemeenten Kozen wonen kunnen hun Lerarenkaart in de plaatselijke bibliotheek afhalen."
                }
            ],
            "issue_year": "2020",
            "support_link": "https://www.klasse.be?pagina=abonnement&stamnummer=19308070066",
            "start_date": "23 december",
            "end_date": "10 juli",
            "past": false,
            "collectionpoint": {
                "id": 201,
                "name": "OPENBARE BIBLIOTHEEK NIEUWERKERKEN/KOZEN",
                "type": "ap",
                "website": "https://www.sint-truiden.be/bibliotheek-toni-coppers",
                "address": [
                    "Pastorijstraat /Opcozenstraat  7",
                    "3850 Nieuwerkerken/Kozen"
                ],
                "map": "https://www.google.be/maps/place/Pastorijstraat+%2FOpcozenstraat++7%2C3850+Nieuwerkerken%2FKozen"
            }
        },
        "template": "ap"
    },
    "message": "Het opgegeven nummer hoort bij een momenteel actieve Lerarenkaart.",
    "version": "v3"
}

Het veld notices (in parameters) is niet altijd aanwezig, enkel indien er een te tonen bijzonder bericht is ivm de WIML-status. Het level van een notice is nu altijd notice, dit kan in de toekomst evt uitgebreid worden met extra levels.