OSR:API/V2/Opvragen mandaat token: verschil tussen versies
(Nieuwe pagina aangemaakt met ' Hieronder is een voorbeeld weergegeven van de request:<br> <syntaxhighlight lang="json"> /api/v1/mandates?supplier_oin=00000003272448340204&school_oin=00000007000...') |
k (Delange02 heeft pagina OSR:2019/Opvragen mandaat token hernoemd naar OSR:API/V2/Opvragen mandaat token: Verplaatsing naar API V2.) |
||
(43 tussenliggende versies door 2 gebruikers niet weergegeven) | |||
Regel 1: | Regel 1: | ||
+ | ==Inleiding== |
||
+ | Het opvragen van het mandaat token, is identiek aan het bericht [[OSR:2019/Valideren_mandaat|Valideren_mandaat]].<br> |
||
+ | Het enige verschil is dat het mandaat van de eigen organisatie wordt bevraagd.<br> |
||
+ | ==Het opvragen van een mandaat token== |
||
− | Hieronder is een voorbeeld weergegeven van de request:<br> |
||
+ | {{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).}} |
||
− | <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 |
||
+ | ===Aanroep=== |
||
+ | |||
+ | ====API endpoint==== |
||
+ | |||
+ | <table><tr> |
||
+ | <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==== |
||
+ | |||
+ | <syntaxhighlight lang="json"> |
||
+ | 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> |
</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 |
+ | | Namespace van de dienstversie. |
| | Verplicht |
| | Verplicht |
||
|- |
|- |
||
| | Supplier_oin |
| | Supplier_oin |
||
− | | |
+ | | OIN van de leverancier. |
| | Verplicht |
| | Verplicht |
||
|- |
|- |
||
| | Reference_date |
| | Reference_date |
||
− | | Datumveld om een mandaat welke |
+ | | Datumveld om een mandaat welke in het verleden of in de toekomst is ingesteld op te vragen. |
| | Optioneel |
| | Optioneel |
||
|} |
|} |
||
− | + | <nowiki>*</nowiki> Om de verschillende versies van een dienst te kunnen onderscheiden wordt de namespace van de dienstversie gebruikt als uniek kenmerk.<br>In de WSDL wordt dit meestal aangeduid met de targetnamespace. De namespace is een unieke URI die voor alle services/operaties in de dienstversie 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=== |
+ | ====Voorbeeld==== |
||
− | Voor de leverancier die zijn eigen mandaat opvraagt kan het volgende response worden teruggegeven: |
||
+ | Voor een systeem die zijn eigen mandaat opvraagt kan de volgende response worden verwacht: |
||
<syntaxhighlight lang="json"> |
<syntaxhighlight lang="json"> |
||
Regel 47: | Regel 60: | ||
"school": {"href": "/api/v1/schools/1"}, |
"school": {"href": "/api/v1/schools/1"}, |
||
"service": {"href": "/api/v1/services/2"} |
"service": {"href": "/api/v1/services/2"} |
||
− | } |
||
} |
} |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
− | ==Response 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 |
||
− | ! |
||
|- |
|- |
||
| | token |
| | token |
||
Regel 75: | Regel 85: | ||
| Directe link naar informatie over de desbetreffende gekoppelde dienst |
| Directe link naar informatie over de desbetreffende gekoppelde dienst |
||
|} |
|} |
||
+ | |||
+ | ====Codes==== |
||
+ | |||
+ | {|class="wikitable" |
||
+ | ! style="text-align:left;"| Route |
||
+ | ! style="text-align:left;"| Code |
||
+ | ! style="text-align:left;"| Inhoud response |
||
+ | |- |
||
+ | | | mandates/{id} |
||
+ | | | 200 |
||
+ | | | Mandaatobject |
||
+ | |- |
||
+ | | | mandates/{id} |
||
+ | | | 403 |
||
+ | | | Melding: "You are not allowed to view this mandate". |
||
+ | |- |
||
+ | | | mandates/{id} |
||
+ | | | 404 |
||
+ | | | Melding: "Mandate with id {id} does not exist". |
||
+ | |} |
||
+ | |||
+ | ==Diensten en dienstversies== |
||
+ | |||
+ | ===Response=== |
||
+ | |||
+ | ====Codes==== |
||
+ | |||
+ | {|class="wikitable" |
||
+ | ! style="text-align:left;"| Route |
||
+ | ! style="text-align:left;"| Code |
||
+ | ! style="text-align:left;"| Inhoud response |
||
+ | |- |
||
+ | | | services/{id} |
||
+ | | | 200 |
||
+ | | | Dienstobject. |
||
+ | |- |
||
+ | | | services/{id} |
||
+ | | | 400 |
||
+ | | | Melding: "Validation error(s)". |
||
+ | |- |
||
+ | | | services/{id} |
||
+ | | | 404 |
||
+ | | | Melding: "Service with id {id} does not exist". |
||
+ | |- |
||
+ | | | service-versions/{id} |
||
+ | | | 200 |
||
+ | | | Dienstversie-object. |
||
+ | |- |
||
+ | | | service-versions/{id} |
||
+ | | | 400 |
||
+ | | | Melding: "Validation error(s)". |
||
+ | |- |
||
+ | | | service-versions/{id} |
||
+ | | | 404 |
||
+ | | | Melding: "Service version with id {id} does not exist". |
||
+ | |} |
||
+ | |||
+ | ==Het opvragen van een lijst van alle mandaatinformatie voor een bepaalde dienst (als systeem)== |
||
+ | |||
+ | {{Info|''' Let op:'''<br>Deze functionaliteit vereist authenticatie met behulp van een API key.<br>Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).}} |
||
+ | |||
+ | Een systeem 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==== |
||
+ | |||
+ | <table><tr> |
||
+ | <td><span style="color:white;font-weight:bold;background-color:#61affe;padding:6px 15px">GET</span></td> |
||
+ | <td><syntaxhighlight lang="json" style="display:inline";> /school-mandates</syntaxhighlight></td> |
||
+ | </tr></table> |
||
+ | |||
+ | ====Voorbeeld==== |
||
+ | |||
+ | <syntaxhighlight lang="json"> |
||
+ | GET /school-mandates?service_code=ABC_DEF |
||
+ | </syntaxhighlight> |
||
+ | |||
+ | ===Response=== |
||
+ | |||
+ | ====Voorbeeld==== |
||
+ | |||
+ | <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. |
||
+ | |} |
||
+ | |||
+ | ====Codes==== |
||
+ | |||
+ | {|class="wikitable" |
||
+ | ! style="text-align:left;"| Route |
||
+ | ! style="text-align:left;"| Code |
||
+ | ! style="text-align:left;"| Inhoud response |
||
+ | |- |
||
+ | | | school-mandates |
||
+ | | | 200 |
||
+ | | | Lijst van schoolobjecten. |
||
+ | |- |
||
+ | | | school-mandates |
||
+ | | | 401 |
||
+ | | | Melding: "Authorization required". |
||
+ | |} |
||
+ | |||
+ | ==Voor wie?== |
||
+ | Deze service is beschikbaar voor iedereen die gekwalificeerd is en een mandaat heeft.<br> |
||
+ | Voor TLS verbindingen (minimaal TLS 1.2) moet een aanvragende partij een geldig PKI overheidscertifcaat/ODOC certificaat gebruiken.<br> |
||
+ | Zie meer informatie over de API op https://osr-api-sb.kennisnet.nl/api/v1/doc<br> |
||
+ | |||
+ | ==Over het gebruik van certificaten== |
||
+ | |||
+ | {{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.}} |
Huidige versie van 4 nov 2022 om 14:50
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 dienstversie. | Verplicht |
Supplier_oin | OIN van de leverancier. | Verplicht |
Reference_date | Datumveld om een mandaat welke in het verleden of in de toekomst is ingesteld op te vragen. | Optioneel |
* Om de verschillende versies van een dienst te kunnen onderscheiden wordt de namespace van de dienstversie gebruikt als uniek kenmerk.
In de WSDL wordt dit meestal aangeduid met de targetnamespace. De namespace is een unieke URI die voor alle services/operaties in de dienstversie gebruikt worden.
Response
Voorbeeld
Voor een systeem 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 | Inhoud response |
---|---|---|
mandates/{id} | 200 | Mandaatobject |
mandates/{id} | 403 | Melding: "You are not allowed to view this mandate". |
mandates/{id} | 404 | Melding: "Mandate with id {id} does not exist". |
Diensten en dienstversies
Response
Codes
Route | Code | Inhoud response |
---|---|---|
services/{id} | 200 | Dienstobject. |
services/{id} | 400 | Melding: "Validation error(s)". |
services/{id} | 404 | Melding: "Service with id {id} does not exist". |
service-versions/{id} | 200 | Dienstversie-object. |
service-versions/{id} | 400 | Melding: "Validation error(s)". |
service-versions/{id} | 404 | Melding: "Service version with id {id} does not exist". |
Het opvragen van een lijst van alle mandaatinformatie voor een bepaalde dienst (als systeem)
![]() |
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 systeem 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. |
Codes
Route | Code | Inhoud response |
---|---|---|
school-mandates | 200 | Lijst van schoolobjecten. |
school-mandates | 401 | Melding: "Authorization required". |
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