Entitlement API

Titel	Entitlement API
Status	DRAFT WERKGROEP KLANKBORDgroep ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT
Stadium	POC PILOT BEHEER
Versie	0.0.4
Datum	12 Juli 2023
Auteur	Werkgroep Verwerven en in gebruik nemen
Acties	Geen acties

De Entitlement API wordt gebruikt om informatie over Aanspraken uit te wisselen vanuit de Faciliteit voor leveren (of arrangeren) van digitale leermiddelen van de Leermiddelenshop. Een Aanspraak is een vertaling van de Bestelgegevens naar alle benodigde informatie voor de geld-goederenstroom.

Vanwege de aard van deze gegevens is het cruciaal dat het verzenden, ontvangen en verwerken van de gegevens te traceren is. Daarnaast kent het opvolgen van een Aanspraak door het Licentiekantoor van de Leermiddelenaanbieder en de Mijn Leermiddelen, Learning Management Systeem van de Leerportaalaanbieder een kritieke volgorde. Om deze reden wordt in de Entitlement API gebruik gemaakt van het transactiepatroon georkestreerde uitwisseling.

De technische specificatie bestaat uit:

1 Samenvatting
2 Berichtdefinitie: Entitlement (Aanspraak)
- 2.1 object entitlement
- 2.2 entitlee variant: school
  - 2.2.1 object school subjects
  - 2.2.2 object groups
- 2.3 entitlee variant: Individual
3 Berichtdefinitie: EntitlementConfirmation
- 3.1 status- en foutcodes
4 Event mediator: Leermiddelenshop (Faciliteit voor leveren (of arrangeren) van digitale leermiddelen)
5 Event processor: Leermiddelenaanbieder (Licentiekantoor)
6 Event processor: Leerportaalaanbieder (Mijn Leermiddelen)
7 Status- en foutcodes
8 Technisch: API specificatie
9 Release notes

Samenvatting

Scopes	ls.entitlement ls.activationcode
Berichten	Entitlement BUITEN SCOPE POC ChangeLicenseStatus BUITEN SCOPE POCActivationCodeRequest BUITEN SCOPE POCActivationCodeRevokeRequest
Bevestigings-berichten	EntitlementConfirmation BUITEN SCOPE POCChangeLicenseStatusConfirmation BUITEN SCOPE POCActivationCodeConfirmation BUITEN SCOPE POCActivationCodeRevokeConfirmation
Producer	Leermiddelenshop – Faciliteit voor leveren (of arrangeren) van digitale leermiddelen
Consumer	Leermiddelenaanbieder – Licentiekantoor Leerportaalaanbieder – Mijn leermiddelen Leerportaalaanbieder – Learning Management System Dashboardaanbieder – Overkoepelend dashboard gebruik
Endpoints	Leermiddelenshop GET Entitlement by ID GET All Entitlements by School ID POST Search ALL Entitlement by User ID (eckId en userId worden via request body verstuurd) PUT Confirm entitlement to Leermiddelenshop BUITEN SCOPE POC PUT Confirm change license status to Leermiddelenshop BUITEN SCOPE POC PUT Confirm activation code to Leermiddelenshop BUITEN SCOPE POC PUT Confirom activation code revoke request to Leermiddelenshop Leermiddelenaanbieder PUT Accept entitlement from Leermiddelenshop BUITEN SCOPE POC PUT Accept change license status request from Leermiddelenshop BUITEN SCOPE POC PUT Accept activation code request from Leermiddelenshop BUITEN SCOPE POC PUT Accept activation code revoke request from Leermiddelenshop Leerportaalaanbieder PUT Accept entitlement from Leermiddelenshop BUITEN SCOPE POC PUT Accept change license status request from Leermiddelenshop Dashboardaanbieder PUT Accept entitlement from Leermiddelenshop BUITEN SCOPE POC PUT Accept change license status request from Leermiddelenshop

Berichtdefinitie: Entitlement (Aanspraak)

