OSR:API/V2/Opvragen mandaat token

Inleiding

Het opvragen van het mandaat token, is identiek aan het bericht Valideren_mandaat.
Het enige verschil is dat het mandaat van de eigen organisatie wordt bevraagd.

Het opvragen van een mandaat token

Let op: Deze functionaliteit vereist authenticatie met behulp van een API key. Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).

Aanroep

API endpoint

GET

/mandates

Voorbeeld

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	Verplicht
Supplier_oin	OIN 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 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

Voorbeeld

Voor een administratiesysteem die zijn eigen mandaat opvraagt kan de volgende response worden verwacht:

{ 
   "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"} 
   } 
}

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

Codes

Route	Code	Melding
mandates/{id}	200	mandate object
mandates/{id}	403	you are not allowed to view this mandate
mandates/{id}	404	Mandate with id {id} does not exist

Diensten en dienstversies

Response codes bij direct bevragen van services of service_version

Route	Code	Melding
service/{id}	200	service object
service/{id}	400	service with {id} does not exist
service-versions/{id}	200	service-version object
service-versions/{id}	400	service-version with {id} does not exist

Het opvragen van een lijst van alle mandaatinformatie voor een bepaalde dienst (als administratiesysteem)

Let op: Deze functionaliteit vereist authenticatie met behulp van een API key. Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).

Een administratiesysteem kan op basis van het gebruikte certificaat in combinatie met de meegegeven dienstcode een lijst van al zijn mandaten opvragen binnen de betreffende dienst.

Aanroep

API endpoint

GET	/school-mandates

Voorbeeld

GET /school-mandates?service_code=ABC_DEF

Response

Voorbeeld

[
  {
    "school_brin": "00AV",
    "school_oin": "0000000700000AV00000",
    "school_oa_id": 123A123,
    "school_name": "GBS De Morgenster",
    "mandates": [
      {
        "token": "d4fe5e12-bf0a-48b9-8844-edf58da93056",
        "start_date": "2018-12-18",
        "end_date": null,
        "_links": {
          "self": {
            "href": "string"
          }
        }
      }
    ],
    "_links": {
      "self": {
        "href": "string"
      }
    }
  }
]

Parameters	Omschrijving
school_brin	Brin van de onderwijsinstelling
school_oin	OIN van de onderwijsinstelling
school_oa_id	Onderwijs aanbieder id van de onderwijsinstelling (momenteel nog niet gevuld).
school_name	Naam van de onderwijsinstelling.
mandates token	Mandaat token, dit is nodig voor de gemandateerde leverancier om een endpoint aan te kunnen maken
mandates 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
mandates end_date	Einddatum van het mandaat. Dit wordt specifiek ingevuld door de onderwijsinstelling
mandates _links self	Directe link om het mandaat op te kunnen vragen.

Voor wie?

Deze service is beschikbaar voor iedereen die gekwalificeerd is en een mandaat heeft.
Voor TLS verbindingen (minimaal TLS 1.2) moet een aanvragende partij een geldig PKI overheidscertifcaat/ODOC certificaat gebruiken.
Zie meer informatie over de API op https://osr-api-sb.kennisnet.nl/api/v1/doc