Delivery API

Titel	Delivery API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	Documentatie: 0.9.1
Versie	schemaVersion: 0.9.1
Datum	27 September 2024
Auteur	Werkgroep Verwerven en in gebruik nemen
Acties	Geen openstaande 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:

1 Samenvatting
2 Bericht: DeliveryOrderRequest
3 Bevestigingsbericht: DeliveryOrderConfirmation
4 Event mediator: Bestelomgeving leermiddelen
5 Event processor: Aanspraakmanager
6 Status- en foutcodes
7 Technisch: API specificatie
8 Release notes

Samenvatting

Gegevensdienst	Leveringsorders
Scopes	eduv.delivery.entitlor (voor Aanspraakmanager) eduv.delivery.licensor (voor Licentieregistratie) eduv.delivery.portal (voor Leermiddelenportaal) eduv.delivery.dashboard (voor Leermiddelendashboard)
Berichten	DeliveryOrderRequest
Bevestigings-berichten	DeliveryOrderConfirmation
Objecten	DeliveryOrder
Verzender en Bron	Bestelomgeving leermiddelen
Ontvanger	Aanspraakmanager
Afnemer	Leermiddelendashboard Leermiddelenportaal Licentieregistratie
Endpoints	Bestelomgeving leermiddelen GET DeliveryOrder GET DeliveryOrders for School POST Get DeliveryOrders for User at School GET DeliveryOrders for Contract PUT Confirm DeliveryOrder to Bestelomgeving leermiddelen Aanspraakmanager PUT Accept DeliveryOrder from Bestelomgeving leermiddelen

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 ReferenceId	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 0834	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.	Zie deliveryType en deliverySpecification	V	Waarde mag niet gewijzigd worden.
deliverySpecification	object	Delivery Specification	Op basis van de deliveryType worden de autorisatiekenmerken voor toekenning van aanspraken opgenomen in de deliverySpecification	Zie deliveryType en 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.	`ordered` `processed` `licensed` `cancelled`	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
email	string	email	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
`school-all`	Onderwijsorganisatie	Alle onderwijsdeelnemers van de school.	Open
`school-studies`	Onderwijsorganisatie	Alle onderwijsdeelnemers die ingeschreven zijn op een gespecificeerd opleidingsjaar.	Open
`school-subjects`	Onderwijsorganisatie	Alle onderwijsdeelnemers die een gespecificeerd vak volgen.	Open
`school-groups`	Onderwijsorganisatie	Alle onderwijsdeelnemers die ingeroosterd zijn in een gespecificeerde stamklas of lesgroep.	Open
`school-students`	Onderwijsorganisatie	De gespecificeerde onderwijsdeelnemer.	Individueel
`school-employees`	Onderwijsorganisatie	De gespecificeerde onderwijsmedewerker.	Individueel
`school-activationcodes`	Onderwijsorganisatie	De eindgebruiker die een gespecificeerde en niet gebruikte activatiecode gebruikt.	Individueel
`customer-student`	Particulier	De gespecificeerde onderwijsdeelnemer.	Individueel
`customer-activationcode`	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
`school-all`	school: referentie naar een onderwijsorganisatie
`school-all`	totalQuantity: aantal producten dat door onderwijsorganisatie is besteld.
`school-studies`	school: referentie naar een onderwijsorganisatie
	studyYears: een array met de volgende informatie: studyYearId: een referentie naar een opleidingsjaar. quantity: optioneel het aantal te leveren producten voor het opleidingsjaar.
	totalQuantity: aantal producten dat door onderwijsorganisatie is besteld.
`school-subjects`	school: referentie naar een onderwijsorganisatie
	subjects: een array met de volgende informatie: subjectId: een referentie naar een vak. quantity: optioneel het aantal te leveren producten voor het vak.
	totalQuantity: aantal producten dat door onderwijsorganisatie is besteld.
`school-groups`	school: referentie naar een onderwijsorganisatie
	groups: een array met de volgende informatie: groupId: een referentie naar een stamklas of lesgroep. quantity: optioneel het aantal te leveren producten voor de groep.
	totalQuantity: aantal producten dat door onderwijsorganisatie is besteld.
