ActivationCode API

Titel	ActivationCode API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	Documentatie: 0.9.1
Versie	schemaVersion: 0.9.1
Datum	27 September 2024
Auteur	Werkgroep Verwerven en in gebruik nemen
Acties	Geen openstaande acties

De ActivationCode API wordt gebruikt om informatie over activatiecodes te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Activatiecodeverzoek met de Bestelomgeving leermiddelen als Verzender en de Licentieregistratie als Ontvanger.

De technische specificatie bestaat uit:

1 Samenvatting
2 Bericht: ActivationCodeRequest
3 Bevestigingsbericht: ActivationCodeConfirmation
4 Bericht: ActivationCodeRevokeRequest
5 Bevestigingsbericht: ActivationCodeRevokeConfirmation
6 Status- en foutcodes
7 Technisch: API specificatie
8 Release notes

Samenvatting

Gegevensdienst	Activatiecodeverzoek
Scopes	eduv.activationcode
Berichten	ActivationCodeRequest ActivationCodeRevokeRequest
Bevestigings-berichten	ActivationCodeConfirmation ActivationCodeRevokeConfirmation
Verzender	Bestelomgeving leermiddelen
Ontvanger	Licentieregistratie
Endpoints	Licentieregistratie PUT Accept activation code request PUT Accept activation code revoke request Bestelomgeving leermiddelen PUT Confirm activation code request PUT Confirom activation code revoke request

Bericht: ActivationCodeRequest

Het ActivationCodeRequest bericht wordt door de Bestelomgeving leermiddelen verstuurd naar de Licentieregistratie binnen de activationcode. In de berichtspecificatie is een requestReferenceId opgenomen die wordt bepaald door de verzender. Dit stelt de verzender in staat om bevestigingsberichten vanuit de Licentieregistratie terug te relateren aan het verstuurde activationCodeRequest bericht. Dit is vergelijkbaar met de uitwisselingsvariant die ook geïmplementeerd is voor aanspraken (Entitlements).

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
request ReferenceId	string	uuid	Referentienummer voor het aanvragen van een activatiecode	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V	Dit nummer wordt gebruikt door de event mediator van de Bestelomgeving leermiddelen om een logboek bij te houden van verzonden en ontvangen meldingen en terugmeldingen met betrekking tot een unieke aanvraag van een activatiecode.
productId	string	string	Referentie naar de Product-beschrijving in de Catalogue API van het Leermiddel waarvoor een activatiecode wordt aangevraagd.	871792713 0834	V	Een aanvraag voor een activatiecode verwijst naar exact 1 Product-Beschrijving (Leermiddel- of Setbeschrijving) Waarde mag niet gewijzigd worden
quantity	integer	integer	Aantal activatiecodes dat wordt aangevraagd.	1	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. De aanvraag voor de activatiecode wordt conform de afspraken uit dit contract behandeld.	2022-12-v1	O	Waarde mag niet gewijzigd worden.

Bevestigingsbericht: ActivationCodeConfirmation

De Licentieregistratie reageert op een ActivationCodeRequest bericht met een ActivationCodeConfirmation bevestigingsbericht. In dit bevestigingsbericht worden de activatiecodes opgenomen. In aanvulling hierop wordt optioneel de informatie uit de aanvraag (product, contractId) ook bevestigd. Door ook een tijdstempel op te nemen kan dit bevestigingsbericht worden gezien als een formele levering van activatiecodes van aan de Bestelomgeving leermiddelen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
request ReferenceId	string	uuid	De referentie van de Bestelomgeving leermiddelen waarop dit bevestigingsbericht een antwoord is.	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V	Waarde mag niet gewijzigd worden.
response ReferenceId	string	uuid	De referentie van de Licentieregistratie voor dit bevestigingsbericht.	eacb81ef-c9d5-4bd8-a624-4088bee04b76	V	Waarde mag niet gewijzigd worden.
productId	string	string	Verwijzing naar de unieke identifier voor het product	871792713 0834	V	Waarde mag gewijzigd worden.
activationCodes	array	string	Door de Licentieregistratie gegenereerde array van activatiecodes voor het product.	[XXXXXX, YYYYYY, ZZZZZZ]	O*	Waarde wordt gevuld indien het verzoek succesvol is verwerkt Waarde mag niet gewijzigd worden.
processed Timestamp	string	datetime	Tijdstip waarop het ActivationCodeRequest bericht is verwerkt door de Licentieregistratie.	2017-07-21T17:32:28Z	V	Het tijdstip kan afwijken van het versturen van het bevestigingsbericht. Intentie is om aan te geven wanneer het bericht is verwerkt.
success	boolean	boolean	Indicatie of de Licentieregistratie het bericht heeft kunnen verwerken	True False	V	False indien de Licentieregistratie 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

