OSR:API/V2/Valideren mandaat: verschil tussen versies

Huidige versie van 21 jun 2023 om 12:09

Inleiding

Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en systeem. 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 systeem gemandateerd is namens een onderwijsinstelling voor een bepaalde dienst.

Valideer mandaat

Aanroep

API endpoint

GET

 /mandates

Voorbeeld

Hieronder is een voorbeeld weergegeven van het request:

GET /api/v2/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. Wanneer leeggelaten, is een Service_code verplicht.	Optioneel
Supplier_oin	OIN van de leverancier, behorende bij het systeem.	Verplicht
Reference_date	Datumveld om een mandaat welke op een specifieke datum in de toekomst of het verleden is ingesteld op te vragen.	Optioneel
Service_code	Code van de dienst. Wanneer leeggelaten, is een Service_version_namespace verplicht.	Optioneel

* Om de verschillende versies binnen een dienst te kunnen onderscheiden worden namespaces gebruikt als kenmerk. De namespace is een unieke URI die voor alle services/operaties gebruikt wordt.

Response

Voorbeeld

HTTP/1.1 200 OK 
{ 
   "code": 200, 
   "message": "Mandate for system exists and is valid" 
}

Codes

Code	Inhoud response
200	Mandaatobject. Deze response wordt gegeven wanneer de API-gebruiker het systeem is, behorende bij het mandaat.
204	Melding: "Mandate for system exists and is valid". Deze response wordt gegeven wanneer de API-gebruiker niet het systeem is, behorende bij het mandaat.
400	Melding: "There is a problem with the system query parameters".
404	Melding: "Mandate not found".

Eigen mandaat opvragen

Het is ook mogelijk om als systeem het eigen mandaat of een lijst van mandaten voor een dienst op te vragen. Bij een specifiek mandaat bevat het resultaat een mandaat token, welke benodigd is bij het registreren 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

Let op:
Bij nieuw aan te vragen certificaten wordt sterk aangeraden te kiezen voor een PKI-overheidscertificaat.
Dit omdat ODOC-certificaten geen onderdeel meer uitmaken van de aankomende Edukoppeling Transactiestandaard versie 1.3.

@@ Regel 1: / Regel 1: @@
+==Inleiding==
-Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en een leverancier. Het mandaat zelf wordt aangemaakt door de OSR beheerder van de onderwijsinstelling via het zakelijk portaal. <br>
+Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en systeem. Het mandaat zelf wordt aangemaakt door de OSR beheerder van de onderwijsinstelling via de grafische beheeromgeving van het OSR. <br>
-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>
-Daarnaast is het mogelijk voor andere partijen om te verifiëren of een leverancier gemandateerd is namens een onderwijsinstelling voor een bepaalde dienst.<br><br>
+Het is mogelijk voor andere partijen om te verifiëren of een systeem gemandateerd is namens een onderwijsinstelling voor een bepaalde dienst.<br><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>
+===Aanroep===
-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.
+====API endpoint====
+<table><tr>
-Hieronder is een voorbeeld weergegeven van de request:<br>
+<td><span style="color:white;font-weight:bold;background-color:#61affe;padding:6px 15px">GET</span></td>
+<td><syntaxhighlight lang="json" style="display:inline";> /mandates</syntaxhighlight></td>
+</tr></table>
+====Voorbeeld====
+Hieronder is een voorbeeld weergegeven van het request:<br>
 <syntaxhighlight lang="json">
-/api/v1/mandates?supplier_oin=00000003272448340204&school_oin=0000000700000AV00000&service_version_namespace=http://xml.eld.nl/schemas/Overstapservice/20180404&reference_date=2019-01-01
+GET /api/v2/mandates?supplier_oin=00000003272448340204&school_oin=0000000700000AV00000&service_version_namespace=http://xml.eld.nl/schemas/Overstapservice/20180404&reference_date=2019-01-01
 </syntaxhighlight>
-==Request parameters==
 {|class="wikitable"
 ! style="text-align:left;"| Parameters
 ! style="text-align:left;"| Omschrijving
 ! style="text-align:left;"| Verplicht/Optioneel
-!
 |-
-| | school_oin
+| | School_oin
-| OIN van de onderwijsinstelling
+| OIN van de onderwijsinstelling.
 | | Verplicht
 |-
-| | Service_version_namespace
+| | Service_version_namespace *
-| Namespace van de dienst*
+| Namespace van de dienst. Wanneer leeggelaten, is een Service_code verplicht.
-| | Verplicht
+| | Optioneel
 |-
 | | Supplier_oin
-| BOIN van de leverancier
+| OIN van de leverancier, behorende bij het systeem.
 | | Verplicht
 |-
 | | Reference_date
-| Datumveld om een mandaat welke bv in de toekomst is ingesteld op te vragen
+| Datumveld om een mandaat welke op een specifieke datum in de toekomst of het verleden is ingesteld op te vragen.
+| | Optioneel
+|-
+| | Service_code
+| Code van de dienst. Wanneer leeggelaten, is een Service_version_namespace verplicht.
 | | Optioneel
 |}
-''' Om de verschillende versies van een dienst te kunnen onderscheiden wordt de namespace van de dienst gebruikt als unieke dienstkenmerk.''''<br>
+<nowiki>*</nowiki> Om de verschillende versies binnen een dienst te kunnen onderscheiden worden namespaces gebruikt als kenmerk. De namespace is een unieke URI die voor alle services/operaties gebruikt wordt.
-''' 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==
+====Voorbeeld====
-Voor de leverancier die zijn eigen mandaat opvraagt kan het volgende response worden teruggegeven:
 <syntaxhighlight lang="json">
+HTTP/1.1 200 OK
 {
+   "code": 200,
-   "token": "d4fe5e12-bf0a-48b9-8844-edf58da93056",
+   "message": "Mandate for system exists and is valid"
-   "start_date": "2018-12-18",
+}
-   "end_date": null,
-   "_links":    {
-      "self": {"href": "/api/v1/mandates/1"},
-      "school": {"href": "/api/v1/schools/1"},
-      "service": {"href": "/api/v1/services/2"}
-   }
-}
 </syntaxhighlight>
+====Codes====
-==Response parameters==
 {|class="wikitable"
-! style="text-align:left;"| Parameters
+! style="text-align:left;"| Code
-! style="text-align:left;"| Omschrijving
+! style="text-align:left;"| Inhoud response
-!
 |-
-| | token
+| | 200
+| | Mandaatobject.<br>Deze response wordt gegeven wanneer de API-gebruiker het systeem is, behorende bij het mandaat.
-| Mandaat token, dit is nodig voor de gemandateerde leverancier om een endpoint aan te kunnen maken
 |-
-| | start_date
+| | 204
+| | Melding: "Mandate for system exists and is valid".<br>Deze response wordt gegeven wanneer de API-gebruiker niet het systeem is, behorende bij het mandaat.
-| 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
+| | 400
+| | Melding: "There is a problem with the system query parameters".
-| Einddatum van het mandaat. Dit wordt specifiek ingevuld door de onderwijsinstelling
 |-
-| | _links self
+| | 404
+| | Melding: "Mandate not found".
-| 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
 |}
+==Eigen mandaat opvragen==
-Voor de leverancier die het mandaat van een andere leverancier opvraagt kan het volgende worden teruggegeven:
+Het is ook mogelijk om als systeem het eigen mandaat of een lijst van mandaten voor een dienst op te vragen.
+Bij een specifiek mandaat bevat het resultaat een mandaat token, welke benodigd is bij het registreren van een endpoint.
-<syntaxhighlight lang="json">
-HTTP/1.1 200 OK
-{
-   "code": 404,
-   "message": "Mandate not found"
-}
-</syntaxhighlight>
-==Response parameters==
-{|class="wikitable"
-! style="text-align:left;"| Response
-! style="text-align:left;"| Omschrijving
-!
-|-
-| | 200 OK
-| Confirmatie dat er een mandaat is afgegeven voor de combinatie onderwijsinstelling, dienst versie en leverancier.
-|-
-| | 404 mandate not found
-| Een van de parameters matcht niet met een mandaat
-|}
+Op de volgende pagina kunt u hier informatie over terugvinden: [[OSR:API/V2/Opvragen_mandaat_token|Opvragen mandaat token]]
 ==Voor wie?==
 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>
-Zie meer informatie over de API op https://osr-sb.kennisnet.nl/api/v1/doc<br>
+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]]

OSR:API/V2/Valideren mandaat: verschil tussen versies

Huidige versie van 21 jun 2023 om 12:09

Inhoud

Inleiding

Valideer mandaat

Aanroep

API endpoint

Voorbeeld

Response

Voorbeeld

Codes

Eigen mandaat opvragen

Voor wie?

Navigatiemenu

Zoeken