Order API

Titel	Order 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 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 address
3 Bevestigingsbericht: OrderConfirmation
4 Bericht: CreditOrderRequest
5 Bevestigingsbericht: CreditOrderConfirmation
6 Status- en foutcodes
7 Technisch: API specificatie
8 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 OrderLineId	string	string	Optioneel inkooporder-regelnummer van de Winkel	OW1234-2	O	Waarde mag niet gewijzigd worden
purchaseOrderType	string	string	Optioneel veld om ordertypes te ondersteunen die bilateraal zijn afgesproken	VSO Tender Small	O	In het voorbeeld staat VSO voor voor seizoensorder.
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.
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

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

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 (product, aantal, purchaseOrderId 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
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.
response ReferenceId	string	uuid	De referentie van het Ordersysteem leermiddelen voor dit bevestigingsbericht.	eacb81ef-c9d5-4bd8-a624-4088bee04b75	V	Waarde mag niet gewijzigd worden.
productId	string	string	Verwijzing naar de unieke identifier voor het product	871792713 0834	O	Optioneel kan de Aanbieder het productId echo-en
quantity	integer	integer	Aantal producten dat de Bestelomgeving leermiddelen wil inkopen.	100	O	Optioneel kan de Aanbieder het aantal echo-en
purchase OrderId	string	string	Inkoopordernummer van de Bestelomgeving leermiddelen	OW1234	O	Waarde mag niet gewijzigd worden
purchase OrderLineId	string	string	Optioneel inkooporder-regelnummer van de Bestelomgeving leermiddelen	OW1234-2	O	Waarde mag niet gewijzigd worden
sales OrderId	string	string	Verkoopordernummer van het Ordersysteem leermiddelen	OA678	O	Waarde mag niet gewijzigd worden
sales OrderLineId	string	string	Optioneel verkooporder-regelnummer van de Ordersysteem leermiddelen	OA678-2	O	Waarde mag niet gewijzigd worden
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	boolean	boolean	Indicatie of het Ordersysteem leermiddelen het bericht heeft kunnen verwerken	True False	V	False indien het Ordersysteem leermiddelen 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

Bericht: CreditOrderRequest

Naast een reguliere Order is het mogelijk om als Bestelomgeving leermiddelen een Order te crediteren. In dat geval dient de Bestelomgeving leermiddelen een CreditOrderRequest in bij het Ordersysteem leermiddelen. In dit CreditOrderRequest specificeert de Bestelomgeving leermiddelen de purchaseOrderId en de purchaseOrderLineId die de Bestelomgeving leermiddelen wil crediteren en voegt de Bestelomgeving leermiddelen optioneel de door het Ordersysteem leermiddelen verstuurde salesOrderId, salesOrderLineId en/of responseReferenceId uit de OrderConfirmation toe.

Op deze wijze kunnen zowel Bestelomgeving leermiddelen als Ordersysteem leermiddelen dit bericht relateren aan de oorspronkelijke OrderConfirmation die gecrediteerd gaat worden. Uiteraard is het afhankelijk van bilaterale afspraken tussen beide leveranciers of crediteren al dan niet mogelijk is en welke informatie in het verzoek opgenomen moet zijn.

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 events met betrekking tot een unieke aanvraag.
purchase OrderId	string	string	Inkoopordernummer van de Bestelomgeving leermiddelen	OW1234	V	Waarde mag niet gewijzigd worden
purchase OrderLineId	string	string	Optioneel inkooporder-regelnummer van de Bestelomgeving leermiddelen	OW1234-2	O	Waarde mag niet gewijzigd worden
sales OrderId	string	string	Verkooporder-nummer van het Ordersysteem leermiddelen	OA678	O	Waarde mag niet gewijzigd worden
sales OrderLineId	string	string	Optioneel verkooporder-regelnummer van het Ordersysteem leermiddelen	OA678-2	O	Waarde mag niet gewijzigd worden
response ReferenceId	string	string	Optionele verwijzing naar de CreditorderBevestiging (CreditOrderConfirmation) waarin het OrderVerzoek door het Ordersysteem leermiddelen is bevestigd.	eacb81ef-c9d5-4bd8-a624-4088bee04b75	O	Waarde mag niet gewijzigd worden

Bevestigingsbericht: CreditOrderConfirmation

Het Ordersysteem leermiddelen reageert op een CreditorderRequest met een bevestigingsbericht CreditOrderConfirmation. Indien het CreditorderRequest wordt geaccepteerd door het Ordersysteem leermiddelen dan wordt via dit bevestigingsbericht de status OK retour gestuurd. De creditOrderStatus wordt in dat geval door het Ordersysteem leermiddelen op approved gezet. Indien de leverancier het creditOrderRequest nog verder moet beoordelen kan het Ordersysteem leermiddelen een bevestigingsbericht sturen met de status pending.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
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.
response ReferenceId	string	uuid	De referentie van het Ordersysteem leermiddelen voor dit bevestigingsbericht.	eacb81ef-c9d5-4bd8-a624-4088bee04b76	V	Waarde mag niet gewijzigd worden.
purchase OrderId	string	string	Inkoopordernummer van de Bestelomgeving leermiddelen	OW1234	V	Waarde mag niet gewijzigd worden
purchase OrderLineId	string	string	Optioneel inkooporder-regelnummer van de Bestelomgeving leermiddelen	OW1234-2	O	Waarde mag niet gewijzigd worden
sales OrderId	string	string	Verkoopordernummer van het Ordersysteem leermiddelen	OA678	O	Waarde mag niet gewijzigd worden
sales OrderLineId	string	string	Optioneel verkooporder-regelnummer van het Ordersysteem leermiddelen	OA678-2	O	Waarde mag niet gewijzigd worden
processed Timestamp	string	datetime	Tijdstip waarop het CreditOrderRequest 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.
creditOrderStatus	string	ENUM	Een indicatie wat de status van verwerking van de CreditOrderRequest 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	boolean	boolean	Indicatie of het Ordersysteem leermiddelen het bericht heeft kunnen verwerken	True False	V	False indien het Ordersysteem leermiddelen 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

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 Order API YAML uitgewerkt.
0.0.2: Op verzoek van de werkgroep zijn drie velden toegevoegd aan het OrderVerzoek en verwerkt in de objecten en koppelvlakspecificatie:
- purchaseOrderType: het type order om verwerking van verzoeken en bevestigingen te optimaliseren.
- deliveryAdress: een optioneel afleveradres voor levering van fysieke leermiddelen.
- deliveryDate: een gewenste afleverdatum voor levering van fysieke leermiddelen.
0.0.3: HuisnummerToevoeging stond niet correct in de YAML.
0.0.4: Conform wijziging in architectuur de schemaVersion als attribuut verwijderd uit de objecten.
0.0.5: / verwijderd achter endpoints.
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.