ActivationCode API

Titel

ActivationCode API

Status

In ontwikkeling BEsluitvorming in beheer

Versie

0.0.2

Datum

13 December 2023

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 en de Aanspraakmanager als Verzenders.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst

Activatiecodeverzoek

Scopes

  • activationcode

Berichten

Bevestigings-berichten

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

Aanspraakmanager

  • PUT Confirm activation code request

  • PUT Confirom activation code revoke request

Berichtdefinitie: ActivationCodeRequest

Het ActivationCodeRequest bericht wordt door de Bestelomgeving leermiddelen of de Aanspraakmanager 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 of de Aanspraakmanager om een logboek bij te houden van verzonden en ontvangen meldingen en terugmeldingen met betrekking tot een unieke aanvraag van een activatiecode.

schemaVersion

string

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

1.3.0

V

Conform Semantic Versioning 2.0.0

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.

Berichtdefinitie: 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 of de Aanspraakmanager.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

request
ReferenceId

string

uuid

De referentie van de Bestelomgeving leermiddelen of de Aanspraakmanager 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.

schemaVersion

string

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

1.3.0

V

Conform Semantic Versioning 2.0.0

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

Berichtdefinitie: 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 of de Aanspraakmanager 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 of Aanspraakmanager 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.

schemaVersion

string

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

1.3.0

V

Conform Semantic Versioning 2.0.0

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

Berichtdefinitie: 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 of de Aanspraakmanager 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.

schemaVersion

string

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

1.3.0

V

Conform Semantic Versioning 2.0.0

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: Berichtdefinities en endpoints zijn overgenomen uit de Entitlement API.

  • 0.0.2: YAML file toegevoegd