Entitlement API

De Entitlement API faciliteert het delen van informatie over aanspraken (claims) op digitale leermiddelen binnen het Edu-V Afsprakenstelsel. Een aanspraak beschrijft het recht van een gebruiker om een digitaal leermiddel te gebruiken.

Deze API is beschikbaar als v1.0 (aanbevolen) en v1.1.0 (release candidate). Zie de EDU-V documentatie voor v1.0.

Rollen

Dit platform ondersteunt twee rollen in de Entitlement API:

Licentieregistratie (standaard)

Als Licentieregistratie ontvangen wij aanspraken van de Aanspraakmanager (schools-zijde). Wanneer een school een digitaal product bestelt, stuurt de Aanspraakmanager een EntitlementRequest naar ons. Wij bevestigen de aanspraak (status entitled) of weigeren deze.

Scope: eduv.entitlement.licensor

Aanspraakmanager (optioneel, ketenvariant IV/IIb)

Als Aanspraakmanager orchestreren wij de volledige aanspraak-lifecycle. Na ontvangst van een leveringsorder maken wij aanspraken aan, sturen deze door naar de Licentieregistratie (intern bij variant IV, extern bij variant IIb) en het Leermiddelenportaal, en ontvangen activatienotificaties.

Scopes: eduv.entitlement.licensor, eduv.entitlement.portal

Activeer deze rol via Apps & Diensten → Aanspraakmanager in het admin-portaal.

Levenscyclus van een aanspraak

created — Aanspraakmanager maakt de aanspraak aan na een leveringsorder
entitled — Licentieregistratie bevestigt de aanspraak (materiaal klaar voor gebruik)
licensed — Gebruiker heeft het leermiddel geactiveerd
cancelled — Aanspraak is geannuleerd (alleen vóór activering)
blocked — Aanspraak is geblokkeerd (omkeerbaar)

urlStatus (portaalplaatsing)

uninitialized — Nog niet naar portaal gestuurd
initialized — Verstuurd naar Leermiddelenportaal
processed — Portaal heeft de toegangslink geplaatst
cancelled / blocked — Portaalplaatsing opgeheven

Het Entitlement-model

Properties

Name
entitlementId
Type
string (uuid)
Description
Unieke identifier voor de aanspraak, toegekend door de Aanspraakmanager.
Name
productId
Type
string
Description
Product-ID (EAN/ISBN) uit de Catalogue API.
Name
entitlementType
Type
enum
Description
Type: school-student, school-employee, school-activationcode, customer-student, customer-activationcode.
Name
entitlementStatus
Type
enum
Description
Huidige status: created, entitled, licensed, cancelled, blocked.
Name
urlStatuses
Type
array
Description
Array van portaalstatussen: [{ portal, urlStatus }].
Name
school
Type
object
Description
Onderwijsorganisatie waarvoor de aanspraak geldt.
Name
user
Type
object
Description
De gebruiker die recht heeft op het leermiddel.
Name
startDate
Type
date
Description
Startdatum van de activeringsperiode.
Name
activationUntilDate
Type
date
Description
Einddatum voor activering.
Name
expirationDate
Type
date
Description
Vervaldatum van de aanspraak (na activering).
Name
contractId
Type
string
Description
Optionele verwijzing naar een contract.

PUT/edu-v/v1/entitlement-api/entitlements

Aanspraak ontvangen

Als Licentieregistratie: ontvangt een EntitlementRequest van de Aanspraakmanager. De aanspraak wordt gevalideerd, geregistreerd en bevestigd. Retourneert 202 Accepted bij succes.

Vereiste velden

Name
entitlementReferenceId
Type
string (uuid)
Description
Unieke referentie voor deze aanspraak.
Name
entitlementId
Type
string (uuid)
Description
Identifier van de aanspraak.
Name
productId
Type
string
Description
Product-ID (EAN/ISBN).
Name
school
Type
object
Description
Onderwijsorganisatie.
Name
user
Type
object
Description
Gebruiker die de aanspraak ontvangt.

Request

PUT

/edu-v/v1/entitlement-api/entitlements

{
    "entitlementReferenceId": "d4e5f6a7-b8c9-0123-def0-234567890123",
    "entitlementId": "e5f6a7b8-c9d0-1234-ef01-345678901234",
    "productId": "9789464421408",
    "entitlementType": "school-student",
    "entitlementStatus": "created",
    "school": {
        "organisationMasterIdentifier": "16SK"
    },
    "user": {
        "userId": "student-001",
        "userIdType": "nlPersonProfileId"
    },
    "startDate": "2026-09-01",
    "activationUntilDate": "2027-08-31"
}

PUT/edu-v/v1/entitlement-api/entitlements/confirmations

Bevestiging ontvangen

Als Aanspraakmanager: ontvangt een EntitlementConfirmation van de Licentieregistratie of het Leermiddelenportaal. Update de aanspraakstatus op basis van de bevestiging.

Scope: eduv.entitlement.licensor of eduv.entitlement.portal

Velden

Name
entitlementReferenceId
Type
string (uuid)
Description
Referentie-ID uit het oorspronkelijke verzoek.
Name
entitlementReceiveId
Type
string (uuid)
Description
Unieke ID van de ontvanger.
Name
entitlementId
Type
string (uuid)
Description
Identifier van de aanspraak.
Name
newEntitlementStatus
Type
string
Description
Nieuwe status (bijv. entitled, licensed).
Name
newUrlStatus
Type
object
Description
Nieuwe portaalstatus: { portal, urlStatus }.
Name
success
Type
boolean
Description
Of de bevestiging succesvol is.

Request

PUT

/edu-v/v1/entitlement-api/entitlements/confirmations

{
    "entitlementReferenceId": "d4e5f6a7-b8c9-0123-def0-234567890123",
    "entitlementReceiveId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "entitlementId": "e5f6a7b8-c9d0-1234-ef01-345678901234",
    "productId": "9789464421408",
    "newEntitlementStatus": "entitled",
    "processedTimestamp": "2026-09-01T10:30:00Z",
    "success": true,
    "status": 0,
    "statusMessage": "Entitlement confirmed"
}

PUT/edu-v/v1/entitlement-api/change-license-status

Licentiestatus wijzigen

Dit endpoint ontvangt een ChangeLicenseStatus-verzoek van de Aanspraakmanager. Hiermee wordt de status van een bestaande aanspraak gewijzigd (bijv. annulering of blokkering).

Request

PUT

/edu-v/v1/entitlement-api/change-license-status

{
    "entitlementReferenceId": "f6a7b8c9-d0e1-2345-f012-456789012345",
    "entitlementId": "e5f6a7b8-c9d0-1234-ef01-345678901234",
    "status": "cancelled"
}

Foutresponses

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