Interfaces Register Sync Proxy

Register Sync Proxy Interface

Algemeen

Deze interface wordt door Resource Clients aangeroepen via Feature core-FHIR-interactie-broker die wordt geboden door Resource Broker ZA-in. Daarom gelden voor het gebruik van Features van de Register Sync Proxy Interface ook de specificaties van core-FHIR-interactie-broker m.b.t. het gebruik van HTTP headers.

Base endpoint en FHIR-versions

De waarde van de base-URL van de FHIR endpoints die de Register Sync Proxy biedt t.b.v. de Register Sync Proxy Interface ( [base] dus ), dient voor alle FHIR-interacties gelijk te zijn aan "https://<FQDN>[/<path-extension>]/fhir/<fhir-version>". De waarde van <fhir-version> is dan bijvoorbeeld "R4" of "R5".

T.b.v. de Register Sync Proxy Interface worden de volgende FHIR-versions ondersteund:

R4

Let op! De Register Sync Proxy wordt door Resource Clients aangeroepen via Resource Broker ZA-in. Een Resource Client dient de base-URL van Resource Broker ZA-in te gebruiken. Resource Broker ZA-in hanteert de base-URL van de Register Sync Proxy.

FHIR-profielen

Over de Register Sync Proxy interface wordt gebruik gemaakt van CommunicationRequest en Communication FHIR profielen. Meer informatie over de gehanteerde FHIR-profielen op deze interfaces:

Feature	aorta-notifyDocumentReady
Type	Subfeature
Versie	1.0.0
Profiel	aorta-notifyDocumentReady
Systeemrolcode	-
Groep	FHIR-profielen
Gepubliceerd	28 Mar 2025
Delta	Initiële versie van feature.
Voorbeelden	https://simplifier.net/vzvz/nl-vzvz-notify-document-ready-example

Feature	aorta-notifyDocumentRetrieved
Type	Subfeature
Versie	1.1.0
Profiel	aorta-notifyDocumentRetrieved
Systeemrolcode	-
Groep	FHIR-profielen
Gepubliceerd
Delta	Foutafhandeling toegevoegd. Gereed. Versie verhoogd van 1.0.0 naar 1.1.0.
Voorbeelden	https://simplifier.net/vzvz/nl-vzvz-notify-document-retrieved-example

Interacties

De interacties van de Register Sync Proxy Interface zijn inhoudelijk gelijk aan de interacties van de Register Sync Client Interface.

Request Document Pickup (Proxy)

Feature	RequestDocumentPickup
Type	Service
Versie	1.0.0
Systeemrolcode	-
Groep	Register Sync
Gepubliceerd
Delta	Initiële versie.
Use case	AOF.UC.RSP.100.v1

Feature	Versie	Dependency	Aanbieder	Afnemer
RequestDocumentPickup	1.0.0	core-FHIR-interactie-broker	>=1	>=1
RequestDocumentPickup	1.0.0	aorta-notifyDocumentReady	>=1.*	>=1

Deze interactie is inhoudelijk gelijk aan de Request Document Pickup (Client) interactie van de Resource Client.

Deze interactie is gebaseerd op de FHIR-create interactie:

CODE

POST [base]/CommunicationRequest

De inhoud van een Register Sync Request is beschreven in het functioneel datamodel en in aorta-notifyDocumentReady.

Document Pickup Notification (Proxy)

Feature	DocumentPickupNotifcation
Type	Service
Versie	1.0.0
Systeemrolcode	-
Groep	Register Sync
Gepubliceerd
Delta	Update FHIR profiel om foutafhandeling mee te nemen. Gereed. Versie verhoogd van 1.0.0 naar 1.1.0. UC versie verhoogd van v1 naar v2.
Use case	AOF.UC.RSP.200.v2

Feature	Versie	Dependency	Aanbieder	Afnemer
DocumentPickupNotifcation	1.0.0	core-FHIR-interactie-broker	>=1	>=1
DocumentPickupNotifcation	1.0.0	aorta-notifyDocumentRetrieved	>=1.*	>=1

Deze interactie is inhoudelijk gelijk aan de Document Pickup Notification (Client) interactie van de Resource Client.

Deze interactie is gebaseerd op de FHIR-create interactie:

CODE

POST [base]/Communication

De inhoud van een Complete Register Sync is beschreven in het functioneel datamodel en in aorta-notifyDocumentRetrieved.

HTTP Status Codes

HTTP statuscodes die kunnen worden geretourneerd zijn opgenomen in onderstaande tabel.

Omdat bepaalde Confluence macro’s nog niet worden ondersteund in de publicatie omgeving, bevat de tabel, in de publicatieomgeving, ook informatie over de wijze waarop de betreffende interface wordt geïmplementeerd in de server component. De statuscodes die kunnen worden geretourneerd zijn opgenomen in de kolom “Uitkomst”. De overige informatie mag worden genegeerd.

