OSR:API/V2/Valideren mandaat: verschil tussen versies
(Nieuwe pagina aangemaakt met 'Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en een leverancier. Het mandaat zelf wordt aangemaakt door de OSR beheerder van de onderwijsinst...') |
|||
(32 tussenliggende versies door 2 gebruikers niet weergegeven) | |||
Regel 1: | Regel 1: | ||
+ | ==Inleiding== |
||
⚫ | |||
⚫ | |||
− | Door het aanmaken van een mandaat is het mogelijk voor een leverancier om een endpoint aan te kunnen maken (of wijzigen) in het OSR.<br> |
||
⚫ | |||
⚫ | |||
− | De opvraging van mandaten kan 2 mogelijke antwoorden teruggeven.<br> |
||
− | * Voor andere partijen die willen verifiëren of een bepaalde leverancier gemandateerd is, wordt alleen een OK of NOK teruggegeven.<br> |
||
− | * Voor de leverancier die zijn eigen mandaat opvraagt wordt er detail informatie teruggegeven over het mandaat.<br><br> |
||
+ | ==Valideer mandaat== |
||
− | Een mandaat heeft altijd een startdatum en mogelijk een einddatum.<br> |
||
⚫ | |||
− | Het kan dus zo zijn dat een mandaat in het verleden wel aanwezig was, maar inmiddels al is beëindigd.<br> |
||
− | Of een mandaat kan in de toekomst ingesteld zijn. Hiervoor is de reference_date parameter bedacht om een mandaat van het verleden of de toekomst op te vragen. |
||
− | |||
− | |||
⚫ | |||
<syntaxhighlight lang="json"> |
<syntaxhighlight lang="json"> |
||
Regel 20: | Regel 13: | ||
</syntaxhighlight> |
</syntaxhighlight> |
||
− | ==Request parameters== |
||
{|class="wikitable" |
{|class="wikitable" |
||
! style="text-align:left;"| Parameters |
! style="text-align:left;"| Parameters |
||
! style="text-align:left;"| Omschrijving |
! style="text-align:left;"| Omschrijving |
||
! style="text-align:left;"| Verplicht/Optioneel |
! style="text-align:left;"| Verplicht/Optioneel |
||
⚫ | |||
|- |
|- |
||
− | | | |
+ | | | School_oin |
| OIN van de onderwijsinstelling |
| OIN van de onderwijsinstelling |
||
| | Verplicht |
| | Verplicht |
||
|- |
|- |
||
− | | | Service_version_namespace |
+ | | | Service_version_namespace * |
− | | Namespace van de dienst |
+ | | Namespace van de dienst |
| | Verplicht |
| | Verplicht |
||
|- |
|- |
||
| | Supplier_oin |
| | Supplier_oin |
||
− | | |
+ | | OIN van de leverancier, behorende bij het administratiesysteem |
| | Verplicht |
| | Verplicht |
||
|- |
|- |
||
Regel 44: | Regel 35: | ||
|} |
|} |
||
− | + | <nowiki>*</nowiki> Om de verschillende versies van een dienst te kunnen onderscheiden wordt de namespace van de dienst gebruikt als uniek dienstkenmerk.<br>In de WSDL wordt dit meestal aangeduid met de targetnamespace. De namespace is een unieke URI die voor alle services/operaties in de dienst gebruikt worden. |
|
− | ''' In de WSDL wordt dit meestal aangeduid met de targetnamespace. De namespace is een unieke URI die voor alle services/operaties in de dienst gebruikt worden. ''' |
||
==Response== |
==Response== |
||
+ | De volgende response kan terug worden gegeven: |
||
− | Voor de leverancier die zijn eigen mandaat opvraagt kan het volgende response worden teruggegeven: |
||
<syntaxhighlight lang="json"> |
<syntaxhighlight lang="json"> |
||
⚫ | |||
{ |
{ |
||
⚫ | |||
− | "token": "d4fe5e12-bf0a-48b9-8844-edf58da93056", |
||
− | " |
+ | "message": "Mandate found" |
⚫ | |||
− | "end_date": null, |
||
− | "_links": { |
||
− | "self": {"href": "/api/v1/mandates/1"}, |
||
− | "school": {"href": "/api/v1/schools/1"}, |
||
− | "service": {"href": "/api/v1/services/2"} |
||
− | } |
||
− | } |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
+ | of 404 Mandate not found, indien er geen mandaat is gevonden voor de combinatie van opgegeven parameters. |
||
− | ==Response parameters== |
||
− | {|class="wikitable" |
||
⚫ | |||
− | ! style="text-align:left;"| Omschrijving |
||
− | ! |
||
⚫ | |||
⚫ | |||
− | | Mandaat token, dit is nodig voor de gemandateerde leverancier om een endpoint aan te kunnen maken |
||
− | |- |
||
− | | | start_date |
||
− | | Startdatum van het mandaat. Dit is de dag van aanmaak van het mandaat of een specifieke datum welke gekozen is door de onderwijsinstelling |
||
− | |- |
||
− | | | end_date |
||
− | | Einddatum van het mandaat. Dit wordt specifiek ingevuld door de onderwijsinstelling |
||
− | |- |
||
− | | | _links self |
||
− | | Directe link om het mandaat op te kunnen vragen. Dit kan alleen worden gebruikt door de leverancier die gemandateerd is |
||
− | |- |
||
− | | | _links school |
||
− | | Directe link naar informatie over de desbetreffende gekoppelde onderwijsinstelling |
||
− | |- |
||
− | | | _links service |
||
− | | Directe link naar informatie over de desbetreffende gekoppelde dienst |
||
− | |} |
||
− | Voor de leverancier die het mandaat van een andere leverancier opvraagt kan het volgende worden teruggegeven: |
||
+ | Response codes |
||
− | <syntaxhighlight lang="json"> |
||
⚫ | |||
− | { |
||
⚫ | |||
− | "message": "Mandate not found" |
||
− | } |
||
− | </syntaxhighlight> |
||
− | |||
− | ==Response parameters== |
||
{|class="wikitable" |
{|class="wikitable" |
||
− | ! style="text-align:left;"| |
+ | ! style="text-align:left;"| Route |
− | ! style="text-align:left;"| |
+ | ! style="text-align:left;"| Code |
⚫ | |||
− | ! |
||
⚫ | |||
+ | | | mandates |
||
⚫ | |||
⚫ | |||
|- |
|- |
||
− | | | |
+ | | | mandates |
+ | | | 400 |
||
− | | Confirmatie dat er een mandaat is afgegeven voor de combinatie onderwijsinstelling, dienst versie en leverancier. |
||
+ | | | some error in query params |
||
|- |
|- |
||
+ | | | mandates |
||
⚫ | |||
+ | | | 404 |
||
− | | Een van de parameters matcht niet met een mandaat |
||
+ | | | mandate not found |
||
|} |
|} |
||
+ | ==Eigen mandaat opvragen== |
||
+ | Het is ook mogelijk om het eigen mandaat op te vragen. Het resultaat bevat een mandaat token wat van belang is bij het aanmaken van een endpoint. |
||
+ | |||
+ | Op de volgende pagina kunt u hier informatie over terugvinden: [[OSR:2019/Opvragen_mandaat_token|Opvragen mandaat token]] |
||
==Voor wie?== |
==Voor wie?== |
||
Deze service is beschikbaar voor iedereen.<br> |
Deze service is beschikbaar voor iedereen.<br> |
||
Voor TLS verbindingen (minimaal TLS 1.2) moet een aanvragende partij een geldige PKI overheidscertifcaat/ODOC certificaat gebruiken<br> |
Voor TLS verbindingen (minimaal TLS 1.2) moet een aanvragende partij een geldige PKI overheidscertifcaat/ODOC certificaat gebruiken<br> |
||
− | Zie meer informatie over de API op https://osr |
+ | Zie meer informatie over de API op https://osr.kennisnet.nl/api/v2/documentation<br> |
+ | |||
+ | {{Info|''' Let op:'''<br>Bij nieuw aan te vragen certificaten wordt sterk aangeraden te kiezen voor een PKI-overheidscertificaat.<br>Dit omdat ODOC-certificaten geen onderdeel meer uitmaken van de aankomende Edukoppeling Transactiestandaard versie 1.3.}} |
||
+ | |||
+ | [[Category:OSR]] |
Versie van 15 jun 2020 13:49
Inleiding
Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en administratiesysteem. Het mandaat zelf wordt aangemaakt door de OSR beheerder van de onderwijsinstelling via de grafische beheeromgeving van het OSR.
Het is mogelijk voor andere partijen om te verifiëren of een administratiesysteem gemandateerd is namens een onderwijsinstelling voor een bepaalde dienst.
Valideer mandaat
Hieronder is een voorbeeld weergegeven van het request:
/api/v1/mandates?supplier_oin=00000003272448340204&school_oin=0000000700000AV00000&service_version_namespace=http://xml.eld.nl/schemas/Overstapservice/20180404&reference_date=2019-01-01
Parameters | Omschrijving | Verplicht/Optioneel |
---|---|---|
School_oin | OIN van de onderwijsinstelling | Verplicht |
Service_version_namespace * | Namespace van de dienst | Verplicht |
Supplier_oin | OIN van de leverancier, behorende bij het administratiesysteem | Verplicht |
Reference_date | Datumveld om een mandaat welke bv in de toekomst is ingesteld op te vragen | Optioneel |
* Om de verschillende versies van een dienst te kunnen onderscheiden wordt de namespace van de dienst gebruikt als uniek dienstkenmerk.
In de WSDL wordt dit meestal aangeduid met de targetnamespace. De namespace is een unieke URI die voor alle services/operaties in de dienst gebruikt worden.
Response
De volgende response kan terug worden gegeven:
HTTP/1.1 200 OK
{
"code": 200,
"message": "Mandate found"
}
of 404 Mandate not found, indien er geen mandaat is gevonden voor de combinatie van opgegeven parameters.
Response codes
Route | Code | Melding |
---|---|---|
mandates | 200 | mandate object |
mandates | 400 | some error in query params |
mandates | 404 | mandate not found |
Eigen mandaat opvragen
Het is ook mogelijk om het eigen mandaat op te vragen. Het resultaat bevat een mandaat token wat van belang is bij het aanmaken van een endpoint.
Op de volgende pagina kunt u hier informatie over terugvinden: Opvragen mandaat token
Voor wie?
Deze service is beschikbaar voor iedereen.
Voor TLS verbindingen (minimaal TLS 1.2) moet een aanvragende partij een geldige PKI overheidscertifcaat/ODOC certificaat gebruiken
Zie meer informatie over de API op https://osr.kennisnet.nl/api/v2/documentation