OSR:2019/Opvragen mandaat token: verschil tussen versies

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken
k (Opvragen mandaat token)
(Opvragen mandaat token)
Regel 3: Regel 3:
 
Het enige verschil is dat het mandaat van de eigen organisatie wordt bevraagd.<br>
 
Het enige verschil is dat het mandaat van de eigen organisatie wordt bevraagd.<br>
  
==Opvragen mandaat token==
+
==Het opvragen van een mandaat token==
  
 
{{Info|''' Let op:'''<br>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).}}
 
{{Info|''' Let op:'''<br>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).}}
Regel 10: Regel 10:
  
 
<syntaxhighlight lang="json">
 
<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
+
/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>
 
</syntaxhighlight>
  
Regel 100: Regel 99:
 
|}
 
|}
  
 +
 +
==Het opvragen van een lijst van alle mandaatinformatie voor een bepaalde dienst (als leverancier)==
 +
 +
Een leverancier kan op basis van het gebruikte certificaat in combinatie met de meegegeven dienstcode een lijst van al zijn mandaten opvragen binnen de betreffende dienst.
 +
 +
Hieronder is een voorbeeld weergegeven van het request:<br>
 +
 +
<syntaxhighlight lang="json">
 +
/api/v2/school-mandates?service_code=ABC_DEF
 +
</syntaxhighlight>
 +
 +
===Response===
 +
 +
Voor deze functionaliteit kan de volgende response bij voorbeeld worden verwacht:
 +
 +
<syntaxhighlight lang="json">
 +
[
 +
  {
 +
    "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"
 +
      }
 +
    }
 +
  }
 +
]
 +
</syntaxhighlight>
 +
 +
{|class="wikitable"
 +
! style="text-align:left;"| Parameters
 +
! style="text-align:left;"| 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.
 +
|}
 +
 +
 +
==Diensten en dienstversies==
  
 
Response codes bij direct bevragen van services of service_version
 
Response codes bij direct bevragen van services of service_version

Versie van 21 apr 2020 om 14:39

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

Info.gif 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).

Hieronder is een voorbeeld weergegeven van het request:

/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

Voor de leverancier 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


Response codes bij direct bevragen van mandaat id

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


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

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

Hieronder is een voorbeeld weergegeven van het request:

/api/v2/school-mandates?service_code=ABC_DEF

Response

Voor deze functionaliteit kan de volgende response bij voorbeeld worden verwacht:

[
  {
    "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.


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

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