Het Entitlement bericht bevat de specificatie van de Entitlement op het leermiddel zoals deze is verworven door een Besteller voor een Entitlee (School of Individu) in een Aanspraakvariant. In het bericht is een unieke referentie opgenomen om de traceerbaarheid van verzonden en ontvangen Berichten bij te kunnen houden. Indien een Ontvanger een bericht ontvangt met eenzelfde entitlementReferenceId is het niet de bedoeling om het Bericht opnieuw te verwerken. Het verzoek is om het bevestigingsbericht opnieuw toe te sturen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlement ReferenceId	string	uuid	Referentienummer voor het versturen entitlement.	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V	Dit nummer wordt gebruikt door de event mediator om een logboek bij te houden van verzonden en ontvangen events met betrekking tot een unieke entitlementId.
entitlement	object	entitlement	De specificatie van de Aanspraak zoals verworven door een Besteller	Zie object entitlement	V

object entitlement

Het object entitlement is de specificatie van de aanspraak zoals deze door de Besteller is verworven. Hierbij wordt onderscheid gemaakt tussen de School of de Particulier (Individual) als Besteller. In de Entitlement wordt de relatie gelegd tussen het product, de Besteller en conform de aanspraakvariant de specificatie van de autorisatieregels. Daarnaast heeft iedere Entitlement een status conform de levenscyclus van een Aanspraak. De waarden uit een Entitlement mogen niet gewijzigd worden (ook niet voor foutcorrecties). Indien de Entitlement niet correct is dan wordt deze geannuleerd en wordt er een nieuwe Entitlement gestuurd.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlementId	string	uuid	Unieke identifier voor deze entitlement	24e39454-5360-4ba4-819f-03e59b8dd679	V	Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
contractId	string	string	Optionele unieke identifier van een contract tussen Leermiddelenaanbieder en Leermiddelenshop waarbinnen deze Aanspraak valt	2022-12-v1	O	Waarde mag niet gewijzigd worden.
startDate	string	date	Datum vanaf wanneer de Aanspraak in gebruik genomen kan worden. Dit is de start van de activatieperiode	2022-08-01	V	Waarde mag niet gewijzigd worden
activationUntilDate	string	date	Datum tot wanneer de Aanspraak in gebruik genomen kan worden. Hierna is de activatieperiode verlopen	2023-07-31	V	Waarde mag niet gewijzigd worden
minExpirationDate	string	date	De default ExpirationDate die door de component Mijn leermiddelen van de Leerportaalaanbieder gehanteerd kan worden bij het beheren van toegangslinks.	2023-07-31	O	De Leermiddelenshop berekent deze waarde op basis van de informatie over het Product uit de catalogus. Voor een jaarlicentie is dit bijvoorbeeld 1 jaar na de startDate. Dit veld is optioneel. Indien het veld leeg is, is er geen einddatum voor het tonen van de toegangslink. De component Mijn leermiddelen kan via het InitialActivation event een nieuwe expirationDate doorkrijgen. Deze nieuwe expirationDate is gelijk aan of ligt verder in de toekomst en overschrijft voor de betreffende gebruiker de in dit veld genoemde minExpiration Date.
endDate	string	date	Datum dat de Entitlement geannuleerd of geblokkeerd is.	2022-09-28	O	De endDate wordt gevuld zodra de status wijzigt naar Cancelled of Blocked Waarde mag niet gewijzigd worden
entitlementType	string	ENUM	Aanspraakvariant die van toepassing is op deze Entitlement	school schoolsubject schoolgroup schoolstudent schoolemployee personal	V	Waarde mag niet gewijzigd worden
productId	string	string	Referentie naar de Productbeschrijving in de Catalogue API van het Leermiddel dat is verworven door Besteller	871792713 0834	V	Een Entitlement verwijst naar exact 1 Product-Beschrijving Waarde mag niet gewijzigd worden
entitlee	object	school individual	Specificatie van de waarden behorende bij de Aanspraakvariant.	Zie voor variant school of variant individual	V	Een Entitlement verwijst naar exact 1 entitlee Waarde mag niet gewijzigd worden
status	string	ENUM	De status waarin de Entitlement zich bevindt.	entitled provisioned link-ready cancelled blocked	V	Status wordt toegekend conform de levenscyclus van de Aanspraak en het bijbehorende proces.

entitlee variant: school

