Usage API

De Usage API faciliteert het delen van activatie- en gebruiksgegevens van digitale leermiddelen binnen het Edu-V Afsprakenstelsel. De Licentieregistratie stuurt activatieberichten en biedt gebruiksdata aan voor dashboards en bestelomgevingen.

Zie de EDU-V documentatie voor Usage API 1.0.

Rol van de Licentieregistratie

Als Licentieregistratie zijn wij de dataprovider van de Usage API. Wanneer een gebruiker een leermiddel voor het eerst activeert, sturen wij een InitialActivation-bericht naar de Aanspraakmanager. Daarnaast bieden wij endpoints aan waarmee bestelomgevingen en dashboards gebruiksdata kunnen opvragen.

Scope: eduv.usage.entitleor (Aanspraakmanager), eduv.usage.seller (Bestelomgeving), eduv.usage.dashboard (Dashboard)

InitialActivation

Het InitialActivation-bericht wordt verstuurd door de Licentieregistratie wanneer een leermiddel voor het eerst wordt geactiveerd.

Properties

Name
entitlementId
Type
string (uuid)
Description
Identifier van de aanspraak die geactiveerd is.
Name
productId
Type
string
Description
Product-ID (EAN/ISBN).
Name
entitlementType
Type
enum
Description
Type: personal of group.
Name
school
Type
object
Description
Onderwijsorganisatie.
Name
user
Type
object
Description
De gebruiker die het leermiddel heeft geactiveerd.
Name
usageDate
Type
date
Description
Datum van eerste activering.
Name
expirationDate
Type
date
Description
Verloopdatum van de licentie.

PUT/edu-v/v1/usage-api/initial-activation

Activatie melden

Dit endpoint wordt aangeroepen op de Aanspraakmanager om een InitialActivation te melden. De Aanspraakmanager registreert de activering en wijzigt de aanspraakstatus naar licensed.

Request

PUT

/edu-v/v1/usage-api/initial-activation

{
    "entitlementId": "e5f6a7b8-c9d0-1234-ef01-345678901234",
    "productId": "9789464421408",
    "entitlementType": "personal",
    "school": {
        "organisationMasterIdentifier": "16SK"
    },
    "user": {
        "userId": "student-001",
        "userIdType": "nlPersonProfileId"
    },
    "usageDate": "2026-09-15",
    "expirationDate": "2027-08-31"
}

Gebruiksdata ophalen

De Usage API biedt diverse GET-endpoints waarmee afnemers gebruiksgegevens kunnen opvragen:

Name
GET /usage/entitlement/:id
Type
EntitlementUsage
Description
Gebruiksdata voor een specifieke aanspraak.
Name
GET /usage/delivery-order/:id
Type
DeliveryOrderUsage
Description
Gebruiksdata voor alle aanspraken in een leveringsorder.
Name
GET /usage/school/:id
Type
array
Description
Gebruiksdata voor alle aanspraken van een school.
Name
POST /usage/user
Type
array
Description
Gebruiksdata voor een specifieke gebruiker bij een school.
Name
GET /usage/contract/:id
Type
array
Description
Gebruiksdata voor alle aanspraken onder een contract.

Foutresponses

Alle endpoints retourneren een StatusResponse bij fouten. Zie EDU-V Foutcodes — Usage API (70xx) voor het volledige overzicht van functionele foutcodes.