OSR:2019/Opvragen mandaten: verschil tussen versies

Uit Kennisnet Developers Documentatie
Naar navigatie springen Naar zoeken springen
 
(30 tussenliggende versies door een andere gebruiker niet weergegeven)
Regel 1: Regel 1:
−
Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en een leverancier. Het mandaat zelf wordt aangemaakt door de onderwijsinstelling via het zakelijk portaal. <br>
 +
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>
  +
−
 
  
 
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>
  
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>
 +
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>
   
 
De opvraging van mandaten kan 2 mogelijke antwoorden teruggeven.<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>
  
  +
* Voor de leverancier die zijn eigen mandaat opvraagt wordt er detail informatie teruggegeven over het mandaat.<br><br>
−
Voor andere partijen die willen verifiëren of een bepaalde leverancier gemandateerd is, wordt alleen een OK of NOK teruggegeven. 
  
  +
−
 
  
  +
Een mandaat heeft altijd een startdatum en mogelijk een einddatum.<br>
−
Een mandaat heeft altijd een startdatum en mogelijk een einddatum. Het kan dus zo zijn dat een mandaat in het verleden wel aanwezig was, maar inmiddels al is beëindigd. 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. 
  
  +
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. 
  +
  +
  +
Hieronder is een voorbeeld weergegeven van de 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
  +
  +
</syntaxhighlight>
  +
  +
==Request parameters==
  +
{|class="wikitable"
  +
! style="text-align:left;"| Parameters
  +
! style="text-align:left;"| Omschrijving
  +
! style="text-align:left;"| Verplicht/Optioneel
  +
!
  +
|-
  +
| | school_oin
  +
| OIN van de onderwijsinstelling
  +
| | Verplicht
  +
|-
  +
| | Service_version_namespace
  +
| Namespace van de dienst*
  +
| | Verplicht
  +
|-
  +
| | Supplier_oin
  +
| BOIN van de leverancier
  +
| | 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 unieke 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. '''
  +
  +
==Response==
  +
  +
Voor de leverancier die zijn eigen mandaat opvraagt kan het volgende response worden teruggegeven: 
  +
  +
<syntaxhighlight lang="json">
  +
{ 
  +
   "token": "d4fe5e12-bf0a-48b9-8844-edf58da93056", 
  +
   "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>
  +
  +
==Response parameters==
  +
{|class="wikitable"
  +
! style="text-align:left;"| Parameters
  +
! style="text-align:left;"| Omschrijving
  +
!
  +
|-
  +
| | token
  +
| 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: 
  +
  +
  +
<syntaxhighlight lang="json">
  +
HTTP/1.1 200 OK 
  +
{ 
  +
   "code": 404, 
  +
   "message": "Mandate not found" 
  +
} 
  +
</syntaxhighlight>
  +
  +
==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>

Huidige versie van 18 jun 2020 om 09:31

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.

Door het aanmaken van een mandaat is het mogelijk voor een leverancier om een endpoint aan te kunnen maken (of wijzigen) in het OSR.
Daarnaast is het mogelijk voor andere partijen om te verifiëren of een leverancier gemandateerd is namens een onderwijsinstelling voor een bepaalde dienst.

De opvraging van mandaten kan 2 mogelijke antwoorden teruggeven.

  • Voor andere partijen die willen verifiëren of een bepaalde leverancier gemandateerd is, wordt alleen een OK of NOK teruggegeven.
  • Voor de leverancier die zijn eigen mandaat opvraagt wordt er detail informatie teruggegeven over het mandaat.

Een mandaat heeft altijd een startdatum en mogelijk een einddatum.
Het kan dus zo zijn dat een mandaat in het verleden wel aanwezig was, maar inmiddels al is beëindigd.
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. 


Hieronder is een voorbeeld weergegeven van de 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

Request parameters

Parameters Omschrijving Verplicht/Optioneel
school_oin OIN van de onderwijsinstelling Verplicht
Service_version_namespace Namespace van de dienst* Verplicht
Supplier_oin BOIN van de leverancier 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 unieke 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

Voor de leverancier die zijn eigen mandaat opvraagt kan het volgende response worden teruggegeven:  

{ 
   "token": "d4fe5e12-bf0a-48b9-8844-edf58da93056", 
   "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"} 
   } 
}

Response parameters

Parameters Omschrijving
token 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:  


HTTP/1.1 200 OK 
{ 
   "code": 404, 
   "message": "Mandate not found" 
} 

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-sb.kennisnet.nl/api/v1/doc

Overgenomen van "https://developers.wiki.kennisnet.nl/index.php?title=OSR:2019/Opvragen_mandaten&oldid=10697"