Indien de Besteller van de Entitlement een Onderwijsorganisatie is dan wordt afhankelijk van de gekozen aanspraakvariant (entitlementType) de waarden gespecificeerd waarop de Leermiddelenaanbieder het Leermiddel in gebruik kan laten nemen conform de bijbehorende autorisatieregels. Zodra de Aanspraakvariant open is, zoals bij een School, SchoolSubject of een SchoolGroup variant, dan wordt in de Entitlement een aantal opgenomen. Dit aantal komt overeen met het aantal door de onderwijsorganisatie bestelde leermiddelen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
schoolId	string	string	Referentie naar de identifier van de onderwijsorganisatie die de Entitlement verworven heeft	-	V	Waarde mag niet gewijzigd worden In het primair onderwijs wordt BasispoortId gehanteerd. In het voortgezet onderwijs en middelbaar beroepsonderwijs wordt digiDeliveryId gehanteerd.
schoolSubjects	array	school Subjects	Specificatie van SchoolVakken indien de aanspraakvariant SchoolVak is gekozen	Zie object school subjects	O*	Verplicht in geval van entitlementType SchoolSubject Er kunnen één of meerdere SchoolSubjects gespecificeerd worden. Waarde mag niet gewijzigd worden
groups	array	groups	Specificiatie van SchoolGroepen indien de aanspraakvariant SchoolGroep is gekozen	Zie object groups	O*	Verplicht in geval van entitlementType SchoolGroup Er kunnen één of meerdere SchoolSubjects gespecificeerd worden. Waarde mag niet gewijzigd worden
entitlees	array	student Reference employee Reference	Specificatie van de leerlingen of leraren indien de aanspraakvariant SchoolOnderwijsdeelnemer of SchoolOnderwijsmedewerker is gekozen	Zie SIS API	O*	Van toepassing in geval van entitlementType schoolstudent of schoolemployee en deze in gebruik worden genomen op basis van id. Als alternatief kan ook het veld activationCodes gebruikt worden. Er kunnen één of meerdere Students of Employees gespecificeerd worden. Waarde mag niet gewijzigd worden
activationCodes	arrray	string	Specificatie van de activatiecodes indien de aanspraakvariant SchoolOnderwijsdeelnemer of SchoolOnderwijsmedewerker is gekozen	[XXXXXX,YYYYYY,ZZZZZZ]	O*	Van toepassing in geval van entitlementType schoolstudent of schoolemployee en deze in gebruik worden genomen op basis van activatiecodes. Als alternatief kan ook het veld entitlees gebruikt worden. Waarde mag niet gewijzigd worden.
quantity	integer	integer	Aantal door de onderwijsorganisatie bestelde leermiddelen	100	O*	Verplicht in geval van entitlementType school, schoolsubject en schoolgroup Waarde mag gewijzigd worden maar dient lager te zijn dan vorige waarde en hoger te zijn dan aantal licenties op Entitlement.

object school subjects

De specificatie van de SchoolSubjects wordt gedaan op basis van de unieke identifiers voor deze entiteiten. Optioneel wordt per specifiek SchoolSubject het aantal bestelde leermiddelen opgegeven.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

schoolSubjectId

string

uuid

Referentie naar de identifier van het SchoolSubject waarvoor het leermiddel is verworven

0935374c-2da8-4493-a2ac-f195fd353650

V

Waarde mag niet gewijzigd worden

quantity

integer

Aantal door de onderwijsorganisatie bestelde leermiddelen voor dit SchoolSubject

25

O

Deze specificatie op SchoolSubject is optioneel.
Indien hier gebruik van wordt gemaakt dan telt het totaal op naar quantity op hoofdniveau van de Entitlement.

Waarde mag wel gewijzigd worden.

object groups

De specificatie van SchoolGroups wordt gedaan op basis van de unieke identifiers voor deze entiteiten. Optioneel wordt per specifiek Group het aantal bestelde leermiddelen opgegeven.

entitlee variant: Individual

