Entitlement API

Titel	Entitlement API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming in beheer
Versie	Documentatie: 0.0.9
Versie	schemaVersion: 0.0.6
Datum	24 April 2024
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	entitlement.seller (voor Bestelomgeving leermiddelen) entitlement.licensor (voor Licentieregistratie) entitlement.portal (voor Leermiddelenportaal) 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 entitlementReceiveId 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
Blokkeren aanspraak	Verzoek tot blokkeren van Entitlement	Wijzigen entitlementStatus Entitlement naar `blocked` voor te versturen bericht naar Licentieregistratie Wijzigen urlStatus Entitlement naar `blocked` voor te versturen bericht naar Leermiddelenportaal	Versturen Entitlement in EntitlementRequest berichten naar Licentieregistratie en Leermiddelenportaal	Entitlement bericht entitlementReferenceId voor entitlementStatus en urlStatus `blocked`
	EntitlementConfirmation bevestigingsbericht van Licentieregistratie met newEntitlementStatus `blocked`	Wijzigen entitlementStatus van een Entitlement naar `blocked` de endDate wordt toegevoegd aan de entitlement	-	EntitlementConfirmation bevestigingsbericht van Licentieregistratie entitlementReceiveId van Licentieregistratie
	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met newUrlStatus `blocked`	Wijzigen urlStatus van een Entitlement naar `blocked`	-	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal entitlementReceiveId 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
Deblokkeren aanspraak	Verzoek tot deblokkeren van Entitlement	Wijzigen entitlementStatus Entitlement naar vorige status `entitled` / `licensed` voor te versturen bericht naar Licentieregistratie Wijzigen urlStatus Entitlement naar `initialized` voor te versturen bericht naar Leermiddelenportaal	Versturen Entitlement in EntitlementRequest berichten naar Licentieregistratie en Leermiddelenportaal	Entitlement bericht entitlementReferenceId voor entitlementStatus `entitled` / `licensed` en urlStatus `initialized`
	EntitlementConfirmation bevestigingsbericht van Licentieregistratie met newEntitlementStatus `entitled`/ `licensed`	Wijzigen entitlementStatus van een Entitlement naar vorige status `entitled` / `licensed` de endDate wordt verwijderd uit de entitlement	-	EntitlementConfirmation bevestigingsbericht van Licentieregistratie entitlementReceiveId van Licentieregistratie
	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met newUrlStatus `initialized`	Wijzigen urlStatus van een Entitlement naar `processed`	-	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal entitlementReceiveId 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
In gebruik nemen digitaal leermiddel	InitialActivation bericht via de Usage API vanuit de Licentieregistratie Optioneel is de expirationDate bijgewerkt voor de betreffende aanspraak.	Wijzigen entitlementStatus van Entitlement naar `licensed` Indien het de eerste leermiddelactivatie binnen de DeliveryOrder betreft: Wijzigen status van DeliveryOrder naar `licensed` en opstellen van DeliveryOrderConfirmation met newStatus `licensed` Indien expirationDate is gewijzigd: Bijwerken van de expirationDate op de Entitlement. Wijzigen van urlStatus van Entitlement naar `initialized`	Versturen DeliveryOrderConfirmation naar Bestelomgeving leermiddelen Versturen Entitlement in EntitlementRequest bericht naar Leermiddelenportaal	DeliveryOrderConfirmation bevestigingsbericht deliveryOrderReceiveId voor newStatus `licensed` Entitlement bericht entitlementReferenceId urlStatus `initialized`
	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met newUrlStatus `processed`	Wijzigen urlStatus Entitlement naar `processed`		entitlementReceiveId van Leermiddelenportaal EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal
	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met foutcode	Notificeren support van Aanspraakmanager	Versturen Supportbericht inclusief foutcode	EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal entitlementReceiveId van Leermiddelenportaal

Event processor: Licentieregistratie

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 digitaal leermiddel	Entitlement in EntitlementRequest bericht met entitlementStatus `created`	Verwerken van Entitlement conform entitlementType en entitlementSpecification Genereren EntitlementConfirmation bevestigingsbericht met newEntitlementStatus `entitled`	Versturen EntitlementConfirmation bevestigingsbericht naar Aanspraakmanager met newEntitlementStatus `processed` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `ordered` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newStatus `processed` \| foutcode
Annuleren levering van digitaal leermiddel	Entitlement in EntitlementRequest bericht met entitlementStatus `cancelled`	Verwerken van annulering van Entitlement en het wijzigen van de entitlementStatus naar `cancelled` Genereren EntitlementConfirmation bevestigingsbericht met newEntitlementStatus `cancelled`	Versturen Entitlement Confirmation bevestigingsbericht naar Aanspraakmanager met newEntitlementStatus `cancelled` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `cancelled` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newEntitlementStatus `cancelled` \| foutcode
Blokkeren aanspraak	Entitlement in EntitlementRequest bericht met entitlementStatus `blocked`	Verwerken van blokkering van Entitlement en het wijzigen van de entitlementSatus naar `blocked` Genereren EntitlementConfirmation bevestigingsbericht met newEntitlementStatus `blocked`	Versturen Entitlement Confirmation bevestigingsbericht naar Aanspraakmanager met newEntitlementStatus `blocked` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `blocked` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newEntitlementStatus `blocked` \| foutcode
Deblokkeren aanspraak	Entitlement in EntitlementRequest bericht met voorde blokkade van toepassing zijnde entitlementStatus `entitled` / `licensed`	Verwerken van deblokkering van Entitlement en het wijzigen van de entitlementSatus naar `entitled` / `licensed` Genereren EntitlementConfirmation bevestigingsbericht met newEntitlementStatus `entitled` / `licensed`	Versturen Entitlement Confirmation bevestigingsbericht naar Aanspraakmanager met newEntitlementStatus `entitled` / `licensed` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `entitled` / `licensed` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newEntitlementStatus `entitled` / `licensed` \| foutcode

