...
| Open api | ||||||
|---|---|---|---|---|---|---|
| ||||||
openapi: 3.0.0
info:
title: Entitlement API
version: '0.9.1'
description: |
The Entitlement API is implemented by the `Aanspraakmanager`, `Licentieregistratie`, and `Leermiddelenportaal`.
The Entitlement API is used to orchestrate the digital delivery of learning materials to all involved reference components.
The `Aanspraakmanager` is responsible for the consistency and traceability of all transactions.
The Aanspraakmanager is the source of Entitlement information and provides GET endpoints to receive the latest state.
Entitlements are send and received via several asynchronous transactions.
Therefore the consuming reference components `Licentieregistratie`, and `Leermiddelenportaal` need to implement endpoints te receive data.
Moreover the `Aanspraakmanager` needs to implement confirmation endpoints to receive confirmations from the consumer that entitlements have been processed.
After consent by the School, a `Leermiddelendashboard` is able to request information about entitlements from the `Aanspraakmanager`. The `Leermiddelendashboard` uses the GET endpoints provided by the `Aanspraakmanager`.
The `Bestelomgeving leermiddelen` is also able to request information from the `Aanspraakmanager`. This allows the `Bestelomgeving leermiddelen` to provide support to buyers.
contact:
name: Edu-V
url: www.edu-v.org/afsprakenstelsel
email: info@edu-v.org
components:
schemas:
schemaVersion:
type: string
description: |
Schema version of this API using semantic versioning 2.0.0.
The API version number is communicated in the header.
The major version is communicated in the URI.
For more information see the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
default: 0.9.1
EntitlementRequest:
title: EntitlementRequest
type: object
x-tags:
- Entitlement
description: |
A new or updated Entitlement is send from the `Aanspraakmanager` to the `Licentieregistratie`, and `Leermiddelenportaal`.
In some cases the `Licentieregistratie` or `Leermiddelenportaal` will send an EntitlementConfirmation to confirm this message.
The Entitlement is always send as latest status. Many fields cannot be changed after initial "entitled" status. just the state can change or quantity be lowered.
The request should always be processed once, the entitlementReferenceId is unique.
properties:
entitlementReferenceId:
type: string
format: uuid
description: |
Unique entitlementReferenceId for this request.
This referenceId is used by the Event Mediator of the `Aanspraakmanager` to match the EntitlementConfirmation conformation message(s) send by the `Licentieregistratie` and/or the `Leermiddelenportaal`.
If a party receives another request with the same entitlementReferenceId value, the receiving party should not process the request again. It should send the confirmation again.
entitlement:
$ref: '#/components/schemas/Entitlement'
required:
- entitlementReferenceId
- entitlement
EntitlementConfirmation:
title: EntitlementConfirmation
type: object
x-tags:
- Entitlement
description: |
The confirmation that is send back when the `Aanspraakmanager` sends an EntitlementRequest message to the `Licentieregistratie` or the `Leermiddelenportaal`.
The confirmation is not always needed, only in the following situations:
Confirmations by `Licentieregistratie`:
- entitlementStatus is created and send to `Licentieregistratie`: `Licentieregistratie` sends a confirmation with the newEntitlementStatus entitled
- entitlementStatus is cancelled and send to `Licentieregistratie`: `Licentieregistratie` sends a confirmation with the newEntitlementStatus cancelled
- entitlementStatus is blocked and send to `Licentieregistratie`: `Licentieregistratie` sends a confirmation with the newEntitlementStatus blocked
Confirmations by `Leermiddelenportaal`:
- urlStatus is initialized and send to `Leermiddelenportaal`: `Leermiddelenportaal` sends a confirmation with the newUrlStatus processed
- urlStatus is cancelled and send to `Leermiddelenportaal`: `Leermiddelenportaal` sends a confirmation with the newUrlStatus cancelled
- urlStatus is blocked and send to `Leermiddelenportaal`: `Leermiddelenportaal` sends a confirmation with the newUrlStatus blocked
The entitlementReferenceId, entitlementId are echoed back to the `Aanspraakmanager`, with a new entitlementReceiveId.
Requests are only handled once. If a request with a similar entitlementReferenceId is received, the processing is only done the first time.
The confirmation may be send multiple times, but always with the same entitlementReceiveId. In this way the `Aanspraakmanager` can validate that the response is processed only once.
Functional status codes and messages are described in the Documentation.
properties:
entitlementReferenceId:
type: string
description: 'The entitlementReferenceId that was send by the `Aanspraakmanager` as part of the Entitlement request'
entitlementReceiveId:
type: string
description: 'A reference to this confirmation message send by the `Licentieregistratie` or the `Leermiddelenportaal` to the `Aanspraakmanager`.'
entitlementId:
type: string
format: uuid
description: 'The entitlementId which was part of the Entitlement request send by the `Aanspraakmanager`.'
productId:
type: string
description: 'The productId which was part of the Entitlement request send by the `Aanspraakmanager`'
processedTimestamp:
type: string
format: date-time
description: |
The moment that the Entitlement request was processed by the `Licentieregistratie` or the `Leermiddelenportaal` and the change became effective.
As requests and confirmation messages are send asynchronous, this is not the moment the confirmation message was send by the `Licentieregistratie` or the `Leermiddelenportaal` to the `Aanspraakmanager`.
Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6
example: "2017-07-21T17:32:28Z"
newEntitlementStatus:
type: string
enum:
- created
- entitled
- licensed
- cancelled
- blocked
description: |
Confirmation of the proposed status.
Example: as a reply to a created status in an Entitlement request, a `Licentieregistratie` can reply with an entitled status to the `Aanspraakmanager`.
newUrlStatus:
type: object
description: |
Confirmation of the processing of the request.
Example: as a reply to a initialized status in an Entitlement request, the `Leermiddelenportaal` application can reply with a processed status to the `Aanspraakmanager`.
properties:
portal:
type: string
description: 'Identifier of the `Leermiddelenportaal` application.'
urlStatus:
type: string
enum:
- initialized
- processed
- cancelled
- blocked
- expired
success:
type: boolean
description: |
Boolean indicating the Entitlement request was processed successfully.
When the `Licentieregistratie` disagrees with a certain change (i.e. cancelled) a false will be returned, along with a status code and a status message.
status:
type: integer
description: 'See functional status codes within the Documentation.'
statusMessage:
type: string
description: 'See functional status messages within the Documentation.'
required:
- entitlementReferenceId
- entitlementReceiveId
- entitlementId
- deliveryOrderId
- productId
- processedTimestamp
- success
- status
Entitlement:
title: Entitlement
type: object
x-tags:
- Entitlement
description: 'The core object that expresses information about a product that is entitled by the `Aanspraakmanager` to a specified user or a user in possession of a specified activation code.'
properties:
entitlementId:
type: string
format: uuid
example: 24e39454-5360-4ba4-819f-03e59b8dd679
deliveryOrderId:
type: string
format: uuid
description: 'The deliveryOrderId which was part of the DeliveryOrder request send by the `Bestelomgeving leermiddelen` to the `Aanspraakmanager`.'
contractId:
type: string
description: |
An optional unique identifier for a contract between the supplier that is responsible for the `Bestelomgeving leermiddelen` and the supplier of the learning materials.
The DeliveryOrder should be handled according to the business rules of the contract.'
productId:
type: string
description: 'Unique identifier of a Product. The productId can be retrieved from the Catalogue API of supplier of the learning materials.'
startDate:
type: string
format: date
description: |
Date from which the product can be activated by the Entitlee(s). The startDate marks the start of the activation period.
Format: YYYY-MM-DD (according to RFC3339).
example: '2021-08-22'
activationUntilDate:
type: string
format: date
description: |
Date on which the product can no longer be activated by the Entitlee(s).
The activationUntilDate marks the end of the activation period.
This does not imply the product can not be used by Licensees who have activated the product during the activation period.
Format: YYYY-MM-DD (according to RFC3339).
example: '2022-07-31'
expirationDate:
type: string
format: date
description: |
ExpirationDate a `Leermiddelenportaal` can use to maintain access links to the Product in the Learning Material Lists of Students or Employees.
An initially set minExpirationDate is calculated by the `Aanspraakmanager` based on info from the Product retrieved from the Catalogue API.
If the `Aanspraakmanager` receives an InitialActivation message regarding this Entitlement from the `Licentieregistratie` via the Usage API, the expirationDate could be updated.
The InitialActivation message could include an updated expirationDate. In that case this new expirationDate overwrites the initially set minExpirationDate.
This triggers the process within the `Aanspraakmanager` to exchange the updated entitlement with the `Leermiddelenportaal`. The urlStatus is updated to `initialized` and is newly exchanged with the `Leermiddelenportaal`.
Format: YYYY-MM-DD (according to RFC3339).
example: '2022-07-31'
endDate:
type: string
format: date
description: |
Date this Entitlement was blocked or cancelled. Mandatory field when the status changes to Cancelled or Blocked.
Format: YYYY-MM-DD (according to RFC3339).
entitlementType:
type: string
description: |
The entitlement type specifies if a student, employee or a user with an activation code can activate and license the product.
enum:
- school-student
- school-employee
- school-activationcode
- customer-student
- customer-activationcode
entitlementSpecification:
$ref: '#/components/schemas/EntitlementSpecification'
entitlementStatus:
type: string
description: 'The status of the entitlement.'
enum:
- created
- entitled
- licensed
- cancelled
- blocked
default: created
urlStatuses:
type: array
items:
type: object
description: 'The status of the accessUrl at the `Leermiddelenportaal` application.'
properties:
portal:
type: string
description: 'Identifier of the `Leermiddelenportaal` application.'
urlStatus:
type: string
description: 'The status of the accessUrl at the `Leermiddelenportaal` application.'
enum:
- uninitialized
- initialized
- processed
- cancelled
- blocked
default: uninitialized
dateCreated:
type: string
description: 'Indicates the date and time the object was first created. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
format: date-time
example: "2017-07-21T17:32:28Z"
dateLastModified:
type: string
description: 'Indicates the date and time the object was last modified. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
format: date-time
example: "2022-08-11T15:31:12Z"
required:
- entitlementId
- deliveryOrderId
- buyer
- productId
- startDate
- activationUntilDate
- entitlementType
- entitlee
- entitlementStatus
- urlStatus
- dateCreated
- dateLastModified
SchoolReference:
type: object
title: SchoolReference
description: 'A reference to a School organisation.'
properties:
organisationMasterIdentifier:
type: string
description: |
The primary identifier for a School. For Schools the `OnderwijsaanbiederId` is used.
(either organisationMasterIdentifier or organisationIds is required)
example: '104A158' # De Mariënborn
organisationIds:
type: array
description: |
A secondary identifier for the School. This value is used whenever the primary identifier is not available.
(either organisationMasterIdentifier or organisationIds is required)
items:
type: object
properties:
organisationId:
type: string
organisationIdType:
type: string
enum:
- OIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
- VE_CODE # Vestigingserkenningcode e.g. 09QQ00 (Marienbornschool)
- BP_ID # Basispoort gegenereerde identifier voor de school.
- DD_ID # Door de Centrale Registratie van Edu-iX gegenereerde DigiDeliveryId van de school.
- AS_ID # Door het Leerlingadministratiesysteem gegenereerde identifier van de school.
required:
- organisationId
- organisationIdType
CustomerReference:
title: CustomerReference
type: object
x-tags:
- DeliveryOrder
description: 'Information about an B2C Customer who acquired the product.'
properties:
displayName:
type: string
description: 'The name of the Customer.'
email:
type: string
description: 'The email address of the Customer.'
EntitlementSpecification:
title: EntitlementSpecification
x-tags:
- Entitlement
oneOf:
- $ref: '#/components/schemas/EntitlementSchoolStudent'
- $ref: '#/components/schemas/EntitlementSchoolEmployee'
- $ref: '#/components/schemas/EntitlementSchoolActivationCode'
- $ref: '#/components/schemas/EntitlementCustomerStudent'
- $ref: '#/components/schemas/EntitlementCustomerActivationCode'
EntitlementSchoolStudent:
title: EntitleeSchoolStudent
type: object
description: 'The specified student at the school is allowed to activate and license the product.'
x-examples:
example-1:
school: {
organisationMasterIdentifier: '104A158'
}
student: {userMasterIdentifier: 'https://ketenid.nl/201703/1a5c9c7203901866532c2d72ce056e1d29cacc70836fe2bc3a517f3f9a53eed3d77ef370ad6dcf80b3f34ced1c547c7d2e679e8e47002355f938213b3656b206'}
properties:
school:
$ref: '#/components/schemas/SchoolReference'
student:
$ref: '#/components/schemas/UserReference'
required:
- school
- student
EntitlementSchoolEmployee:
title: EntitleeSchoolEmployee
type: object
description: 'The specified employee at the school is allowed to activate and license the product.'
x-examples:
example-1:
school: {
organisationMasterIdentifier: '104A158'
}
employee: {userMasterIdentifier: 'https://ketenid.nl/201703/1a5c9c7203901866532c2d72ce056e1d29cacc70836fe2bc3a517f3f9a53eed3d77ef370ad6dcf80b3f34ced1c547c7d2e679e8e47002355f938213b3656b206'}
properties:
school:
$ref: '#/components/schemas/SchoolReference'
employee:
$ref: '#/components/schemas/UserReference'
required:
- school
- student
EntitlementSchoolActivationCode:
title: EntitleeSchoolActivationCode
type: object
description: 'A user from a school is allowed to activate and license the product using the ActivationCode.'
x-examples:
example-1:
school: {
organisationMasterIdentifier: '104A158'
}
activationCode: 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX'
properties:
school:
$ref: '#/components/schemas/SchoolReference'
activationCode:
type: string
description: 'The activation codes, the school can use to activate and license the product. Activation codes can be requested from the `Licentieregistratie`'
example: 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXY'
required:
- school
- activationCode
EntitlementCustomerStudent:
title: EntitleeCustomerStudent
type: object
description: 'The specified student is allowed to activate and license the product.'
x-examples:
example-1:
student: {userMasterIdentifier: 'https://ketenid.nl/201703/1a5c9c7203901866532c2d72ce056e1d29cacc70836fe2bc3a517f3f9a53eed3d77ef370ad6dcf80b3f34ced1c547c7d2e679e8e47002355f938213b3656b206'}
properties:
student:
$ref: '#/components/schemas/UserReference'
required:
- student
EntitlementCustomerActivationCode:
title: EntitleeCustomerActivationCode
type: object
description: 'A user is allowed to activate and license the product using the ActivationCode.'
x-examples:
example-1:
activationCode: 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX'
properties:
activationCode:
type: string
description: 'The activation codes, the school can use to activate and license the product. Activation codes can be requested from the `Licentieregistratie`'
example: 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXY'
required:
- activationCode
UserReference:
type: object
title: UserReference
properties:
userMasterIdentifier:
type: string
description: |
The primary identifier for a User.
For Students the ECK iD is used.
For Employees this value is empty. There is no primary identifier for Employees.
(either userMasterIdentifier or userIds is required)
userIds:
type: array
description: |
A secondary identifier for a User. This value is used whenever the primary identifier is not available.
For Employees this value is mandatory.
(either userMasterIdentifier or userIds is required)
items:
type: object
properties:
userId:
type: string
userIdType:
type: string
enum:
- NEPPI # nlPersonProfileId – value can be used for students and employees
- BPI # Basispoort ID – value can be used for students and employees
- eduID # eduID identifier – value can be used for students and employees
- NEPRI # nlPersonRealId – value can be used for students only
- ASI # Las-key – value can be used for students only
- eckId # ECK iD – value can be used for employees only, eckId is userIdType for userMasterIdentifier for students
required:
- userId
- userIdType
StatusResponse:
title: StatusResponse
type: object
description: 'Functional status code and status message.'
properties:
status:
type: integer
description: 'See functional status codes within the Documentation.'
statusMessage:
type: string
description: 'See functional status messages within the Documentation.'
required:
- status
DeliveryOrderEntitlements:
title: DeliveryOrderEntitlements
type: object
x-tags:
- Entitlement
description: |
This object reports all Entitlement information for a single DeliveryOrder.
properties:
deliveryOrderId:
type: string
format: uuid
description: 'The deliveryOrderId which was part of the DeliveryOrder request send by the `Bestelomgeving leermiddelen` to the `Aanspraakmanager`.'
contractId:
type: string
description: 'An optional unique identifier for a contract between the supplier that is responsible for the `Bestelomgeving leermiddelen` and the supplier of the learning materials.'
totalQuantity:
type: integer
description: |
Total quantity as specified in the DeliveryOrder received from the `Bestelomgeving leermiddelen`.
totalCreated:
type: integer
description: 'Total number of entitlements that are created.'
totalEntitled:
type: integer
description: 'Total number of entitlements that are entitled to users.'
totalLicensed:
type: integer
description: 'Total number of entitlements that are licensed to users.'
totalCancelled:
type: integer
description: 'Total number of entitlements that are cancelled for users.'
totalBlocked:
type: integer
description: 'Total number of entitlements that are blocked for users.'
entitlements:
type: array
description: 'An array of all entitlements for this deliveryOrder.'
items:
$ref: '#/components/schemas/Entitlement'
required:
- deliveryOrderId
- entitlements
EntitlementProduct:
title: EntitlementProduct
type: object
x-tags:
- Entitlement
description: |
This object describes the Product information a `Leermiddelenportaal` can use to display accessUrls to a User.
properties:
entitlementId:
type: string
format: uuid
example: 24e39454-5360-4ba4-819f-03e59b8dd679
productId:
type: string
description: 'Unique identifier of a Product. The productId can be retrieved from the Catalogue API of supplier of the learning materials.'
entitlementStatus:
type: string
description: 'The status of the entitlement.'
enum:
- created
- entitled
- licensed
- cancelled
- blocked
startDate:
type: string
format: date
description: |
Date from which the product can be activated by the Entitlee(s). The startDate marks the start of the activation period.
Format: YYYY-MM-DD (according to RFC3339).
example: '2021-08-22'
activationUntilDate:
type: string
format: date
description: |
Date on which the product can no longer be activated by the Entitlee(s).
The activationUntilDate marks the end of the activation period.
This does not imply the product can not be used by Licensees who have activated the product during the activation period.
Format: YYYY-MM-DD (according to RFC3339).
example: '2022-07-31'
expirationDate:
type: string
format: date
description: |
ExpirationDate a `Leermiddelenportaal` can use to maintain access links to the Product in the Learning Material Lists of Students or Employees.
An initially set minExpirationDate is calculated by the `Aanspraakmanager` based on info from the Product retrieved from the Catalogue API.
If the `Aanspraakmanager` receives an InitialActivation message regarding this Entitlement from the `Licentieregistratie` via the Usage API, the expirationDate could be updated.
The InitialActivation message could include an updated expirationDate. In that case this new expirationDate overwrites the initially set minExpirationDate.
This triggers the process within the `Aanspraakmanager` to exchange the updated entitlement with the `Leermiddelenportaal`. The urlStatus is updated to `initialized` and is newly exchanged with the `Leermiddelenportaal`.
Format: YYYY-MM-DD (according to RFC3339).
example: '2022-07-31'
required:
- entitlementId
- productId
- entitlementStatus
- startDate
- activationUntilDate
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.example.com/oauth2/token
refreshUrl: https://api.example.com/oauth2/token
scopes:
eduv.entitlement.seller: 'scope that allows a `Bestelomgeving leermiddelen` to request entitlement information.'
eduv.entitlement.licensor: 'scope needed to send and receive Entitlement requests and Confirmation messages to the `Licentieregistratie` and to request entitlement information as a `Licentieregistratie.'
eduv.entitlement.portal: 'scope needed to send and receive Entitlement requests and Confirmation messages to the `Leermiddelenportaal` and to request entitlement information as a `Leermiddelenportaal`. to display accessUrls.'
eduv.entitlement.dashboard: 'scope that allows a `Leermiddelendashboard` to request entitlement information.'
description: ''
paths:
# GET endpoint for support processes of all parties involved, therefore applicable to all reference components.
/entitlements/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
description: 'Specific entitlementId of an Entitlement.'
get:
summary: Get Entitlement
operationId: get-entitlement
tags:
- Aanspraakmanager
x-tags:
- Entitlement
description: |
Retrieve an entitlement by ID from a `Aanspraakmanager`.
The `Aanspraakmanager` is the provider of this endpoint.
The `Licentieregistratie` and `Leermiddelenportaal` should give a 405 HTTP status as result when called.
This endpoint can be used by the `Bestelomgeving leermiddelen`, `Licentieregistratie`, and `Leermiddelenportaal` for support processes.
Consent is required for exchange of entitlement information from the 'Aanspraakmanager' to the `Leermiddelenportaal` and the `Leermiddelendashboard`.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Entitlement'
'400':
description: Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'405':
description: Method not allowed - Aanspraakmanager is provider of this endpoint
security:
- OAuth2:
- eduv.entitlement.seller
- eduv.entitlement.licensor
- eduv.entitlement.portal
- eduv.entitlement.dashboard
/entitlements/deliveryorder/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
description: 'The deliveryOrderId for which entitlement information is requested.'
get:
summary: Get Entitlements by DeliveryOrder
operationId: get-entitlements-by-delivery-order
tags:
- Aanspraakmanager
x-tags:
- Entitlement
- DeliveryOrder
description: |
Retrieve all entitlements for a deliveryOrder from a `Aanspraakmanager`.
The `Aanspraakmanager` is the provider of this endpoint.
The `Licentieregistratie` and `Leermiddelenportaal` should give a 405 HTTP status as result when called.
Consent is required for exchange of entitlement information from the 'Aanspraakmanager' to the `Leermiddelenportaal` and the `Leermiddelendashboard`.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Entitlement'
'400':
description: Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'405':
description: Method not allowed - Aanspraakmanager is provider of this endpoint
security:
- OAuth2:
- eduv.entitlement.seller
- eduv.entitlement.licensor
- eduv.entitlement.portal
- eduv.entitlement.dashboard
# GET endpoints for `Leermiddelendashboard` and `Leermiddelenportaal`
/entitlements/school:
parameters:
- schema:
type: string
name: orgMasterId
in: query
required: false
description: |
The organisationMasterIdentifier of the school.
This parameter is used when the primary identifier for a school (being the `OnderwijsaanbiederId`) is available.
- schema:
type: string
name: orgId
in: query
required: false
description: |
The organisationIdentifier (secondary identifier) of the school.
This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.
- schema:
type: string
example: DD_ID
enum:
- OIE_CODE
- VE_CODE
- BP_ID
- DD_ID
- AS_ID
name: orgIdType
in: query
required: false
description: |
The type of the organisationIdentifier.
This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.
- schema:
type: string
name: deliveryOrderId
in: query
description: 'Filter by deliveryOrderId'
- schema:
type: string
example: entitled
enum:
- created
- entitled
- licensed
- cancelled
- blocked
name: entitlementStatus
in: query
description: 'Filter by entitlementStatus'
get:
summary: Get Entitlements for School
operationId: get-entitlements-for-school
tags:
- Aanspraakmanager
x-tags:
- Entitlement
- DeliveryOrder
description: |
Retrieve all entitlements for a specific school from a `Aanspraakmanager`.
The `Aanspraakmanager` is the provider of this endpoint.
The `Licentieregistratie` and `Leermiddelenportaal` should give a 405 HTTP status as result when called.
Consent is required for exchange of entitlement information from the 'Aanspraakmanager' to the `Leermiddelenportaal` and the `Leermiddelendashboard`.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Entitlement'
'400':
description: Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'405':
description: Method not allowed - Aanspraakmanager is provider of this endpoint
security:
- OAuth2:
- eduv.entitlement.dashboard
- eduv.entitlement.portal
/entitlements/school/user:
parameters:
- schema:
type: string
example: entitled
enum:
- created
- entitled
- licensed
- cancelled
- blocked
name: status
in: query
description: 'Filter by status'
post:
summary: Get Entitlements for User at School
operationId: get-entitlements-for-user-at-school
tags:
- Aanspraakmanager
x-tags:
- Entitlement
description: |
Retrieve all entitlements for a user at a school from an `Aanspraakmanager`
The `Aanspraakmanager` is the provider of this endpoint.
The `Licentieregistratie` and `Leermiddelenportaal` should give a 405 HTTP status as result when called.
Consent is required for exchange of entitlement information from the 'Aanspraakmanager' to the `Leermiddelenportaal` and the `Leermiddelendashboard`.
Due to the confidentiality of the eckId and userIds this endpoint has been implemented as a POST endpoint where the confidential information is securely send within the request body.
requestBody:
content:
application/json:
schema:
type: object
properties:
school:
$ref: '#/components/schemas/SchoolReference'
user:
$ref: '#/components/schemas/UserReference'
required:
- school
- user
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Entitlement'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'405':
description: Method not allowed - Aanspraakmanager is provider of this endpoint
security:
- OAuth2:
- eduv.entitlement.dashboard
- eduv.entitlement.portal
# GET endpoint for `Leermiddelenportaal`
/entitlements/school/user/products:
parameters:
- schema:
type: string
example: entitled
enum:
- created
- entitled
- licensed
- cancelled
- blocked
name: status
in: query
description: 'Filter by status'
post:
summary: Get Entitlementproducts for User at School
operationId: get-entitlementproducts-for-user-at-school
tags:
- Aanspraakmanager
x-tags:
- Entitlement
description: |
Retrieve a subset of product information of entitlements for a user at a school from an `Aanspraakmanager`
The `Aanspraakmanager` is the provider of this endpoint. The `Leermiddelenportaal` is the targeted consumer of this endpoint.
In practice only entitlement with the entitlementStatus entitled and licensed are requested.
The `Licentieregistratie` and `Leermiddelenportaal` should give a 405 HTTP status as result when called.
Consent is required for exchange of entitlement information from the 'Aanspraakmanager' to the `Leermiddelenportaal` and the `Leermiddelendashboard`.
Due to the confidentiality of the eckId and userIds this endpoint has been implemented as a POST endpoint where the confidential information is securely send within the request body.
requestBody:
content:
application/json:
schema:
type: object
properties:
school:
$ref: '#/components/schemas/SchoolReference'
user:
$ref: '#/components/schemas/UserReference'
required:
- school
- user
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EntitlementProduct'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'405':
description: Method not allowed - Aanspraakmanager is provider of this endpoint
security:
- OAuth2:
- eduv.entitlement.dashboard
- eduv.entitlement.portal
# GET endpoints for `Bestelomgeving leermiddelen` en `Licentieregistratie`
/entitlements/contracts/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
description: 'The contractId for which entitlement information is requested.'
get:
summary: Get Entitlements by Contract
operationId: get-entitlements-by-contract
tags:
- Aanspraakmanager
x-tags:
- Entitlement
- DeliveryOrder
description: |
Retrieve all entitlements for a specific contract grouped by deliveryOrder from a `Aanspraakmanager`.
The `Aanspraakmanager` is the provider of this endpoint.
The `Licentieregistratie` and `Leermiddelenportaal` should give a 405 HTTP status as result when called.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DeliveryOrderEntitlements'
'400':
description: Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'405':
description: Method not allowed - Aanspraakmanager is provider of this endpoint
security:
- OAuth2:
- eduv.entitlement.seller
- eduv.entitlement.licensor
# PUT endpoints for asynchronous processing of entitlements by `Licentieregistratie` and `Leermiddelenportaal`
/entitlements:
put:
summary: Accept Entitlement from Aanspraakmanager
operationId: accept-entitlement
tags:
- Licentieregistratie
- Leermiddelenportaal
x-tags:
- Entitlement
description: |
As a `Aanspraakmanager`, send a new Entitlement to a `Licentieregistratie` or `Leermiddelenportaal`.
The `Licentieregistratie` and 'Leermiddelenportaal' are the providers of this endpoint.
The `Aanspraakmanager` should give a 405 HTTP status as result when called.
Consent is required for exchange of entitlement information from the 'Aanspraakmanager' to the `Leermiddelenportaal`.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementRequest'
responses:
'202':
description: Accepted
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'405':
description: Method Not Allowed - Licentieregistratie and Leermiddelenportaal are providers of this endpoint
security:
- OAuth2:
- eduv.entitlement.licensor
- eduv.entitlement.portal
/entitlements/confirmations:
put:
summary: Confirm Entitlement to Aanspraakmanager
operationId: confirm-entitlement
tags:
- Aanspraakmanager
x-tags:
- Entitlement
description: |
As a `Licentieregistratie` or `Leermiddelenportaal` confirm an Entitlement to the `Aanspraakmanager`.
The `Aanspraakmanager` is the provider of this endpoint.
The `Licentieregistratie` and `Leermiddelenportaal` should give a 405 HTTP status as result when called.
Consent is required for exchange of entitlement information from the 'Aanspraakmanager' to the `Leermiddelenportaal`.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementConfirmation'
responses:
'202':
description: Accepted
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'405':
description: Method Not Allowed - Aanspraakmanager is provider of this endpoint
security:
- OAuth2:
- eduv.entitlement.licensor
- eduv.entitlement.portal
x-tags:
- name: Entitlement
- name: DeliveryOrder |
...
0.0.1: Eerste draft van de API.
0.0.2: Objecten en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.
0.0.3: De technische specificatie is verder uitgewerkt. Ook is de feedback uit de werkgroepen verwerkt in een volgende versie:
Endpoint toegevoegd waarin entitlements voor een onderwijsdeelnemer of onderwijsmedewerker opgevraagd kunnen worden.
Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van het regie op gegevens en de M2M identificatie en authenticatie.
Het transactiepatroon georkestreerde uitwisseling met een opeenvolging van asynchrone uitwisselingen is toegepast op de Entitlement API. Dit heeft geresulteerd in PUT endpoints voor de meldingen en de terugmeldingen (confirmations) voor de relevante referentiecomponenten.
BasispoortIDs zijn toegevoegd als opties voor Onderwijsdeelnemer, Onderwijsmedewerker en School.
In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.
0.0.4: De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.
0.0.5: Objecten geactualiseerd op basis van herziening rollen en referentiecomponenten in het architectuurkader. Objecten ChangeLicenseStatus en ChangeLicenseStatusConfirmation toegevoegd.
0.0.6: YAML file aangepast. Endpoints voor activatiecode verwijderd en verplaatst naar de ActivationCode API.
0.0.7: Typo’s verwijderd uit de YAML file.
0.0.8: De objecten en koppelvlakspecificatie inclusief de YAML zijn aangepast naar het nieuwe conceptueel model. Dit heeft geleid tot de volgende wijzigingen:
Aanspraken zijn van toepassing voor een enkele eindgebruiker. De voorheen open aanspraakvarianten zijn verplaatst naar de leveringsorders in de Delivery API
Aanspraken zijn er nog steeds in typen. De typen variëren vanuit de beoogde gebruiker: onderwijsdeelnemer, onderwijsmedewerker en een eindgebruiker met een activatiecode. Daarnaast zijn er aanspraken die toebehoren aan een onderwijsorganisatie.
De statusinformatie van aanspraken is gewijzigd. Dit heeft geleid tot de status van een aanspraak en de status van de plaatsing van de links in het leermiddelenportaal.
Er zijn GET endpoints toegevoegd voor het Leermiddelendashboard
Er zijn GET endpoints toegevoegd voor het Leermiddelenportaal om aanspraken en producten uit aanspraken op te vragen voor een specifieke eindgebruiker.
Er zijn GET endpoints toegevoegd voor de Bestelomgeving leermiddelen en de Licentieregistratie om aanspraken op basis van een leveringsorderId en contractId op te vragen.
Het transactiepatroon voor het Leermiddelendashboard is gewijzigd naar een Bevraging. Het Leermiddelendashboard ontvang geen meldingen meer vanuit de Aanspraakmanager en speelt geen rol meer in de georkestreerde uitwisseling.
De scopes zijn aangepast met een specifieke scope voor de gegevensafnemende referentiecomponenten: Bestelomgeving leermiddelen, Licentieregistratie, Leermiddelendashboard en Leermiddelenportaal.
0.0.9: Er zijn wijzigingen verwerkt:
Wijzigen in de architectuur:
Attribuut schemaVersion is verwijderd uit de objecten.
Query parameter schemaVersion is verwijderd uit de koppelvlakken.
Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.
Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.
Primaire en secundaire identifiers voor onderwijsaanbieders en eindgebruikers bijgewerkt.
Feedback vanuit de werkgroep Verwerven en in gebruik nemen:
Attribuut urlStatus is vervangen door urlStatusses met een verwijzing naar de urlStatus per Portaal.
Endpoint entitlementproducts/school/user is hernoemd naar entitlements/school/user/products
0.0.10: / achter endpoints verwijderd.
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.De parameters voor paginering zijn uit de koppelvlakspecificatie verwijderd. Binnen het afsprakenstelsel zijn de afspraken hierover beschreven op de pagina paginering, sorteren en rate limiting.
De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.