Entitlement API

Titel	Entitlement API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	Documentatie: 1.0.0
Versie	schemaVersion: 1.0.0
Datum	13 maart 2025
Auteur	Werkgroep Verwerven en in gebruik nemen
Acties	Geen openstaande acties

De Entitlement API wordt gebruikt om informatie over aanspraken te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Aanspraken en leermiddelactivatie met de Aanspraakmanager als Verzender.

Aanspraken vervullen een cruciale rol in de gesloten-geld-goederenstroom. Hierdoor is het cruciaal dat het verzenden, ontvangen en verwerken van de gegevens te traceren is. Daarnaast kent het opvolgen van een aanspraak door de Licentieregistratie en het Leermiddelenportaal 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 Bericht: EntitlementRequest (Aanspraak)
3 Object: Entitlement
- 3.1 objecten: EntitlementType en EntitlementSpecification
- 3.2 object: UrlStatus
4 Bevestigingsbericht: EntitlementConfirmation
5 Object: EntitlementProduct
6 Event mediator: Aanspraakmanager
7 Event processor: Licentieregistratie
8 Event processor: Leermiddelenportaal
9 Status- en foutcodes
10 Technisch: API specificatie
11 Release notes

Samenvatting

Gegevensdienst	Aanspraken en leermiddelactivatie
Scopes	eduv.entitlement.seller (voor Bestelomgeving leermiddelen) eduv.entitlement.licensor (voor Licentieregistratie) eduv.entitlement.portal (voor Leermiddelenportaal) eduv.entitlement.dashboard (voor Leermiddelendashboard)
Berichten	EntitlementRequest
Bevestigings-berichten	EntitlementConfirmation
Objecten	Entitlement EntitlementProduct
Verzender en bron	Aanspraakmanager
Ontvanger	Licentieregistratie Leermiddelenportaal
Afnemer	Leermiddelendashboard Leermiddelenportaal Bestelomgeving leermiddelen
Endpoints	Aanspraakmanager GET Entitlement by ID GET All Entitlements by School ID POST GET ALL Entitlement by User ID (eckId en userId worden via request body verstuurd) PUT Confirm Entitlement PUT Confirm ChangeLicenseStatus Licentieregistratie PUT Accept Entitlement PUT Accept ChangeLicenseStatus request Leermiddelenportaal PUT Accept Entitlement PUT Accept ChangeLicenseStatus request Leermiddelendashboard PUT Accept Entitlement PUT Accept ChangeLicenseStatus request

Bericht: EntitlementRequest (Aanspraak)

Het EntitlementRequest bericht bevat de specificatie van de aanspraak op een leermiddel. 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 van de aanspraak.	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V	Dit nummer wordt gebruikt door de event mediator om een logboek bij te houden van verzonden en ontvangen meldingen en terugmeldingen met betrekking tot een unieke entitlementId.
entitlement	object	entitlement	De specificatie van de aanspraak	Zie object Entitlement	V

Object: Entitlement

Het object Entitlement beschrijft de aanspraak zoals deze is aangemaakt op basis van de leverspecificatie uit een leveringsorder die door de Aanspraakmanager door een Bestelomgeving leermiddelen is ontvangen.

Iedere aanspraak heeft een status conform de levenscyclus van een Aanspraak. De waarden uit een aanspraak mogen niet gewijzigd worden (ook niet voor foutcorrecties). Indien de aanspraak niet correct is dan wordt deze geannuleerd en wordt er een nieuwe aanspraak gestuurd.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlementId	string	uuid	Unieke identifier voor deze aanspraak	24e39454-5360-4ba4-819f-03e59b8dd679	V	Waarde mag niet gewijzigd worden
deliveryOrderId	string	uuid	Unieke identifier voor de leveringsorder waartoe de entitlement behoort.	24e39454-5360-4ba4-819f-03e59b8dd679	V	Waarde mag niet gewijzigd worden
contractId	string	string	Optionele unieke identifier van een contract tussen de leverancier van het leermiddel en de leverancier die de verwerving verzorgt.	2022-12-v1	O	Waarde mag niet gewijzigd worden.
productId	string	string	Referentie naar de Productbeschrijving in de Catalogue API van het leermiddel.	871792713 0834	V	Een aanspraak verwijst naar exact 1 Product-Beschrijving Waarde mag niet gewijzigd worden
startDate	string	date	Datum vanaf wanneer het product 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 het product in gebruik genomen kan worden. Hierna is de activatieperiode verlopen	2023-07-31	V	Waarde mag niet gewijzigd worden
expirationDate	string	date	De expirationDate die door de het Leermiddelenportaal gehanteerd kan worden bij het beheren van toegangslinks. In het eerste bericht wordt dit veld gebruikt met een minExpirationDate die door de Aanspraakmanager wordt bepaald.	2023-07-31	O	Deze waarde wordt berekend 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 Aanspraakmanager kan via een InitialActivation bericht een nieuwe expirationDate doorkrijgen uit de Licentieregistratie. In dat geval wordt het plaatsen van de toegangslink door het Leermiddelenportaal opnieuw geïnitieerd door de Aanspraakmanager. Deze nieuwe expirationDate is gelijk aan of ligt verder in de toekomst en overschrijft voor de betreffende gebruiker de eerder berekende minExpiration Date.
endDate	string	date	Datum dat de aanspraak 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	Het type aanspraak beschrijft op welke wijze een individu een aanspraak kan activeren. Dit kan met behulp van een ID of een activatiecode en al dan niet vanuit een onderwijsorganisatie.	Zie entitlementType en entitlementSpecification	V	Waarde mag niet gewijzigd worden
entitlementSpecification	object	Entitlement Specification	Specificatie van de waarden behorende bij het type aanspraak.	Zie entitlementType en entitlementSpecification	V	Waarde mag niet gewijzigd worden
entitlementStatus	string	ENUM	De status waarin de aanspraak zich bevindt.	`created` `entitled` `licensed` `cancelled` `blocked`	V	Status wordt toegekend conform de levenscyclus van de Aanspraak.
urlStatuses	array	UrlStatus	De status waarin de plaatsing van de toegangslink bij een Leermiddelenportaa applicatiel zich bevindt.	Zie object UrlStatus	V	De toegangslink kan bij meerdere portalen geplaatst zijn of worden.
dateCreated	string	datetime	Datum en tijdstip waarop de entiteit is aangemaakt	2017-07-21T17:32:28Z	V
dateLastModified	string	datetime	Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd	2022-08-11T15:31:12Z	V

