Subscription Interface 1.2.1 (deze versie niet gebruiken!)

Inleiding

Het subscription interface hoort bij de /wiki/spaces/MedMijAfsprakenstelsel120/pages/135103542.

Op deze pagina staan alleen de verantwoordelijkheden inzake het resource interface die nog niet genoemd staan in de OAuth 2-specificatie.

1. De OAuth Client gebruikt voor het sturen van het acces token, in de subscription request, de methode Authorization Request Header Field, zoals beschreven in sectie 2.1 van RFC6750.

2. De subcription interface kent drie typen requests:

subscription creation request subscription duration request subscription duration request

2a. voor het aanmaken van een nieuw Abonnement door een Persoon bij een Zorgaanbieder op (Notificaties over) deze Gegevensdienst voor het wijzigen van de duur van een bestaand Abonnement door een Persoon bij deze Zorgaanbieder op (Notificaties over) deze Gegevensdienst voor het wijzigen van de duur van een bestaand Abonnement door een Persoon bij deze Zorgaanbieder op (Notificaties over) deze Gegevensdienst

2b. HTTP POST-request met structuur: <base url>/Subscription/ HTTP PATCH-request met structuur: <base url>/Subscription/<subscription-id> HTTP PATCH-request met structuur: <base url>/Subscription/<subscription-id>

Abonnement als overeenkomst

Met de subscription creation request biedt de PGO Server aan de Subscription Server een nieuwe Subscription-resource aan, die het Abonnement representeert, met daaraan verbonden het vooralsnog eenzijdige akkoord van de Persoon. Hij verzoekt daarmee bovendien om een subscription response, waarmee ook het akkoord van de Zorgaanbieder is verbonden. Zo ontstaat de overeenkomst.

Ook het aanpassen van de duur, via de einddatum parameter, van het Abonnement, door het versturen van een subscription duration request, ontvangt zo het akkoord van beide partijen; al mag de Zorgaanbieder een verkorting van het Abonnement niet weigeren; een verlenging kan wel geweigerd worden door de Zorgaanbieder.

Een verkorting of beëindiging van een Abonnement, door het versturen van een subscription duration request respectievelijk een subscription termination request, is een eenzijdige aanpassing dan wel opzegging van de overeenkomst. De Zorgaanbieder mag deze niet weigeren en er is in die zin geen sprake van een akkoord van beide partijen.

2c. De OAuth Client gebruikt voor het sturen van het access token, voor alle subscription requests, de methode Authorization Request Header Field, zoals beschreven in sectie 2.1 van RFC6750.

De methode Authorization Request Header Field biedt de beste beveiliging.

2d. De OAuth Client en de Subscription Server maken voor het uitwisselen van alle subscription requests en de bijbehorende responses gebruik van JSON.

subscription creation request subscription duration request subscription duration request

3.

3a. De subscription creation request:

in de url MOGEN GEEN parameters worden meegeven
bevat een complete representatie van de Subscription Resource met de volgende parameters:

parameter	vulling	toelichting
`zorgaanbieder`	verplicht, dezelfde waarde als voor de Zorgaanbieder in de scope van het gebruikte access token	-
`gegevensdienst`	verplicht, dezelfde waarde als voor de Gegevensdienst in de scope van het gebruikte access token	-
`client_id`	verplicht, dezelfde waarde als de `client_id` die gebruikt is in het gebruikte access token	-
`end_date`	verplicht, de waarde voor de gewenste dag waarop het Abonnement stopt.	De `end_date` dient gespecificeerd conform RFC 3339 `full-date`: 'YYYY-MM-DD' De Subscription Server controleert of de `end_date` geldig is, dit is als: de `end_date` valt binnen de huidige datum + de waarde van duur in het gebruikte access token (zie /wiki/spaces/MedMijAfsprakenstelsel120/pages/135103432 ) de `end_date` valt binnen de gestelde maximale duur van een Abonnement de `end_date` heeft een hogere waarde dan de huidige datum

3b. De subscription duration request:

MOET in de url de correcte subscription-id meegeven
bevat alleen de volgende parameters:

parameter vulling toelichting

end_date

verplicht, datum waarop het Abonnement verloopt.

De end_date dient gespecificeerd conform RFC 3339 full-date: 'YYYY-MM-DD'

De Subscription Server controleert of de end_date geldig is, dit is als:

de end_date valt binnen de huidige datum + de waarde van duur in het gebruikte access token (zie /wiki/spaces/MedMijAfsprakenstelsel120/pages/135103432 )
de end_date valt binnen de gestelde maximale duur van een Abonnement
de end_date heeft een hogere waarde dan de huidige datum

Met de subscription duration request verzoekt de PGO Server aan de Subscription Server de duur van een Abonnement aan te passen. Daarbij geeft de PGO Server bovendien alvast aan dat deze wijziging de goedkeuring van de Persoon heeft. Een Zorgaanbieder mag de verlenging van een Abonnement weigeren; een verkorting moet worden gehonoreerd.

3c. De subscription termination request:

MOET in de url de correcte subscription-id meegeven
MOET GEEN andere parameters bevatten.

Het access token moet een scope hebben die precies overeenkomt met de parameters van het betreffende subscription creation request of subscription duration request of subscription termination request en met het abonnement aangeduid met het subscription-id.

Daarnaast geldt dat in het geval van een subscription creation request of subscription duration request de duur in het access token een waarde moet hebben die groter is dan 0; in het geval van een subscription termination request moet de waarde van duur in het access token 0 zijn.

subscription creation request subscription duration request subscription duration request

4a. In het geval van een subscription creation request waarbij succesvol een Subscription-resource wordt aangemaakt, MOET de response een location header bevatten met een link naar de nieuwe resource (inclusief de toegekende subscription-id): <base url>/Subscription/<subscription-id>

4b. In het geval van een subscription duration request of een subscription termination request verifieert de Subscription Server dat voor het meegegeven subscription-id een geldig Abonnement is geregistreerd, waarvan de waarden van de attributen overeenkomen met de parameters in de scope van het gebruikte access token. Indien dit niet het geval is, behandelt de Subscription Server dat als uitzondering Subscription interface 4.

4c. In het geval van een subscription creation request of een subscription duration request stelt de Subscription Server stelt de einddatum (end_date) van het Abonnement in onder voorbehoud van het beleid van de Zorgaanbieder (zie 3c.) en de waarde van de maximale duur van de desbetreffende Gegevensdienst in de Catalogus.

Datumgrens en systeemdatum

De subscription server heeft zekere vrijheid om bij het verwerken van een request rekening te houden met tijdzone's en datumgrenzen bij het bepalen van de einddatum van een Abonnement.

4d. In het geval van een subscription creation request of een subscription duration request mag de Subscription Server een request toetsen aan het beleid dat de Zorgaanbieder voert voor Abonnementen op de Gegevensdienst en een request op grond hiervan een kortere duur toekennen of weigeren. In geval van weigering behandelt de Subscription Server dit 4als uitzondering Subscription interface 5.

Beleid omtrent Abonnementen

Een Zorgaanbieder heeft zowel verantwoordelijkheden als vrijheidsgraden rond het aanbieden en aangaan van Abonnementen. In het Afsprakenstelsel wordt dit gefaciliteerd door de Zorgaanbieder de mogelijkheid te geven beleid te voeren rond Abonnement op Notificaties. Een Zorgaanbieder kan voor een bepaalde Gegevensdienst een eigen maximale duur (binnen die gesteld in de Catalogus) opgeven. Ook kan de Zorgaanbieder bijvoorbeeld bepalen of het aantal Abonnementen per Persoon per Gegevensdienst begrensd is tot een bepaald maximum. Een Zorgaanbieder mag het verlengen van een bestaand Abonnement weigeren.

4e. In het geval van een subscription creation request of een subscription duration request laat de Subscription Server, wanneer aan alle bovenstaande voorwaarden voldaan is, het Abonnement per direct ingaan.

subscription creation request subscription duration request subscription duration request

5 5a. De http status van de subscription response wordt gezet op 201 na het succesvol aanmaken van het Abonnement. 5a. De http status van de subscription response wordt gezet op 200 na het succesvol bijwerken van het Abonnement. 5a. De http status van de subscription response wordt gezet op 204 na het succesvol verwijderen van het Abonnement.

Subscription response

Met de subscription response geeft de Subscription Server aan dat ook de Zorgaanbieder akkoord gaat met het Abonnement.

5b. De parameters in de response op een subscription creation request worden als volgt gevuld:

parameter	vulling	toelichting
`gegevensdienst`	verplicht, dezelfde waarde als voor de Gegevensdienst in het request	-
`client_id`	verplicht, dezelfde waarde als de `client_id` die gebruikt is in het gebruikte access token	-
`end_date`	datum waarop het Abonnement verloopt.	Deze datum geeft de dag aan waarop de Subscription Server stopt met het sturen van Notificaties voor dit Abonnement. Conform RFC 3339 `full-date`: 'YYYY-MM-DD'
`subscription_id`	identificatie waarmee de Subscription Server het Abonnement uniek voor deze Persoon en de Dienstverlener persoon identificeert	Deze waarde gebruikt de Subscription Server om bij een binnenkomende Subscription Creation Request of Subscription Duration Request het betreffende Abonnement te identificeren. Ook identificeert dit het Abonnement in logbestanden. Het `subscription_id` kan een integer waarde zijn, of een UUID, maar kan ook volgens een ander geldig identificatiepatroon worden gevuld.