Zodra de Entitlement is verworven door een Particulier dan wordt de entitlee gespecificeerd conform onderstaande tabel. In deze specificatie is de naam en het e-mailadres van de Besteller optioneel bijgevoegd. Een Entitlement aangeschaft voor een Particulier betreft altijd een aantal van 1 en is voor een enkele onderwijsdeelnemer. De identifier van deze onderwijsdeelnemer wordt toegevoegd aan de specificatie.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
displayName	string	string	De naam van de Particulier die de Entitlement heeft verworven	Jan Janssen	O	Waarde mag niet gewijzigd worden
email	string	email	Het emailadres van de Particulier die de Entitlement heeft verworven.	koper@prive.nl	O	Emailadres kan worden gebruikt om updates over de levering te versturen en om informatie over toegang toe te sturen. Waarde mag niet gewijzigd worden
eckId	string	ECK iD	Het ECK iD van de onderwijsdeelnemer waarvoor de Entitlement is verworven		V*	Van toepassing als de Aanspraak op naam is verkocht en op basis van id in gebruik wordt genomen. eckId is verplicht. Indien onbekend dan kan userId gehanteerd worden. Waarde mag niet gewijzigd worden
userId	array	userId	Alternatief userId indien eckId onbekend is	Zie object userId in SIS API	O*	Van toepassing als de Aanspraak op naam is verkocht en op basis van id in gebruik wordt genomen. Verplicht zodra eckId onbekend is. Waarde mag niet gewijzigd worden
activationCode	string	string	Specificatie van de activatiecode	XXXXXX	O*	Van toepassing als het leermiddel met een activatiecode is verkocht. Indien dit het geval is dan zijn eckId en userId leeg. Waarde mag niet gewijzigd worden.

Berichtdefinitie: EntitlementConfirmation

Een Leermiddelenaanbieder of Leerportaalaanbieder antwoorden op Entitlement berichten.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlement ReferenceId	string	uuid	De referentie van de Leermiddelenshop waarop dit bevestigingsbericht een antwoord is.	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V
entitlement ReceiveId	string	uuid	De referentie van de Leermiddelenaanbieder of de Leerportaalaanbieder voor dit bevestigingsbericht	3437e98f-855d-4f29-9092-7ba311228920	V
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
entitlementId	string	uuid	Verwijzing naar de unieke identifier voor de entitlement	24e39454-5360-4ba4-819f-03e59b8dd679	V
productId	string	string	Verwijzing naar de unieke identifier voor het product	871792713 0834	V
processed Timestamp	string	datetime	Tijdstip waarop de het Entitlement bericht is verwerkt door de Leermiddelenaanbieder of de Leerportaalaanbieder	2017-07-21T17:32:28Z	V
newEntitlement Status	string	ENUM	De nieuwe status van de Entitlement	entitled provisioned link-ready cancelled blocked	V	De status wordt gekozen afhankelijk van de rol en de stap in het proces.
newEntitlement Quantity	integer	integer	De nieuwe waarde voor quantity wordt door de Leermiddelenaanbieder geconformeerd aan de Leermiddelenshop, indien deze in het bericht gewijzigd was.	90	O	Deze waarde wordt door de Leermiddelenaanbieder gevuld indien de waarde van de Entitlement is gewijzigd door de Leermiddelenshop
success	boolean	boolean	Indicatie of de Ontvanger het (wijzigings)bericht heeft kunnen verwerken	True False	V	False indien de Ontvanger niet akkoord is of er een fout is opgetreden.
status	integer	ENUM	Status	0 (=OK)	V	Zie status en foutcodes
statusMessage	string	string	Toelichting op status	-	O	Zie status en foutcodes

status- en foutcodes

