Release candidate Order API

Titel	Order API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	Documentatie: 0.9.4
Versie	schemaVersion: 0.9.4
Datum	3 november 2025
Auteur	Werkgroep Verwerven en in gebruik nemen
Acties	Geen openstaande acties

De Order API wordt gebruikt om informatie over leermiddelorders te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst leermiddelorders met de Bestelomgeving leermiddelen als Verzender.

De technische specificatie bestaat uit:

1 Samenvatting
2 Bericht: OrderRequest
- 2.1 Object: OrderLines
- 2.2 Object Address
- 2.3 Object: Schoolbuyer
3 Bevestigingsbericht: OrderConfirmation
- 3.1 Object: OrderConfirmationLine
4 Bericht: CreditOrderRequest
5 Object: CreditOrderLine
6 Bevestigingsbericht: CreditOrderConfirmation
- 6.1 Object: CreditOrderConfirmationLine
7 Status- en foutcodes
8 Technisch: API specificatie
9 Release notes

Samenvatting

Gegevensdienst	Leermiddelorders
Scopes	eduv.order
Berichten	OrderRequest CreditOrderRequest
Bevestigings-berichten	OrderConfirmation CreditOrderConfirmation
Verzender	Bestelomgeving leermiddelen
Ontvanger	Ordersysteem leermiddelen
Endpoints	Ordersysteem leermiddelen PUT Accept order request PUT Accept credit order request Bestelomgeving leermiddelen PUT Confirm order request PUT Confirom credit order request

Bericht: OrderRequest

Het OrderRequest bericht wordt door de Bestelomgeving leermiddelen van een leermiddelenverkoper verstuurd naar het Ordersysteem leermiddelen van een leermiddelenaanbieder. In de berichtspecificatie is een requestReferenceId opgenomen die wordt bepaald door de Bestelomgeving leermiddelen. Dit stelt de Bestelomgeving leermiddelen in staat om het bevestigingsbericht van het Ordersysteem leermiddelen terug te relateren aan het verstuurde OrderRequest bericht.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
request ReferenceId	string	uuid	Referentienummer voor het versturen van de order	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V	Dit nummer wordt gebruikt door de event mediator van de Bestelomgeving leermiddelen om een logboek bij te houden van verzonden en ontvangen meldingen met betrekking tot een unieke aanvraag.
purchase OrderId	string	string	Inkooporder-nummer van de Winkel	OW1234	V	Waarde mag niet gewijzigd worden
purchase OrderType	string	string	Optioneel veld om ordertypes te ondersteunen die bilateraal zijn afgesproken	VSO Tender Small	O	In het voorbeeld staat VSO voor voor seizoensorder.
contractId	string	string	Optionele unieke identifier van een contract tussen de leveranciers waarbinnen deze Order valt	2022-12-v1	O	Waarde mag niet gewijzigd worden.
deliveryLocation	object	Address	Optioneel afleveradres waar de leermiddelenverkoper (bijvoorbeeld in welk magazijn) de folio leermiddelen geleverd wil hebben.	Zie object Address	O
deliveryDate	string	date	De gewenste afleverdatum voor levering van de folio leermiddelen.	2024-03-11	O
deliveryType	string	ENUM	De levervariant beschrijft de wijze waarop de aanspraakmanager de aanspraken dient toe te kennen.	Zie deliveryType en deliverySpecification	O	Deze string is een directe verwijzing naar het gedeelde model deliveryType uit de Delivery API.
schoolBuyer	object	schoolBuyer	Optioneel object waar we de schoolBuyer kunnen toevoegen voor het afleveren van digitale orders.		O
orderLines	array	Order Lines	Specificatie van de producten die de Bestelomgeving wil bestellen.	Zie object OrderLines	V

Object: OrderLines

Een OrderLine bevat een referentie naar het te bestellen product en het gewenste aantal.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
purchase OrderLineId	string	string	Optioneel inkooporder-regelnummer van de Winkel	OW1234-2	O	Waarde mag niet gewijzigd worden
productId	string	string	Referentie naar de Product-beschrijving in de Catalogue API van het Leermiddel	871792713 0834	V	Een Order verwijst naar exact 1 Product-Beschrijving( Leermiddel- of Setbeschrijving) Waarde mag niet gewijzigd worden
quantity	integer	integer	Aantal producten dat de Bestelomgeving leermiddelen wil inkopen.	100	V	Waarde mag niet gewijzigd worden.

Object Address

