ActivationCode API

Titel

ActivationCode API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.9.1

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:

Samenvatting

Gegevensdienst

Activatiecodeverzoek

Scopes

  • eduv.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

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.