Status	statusMessage	EntitlmentTypes	Toelichting
0	OK	Allen	Bericht succesvol verwerkt
1	Field missing	Allen	Schemavalidatie niet succesvol
2	userId, eckID or activationCode missing	Personal, SchoolStudent, SchoolEmployee	Specificatie van entitlees of activatiecodes niet volledig
3	userId or eckId unknown	Personal, SchoolStudent, SchoolEmployee	Gespecificeerde entitlees zijn niet bekend bij Ontvanger
4	schoolSubject missing	SchoolSubject	Specificatie van schoolSubjects ontbreekt
5	schoolSubject unknown	SchoolSubject	Gespecificeerde schoolSubjects zijn niet bekend bij Ontvanger
6	Group missing	SchoolGroup	Specificatie van Groups ontbreekt
7	Group unknown	SchoolGroup	Gespecificeerde Groups zijn niet bekend bij Ontvanger
8	schoolId missing	School SchoolSubject SchoolGroup SchoolStudent	Onderwijsorganisatie is niet gespecificeerd
9	schoolId unknown	School SchoolSubject SchoolGroup SchoolStudent	Gespecificeerde Onderwijsorganisatie is niet bekend bij Ontvanger
10	productId missing	Allen	Specificatie van Product ontbreekt
11	productId unknown	Allen	Gespecificeerd Product onbekend bij Ontvanger
12	Product not yet for sale	Allen	Gespecificeerd Product is nog niet in de verkoop
13	Product no longer for sale	Allen	Gespecificeerd Product is niet langer in de verkoop
14	startDate before firstPublishedDate	Allen	Gespecificeerde startdatum van de activatieperiode ligt voor de datum dat het product op de markt verschijnt
20	contractId unknown	Allen	Gespecificeerd contractId is onbekend bij de ontvangende Leermiddelenaanbieder
21	Contract restrictions	Allen	Bericht niet toegestaan als gevolg van contractuele afspraken tussen Leermiddelenshop en Leermiddelenaanbieder
30	Quantity at least 1	School SchoolSubject SchoolGroup	Het gespecificeerde aantal voor open School entitlements is minimaal 1
40	entitlementId unknown	Allen	Het entitlementId waarvoor een wijziging wordt gestuurd is onbekend
41	newAmount is not allowed	School SchoolSubject SchoolGroup	Indien het aantal door de Leermiddelenshop wordt gewijzigd in een wijzigingsbericht dan dient deze: lager te zijn dan het huidige aantal hoger te zijn dan het aantal geactiveerde licenties
42	License registered on Entitlement	SchoolStudent SchoolEmployee Personal	Indien een Leermiddelenshop een Entitlement wil annuleren dan mag er geen licentie geregistreerd zijn op de Entitlement
50	activationCode unknown	SchoolStudent SchoolEmployee Personal	Gespecificeerde activatiecode is onbekend bij de ontvangende Leermiddelenaanbieder
51	activationCode already used	SchoolStudent SchoolEmployee Personal	Gespecificeerde activatiecode is reeds gebruikt voor een aanspraak
52	activationCode revoked	SchoolStudent SchoolEmployee Personal	Gespecificeerde activatiecode is ingetrokken
99	Vullingsregel: in statusMessage een beschrijving van de reden opnemen	Allen	Overige reden

Event mediator: Leermiddelenshop (Faciliteit voor leveren (of arrangeren) van digitale leermiddelen)

Buiten scope POC

Alleen het gedrag zoals beschreven bij Leveren leermiddelen is in scope van de POC.

De Event mediator van de Entitlement API van de Faciliteit voor leveren (of arrangeren) van digitale leermiddelen orkestreert aan de hand van het verzenden van Entitlement en ChangeLicenseStatus berichten en het ontvangen en verwerken van EntitlementConfirmation en ChangeLicenseStatusConfirmation berichten de volgordelijkheid in traceerbaarheid van de processen zoals beschreven in paragraaf 3.5.

Event processor: Leermiddelenaanbieder (Licentiekantoor)

Buiten scope POC

Alleen het gedrag zoals beschreven bij Leveren leermiddelen is in scope van de POC.

Bij het verwerken van Entitlement wordt gewerkt met terugmeldingen. Op deze manier zijn de activiteiten van de drie rollen die betrokken zijn in dit proces altijd te traceren. In onderstaande tabel is het gedrag van de Event processor van het Licentiekantoor beschreven.

Proces	Trigger	Actie	Output	Registratie
Leveren leermiddelen	Entitlement bericht met status entitled	Verwerken van Entitlement conform entitlementType en specificaties Genereren EntitlementConfirmation bevestigingsbericht met newStatus provisioned	Versturen Entitlement Confirmation bevestigingsbericht naar Leermiddelenshop met newStatus provisioned of indien verwerking niet succesvol met foutcode	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status entitled EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newStatus provisioned \| foutcode
	Entitlement bericht met status provisioned	-	-	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status provisioned
	Entitlement bericht met status link-ready	-	-	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status link-ready
Annuleren bestelling	Entitlement bericht met status cancelled	Verwerken van annulering van Entitlement conform entitlementType en specificaties Genereren EntitlementConfirmation bevestigingsbericht met newStatus cancelled	Versturen Entitlement Confirmation bevestigingsbericht naar Leermiddelenshop met newStatus cancelled of indien verwerking niet succesvol met foutcode	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status cancelled EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newStatus cancelled \| foutcode
Wijzigen bestelling	Entitlement bericht met newQuantity	Verwerken van gewijzigde quantity van Entitlement conform entitlementType en specificaties Genereren EntitlementConfirmation bevestigingsbericht met newQuantity newQuantity	Versturen Entitlement Confirmation bevestigingsbericht naar Leermiddelenshop met newStatus cancelled of indien verwerking niet succesvol met foutcode	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status newQuantity EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newQuantity newQuantity \| foutcode
Blokkeren en deblokkeren leerling- of leraarlicentie	ChangeLicenseStatus bericht met status activated \| blocked	Verwerken van wijziging status van licentie die geregistreerd is op Entitlement Genereren ChangeLicense StatusConfirmation bevestigingsbericht met newStatus activated \| blocked	Versturen ChangeLicense StatusConfirmation bevestigingsbericht naar Leermiddelenshop met newStatus cancelled of indien verwerking niet succesvol met foutcode	ChangeLicenseStatus bericht van Leermiddelenshop entitlementAndLicenseReferenceId voor status activated \| blocked ChangeLicenseStatus Confirmation bevestigingsbericht entitlementAndLicenseReceiveId voor newStatus activated \| blocked \| foutcode
Blokkeren aanspraak	Entitlement bericht met status blocked	Verwerken van blokkering van Entitlement conform entitlementType en specificaties inclusief het wijzigen van de status van alle licenties die geregistreerd zijn op de entitlement naar blocked Genereren EntitlementConfirmation bevestigingsbericht met newStatus blocked	Versturen Entitlement Confirmation bevestigingsbericht naar Leermiddelenshop met newStatus blocked of indien verwerking niet succesvol met foutcode	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status blocked EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newStatus blocked \| foutcode

Event processor: Leerportaalaanbieder (Mijn Leermiddelen)

Buiten scope POC

Alleen het gedrag zoals beschreven bij Leveren leermiddelen is in scope van de POC.

Bij het verwerken van Entitlement wordt gewerkt met bevestigingsberichten. Op deze manier zijn de activiteiten van de componenten die betrokken zijn in dit proces altijd te traceren. In onderstaande tabel is het gedrag van de Event processor van het de component Mijn leermiddelen van de Leerportaalaanbieder toegelicht.

Proces	Trigger	Actie	Output	Registratie
Leveren leermiddelen	Entitlement bericht met status entitled	-	-	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status entitled
	Entitlement bericht met status provisioned	Verwerken van Entitlement conform entitlementType en specificaties Genereren Entitlement Confirmation bevestigingsberichtmet newStatus link-ready	Versturen Entitlement Confirmation bevestigingsbericht naar Leermiddelenshop met newStatus link-ready of indien verwerking niet succesvol met foutcode	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status provisioned EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newStatus link-ready \| foutcode
	Entitlement bericht met status link-ready	-	-	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status link-ready