`school-students`	school: referentie naar een onderwijsorganisatie
`school-students`	students: een array met referenties naar een eindgebruiker
`school-employees`	school: referentie naar een onderwijsorganisatie
`school-employees`	employees: een array met referenties naar een eindgebruiker
`school-activationcodes`	school: referentie naar een onderwijsorganisatie
`school-activationcodes`	activationCodes: een array met activatiecodes.
`customer-student`	student: een referentie naar een eindgebruiker
`customer-activationcode`	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 ReferenceId	string	uuid	De referentie van de Bestelomgeving leermiddelen waarop dit bevestigingsbericht een antwoord is.	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V
deliveryOrder ReceiveId	string	uuid	De referentie van de Aanspraakmanager voor dit bevestigingsbericht	3437e98f-855d-4f29-9092-7ba311228920	V
deliveryOrderId	string	uuid	Verwijzing naar de unieke identifier voor de leveringsorder	24e39454-5360-4ba4-819f-03e59b8dd679	V
productId	string	string	Verwijzing naar de unieke identifier voor het product	871792713 0834	V
processed Timestamp	string	datetime	Tijdstip waarop het leveringsorder verzoek is verwerkt door de Aanspraakmanager	2017-07-21T17:32:28Z	V
newStatus	string	ENUM	De nieuwe status van de leveringsorder	`ordered` `processed` `licensed` `cancelled`	V	De status wordt gekozen afhankelijk van de stap in het leverproces.
newTotalQuantity	integer	integer	De nieuwe waarde voor quantity wordt door de Aanspraakmanager geconformeerd aan de Bestelomgeving leermiddelen, indien deze in het bericht gewijzigd was.	90	O	Deze waarde wordt door de Aanspraakmanager gevuld indien de waarde van de leveringsorder is gewijzigd door de Bestelomgeving leermiddelen.
success	boolean	boolean	Indicatie of de Aanspraakmanager het (wijzigings)bericht heeft kunnen verwerken	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

Event mediator: Bestelomgeving leermiddelen

De Event mediator van de Delivery API van de Bestelomgeving leermiddelen hanteert asynchrone uitwisselingen bij het verzenden van DeliveryOrders naar de Aanspraakmanager en het ontvangen van DeliveryOrderConfirmations bevestigingsberichten vanuit de Aanspraakmanager. In onderstaande tabel wordt aangeven op welke wijze deze Asynchrone uitwisseling ingericht kan worden.

Proces	Trigger	Actie	Output	Registratie
Leveren van digitaal leermiddel	Digitale leermiddelen uit bestelling in Bestelomgeving leermiddelen dient geleverd te worden.	Genereren DeliveryOrders met status `ordered` voor de producten uit de Bestelling.	Versturen DeliveryOrder in DeliveryOrderRequest bericht naar Aanspraakmanager	deliveryOrderRequest bericht deliveryOrderReferenceId voor status `ordered`
	DeliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager newStatus `processed`	Wijzigen status DeliveryOrder naar `processed`		deliveryOrderReceiveId van Aanspraakmanager EntitlementConfirmation bevestigingsbericht van Aanspraakmanager
	DeliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager met foutcode	Notificeren support van Bestelomgeving leermiddelen	Versturen Supportbericht inclusief foutcode	deliveryOrderReceiveId van Aanspraakmanager deliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager
Annuleren levering van digitaal leermiddel	Annulering van een levering van digitale leermiddelen uit een bestelling Er is gecontroleerd door de Bestelomgeving leermiddelen dat de status `processed` is en dus nog niet `licensed` Een deliveryOrder die `licensed` is kan niet meer geannuleerd worden	Wjizigen status DeliveryOrder naar `cancelled` voor te versturen bericht naar Aanspraakmanager	Versturen DeliveryOrderRequest bericht met gewijzigde DeliveryOrder naar Aanspraakmanager	deliveryOrderRequest bericht deliveryOrderReferenceId voor status `cancelled`
	DeliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager newStatus `processed`	Definitief wijzigen status DeliveryOrder naar `cancelled`		deliveryOrderReceiveId van Aanspraakmanager deliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager
	DeliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager met foutcode	Notificeren support van Bestelomgeving leermiddelen	Versturen Supportbericht inclusief foutcode	deliveryOrderReceiveId van Aanspraakmanager deliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager
Wijzigen aantal te leveren digitale leermiddelen	Wijziging van het aantal op een bestelling van digitale leermiddelen met een open leveringsvariant. `newQuantity` is gecontroleerd en is lager dan huidige quantity en hoger dan aantal entitlements met status entitled en licensed die geregistreerd zijn op de DeliveryOrder.	Wijzigen waarde op `totalQuantity` van een DeliveryOrder voor te versturen bericht naar Aanspraakmanager.	Versturen DeliveryOrderRequest bericht met gewijzigde waarde op `totalQuantity` naar Aanspraakmanager	deliveryOrderRequest bericht deliveryOrderReferenceId voor newDeliveryOrderTotalQuantity
	DeliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager met nieuwe waarde voor `newTotalQuantity`	Definitief wijzigen waarde `totalQuantity` voor de DeliveryOrder		deliveryOrderReceiveId van Aanspraakmanager deliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager
	DeliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager met foutcode	Notificeren support van Bestelomgeving leermiddelen	Versturen Supportbericht inclusief foutcode	deliveryOrderReceiveId van Aanspraakmanager deliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager
In gebruik nemen digitaal leermiddel	DeliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager newStatus `licensed`	Definitief wijzigen status DeliveryOrder naar `licensed`		deliveryOrderReceiveId van Aanspraakmanager deliveryOrderConfirmation bevestigingsbericht van Aanspraakmanager

Event processor: Aanspraakmanager

De Event processor van de Delivery API van de Aanspraakmanager reageert op meldingen ontvangen van de Bestelomgeving leermiddelen door het asynchroon verwerken van verzoeken en het terugmelden van het verwerkingsresultaat. In onderstaande tabel wordt aangeven op welke wijze deze Asynchrone uitwisseling ingericht kan worden.

Proces	Trigger	Actie	Output	Registratie
Leveren van digitaal leermiddel	DeliveryOrder in DeliveryOrderRequest bericht met status `ordered`	Verwerken van DeliveryOrder conform deliveryType en deliverySpecification Genereren DeliveryOrderConfirmation bevestigingsbericht met newStatus `processed`	Versturen DeliveryOrder Confirmation bevestigingsbericht naar Bestelomgeving leermiddelen met newStatus `processed` of indien verwerking niet succesvol met foutcode	DeliveryOrderRequest bericht van Bestelomgeving leermiddelen deliveryOrderReferenceId voor status `ordered` DeliveryOrderConfirmation bevestigingsbericht entitlementReceiveId voor newStatus `processed` \| foutcode
Annuleren levering van digitaal leermiddel	DeliveryOrder in DeliveryOrderRequest bericht met status `cancelled`	Verwerken van annulering van DeliveryOrder Genereren DeliveryOrderConfirmation bevestigingsbericht met newStatus `cancelled`	Versturen DeliveryOrderConfirmation bevestigingsbericht naar Bestelomgeving leermiddelen met newStatus `cancelled` of indien verwerking niet succesvol met foutcode	DeliveryOrderRequest bericht van Aanspraakmanager deliveryOrderReferenceId voor status `cancelled` DeliveryOrderConfirmation bevestigingsbericht deliveryOrderReceiveId voor newStatus `cancelled` \| foutcode
Wijzigen aantal te leveren digitale leermiddelen	DeliveryOrder in DeliveryOrderRequest bericht met nieuwe waarde voor `totalQuantity`	Verwerken van gewijzigde `totalQuantity` van DeliveryOrder Genereren DeliveryOrderConfirmation bevestigingsbericht met nieuwe waarde voor `newTotalQuantity`	Versturen DeliveryOrderConfirmation bevestigingsbericht naar Aanspraakmanager met `newTotalQuantity` of indien verwerking niet succesvol met foutcode	DeliveryOrderRequest bericht van Aanspraakmanager DeliveryOrderReferenceId voor `newTotalQuantity` DeliveryOrderConfirmation bevestigingsbericht deliveryOrderReceiveId voor newTotalQuantity `newTotalQuantity` \| foutcode

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 overgenomen en Delivery API YAML uitgewerkt.
0.0.2: Objecten en koppelvlakspecificatie bijgewerkt op basis van nieuwe versie conceptueel model.
- Leveringsorders bevatten een levervariant (deliveryType) en de voor de variant van toepassing zijnde specificatie (deliverySpecification).
- Levervarianten kunnen open of individueel zijn en gebaseerd zijn op een onderwijsorganisatie of particulier als besteller.
- Leveringsorders bevatten informatie over de besteller.
- Non-happy flows zijn het annuleren van een levering van een digitaal leermiddel en het wijzigen van het aantal op een leveringsorder met een open leveringsvariant.
- Er zijn GET endpoints toegevoegd voor het Leermiddelendashboard
- Er zijn GET endpoints toegevoegd voor het Leermiddelenportaal om leveringsorders op te vragen voor een specifieke school.
- Er zijn GET endpoints toegevoegd voor de Aanspraakmanager en de Licentieregistratie om leveringsorders op basis van een contractId op te vragen.
- De scopes zijn aangepast met een specifieke scope voor de gegevensafnemende referentiecomponenten: Aanspraakmanager, Licentieregistratie, Leermiddelendashboard en Leermiddelenportaal.
0.0.3: YAML file bijgewerkt op basis van nieuwe versie objecten en koppelvlakspecificatie.
0.0.4: 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 portals is toegevoegd aan een deliveryOrder.
0.0.5: Typo’s in de YAML.
0.0.6: / achter endpoints weggehaald
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.