Delivery API

Titel

Delivery API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.9.1

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:

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

Bevestigings-berichten

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

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

students: een array met referenties naar een eindgebruiker

school-employees

school: referentie naar een onderwijsorganisatie

employees: een array met referenties naar een eindgebruiker

school-activationcodes

school: referentie naar een onderwijsorganisatie

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.