objecten: EntitlementType en EntitlementSpecification

Een aanspraak betreft het recht om een digitaal leermiddel als individu in gebruik te nemen en te gaan gebruiken. Het type aanspraak specificeert op welke wijze een individu een leermiddel kan gaan activeren. We hanteren de volgende varianten.

Type aanspraak	Besteller	Licentieregistratie staat activering toe zodra:
`school-student`	Onderwijsorganisatie	De gespecificeerde onderwijsdeelnemer vanuit de gespecificeerde onderwijsorganisatie het leermiddel in gebruik gaat nemen.
`school-employee`	Onderwijsorganisatie	De gespecificeerde onderwijsmedewerker vanuit de gespecificeerde onderwijsorganisatie het leermiddel in gebruik gaat nemen.
`school-activationcode`	Onderwijsorganisatie	Een eindgebruiker vanuit de gespecificeerde onderwijsorganisatie het leermiddel in gebruik gaat nemen en hierbij de gespecificeerd en niet gebruikte activatiecode gebruikt.
`customer-student`	Particulier	De gespecificeerde onderwijsdeelnemer het leermiddel in gebruik gaat nemen.
`customer-activationcode`	Particulier	Een eindgebruiker die de gespecificeerde en niet gebruikte activatiecode gebruikt.

Voor ieder van de type aanspraken (entitlementType) geldt een eigen verplichte specificatie (entitlementSpecification) die opgenomen dient te worden in de aanspraak. De velden worden weergegeven in onderstaande tabel.

entitlementType	entitlementSpecification
`school-student`	school: referentie naar een onderwijsorganisatie
`school-student`	student: referentie naar een eindgebruiker
`school-employee`	school: referentie naar een onderwijsorganisatie
`school-employee`	employee: referentie naar een eindgebruiker
`school-activationcode`	school: referentie naar een onderwijsorganisatie
`school-activationcode`	activationCode: een activatiecode
`customer-student`	student: een referentie naar een eindgebruiker
`customer-activationcode`	activationCode: een activatiecode

object: UrlStatus

Het object UrlStatus geeft de status weer van de url zoals deze is verwerkt door een Leermiddelenportaal.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
portal	string	string	De identifier van de Leermiddelenportaal applicatie waar de toegangslink geplaatst is of dient te worden.		V
urlStatus	string	ENUM	De status waarin de plaatsing van de toegangslink bij het Leermiddelenportaal zich bevindt.	`uninitialized` `initialized` `processed` `cancelled` `blocked`	V	Status wordt toegekend conform de stap waarin het proces van plaatsen van toegangslinks zich bevindt.

Bevestigingsbericht: EntitlementConfirmation

De Licentieregistratie en het Leermiddelenportaal antwoorden op Entitlement berichten.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlement ReferenceId	string	uuid	De referentie van de Aanspraakmanager waarop dit bevestigingsbericht een antwoord is.	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V
entitlement ReceiveId	string	uuid	De referentie van de Licentieregistratie of het Leermiddelenportaal voor dit bevestigingsbericht	3437e98f-855d-4f29-9092-7ba311228920	V
entitlementId	string	uuid	Verwijzing naar de unieke identifier voor de aanspraak	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 het aanspraak verzoek is verwerkt door de Licentieregistratie of het Leermiddelenportaal	2017-07-21T17:32:28Z	V
newEntitlement Status	string	ENUM	De nieuwe status van de aanspraak	`created` `entitled` `licensed` `cancelled` `blocked`	V	De Licentieregistratie antwoordt via dit veld naar de Aanspraakmanager met een nieuwe status indien de verwerking succesvol was.
newUrlStatus	object	UrlStatus	De nieuwe status in het proces van plaatsen van toegangslinks door het Leermiddelenportaal	Zie object UrlStatus	V	Het Leermiddelenportaal antwoordt via dit veld naar de Aanspraakmanger met een nieuwe status indien de verwerking succesvol was.
success	boolean	boolean	Indicatie of de Aanspraakmanager 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