5c. De parameters in de response op een subscription duration request worden als volgt gevuld:

parameter	vulling	toelichting
`end_date`	datum waarop het Abonnement verloopt.	Deze datum geeft de dag aan waarop de Subscription Server stopt met het sturen van Notificaties voor dit Abonnement. Conform RFC 3339 `full-date`: 'YYYY-MM-DD'

5d. De response op een subscription termination request mag geen parameters bevatten.

Einddatum en tijd

De Subscription Server heeft enige vrijheid bij het hanteren van het precieze moment op de dag waarop gestopt wordt met het versturen van Notificaties. Het staat de Subscription Server vrij om dit op enig moment van de betreffende dag te doen. Bij het verlopen van het Abonnement verstuurt de Subscription Server een subscription notification naar de client van de Persoon.

6. Na ontvangst van een subscription creation request of een subscription duration request of een subscription termination request , in UCI Abonneren, zal de Subscription Server, indien in antwoord daarop een subscription response dient te worden gedaan, na maximaal zestig (60) seconden dit subscription response ter beschikking stellen aan de PGO Server. Dit gedrag van de Subscription Server is gedurende minimaal 98,5% van de tijd beschikbaar.

7. Voor zover er in het verkeer tussen PGO Server en Subscription Server in UCI Abonneren sprake is, in de stuurgegevens, van een gegevenselement dat tot de identiteit van de Zorggebruiker herleid kan worden, gebruiken zij daarvoor niets anders dan de OAuth-gegevens die zij in hun respectievelijke OAuth Client en OAuth Resource Server moeten uitwisselen. PGO Server, Authorization Server en Subscription Server treffen goed beveiligde voorzieningen waarmee zij hieruit waar nodig zelf de identiteit van de Zorggebruiker kunnen vaststellen.

Toelichting
Met het oog op het borgen van de privacy en het zo eenvoudig mogelijk houden van de architectuur van het MedMij Afsprakenstelsel, wordt ervoor gekozen de identifier voor de Zorggebruiker onderweg zo betekenisloos mogelijk te houden. Alle betekenis wordt er ter weerszijden aan verbonden door raadpleging van interne registraties. Omdat de PGO Server, Authorization Server en Subscription Server samen een OAuth-flow afhandelen, beschikken zij (na authenticatie van de Zorggebruiker) over tokens die de identiteit van de Zorggebruiker vertegenwoordigen, namelijk (eerst) de authorization code en (later) het access token. Buiten deze hoeven en mogen er geen identificerende gegevenselementen in het verkeer worden opgenomen.

8. OAuth Resource Server en OAuth Client handelen uitzonderingssituaties inzake het subscription interface af volgens onderstaande tabel.

Nummer	Implementeert uitzondering	Uitzondering	Actie	Melding	Vervolg
Subscription interface 1	UC Abonneren 6	De validatie van het access token door Subscription Server faalt, of er wordt niet voldaan aan de beschikbaarheidsvoorwaarde. Zie ook de toelichting op Beschikbaarheids- en ontvankelijkheidsvoorwaarde.	Subscription Server informeert PGO Server over deze uitzondering. PGO Server informeert daarop Zorggebruiker hierover.	Conform HTTP specificatie met status code 401 "Niet geautoriseerd"	Allen stoppen de flow onmiddellijk na geïnformeerd te zijn over de uitzondering.
Subscription interface 2	UC Abonneren 6	Subscription Server ontvangt een ongeldig verzoek.		Conform HTTP specificatie met status code 400 "Foute aanvraag"
Subscription interface 3	UC Abonneren 3	Subscription Server kan in de request niet, niet geheel of niet tijdig uitvoeren, om redenen anders dan uitzondering Subscription interface 1, 2, 4 of 5.		Conform HTTP specificatie met met status code 500 "Interne serverfout"
Subscription interface 4	UC Abonneren 7	Subscription Server ontvangt een correct verzoek dat op basis van door de Zorgaanbieder ingesteld beleid geweigerd wordt.		Conform HTTP specificatie met status code 422 "Aanvraag kan niet verwerkt worden"
Subscription interface 5	UC Abonneren 8	Subscription Server ontvangt een correct verzoek dat verwijst naar een niet bestaand Abonnement (subscription-id).		Conform HTTP specificatie met status code 404 "Niet gevonden"