| Info |
|---|
Beskrivelse af snitflade snitflader som Orkestreringskomponenten udstiller og som anvendes af visningklienter der implementerer overbliksvisninger. På siden vises kun nyeste version af snitflader. Redaktør: Kurt Hansen |
| Expand |
|---|
...
|
...
|
...
|
1 Hentsagsliste
...
1.
...
Introduktion
Servicen ”hentsagsliste” er en service som orkestreringskomponenten udstiller til visningsklienter, hvor visningsklienten, fx borger.dk, kan hente en liste over sager for en borger. Borgeren skal være identificeret med et CPR-nr, da dette er den primære nøgle ved hentning af sagsliste.
Servicen returnerer en liste over sager for borgeren, fra de datakilder der er tilsluttet Orkestreringskomponenten. Listen indeholder et begrænset antal attributter, der anvendes til at danne en overbliksliste over sager for borgeren.
1.2 Servicebeskrivelse
Servicenavn: /hentsagsliste
Beskrivelse: Servicen kaldes med et CPR-nr for den borger, der skal hentes sagsdata for. Servicen returnerer en liste af sager for borgeren. Den returnerede liste indeholder et begrænset antal attributter herunder status for sagen, og er designet til at understøtte visning af en overbliksliste over sager for den givne borger.
URL: https://orkestreringskomponenten.dk/hentsagsliste/v0.9.1
Metode: servicen anvender http-verb: POST
Parametre:
...
Navn
...
Obligatorisk
...
Type
...
Beskrivelse
...
CPR-nr
...
Ja
...
String
...
Personnummer for bruger logget ind i visningsklient
...
kommunenr
...
Ja
...
String
...
Kommunenr for bopælskommune for borger angivet ved CPR-nr. Parameter skal anvendes af KOMBIT for at fremsøge data.
...
visningsklientID
...
Ja
...
String
...
ID for visningsklient, således at dette kan anvendes til brug for udvælgelse af datakilder og aftalestyring.
...
Token
...
Ja
...
String
...
Sikkerhedstoken fra visningsklient, der medsendes til orkestreringskomponent for videresendelse til datakilder så disse har mulighed for at validere om der skal returneres data og hvilke data om borgeren.
Parameter udgår
Response:
...
http-response
...
Beskrivelse
...
200 (OK)
...
Kald til service er succesfuld og fremfundne sagsliste-data returneres.
...
400 (bad request)
...
Fejl i visningsklient i kald til service
...
401 (Unauthorized)
...
Visningsklient er ikke autoriseret til at kalde service
...
500 (Internal Server Error)
...
Fejl internt i orkestreringskomponenten
Data-svar (her angivet i JSON):
{
“sagslistedata” : {
”type” : “array”,
“items” : {
“type” : “BorgervendtSagListe”
}
}
}
”BorgervendtSagListe” er specificeret i skemafilen: BorgervendtsagUdvekslingsskemaer
Fejl (error):
For fejl ved kald til en datakilde, fx timeout, vil der i det sammenstillede svar, blive inkluderet et fejlobjekt, der følger nedenstående struktur:
<fejlstruktur>
<type />
<title />
<status />
<detail />
<instance />
<datakilde />
</fejlstruktur>
Hvis der er fejl for flere datakilder, vil der være en fejlstruktur pr. datakilde.
2 Hentsagsdetaljer
2.1 Introduktion
Servicen ”hentsagsdetaljer” er en service som orkestreringskomponenten udstiller til visningsklienter, hvor visningsklienten, fx borger.dk, kan hente detaljerede informationer for de sager en borger har. Borgeren skal være identificeret med et CPR-nr, da dette er den primære nøgle ved hentning af sagsdetaljer.
Servicen returnerer sagsdetaljer for den specifikke sag der er angivet i kaldet, fra de datakilder der er tilsluttet Orkestreringskomponenten. Der kan kun hentes detaljer for en sag pr. kald.
2.2 Servicebeskrivelse
Servicenavn: /hentsagsdetaljer
Beskrivelse: Servicen kaldes med et CPR-nr for den borger, der skal hentes sagsdetaljer for. Der skal specifikt angives en sag, der ønskes sagsdetaljer for.
Hvis det angivne ”sagsID” ikke er for en sag for den angivne borger, returnerer servicen et tomt svar.
URL: https://orkestreringskomponenten.dk/hentsagsdetaljer/v0.9.1
Metode: servicen anvender http-verb: POST
Parametre:
...
Navn
...
Obligatorisk
...
Type
...
Beskrivelse
...
CPR-nr
...
Ja
...
String
...
Personnummer for bruger logget ind i visningsklient
...
visningsklientID
...
Ja
...
String
...
ID for visningsklient, således at dette kan medsendes ved kald til datakilder fra OK, til brug for udvælgelse af data og aftalestyring.
...
sagsID
...
ja
...
Sagsnummer
...
Nøgle for sag der skal hentes detaljer for.
...
datakilde
...
Ja
...
Datakilde-struktur
...
Visningsklient skal medsende datakilde-struktur for den udvalgte sag, som blev modtaget fra kald til overbliksliste. Der skal ikke ændres i indholdet af strukturen.
Datakilde er specificeret i BorgervendtSag-xsd.xsd
...
myndighedskode
...
Ja
...
string
...
Visningsklient skal medsende myndighedsKode for den udvalgte sag, som blev modtaget fra kald til overbliksliste. MyndighedsKode skal hentes fra entiteten Myndighed relateret til den udvalgte sag.
Response:
...
http-response
...
Beskrivelse
...
200 (OK)
...
Kald til service er succesfuld og fremfundne sagsdetalje-data returneres.
...
400 (bad request)
...
Fejl i visningsklient i kald til service
...
401 (Unauthorized)
...
Visningsklient er ikke autoriseret til at kalde service
...
500 (Internal Server Error)
...
Fejl internt i orkestreringskomponenten
Data-svar (her angivet i JSON):
{
“sagsdetaljedata” : {
“type” : “BorgervendtSag”
}
}
”BorgervendtSag” er specificeret i skemafilen: Borgervendtsa. Udvekslingsskemaer
Fejl (error):
Ingen fejlstruktur for detalje.
3 Hentbevillingsliste
3.1 Introduktion
Servicen ”hentbevillingsliste” er en service som orkestreringskomponenten udstiller til visningsklienter, hvor visningsklienten, fx borger.dk, kan hente en liste over ydelser som en borger modtager eller har modtaget. Borgeren skal være identificeret med et CPR-nr, da dette er den primære nøgle ved hentning af bevillingsliste.
Servicen returnerer en liste over ydelser for borgeren, fra de datakilder der er tilsluttet Orkestreringskomponenten. Listen indeholder et begrænset antal attributter, der anvendes til at danne en overbliksliste over ydelser for borgeren.
3.2 Servicebeskrivelse
Servicenavn: /hentbevillingsliste
Beskrivelse: Servicen kaldes med et CPR-nr for den borger, der skal hentes økonomiske ydelser for. Servicen returnerer en liste af ydelser for borgeren. Den returnerede liste indeholder et begrænset antal attributter, og er designet til at understøtte visning af en overbliksliste over ydelser for den givne borger.
URL: https://orkestreringskomponenten.dk/hentbevillingsliste/v2.0.0
Metode: servicen anvender http-verb: POST
Parametre:
...
Navn
...
Obligatorisk
...
Type
...
Beskrivelse
...
CPR-nr
...
Ja
...
String
...
Personnummer for bruger logget ind i visningsklient
...
kommunenr
...
Ja
...
String
...
Kommunenr for bopælskommune for borger angivet ved CPR-nr. Parameter skal anvendes af KOMBIT for at fremsøge data.
...
visningsklientID
...
Ja
...
String
...
ID for visningsklient, således at dette kan anvendes til brug for udvælgelse af datakilder og aftalestyring.
Response:
...
http-response
...
Beskrivelse
...
200 (Ok)
...
Kald til service er succesfuld og fremfundne bevillingsliste-data returneres.
...
400 (bad request)
...
Fejl i visningsklient i kald til service
...
401 (Unauthorized)
...
Visningsklient er ikke autoriseret til at kalde service
...
500 (Internal Server Error)
...
Fejl internt i orkestreringskomponenten
Data-svar (her angivet i JSON):
{
“bevillingsdata” : {
”type” : “array”,
“items” : {
“type” : “BorgervendtBevillingsListe”
}
}
}
”BorgervendtBevillingsListe” er specificeret i skemafilen: BorgervendtYdelse. Udvekslingsskemaer
Fejl (error):
For fejl ved kald til en datakilde, fx timeout, vil der i det sammenstillede svar, blive inkluderet et fejlobjekt, der følger nedenstående strutkur:
<fejlstruktur>
<type />
<title />
<status />
<detail />
<instance />
<datakilde />
</fejlstruktur>
Hvis der er fejl for flere datakilder, vil der være en fejlstruktur pr. datakilde.
4 Hentbevillingsdetaljer
4.1 Introduktion
Servicen ”hentbevillingsdetaljer” er en service som orkestreringskomponenten udstiller til visningsklienter, hvor visningsklienten, fx borger.dk, kan hente detaljerede informationer for de ydelser en borger modtager. Borgeren skal være identificeret med et CPR-nr, da dette er den primære nøgle ved hentning af detaljer om ydelser.
Servicen returnerer detaljer for den specifikke ydelse der er angivet i kaldet, fra den datakilde der er tilsluttet Orkestreringskomponenten.
4.2 Servicebeskrivelse
Servicenavn: /hentbevillingsdetaljer
Beskrivelse: Servicen kaldes med et CPR-nr for den borger, der skal hentes ydelsedetaljer for. Der skal specifikt angives en ydelse som der ønskes detaljer for.
Der kan kun hentes ydelsesdetaljer for en udvalgt ydelse angivet ”ID” som input parameter i kaldet til servicen.
Hvis det angivne ”ID” ikke er for ydelser for den angivne borger, returnerer servicen et tomt svar.
URL: https://orkestreringskomponenten.dk/hentbevillingsdetaljer/v0.9.1
Metode: servicen anvender http-verb: POST
Format: Service understøtter både JSON og XML
Parametre:
...
Navn
...
Obligatorisk
...
Type
...
Beskrivelse
...
CPR-nr
...
Ja
...
String
...
Personnummer for bruger logget ind i visningsklient
...
visningsklientID
...
Ja
...
String
...
ID for visningsklient, således at dette kan medsendes til ved kald til datakilder fra OK, til brug for udvælgelse af data og aftalestyring.
...
ydelseID
...
Ja
...
String
...
Nøgle for den ydelse der skal hentes detaljer for.
...
myndighedskode
...
Ja
...
string
...
Visningsklient skal medsende myndighedsKode for den udvalgte ydelse, som blev modtaget fra kald til overbliksliste. MyndighedsKode skal hentes fra entiteten Myndighed relateret til den udvalgte ydelse.
...
datakilde
...
Ja
...
Datakilde-struktur
...
Visningsklient skal medsende datakilde-struktur for den udvalgte ydelse, som blev modtaget fra kald til overbliksliste. Datakilde er specificeret i BorgervendtYdelse-xsd.xsd
Response:
...
http-response
...
Beskrivelse
...
200 (OK)
...
Kald til service er succesfuld og fremfundne økonomisk ydelsesdetalje-data returneres.
...
400 (bad request)
...
Fejl i visningsklient i kald til service
...
401 (Unauthorized)
...
Visningsklient er ikke autoriseret til at kalde service
...
500 (Internal Server Error)
...
Fejl internt i orkestreringskomponenten
Data-svar (her angivet i JSON):
{
“borgervendtbevillingdata” : {
“type” : “BorgervendtBevilling”
}
}
”BorgervendtBevilling” er specificeret i skemafilen: BorgervendtYdelse. Udvekslingsskemaer
Fejl (error):
Ingen fejlstruktur for detalje.
5 Sikkerhed
Der anvendes best practices for identifikation af og validering af akkreditiv ved kald til webservices, gennem sikring af identiteten af både den kaldende og udstillende part vha. certifikater (Two way TLS).
Korreleringsnøgle til logning placeres i http-header for REST-services i header elementet ”x-correlation-id”.
Snitfladebeskrivelser er opdelt i et dokument per datamodel. Hvis der er flere versioner af en snitflade for en datamodel, vil der være et dokument per version.
Snitfladebeskrivelser
Datamodel | Snitfladedokumentation | ||||
|---|---|---|---|---|---|
Borgervendt Sag v2.0.1 |
| ||||
Borgervendt Økonomisk ydelse v1.0.0 |
| ||||
Borgervendt Ydelse v2.1.0 (Serviceydelser og hjælpemidler) |
| ||||
Borgervendt Aftaler og frister v1.0.1 |
| ||||
Borgervendt Gæld og betalinger v1.0.0 |
| ||||
Borgervendt Akkreditiv v1.1.0 (Beviser, attester og tilladelser) |
| ||||
Borgervendt Stamdata v1.0.0 |
|
|
2. Fejlhåndtering og fejl-struktur
Fejl der optræder på snitflader mod datakilder, håndteres af Orkestreringskomponenten, men rapporteres videre til visningsklienter sammen med fejl fra Orkestreringskomponenten i data-strukturen , der returneres til visningsklienten, således at visningsklienter kan vise relevant information om fejl til borgere.
Følgende fejltyper kan returneres fra Orkestreringskomponenten.
Type | Title | Status |
Agreement-error | Internal error in OK during agreement control | 500 |
Data-source-error | Error calling data source | Get from Data source response status |
Data-source-timeout-error | Timeout reached for data source | 408 |
Data-source-internal-error | Internal error at data source | 500 |
Data-source-security-error | Security validation error when calling data source | 400 |
Data-source-format-error | Invalid format in response from data source | 422 |
Input-param-error | Invalid input parameter from display client | 400 |
Circuit-breaker-error | Circuit breaker is currently active for data source | 502 |
Data-validation-error | Validation error of data in response from data source | 400 |
Fejlstruktur.
Fejl returneres i en fejlstruktur der følger RFC 7807, og har følgende skema-definition.
"fejlstruktur": {
"type": "object",
"properties": {
"error": {
"oneOf": [
{
"$ref": "#/definitions/ErrorStructure"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"ErrorStructure": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"detail": {
"type": "string"
},
"instance": {
"type": "string"
},
"datakilde": {
"type": [
"string",
"null"
]
}
},
"required": [
"type",
"title",
"status",
"detail",
"instance"
],
"additionalProperties": false
}
Eksempel på udfyldt fejlstruktur.
<fejlstruktur>
<type>https://orchestrationcomponent.digst.dk/probs/Input-param-error</type>
<title>Invalid input parameter from display client</title>
<status>400</status>
<detail>There was an error when validating the display client</detail>
<instance>https://orchestrationcomponent.digst.dk/correlationID/78306376-
8f3c-4630-890a-4f3d490722f1</instance>
<datakilde/>
</fejlstruktur>
| Expand | ||
|---|---|---|
| ||
|