Event processor: Leermiddelenportaal

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 Leermiddelenportaal toegelicht.

Proces	Trigger	Actie	Output	Registratie
Leveren digitaal leermiddel	Entitlement in EntitlementRequest bericht met urlStatus `initialized`	Toegangslink naar product plaatsen voor eindgebruiker binnen aangegeven datumvelden. Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus `processed`	Versturen EntitlementConfirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus `processed` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `initialized` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newUrlStatus `processed` \| foutcode
Annuleren levering van digitaal leermiddel	Entitlement in EntitlementRequest bericht met urlStatus `cancelled`	Toegangslink van product verwijderen voor eindgebruiker. Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus `cancelled`	Versturen Entitlement Confirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus `cancelled` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `cancelled` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newUrlStatus `cancelled` \| foutcode
Blokkeren aanspraak	Entitlement in EntitlementRequest bericht met urlStatus `blocked`	Toegangslink van product verwijderen voor eindgebruiker. Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus `blocked`	Versturen Entitlement Confirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus `blocked` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `blocked` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newUrlStatus `blocked` \| foutcode
Deblokkeren aanspraak	Entitlement in EntitlementRequest bericht met urlStatus `initialized`	Toegangslink naar product plaatsen voor eindgebruiker binnen aangegeven datumvelden. Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus `processed`	Versturen Entitlement Confirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus `processed` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `initialized` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newUrlStatus `processed` \| foutcode
In gebruik nemen digitaal leermiddel	Entitlement in EntitlementRequest bericht met urlStatus `initialized` Het veld van de expirationDate is gewijzigd. De aanspraakmanager heeft dit veld gewijzigd op basis van een ontvangen InitialActivation bericht van de Licentieregistratie.	Toegangslink naar product plaatsen voor eindgebruiker binnen aangegeven datumvelden. De link blijft actief tot en met de nieuwe waarde in de expirationDate. Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus `processed``	Versturen Entitlement Confirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus `processed` of indien verwerking niet succesvol met foutcode	EntitlementRequest bericht van Aanspraakmanager entitlementReferenceId voor status `initialized` EntitlementConfirmation bevestigingsbericht entitlementReceiveId voor newUrlStatus `processed` \| foutcode

Status- en foutcodes

Voor alle APIs uit het Afsprakenstelsel Edu-V zijn de status- en foutcodes beschreven op de pagina Status- en foutcodes. Hierbij is onderscheid gemaakt in algemene en voor de API specifieke status- en foutcodes.

Technisch: API specificatie

Release notes

0.0.1: Eerste draft van de API.
0.0.2: Objecten 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 regie op gegevens 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.
0.0.5: Objecten geactualiseerd op basis van herziening rollen en referentiecomponenten in het architectuurkader. Objecten ChangeLicenseStatus en ChangeLicenseStatusConfirmation toegevoegd.
0.0.6: YAML file aangepast. Endpoints voor activatiecode verwijderd en verplaatst naar de ActivationCode API.
0.0.7: Typo’s verwijderd uit de YAML file.
0.0.8: De objecten en koppelvlakspecificatie inclusief de YAML zijn aangepast naar het nieuwe conceptueel model. Dit heeft geleid tot de volgende wijzigingen:
- Aanspraken zijn van toepassing voor een enkele eindgebruiker. De voorheen open aanspraakvarianten zijn verplaatst naar de leveringsorders in de Delivery API
- Aanspraken zijn er nog steeds in typen. De typen variëren vanuit de beoogde gebruiker: onderwijsdeelnemer, onderwijsmedewerker en een eindgebruiker met een activatiecode. Daarnaast zijn er aanspraken die toebehoren aan een onderwijsorganisatie.
- De statusinformatie van aanspraken is gewijzigd. Dit heeft geleid tot de status van een aanspraak en de status van de plaatsing van de links in het leermiddelenportaal.
- Er zijn GET endpoints toegevoegd voor het Leermiddelendashboard
- Er zijn GET endpoints toegevoegd voor het Leermiddelenportaal om aanspraken en producten uit aanspraken op te vragen voor een specifieke eindgebruiker.
- Er zijn GET endpoints toegevoegd voor de Bestelomgeving leermiddelen en de Licentieregistratie om aanspraken op basis van een leveringsorderId en contractId op te vragen.
- Het transactiepatroon voor het Leermiddelendashboard is gewijzigd naar een Bevraging. Het Leermiddelendashboard ontvang geen meldingen meer vanuit de Aanspraakmanager en speelt geen rol meer in de georkestreerde uitwisseling.
- De scopes zijn aangepast met een specifieke scope voor de gegevensafnemende referentiecomponenten: Bestelomgeving leermiddelen, Licentieregistratie, Leermiddelendashboard en Leermiddelenportaal.
0.0.9: Er zijn wijzigingen verwerkt:
- Wijzigen in de architectuur:
  - Attribuut schemaVersion is verwijderd uit de objecten.
  - Query parameter schemaVersion is verwijderd uit de koppelvlakken.
  - Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.
  - Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.
  - Primaire en secundaire identifiers voor onderwijsaanbieders en eindgebruikers bijgewerkt.
- Feedback vanuit de werkgroep Verwerven en in gebruik nemen:
  - Attribuut urlStatus is vervangen door urlStatusses met een verwijzing naar de urlStatus per Portaal.
  - Endpoint entitlementproducts/school/user is hernoemd naar entitlements/school/user/products
0.0.10: / achter endpoints verwijderd.