Object: EntitlementProduct

Een Leermiddelenportaal kan bij een Aanspraakmanager de producten opvragen waar een Eindgebruik een aanspraak op heeft. Dit object bevat enkel informatie over het product, de status van de aanspraak en de datumvelden die van toepassing zijn op de activatie- en gebruiksperiode.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlementId	string	uuid	Verwijzing naar de unieke identifier voor de aanspraak	24e39454-5360-4ba4-819f-03e59b8dd679	V
productId	string	string	Verwijzing naar de unieke identifier voor het product	871792713 0834	V
entitlementStatus	string	ENUM	De status waarin de aanspraak zich bevindt.	`created` `entitled` `licensed` `cancelled` `blocked`	V	Status wordt toegekend conform de levenscyclus van de Aanspraak.
startDate	string	date	Datum vanaf wanneer het product 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 het product in gebruik genomen kan worden. Hierna is de activatieperiode verlopen	2023-07-31	V	Waarde mag niet gewijzigd worden
expirationDate	string	date	De expirationDate die door de het Leermiddelenportaal gehanteerd kan worden bij het beheren van toegangslinks. In het eerste bericht wordt dit veld gebruikt met een minExpirationDate die door de Aanspraakmanager wordt bepaald.	2023-07-31	O	Deze waarde wordt berekend 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 Aanspraakmanager kan via een InitialActivation bericht een nieuwe expirationDate doorkrijgen uit de Licentieregistratie. In dat geval wordt het plaatsen van de toegangslink door het Leermiddelenportaal opnieuw geïnitieerd door de Aanspraakmanager. Deze nieuwe expirationDate is gelijk aan of ligt verder in de toekomst en overschrijft voor de betreffende gebruiker de eerder berekende minExpiration Date.

Event mediator: Aanspraakmanager

De Event mediator van de Entitlement API van de Aanspraakmanager orkestreert aan de hand van het verzenden van Entitlement berichten en het ontvangen en verwerken van EntitlementConfirmation berichten het toekennen van aanspraken aan eindgebruikers en het plaatsen van toegangslinks in het Leermiddelenportaal.

Proces	Trigger	Actie	Output	Registratie
Leveren digitaal leermiddel	Een nieuwe DeliveryOrder die verwerkt dient te worden Een nieuwe van een onderwijsdeelnemer op een opleidingsjaar of op een vak	Genereren Entitlement met entitlementStatus `created`	Versturen Entitlement in EntitlementRequest bericht naar Licentieregistratie	EntitlementRequest bericht entitlementReferenceId voor entitlementStatus `created`
	EntitlementConfirmation bevestigingsbericht van Licentieregistratie met newEntitlementStatus `entitled`	Wijzigen entitlementStatus van een Entitlement naar `entitled`		entitlementReceiveId van Licentieregistratie EntitlementConfirmation bevestigingsbericht van Licentieregistratie
	Leermiddelenportaal laat plaatsing verzorgen door Aanspraakmanager. Een Entitlement is gewijzigd van status naar `entitled`.	Wijzigen urlStatus van een Entitlement naar `initialized`	Versturen Entitlement in EntitlementRequest bericht naar Leermiddelenportaal	EntitlementRequest bericht entitlementReferenceId voor urlStatus `initialized`
	EntitlementConfirmation bevestigingsbericht van Licentieregistratie met newUrlStatus `processed`	Wijzigen urlStatus Entitlement naar `processed`		entitlementReceiveId van Leermiddelenportaal EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal
	EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal met foutcode	Notificeren support van Aanspraakmanager	Versturen Supportbericht inclusief foutcode	EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal entitlementReceiveId van Licentieregistratie of Leermiddelenportaal
Annuleren levering van digitaal leermiddel	Een DeliveryOrder wordt geannuleerd. Een Onderwijsdeelnemer is niet meer ingeschreven op een opleidingsjaar of vak. De aanspraak is gecontroleerd en heeft niet de status `licensed`	Wijzigen entitlementStatus Entitlement naar `cancelled` voor te versturen bericht naar Licentieregistratie Wijzigen urlStatus Entitlement naar `cancelled` voor te versturen bericht naar Leermiddelenportaal	Versturen Entitlement in EntitlementRequest berichten naar Licentieregistratie en Leermiddelenportaal	Entitlement bericht entitlementReferenceId voor entitlementStatus en urlStatus `cancelled`
	EntitlementConfirmation bevestigingsbericht van Licentieregistratie met newEntitlementStatus `cancelled`	Wijzigen entitlementStatus van een Entitlement naar `cancelled` de endDate wordt toegevoegd aan de entitlement	-	EntitlementConfirmation bevestigingsbericht van Licentieregistratie entitlementReceiveId van Licentieregistratie
	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met newUrlStatus `cancelled`	Wijzigen urlStatus van een Entitlement naar `cancelled`	-	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal