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