Alle adresgegevens zijn samengevoegd in een blok. Dit adres kan in Nederland en ook in het buitenland zijn.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
name	string	string	Ter attentie van omschrijving		O
street	string	string	Straatnaam van het adres	Rijnkade	V
houseNumber	integer	integer	Huisnummer	12	V	Huisnummer is verplicht.
houseNumberSuffix	string	string	Huisnummer toevoeging	a	O	Toevoeging is optioneel.
zipCode	string	string	Postcode	1000 AA	V	Waarde is bij een Nederlands adres volgens het patroon van 4 cijfers en 2 letters
city	string	string	De woonplaats	Arnhem	V
countryCode	string	string	Landcode	NL	O	Waarde is de Alpha-2 code (2 letters) uit de ISO 3166 standaard dat correspondeert met het land zoals aangegeven door het veld Country
country	string	string	Het land van het adres van de leerling	Nederland	V

Object: Schoolbuyer

Het object schoolBuyer bevat informatie over een onderwijsorganisatie die leermiddelen bestelt.

De referentie naar een onderwijsorganisatie is uniform gespecificeerd voor alle APIs en terug te vinden op de pagina Technische specificatie digitale identiteiten – referentie onderwijsorganisatie.

Aangevuld met contactgegevens (displayName en email).

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
displayName	string	string	Weergavenaam van de contactpersoon van de onderwijsorganisatie		V
email	string	string	E-mailadres van de contactpersoon van de onderwijsorganisatie		V
organisationMasterIdentifier	string	string	Primaire identifier van de onderwijsorganisatie (OnderwijsaanbiederId). Ofwel organisationMasterIdentifier ofwel organisationIds is verplicht.	104A158	O	Minimaal één van organisationMasterIdentifier of organisationIds moet ingevuld zijn.
organisationIds	array	array	Secundaire identifiers van de onderwijsorganisatie. Ofwel organisationMasterIdentifier ofwel organisationIds is verplicht.	-	O	Minimaal één van organisationMasterIdentifier of organisationIds moet ingevuld zijn.

Bevestigingsbericht: OrderConfirmation

Een Ordersysteem leermiddelen reageert op een OrderRequest bericht met een OrderConfirmation bevestigingsbericht. In dit bevestigingsbericht wordt de requestReferenceId die door de Bestelomgeving leermiddelen is aangemaakt opgenomen. In aanvulling hierop wordt optioneel de informatie uit de order (puchaseOrderId) en de OrderLines (product, aantal, en purchaseOrderLineId) ook bevestigd. Het Ordersysteem leermiddelen heeft de mogelijkheid om een eigen verkoopordernummer (salesOrderId en salesOrderLineId) toe te voegen aan de orderbevestiging. Dit verkoopnummer kan gebruikt worden door de Bestelomgeving leermiddelen in het geval van supportvragen over de orderbevestiging. Door een tijdstempel op te nemen kan dit bevestigingsbericht worden gezien als een formele afspraak tussen beide leveranciers.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
response ReferenceId	string	uuid	De referentie van het Ordersysteem leermiddelen voor dit bevestigingsbericht.	eacb81ef-c9d5-4bd8-a624-4088bee04b75	V	Waarde mag niet gewijzigd worden.
request ReferenceId	string	uuid	De referentie van de Bestelomgeving leermiddelen waarop dit bevestigingsbericht een antwoord is.	eacb81ef-c9d5-4bd8-a624-4088bee04b73	V	Waarde mag niet gewijzigd worden.
sales OrderId	string	string	Verkoopordernummer van het Ordersysteem leermiddelen	OA678	O	Waarde mag niet gewijzigd worden.
purchase OrderId	string	string	Inkoopordernummer van de Bestelomgeving leermiddelen	OW1234	O	Optioneel kan de Aanbieder het purchaseOrderId echo-en.
processed Timestamp	string	datetime	Tijdstip waarop het OrderRequest bericht is verwerkt door het Ordersysteem leermiddelen.	2017-07-21T17:32:28Z	V	Het tijdstip kan afwijken van het versturen van het bevestigingsbericht. Intentie is om aan te geven wanneer het bericht is verwerkt.
orderStatus	string	ENUM	Een indicatie wat de status van verwerking van de OrderRequest is.	pending approved declined	V	Status pending wordt gecommuniceerd zodra de leverancier extra controles uit gaat voeren (bijvoorbeeld credit check). Een bevestigingsbericht wordt op termijn opgevolgd door een nieuw bevestigingsbericht met de status approved of declined. Indien declined, dan wordt de foutcode gespecificeerd in statusMessage.
success