Mandate API

Titel	Mandate API
Status	DRAFT ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT
Stadium	POC PILOT BEHEER
Versie	0.0.2
Datum	12 Juli 2023
Auteur	Architectenraad Edu-V
Acties	Gesprek met Kennisnet voeren over toepassing van API Onderwijs Service Register als basis voor de POCs.

De Mandate API is de technische implementatie van het bevragen van het verwerkersregister of het onderwijsbestuur als verwerkersverantwoordelijke en verwerkersovereenkomst heeft gesloten met een leverancier. De leverancier treedt vervolgens op als verwerker en heeft toestemming om gegevens namens het onderwijsbestuur te verwerken en uit te wisselen.

De technische specificatie bestaat uit:

1 Samenvatting
2 Berichtdefinitie: Mandate (Mandaat)
3 Status- en foutcodes
4 Technisch: API specificatie
5 Release notes

Samenvatting

Scope	mandate
Entiteiten	Mandate
Producer	Registerhouder – Verwerkersregister
Consumer	Registerhouder – Consentmanagement
Endpoints	Verwerkersregister GET mandates

Via de Mandate API kan een component Consentmanagement van een Leverancier bij de Component Verwerkersregister bij de Registerhouder van de Onderwijsorganisatie de status van een Mandaat opvragen. Dit kan via het Enpdoint GET mandates.

Berichtdefinitie: Mandate (Mandaat)

In het mandaat is af te lezen of een leverancier een geldige verwerkersovereenkomst heeft met een onderwijsbestuur. De meeste velden zijn optioneel en zijn niet beschikbaar voor een Leverancier die verifieert of een andere Leverancier beschikt over een verwerkersovereenkosmt. Zodra het eigen mandaat wordt opgevraagd van het betreffende onderwijsbestuur dan zijn de velden wel gevuld.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
token	string	string	Unieke referentie naar het mandaat.		O*	Veld is gevuld indien het eigen mandaat voor het onderwijsbestuur wordt opgevraagd.
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
supplierOin	string	string	OIN van de leverancier		V
boardId	string	string	Bestuursnummer van het Onderwijsbestuur		V	Bevoegd gezag nummer
valid	bool	boolean	Indicatie of de Leverancier een geldige verwerkersovereenkomst heeft met het onderwijsbestuur	True False	V
startDate	string	date	Startdatum van het mandaat	2022-08-01	O*	Veld is gevuld indien het eigen mandaat voor het onderwijsbestuur wordt opgevraagd.
endDate	string	date	Einddatum van het mandaat	2023-08-01	O	Veld is optioneel. Het mandaat kan ook geen einddatum hebben.

Status- en foutcodes

Status code	Status	statusMessage	Omschrijving
200	0	OK
400	1	Schema incorrect	Schemavalidatie niet succesvol
400	2	schemaVersion not supported	De ontvanger kan de gehanteerde schemaVersion niet verwerken
401	4	scope required	Leverancier is niet geautoriseerd voor scope mandate
403	5	No mandate with School Board	De bevrager van het endpoint heeft zelf geen mandaat van (oftewel geen verwerkersovereenkomst met) het onderwijsbestuur.
404	6	School Board unknown	Onderwijsbestuur onbekend
404	7	Supplier unknown	Leverancier onbekend
400	99	Vullingsregel: in statusMessage een beschrijving van de reden opnemen	Overige reden

Technisch: API specificatie

Release notes

0.0.1: Pagina aangemaakt met verwijzing naar Mandatenregister van OSR Kennisnet.
0.0.2: Eerste versie Mandate API gespecificeerd met endpoint om te valideren of een Leverancier een verwerkersoverenkomst heeft met een onderwijsbestuur. Hierbij is een berichtdefinitie Mandaat toegevoegd en zijn ook de status codes beschreven.