Annuleren bestelling	Entitlement bericht met status cancelled	Verwerken van annulering van Entitlement conform entitlementType en specificaties. Genereren Entitlement Confirmation bevestigingsbericht met newStatus cancelled	Versturen Entitlement Confirmation bevestigingsbericht naar Leermiddelenshop met newStatus cancelled of indien verwerking niet succesvol met foutcode.	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status cancelled EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newStatus cancelled \| foutcode
Wijzigen bestelling	Entitlement bericht met newQuantity	-	-	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status newQuantity
Blokkeren en deblokkeren leerling- of leraarlicentie	ChangeLicenseStatus bericht met status activated \| blocked	Verwerken van wijziging status van licentie die geregistreerd is op Entitlement Genereren ChangeLicense StatusConfirmation bevestigingsberichtmet newStatus activated \| blocked	Versturen ChangeLicense StatusConfirmation bevestigingsbericht naar Leermiddelenshop met newStatus cancelled of indien verwerking niet succesvol met foutcode	ChangeLicenseStatus bericht van Leermiddelenshop entitlementAndLicenseReferenceId voor status activated \| blocked ChangeLicenseStatus Confirmation bevestigingsbericht entitlementAndLicenseReceiveId voor newStatus activated \| blocked \| foutcode
Blokkeren aanspraak	Entitlement bericht met status blocked	Verwerken van blokkering van Entitlement conform entitlementType en specificaties inclusief het wijzigen van de status van alle licenties die geregistreerd zijn op de entitlement naar blocked Genereren Entitlement Confirmation bevestigingsbericht met newStatus blocked	Versturen Entitlement Confirmation bevestigingsbericht naar Leermiddelenshop met newStatus blocked of indien verwerking niet succesvol met foutcode	Entitlement bericht van Leermiddelenshop entitlementReferenceId voor status blocked EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newStatus blocked \| foutcode

De Leerportaalaanbieder volgt de berichten van de Leermiddelenshop en hoeft zelf geen controles uit te voeren bij de Leermiddelenaanbieder.

Dit betekent bijvoorbeeld in het geval van een annulering van een Entitlement dat de Leerportaalaanbieder niet hoeft te controleren of het leermiddel in gebruik is genomen. Indien er een foutmelding vanuit de Leermiddelenaanbieder naar de Leermiddelenshop gaat dan is de Leermiddelenshop verantwoordelijk voor het herstellen en ongedaan maken van de annulering. In de praktijk zal dit ertoe leiden dat de Leermiddelenshop een Entitlement bericht toestuurt met de (oude) status provisioned. De Leerportaalaanbieder plaatst de link vervolgens opnieuw, stuurt een EntitlementConfirmation bericht terug met link-ready en de Leermiddelenshop verandert vervolgens de status van de entitlement weer naar link-ready.

Status- en foutcodes

Status code	Status	statusMessage	Toelichting
200	0	OK	Verzoek succesvol verwerkt
400	1	schema validation unsuccessful	Schemavalidatie niet succesvol
400	2	schemaVersion not supported	De ontvanger kan de gevraagde SchemaVersion niet aanbieden.
401	3	scope required	Client is niet geautoriseerd voor scope.
403	4	consent required	De gegevenssoort is van classificatie II of IV. Dit vereist een activering van de gegevensuitwisseling. Dit is in dit foutscenario niet het geval.
403	5	edu_org_id unknown	De Verzender communiceert in de context van een Onderwijsorganisatie die niet bekend is bij Ontvanger.
404	6	School unknown	De identifier van de onderwijsorganisatie is onbekend.
404	7	User unknown	De identifier van de onderwijsdeelnemer of onderwijsmederker is onbekend.
404	8	Entitlement unknown	De identifier van de Aanspraak is onbekend.
400	99	Vullingsregel: in statusMessage een beschrijving van de reden opnemen	Overige reden

Technisch: API specificatie

Release notes

0.0.1: Eerste draft van de API.
0.0.2: Berichtdefinities en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.
0.0.3: De technische specificatie is verder uitgewerkt. Ook is de feedback uit de werkgroepen verwerkt in een volgende versie:
- Endpoint toegevoegd waarin entitlements voor een onderwijsdeelnemer of onderwijsmedewerker opgevraagd kunnen worden.
- Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van het activeren en deactiveren van gegevensuitwisselingen en de M2M identificatie en authenticatie.
- Het transactiepatroon georkestreerde uitwisseling met een opeenvolging van asynchrone uitwisselingen is toegepast op de Entitlement API. Dit heeft geresulteerd in PUT endpoints voor de meldingen en de terugmeldingen (confirmations) voor de relevante referentiecomponenten.
- BasispoortIDs zijn toegevoegd als opties voor Onderwijsdeelnemer, Onderwijsmedewerker en School.
- In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
- De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.
0.0.4: De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.