Order API

Titel

Order 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 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:

Samenvatting

Gegevensdienst

Leermiddelorders

Scopes

  • eduv.order

Berichten

Bevestigings-berichten

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.