AOF.UCe.VAL.100.v1 - Toetsing type content		Uitkomst
Stap	Omschrijving	Uitkomst
i	Het systeem ontvangt een verzoek en start de verwerking. Het systeem toetst of het gevraagde type content (Accept header) en het gehanteerde type content (Content-Type header) worden ondersteund. NB. wanneer het verzoek wordt ontvangen van een component van VZVZ, dan hoeft geen toets op type content te worden uitgevoerd.	Gevraagd type content niet ondersteund statuscode 406 Not Acceptable Deze situatie kan slechts optreden wanneer requests worden ontvangen via HTTP(S)
		Gehanteerd type content niet ondersteund statuscode 415 Unsupported Media Type Deze situatie kan slechts optreden wanneer requests worden ontvangen via HTTP(S)
		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.

AOF.UCe.VAL.250.v1 - Toetsing van een intern RB-request		Uitkomst
Stap	Omschrijving	Uitkomst
i	Het systeem controleert of alle vereiste tokens zijn toegevoegd aan het request	Ontbrekend token statuscode 401 Unauthorized In deze situatie wordt geen nadere informatie over de opgetreden fout geretourneerd. In deze situatie wordt, conform RFC 6750, ook een WWW-Authenticate HTTP response header met als auth-scheme "Bearer", maar zonder foutcode of nadere informatie omtrent de fout geretourneerd. Indien de `WWW-Authenticate` HTTP response header wordt geproduceerd door de resource broker, dan wordt een `realm` attribuut met waarde "`aorta`" toegevoegd.
i		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.
ii	Het systeem controleert de geldigheid van de meegezonden, van toepassing zijnde, tokens AORTA access_token, zoals omschreven in de sectie "Toetsing AORTA access_token". DigiD Authenticatietoken, zoals omschreven in de sectie “Toetsing DigiD Authenticatietoken”. NB. wanneer het verzoek via een intern netwerk wordt ontvangen, en van een component van VZVZ, dan hoeft deze toets niet te worden uitgevoerd. Welke tokens van toepassing zijn is beschreven in de interface specificaties die horen bij deze use case.	Ongeldig token statuscode 401 Unauthorized In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`invalid_token`" geretourneerd. Indien de `WWW-Authenticate` HTTP response header wordt geproduceerd door de resource broker, dan wordt een `realm` attribuut met waarde "`aorta`" toegevoegd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`security`" worden geretourneerd.
ii		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.
iii	Indien van toepassing: Het systeem controleert de samenhang tussen het AORTA access_token en het DigiD authenticatietoken, zoals omschreven in de de sectie "Toetsing van samenhang tussen tokens". NB. wanneer het verzoek via een intern netwerk wordt ontvangen, en van een component van VZVZ, dan hoeft deze toets niet te worden uitgevoerd. Welke tokens van toepassing zijn is beschreven in de interface specificaties die horen bij deze use case.	Ongeldig token statuscode 401 Unauthorized In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`invalid_token`" geretourneerd. Indien de `WWW-Authenticate` HTTP response header wordt geproduceerd door de resource broker, dan wordt een `realm` attribuut met waarde "`aorta`" toegevoegd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`security`" worden geretourneerd.
iii		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.

Stap

Omschrijving

Uitkomst

1

Het systeem stuurt de notificatie door naar de secundaire actor.

Fout bij sturen notificatie naar de secundaire actor

statuscode 500 Internal Server Error

Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.

2

<exit>

Het systeem retourneert een response naar de primaire actor.

Verwerking succesvol

statuscode 200 OK

Aanvullende eisen

AOF-I.GEN.150.v1 - Gebruik van HTTP

HTTP-requests en -responses op deze interface worden verzonden conform HTTP versie 1.1.

Alle HTTP-verkeer wordt verzonden binnen een TLS verbinding.

AOF-I.GEN.200.v1 - TLS verbindingen

TLS clients en TLS servers dienen tenminste TLS versie 1.2 te ondersteunen en mogen hierbij slechts gebruik maken van algoritmeselecties uit de categorie "Goed", zoals genoemd in bijlage C van de ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS).

Bij het opzetten van een verbinding dient gebruik te worden gemaakt van de sterkste algoritmeselectie die door beide partijen wordt ondersteund. TLS clients en TLS servers maken bij voorkeur echter gebruik van een hogere TLS versie dan 1.2.

Binnen TLS verbindingen dienen tijdelijke sleutels te worden toegepast, die elke 5 minuten worden ververst door middel van TLS Secure Renegotiation.

TLS verbindingen worden opgezet middels PKIo servercertificaten of, voor zorgaanbieders, m.b.v. UZI-servercertificaten.

AOF-I.GEN.250.v1 - Systeem Authenticatie (mTLS)

