DVPA-s onboarding

Inleiding

Deze specificatie beschrijft het onboarding protocol voor de DVPA-s component.

Achtergrond en doel van de DVPA-s koppeling wordt beschreven in DVPA-s API.

Aannames en conventies

De API is RESTful opgezet en maakt gebruik van JSON voor request- en response-payloads. Deze specificatie beschrijft per endpoint de gebruikte HTTP-methode, het pad en de JSON-structuur van request en response.

Transport en authenticatie

• Alle communicatie verloopt via HTTPS.

• Het XIS moet de serverauthenticiteit valideren.

• Authenticatie vindt plaats via:

  • mTLS (aanbevolen), of
  • een bearer token in de Authorization header.

• Authenticatiegegevens worden verkregen via de Link API / onboardingprocedure.

REST en JSON conventies

Basisprincipes

• Requests en responses gebruiken JSON.

• Encoding: UTF-8.

• Content-Type bij requests met body:

  Content-Type: application/json

• Indien van toepassing:

  Accept: application/json

• Basis-URL:

  https://<systeem-url>/mdlink/v1/

HTTP-semantiek

Methode	Betekenis
GET	Ophalen van een resource
POST	Aanmaken van een nieuwe resource
PUT	Volledig vervangen van een bestaande resource
DELETE	Permanent verwijderen van een resource

De server gebruikt standaard HTTP statuscodes conform REST-principes.

Responses en foutafhandeling

Succesvolle responses

• 2xx HTTP statuscode
• Indien van toepassing bevat de response een JSON body met de gevraagde resource.

Voorbeeld:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "connectionRequestIdentifier": "1234-abcd"
}

Fouten – Problem Details (RFC 7807)

Bij fouten retourneert de server:

• Een passende HTTP statuscode (4xx of 5xx)

• Content-Type:

  application/problem+json

De response body voldoet aan RFC 7807 Problem Details en bevat minimaal:

Veld	Type	Beschrijving
type	string	URI die het type fout beschrijft
title	string	Korte omschrijving van het probleem
status	integer	HTTP statuscode
detail	string	Technische detailinformatie (optioneel)
instance	string	Identificatie van de specifieke fout (optioneel)

Voorbeeld

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://dvpa-s.example/errors/authentication-required",
  "title": "Authenticatie vereist",
  "status": 401,
  "detail": "Er zijn geen geldige credentials meegegeven."
}

Mapping van applicatiefouten

TODO uitwerken van verschillende error types invulling

Error code	Beschrijving
-9001	Er zijn geen credentials meegegeven (token of TLS certificaat); er is geen interactie mogelijk.
-9011	Het systeem is niet geregistreerd (of token bestaat niet).
-9021	Het systeem is bekend maar (nog) niet geautoriseerd voor deze operatie.
-9031	Het systeem is bekend maar heeft nog geen metadata geregistreerd.
-9041	Algemeen: operatie niet toegestaan.
-32602	Algemeen: operatie voldoet niet aan specificatie.
-32000	Algemeen: interne applicatie fout (graag melden).

NB: -9021 geeft aan dat de koppeling nog niet bruikbaar is; credentials zijn nog geldig. NB: -9041 bijv. wanneer client een resource probeert te lezen/schrijven waar geen toegang toe is.

Ownership

Resources horen bij het XIS dat ze aanmaakt. Andere systemen kunnen ze niet zien.

• Resource identifiers zijn uniek per owner
• IDs mogen voor andere systemen niet afleidbaar zijn

Testen van de verbinding

Om te controleren of de verbinding en DVPA-s functioneren is er een ping endpoint ingericht. Dit endpoints is het enige endpoint waar geen geldige authenticatie is vereist.

Voorbeeld

GET /mdlink/v1/ping
Content-Type: application/json
... 

"pong"

Systeem koppelen (onboarding)

Voordat de DPVA-r toegankelijk is voor het XIS, moet het XIS een onboardingprocedure doorlopen. Deze procedure wordt in dit hieronder toegelicht.

De onboardingprocedure bestaat uit 4 stappen:

1. het XIS zet een verbinding op met de DVPA-s via HTTP over mutual TLS (mTLS)
2. De DVPA-s valideert het verbindingsverzoek
3. De DVPA-s stuurt een eenmalige autorisatietoken naar het XIS via een out-of-band transport
4. het XIS verstuurt de autorisatietoken via de oorspronkelijke mTLS-verbinding

Deze methodiek gaat ervan uit dat het XIS en de DVPA-s worden beheerd door verschillende partijen. Als dit niet het geval is, is het zoeken en contact opnemen met de bevragende partij uiteraard niet nodig. Maar het genereren en terugsturen van het connectionRequestToken (stap 2. en 3.) blijven nodig om de koppeling te voltooien.

1. Een verbinding aanvragen

Wanneer het XIS een verbinding wil aanvragen, stuurt deze een HTTP POST-verzoek naar het endpoint /mdlink/v1/onboarding met een JSON-payload die de volgende informatie bevat:

key	Type	Beschrijving
organizationFormalName	string	Formele (KvK-)naam van de organisatie die het XIS beheert
organizationIdentifier	string	Identificatie van de organisatie (HAP), bijvoorbeeld een UZI (URA)-identificatie of KvK-nummer
organizationIdentifierType	string	Type dat wordt gebruikt als organizationIdentifier, bijvoorbeeld AGB- of KvK-nummer (voorbeelden)

Als resultaat wordt een connectionRequestIdentifier geretourneerd. Deze identificatie is uniek voor dit verbindingsverzoek. De connectionRequestIdentifier is nodig om de verbinding in een latere stap te voltooien en moet daarom worden opgeslagen voor later gebruik.

Voorbeeld

Als een client een verbinding met de DVPA-s wil aanvragen, stuurt deze het volgende verzoek naar het /mdlink/v1/onboarding-endpoint van de DVPA-s:

POST /mdlink/v1/onboarding
Content-Type: application/json
... 

{
    "organisationFormalName": "Apotheek De Vlinder",
    "organisationIdentifier": "67891234",
    "organisationIdentifierType": "KvK"
}

Als resultaat retourneert de DVPA-s de volgende response:

200 OK
Content-Type: application/json
...

{
    "connectionRequestIdentifier": "1234-abcd"
}

2. Het verbindingsverzoek valideren

Het doel van dit verzoek is dat de eigenaar van de DVPA-s kan controleren of het verzoek legitiem is. Dit kan worden gedaan door de aanvragende organisatie op te zoeken in het KvK-register en/of het AGB-register. De volgende stap is om contact op te nemen met de organisatie via de contactgegevens (bijvoorbeeld het postadres) die in deze officiële registers zijn opgenomen, en vast te stellen dat het verzoek daadwerkelijk door deze organisatie is geïnitieerd.

Als dat het geval is, wordt het verbindingsverzoek als geldig gemarkeerd en wordt een connectionRequestToken aangemaakt en gekoppeld aan dit verbindingsverzoek. Deze connectionRequestToken moet, in combinatie met de unieke connectionRequestIdentifier, door het XIS worden gebruikt om de verbinding te voltooien.

3. Verstuur de connectionRequestToken naar het XIS via een out-of-band transport

Vervolgens dient de eigenaar van de DVPA-s deze connectionRequestToken via een out-of-band transport naar de eigenaar van het XIS te sturen, bijvoorbeeld per post of telefonisch.

4. Verstuur de verkregen connectionRequestToken naar de DVPA-s om de verbinding te voltooien

Zodra de eigenaar van het XIS de connectionRequestToken heeft ontvangen, kan deze worden gebruikt om het verbindingsverzoek te voltooien door een HTTP POST-verzoek te sturen naar het endpoint /mdlink/v1/onboarding/{connectionRequestIdentifier}. De JSON-payload doe wordt meegestuurd bevat de volgende informatie:

key	Type	Beschrijving
connectionRequestToken	string	Het verkregen connectionRequestToken

Hierbij is de connectionRequestIdentifier uit stap #1 vereist. De connectionRequestToken is gekoppeld aan dit specifieke verbindingsverzoek.

Dus als de in stap #1 verkregen connectionRequestIdentifier gelijk is aan 1234-abcd en de connectionRequestToken gelijk is aan 5678-efgh, dan moet het volgende verzoek worden gedaan om de verbinding te voltooien:

POST /mdlink/v1/onboarding/1234-abcd
Content-Type: application/json
...

{
  "connectionRequestToken": "5678-efgh"
}

Als het verzoek succesvol wordt gevalideerd — dat wil zeggen dat de connectionRequestToken daadwerkelijk hoort bij dit verbindingsverzoek — dan wordt de verbinding door de DVPA-s voltooid en kunnen de overige DVPA-s API-methoden door het XIS worden aangeroepen met hetzelfde clientcertificaat dat is gebruikt om deze verbinding op te zetten.

De koppeling beheren

Nadat de koppeling is opgezet kan het XIS de koppeling beheren, D.W.Z aanvullende informatie van het XIS system aanvullen en / of de authenticatie gegevens aanpassen (sleutel rotatie). Hiervoor zijn de volgende endpoints beschikbaar:

Method	Endpoint	Beschrijving
GET	/mdlink/v1/xis	Opvragen van momenteel bekende gegevens van XIS
PUT	/mdlink/v1/xis/info	Aanpassen XIS systeem informatie
PUT	/mdlink/v1/xis/auth	Aanpassen XIS authenticatie gegevens (sleutel rotatie)
DELETE	/mdlink/v1/xis	Koppeling verwijderen

TODO: Verdere uitwerking vereist

Informatie opvragen over DVPA-s

Als het gekoppelde XIS informatie over de DVPA-s wil opvragen, stuurt deze een HTTP GET-verzoek naar het endpoint /mdlink/v1/dvpa-s

TODO: Verdere uitwerking vereist