Delivery API
Titel | Delivery API |
Status | In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer |
Versie | Documentatie: 1.0.0 |
schemaVersion: 1.0.0 | |
Datum | 13 maart 2025 |
Auteur | Werkgroep Verwerven en in gebruik nemen |
Acties |
|
De Delivery API wordt gebruikt om informatie over leveringsorders te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst leveringsorders met de Bestelomgeving leermiddelen als Verzender.
De technische specificatie bestaat uit:
Samenvatting
Gegevensdienst | Leveringsorders |
Scopes |
|
Berichten | |
Bevestigings-berichten | |
Objecten |
|
Verzender en Bron |
|
Ontvanger |
|
Afnemer |
|
Endpoints | Bestelomgeving leermiddelen
Aanspraakmanager
|
Bericht: DeliveryOrderRequest
Het DeliveryOrderRequest object wordt door de Bestelomgeving leermiddelen verstuurd naar de Aanspraakmanager. In de object is een requestReferenceId opgenomen die wordt bepaald door de Bestelomgeving leermiddelen. Dit stelt de Bestelomgeving leermiddelen in staat om het bevestigingsbericht van de Aanspraakmanager terug te relateren aan het verstuurde DeliveryOrderRequest bericht.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
deliveryOrder | string | uuid | Referentienummer voor het versturen van de leveringsorder. | eacb81ef-c9d5-4bd8-a624-4088bee04b73 | V | Dit nummer wordt gebruikt door de event mediator om een logboek bij te houden van verzonden en ontvangen meldingen en terugmeldingen met betrekking tot een unieke deliveryOrderId. |
deliveryOrder | object | deliveryOrder | De specificatie van de leveringsorder zoals verworven door een Besteller | Zie object deliveryOrder | V |
|
object DeliveryOrder
Het object deliveryOrder beschrijft de leveringsorder van een bestelling die bij een Bestelomgeving is geplaatst. Hierbij wordt onderscheid gemaakt tussen de School of de Particulier (Individual) als Besteller. In de leveringsorder wordt de relatie gelegd tussen het product, de Besteller en conform de aanspraakvariant de specificatie van de autorisatieregels. Daarnaast heeft iedere leveringsorder een status. De waarden uit een leveringsorder mogen niet gewijzigd worden (ook niet voor foutcorrecties). Indien de leveringsorder niet correct is dan wordt deze geannuleerd en wordt er een nieuwe leveringsorder gestuurd.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
deliveryOrderId | string | uuid | Unieke identifier voor deze leveringsorder | 24e39454-5360-4ba4-819f-03e59b8dd679 | 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. | 2022-12-v1 | O | Waarde mag niet gewijzigd worden. |
buyer | object | Buyer | Een onderwijsorganisatie of particulier die het product heeft verworven. | Zie object Buyer | V | Waarde mag niet gewijzigd worden. Betreft een verwijzing naar een onderwijsorganisatie of een particulier. |
productId | string | string | Referentie naar de Productbeschrijving in de Catalogue API van het leermiddel dat is verworven door Besteller | 871792713 | V | Een leveringsorder verwijst naar exact 1 Product-Beschrijving Waarde mag niet gewijzigd worden |
deliveryType | string | ENUM | De levervariant beschrijft de wijze waarop de aanspraakmanager de aanspraken dient toe te kennen. | V | Waarde mag niet gewijzigd worden. | |
deliverySpecification | object | Delivery | Op basis van de deliveryType worden de autorisatiekenmerken voor toekenning van aanspraken opgenomen in de deliverySpecification | V | deliverySpecification is afhankelijk van de gekozen levervariant. Waarde mag niet gewijzigd worden. | |
portals | array | string | Een lijst met identifiers van Leermiddelenportalen waar de toegangslink voor het product geplaatst moeten worden. |
| O |
|
startDate | string | date | Datum vanaf wanneer het product in gebruik genomen kan worden. Dit is de start van de activatieperiode | 2022-08-01 | V | Waarde mag niet gewijzigd worden |
activationUntilDate | string | date | Datum tot wanneer het product in gebruik genomen kan worden. Hierna is de activatieperiode verlopen | 2023-07-31 | V | Waarde mag niet gewijzigd worden |
endDate | string | date | Datum dat de leveringsorder geannuleerd. | 2022-09-28 | O | De endDate wordt gevuld zodra de status wijzigt naar Cancelled. Waarde mag niet gewijzigd worden |
status | string | ENUM | De status waarin de leveringsorder zich bevindt. |
| V | Status wordt toegekend conform de levenscyclus van de leveringsorder en het bijbehorende proces. |
dateCreated | string | datetime | Datum en tijdstip waarop de entiteit is aangemaakt | 2017-07-21T17:32:28Z | V |
|
dateLastModified | string | datetime | Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd | 2022-08-11T15:31:12Z | V |
|
object: Buyer
Het object Buyer bevat informatie over de Besteller van de leermiddelen. In het Edu-V afsprakenstelsel hanteren we twee bestellers: onderwijsorganisaties en particulieren. Het object wordt dan ook gevuld met een referentie naar een onderwijsorganisatie of een particulier.
De referentie naar een onderwijsorganisatie is uniform gespecificeerd voor alle APIs en terug te vinden op de pagina Technische specificatie digitale identiteiten – referentie onderwijsorganisatie.
De referentie naar een particulier is uitgewerkt in onderstaande tabel.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
displayName | string | string | De naam van de klant die het product heeft verworven bij de Bestelomgeving leermiddelen. | Jan Janssen | O |
|
string | Het mailadres van de klant die het product heeft verworven. | jan@janssen.nl | O |
|
objecten: deliveryType en deliverySpecification
In de leveringsorder is de levervariant opgenomen. Deze levervariant bevat informatie voor de Aanspraakmanager om aanspraken toe te kennen aan eindgebruikers. We hanteren de volgende levervarianten:
Levervariant | Besteller | Autorisatieregel | Type levervariant |
| Onderwijsorganisatie | Alle onderwijsdeelnemers van de school. | Open |
| Onderwijsorganisatie | Alle onderwijsdeelnemers die ingeschreven zijn op een gespecificeerd opleidingsjaar. | Open |
| Onderwijsorganisatie | Alle onderwijsdeelnemers die een gespecificeerd vak volgen. | Open |
| Onderwijsorganisatie | Alle onderwijsdeelnemers die ingeroosterd zijn in een gespecificeerde stamklas of lesgroep. | Open |
| Onderwijsorganisatie | De gespecificeerde onderwijsdeelnemer. | Individueel |
| Onderwijsorganisatie | De gespecificeerde onderwijsmedewerker. | Individueel |
| Onderwijsorganisatie | De eindgebruiker die een gespecificeerde en niet gebruikte activatiecode gebruikt. | Individueel |
| Particulier | De gespecificeerde onderwijsdeelnemer. | Individueel |
| Particulier | De eindgebruiker die een gespecificeerde en niet gebruikte activatiecode gebruikt. | Individueel |
Voor ieder van de levervarianten (deliveryType) geldt een eigen leverspecificatie (deliverySpecification) die opgenomen dient te zijn in de leveringsorder. De velden worden weergegeven in onderstaande tabel.
deliveryType | deliverySpecification |
| |
totalQuantity: aantal producten dat door onderwijsorganisatie is besteld. | |
| |
studyYears: een array met de volgende informatie:
| |
totalQuantity: aantal producten dat door onderwijsorganisatie is besteld. | |
| |
subjects: een array met de volgende informatie:
| |
totalQuantity: aantal producten dat door onderwijsorganisatie is besteld. | |
| |
groups: een array met de volgende informatie:
| |
totalQuantity: aantal producten dat door onderwijsorganisatie is besteld. | |
| |
students: een array met referenties naar een eindgebruiker | |
| |
employees: een array met referenties naar een eindgebruiker | |
| |
activationCodes: een array met activatiecodes. | |
| student: een referentie naar een eindgebruiker |
| activationCode: een activatiecode |
Bevestigingsbericht: DeliveryOrderConfirmation
Een Aanspraakmanager reageert op een DeliveryOrderRequest bericht met een DeliveryOrderConfirmation bevestigingsbericht. In dit bevestigingsbericht wordt de requestReferenceId die door de Bestelomgeving leermiddelen is aangemaakt opgenomen. In aanvulling hierop wordt optioneel de informatie uit de delivery order ook bevestigd. Door een tijdstempel op te nemen kan dit bevestigingsbericht worden gezien als een formele afspraak tussen beide leveranciers.
De Aanspraakmanager verstuurt voor iedere stap die is uitgevoerd een nieuwe DeliveryOrderConfirmation naar de Bestelomgeving leermiddelen. In deze reeks van berichten wijzigt de status van orderen naar entitled naar provisioned naar link-ready en licensed. Indien tussentijds de DeliveryOrder wordt geannuleerd of geblokkeerd dan verandert de status naar respectievelijk cancelled en blocked.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
deliveryOrder | string | uuid | De referentie van de Bestelomgeving leermiddelen waarop dit bevestigingsbericht een antwoord is. | eacb81ef-c9d5-4bd8-a624-4088bee04b73 |