Indien uitwisseling plaatsvindt binnen TLS verbindingen, dan dient op deze interface gebruik te worden gemaakt van tweezijdige authenticatie (mutual TLS, mTLS), waarbij de TLS client en de TLS server zich wederzijds authenticeren.

AOF-I.GEN.400.v1 - FHIR

Op deze interface gelden de generieke eisen uit de MedMij informatiestandaarden. Dit betekent ondermeer dat zowel JSON als XML moet worden ondersteund.

AOF-I.GEN.450.v1 - Verkrijgen base-URL van component

Deze interface wordt geboden door een component die is opgenomen in het AORTA Stelseltoken. In de specificaties is aangegeven welke component het betreft.

Wanneer deze interface wordt gebruikt via HTTP, dan mag deze slechts worden gericht aan de base-URL van een server/component die deze rol blijkens het AORTA Stelseltoken vervuld.

Het geldende AORTA Stelseltoken dient periodiek te worden opgehaald via de AORTA Stelsel Metadata Interface. De aangeven caching directives dienen hierbij te worden gevolgd.

Functioneel datamodel Request Document Pickup

Het functionele datamodel van een Request Document Pickup, en de mapping ervan op een FHIR CommunicationRequest is beschreven in onderstaande tabel.

Attribute		Cardinaliteit	Toelichting
Functioneel	FHIR	Cardinaliteit	Toelichting
Verzoek-id	`CommunicationRequest.identifier`	1..1	Unieke id van het verzoek.
Register sync-id	`CommunicationRequest.groupIdentifier`	1..1	Unieke id van de register sync waar deze CommunicationRequest een onderdeel van is.
Verzoek-status	`CommunicationRequest.status`	1..1	Status van het verzoek. Moet waarde `active` bevatten.
Verzoek-aanmaak-tijdstip	`CommunicationRequest.authoredOn`	1..1	Datum en tijd dat het verzoek is aangemaakt.
Verzoek-indiener	`CommunicationRequest.requester`	1..1	Wie/wat het verzoek indient. Moet een Device of Organisatie bevatten.
Type-register-sync	`CommunicationRequest.reasonCode`	1..1	Reden dat de communicatie nodig is. Geeft aan welke register gesynct moet worden. Moet een van de onderstaande waardes bevatten: `vwi-sync` `act-sync` `abr-sync`
Document-referentie	`CommunicationRequest.reasonReference`	1..1	Verwijzing naar de contained DocumentReference met meer info over het op te halen document.
Document-id	`DocumentReference.identifier`	1..1	Unieke id van bestand op locatie.
Document-type	`DocumentReference.type`	1..1	Type bestand, Moet waarde van de codelijst bevatten. Codelijst: https://decor.nictiz.nl/pub/vzvz/aorta-vzvz-html-20240227T092043/voc-2.16.840.1.113883.2.4.3.111.3.9.11.1-2016-09-15T163915.html
Document-url	`DocumentReference.content` `.attachment.url`	1..1	Url van de Binary waar de opvrager het kan opvragen.
Document-mime-type	`DocumentReference.content.attachment.contentType`	1..1	Mime type van het document.
Document- beschikbaar-vanaf	`CommunicationRequest.occurrencePeriod.start`	1..1	Aanmaakperiode. De periode waarin het bestand is aangemaakt.
Document-beschikbaar-tot	`CommunicationRequest.occurrencePeriod.end`	1..1	Expiratietijd. Het bestand kan gegarandeerd tot dit tijdstip worden opgehaald. Moet minimaal 3 dagen zijn na de Document- beschikbaar-vanaf tijd zijn.

Functioneel datamodel Document Pickup Notification

Het functionele datamodel van een Register Sync Notification, en de mapping ervan op een FHIR Communication is beschreven in onderstaande tabel.

Attribute		Cardinaliteit	Toelichting
Functioneel	FHIR	Cardinaliteit	Toelichting
Verzoek-id	`Communication.identifier`	1..1	Unieke id van het verzoek.
Referentie-gerelateerde-RequestDocumentPickup	`Communication.basedOn`	1..1	Verzoek-id van het eerder ontvangen RequestDocumentPickup waaraan deze notifcaitie gerelateerd is.
Notificatie-status	`Communication.status`	1..1	Status van het verzoek. Kan de waarde `completed` bevatten om aan te geven dat het document succesvol is opgehaald, of `not-done` als er iets mis is gegaan. Indien de waarde `not-done` is moet de statusReason worden meegestuurd.
Foutmelding-reden	`Communication.statusReason`	0..1	Bevat de foutcode indien er iets mis was gegaan.
Type-register-sync	`Communication.reasonCode`	1..1	Reden dat de communicatie nodig is. Geeft aan welke register gesynct moet worden. Moet een van de onderstaande waardes bevatten: `vwi-sync` `act-sync` `abr-sync`
Document-referentie	`Communication.reasonReference`	1..1	Verwijzing naar de DocumentReference welke opgehaald is.