Bericht: ActivationCodeRevokeRequest

Naast een regulier verzoek om een activatiecode is het mogelijk om om een activatiecode in te laten trekken. Ook dit bericht wordt verstuurd binnen de scope activationcode. In dat geval dient de Bestelomgeving leermiddelen een ActivationCodeRevokeRequest in bij de Licentieregistratie.

In dit bericht wordt de activatiecode en optioneel het responseReferenceId ontvangen van de Aanbieder gespecificeerd. Op deze wijze kunnen zowel Bestelomgeving leermiddelen als Licentieregistratie dit bericht relateren aan de oorspronkelijke aanvraag voor de activatiecode die ingetrokken dient te worden. Uiteraard is het afhankelijk van bilaterale afspraken tussen leveranciers of het intrekken van een activatiecode al dan niet mogelijk is.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
request ReferenceId	string	uuid	Referentienummer voor het retourneren van een activatiecode	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V	Dit nummer wordt gebruikt door de event mediator van de Bestelomgeving leermiddelen of de Licentieregistratie om een logboek bij te houden van verzonden en ontvangen meldingen en terugmeldingen met betrekking tot een unieke aanvraag van een activatiecode.
activationCode	string	string	Door de Licentieregistratie gegenereerde activatiecode die ingetrokken dient te worden.	XXXXXX	V	Waarde mag niet gewijzigd worden.
response ReferenceId	string	string	Optionele verwijzing naar de ActivatiecodeBevestiging (ActivationCodeConfirmation) waarin de activatiecode door de Licentieregistratie is geleverd.	eacb81ef-c9d5-4bd8-a624-4088bee04b76	O	Waarde mag niet gewijzigd worden

Bevestigingsbericht: ActivationCodeRevokeConfirmation

De Licentieregistratie reageert op een ActivationCodeRevokeRequest met een bevestigingsbericht ActivationCodeRevokeConfirmation.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
request ReferenceId	string	uuid	De referentie van de Bestelomgeving leermiddelen waarop dit bevestigingsbericht een antwoord is.	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V	Waarde mag niet gewijzigd worden.
response ReferenceId	string	uuid	De referentie van de Licentieregistratie voor dit bevestigingsbericht.	24e39454-5360-4ba4-819f-03e59b8dd679	V	Waarde mag niet gewijzigd worden.
activationCode	string	string	Door de Licentieregistratie gegenereerde activatiecode die ingetrokken dient te worden.	XXXXX-XXXXX-XXXXX-XXXXX-XXXXX	V	Waarde mag niet gewijzigd worden.
processed Timestamp	string	datetime	Tijdstip waarop het ActivationCodeRevokeRequest bericht is verwerkt door de Licentieregistratie.	2017-07-21T17:32:28Z	V	Het tijdstip kan afwijken van het versturen van het bevestigingsbericht. Intentie is om aan te geven wanneer het bericht is verwerkt.
success	boolean	boolean	Indicatie of de Licentieregistratie de activatiecode heeft ingetrokken	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

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: Objecten en endpoints zijn overgenomen uit de Entitlement API.
0.0.2: YAML file toegevoegd voor de ActivationCode API
0.0.3: Conform wijziging in architectuur de schemaVersion als attribuut verwijderd uit de objecten.
0.0.4: Aanspraakmanager stond nog per abuis in de specificatie en YAML.
0.9.0: Het Bestuurlijk Overleg heeft tijdens de bijeenkomst van 27 juni 2024 het Afsprakenstelsel Edu-V als versie 0.9.0 goedgekeurd voor implementatie.
0.9.1: Wijzigingen naar aanleiding van RFC’s:
- Op basis van RFC002 is de scope aangepast met een prefix eduv.. Dit stelt leveranciers in staat om onderscheid te maken tussen gegevensuitwisselingen met leveranciers binnen en buiten het Edu-V afsprakenstelsel.