Tallennus ja korvaus
Sote-luovutusluvan tallennuksessa ja korvauksessa käytettävän HTTP-pyynnön tiedot välittyvät HTTP header- ja body-osuuksiin jaettuna. Tällä sivulla kuvataan nämä osuudet tarkemmin tallennus- ja korvauspyyntöjen osalta.
HTTP pyyntö (request)
Tallennuspyyntö välitetään palvelulle HTTP pyyntönä (request) POST-metodilla FHIR-palvelun endpoint:in juureen. POST: [base]/
Esim. POST http://example.org/baseR4/
Myös korvauspyyntö välitetään palvelulle HTTP pyyntönä (request) POST-metodilla FHIR-palvelun endpoint:in juureen. POST: [base]/
Esim. POST http://example.org/baseR4/
HUOM. Myös korvauksessa käytetään POST-metodia, sillä HTTP body-osuudessa oleva FHIR-resurssi on Bundle ja tyypiltään transaction!
URL:in muoto noudattaa sekä tallennuksessa että korvauksessa FHIR määrittelyjä (Style Guide). Eri ympäristöjen käytettävät juuret ilmoitetaan erikseen eikä niitä julkisteta tässä implementointioppaassa.
HTTP pyynnön header
Tallennuksen ja korvauksen HTTP-pyyntöjen header-osuudet noudattavat Kanta-palveluiden yhteisiä Kanta FHIR HTTP header ja Kanta JSON Web Token määrittelyitä ja näissä kuvattuja tietoja ja tietojen pakollisuuksia.
HTTP pyynnön body
HTTP pyynnön body-osuus sisältää pyynnössä välitettävät resurssit. Alla olevassa kuvassa on kuvattu HTTP body-osuuden rakentuminen:
Sekä uuden Sote-luovutusluvan tallennuksessa Tahdonilmaisupalveluun että Tahdonilmaisupalveluun jo tallennetun Sote-luovutusluvan korvauksessa Sote-luovutusluvan tiedot lähetetään Tahdonilmaisupalveluun Bundle-resurssilla, joka sisältää yksi tai kaksi Consent- ja Provenance -paria. Jos samalla Bundle-resurssilla tuodaan kaksi paria, tulee sen sisältämien Consent-resurssien sisältää eri luovutusluvat (eli lupa luovuttaa terveydenhuollosta sosiaalihuoltoon ja lupa luovuttaa sosiaalihuollosta terveydenhuoltoon). Consent -resurssi sisältää varsinaisen sote-luovutusluvan sisällön ja Provenance-resurssi siihen liittyvät metatiedot.
Bundlen tyyppi on transaction eli käytännössä molemmat resurssit käsitellään omina operaatioinaan ja molempien operaatioiden on onnistuttava, jotta tallennus tai korvaus on kokonaisuudessa onnistunut.
Bundle-resurssi allekirjoitetaan sähköisellä allekirjoituksella, jolla varmistetaan vaatimus välitettävien resurssien muuttumattomuudesta pysyväissäilytyksessä. Sähköinen allekirjoitus on määritelty erillisessä määrittelyssä Kanta FHIR sähköinen allekirjoitus.
Sote-luovutusluvan tiedot sisältävästä Consent-resurssista viitataan seuraavaan resurssiin, jotka esitetään Consent-resurssin sisällä olevassa contained-rakenteessa:
- Patient (asiakkaan tiedot, jonka lupaa käsitellään)
Sote-luovutusluvan metatiedot sisältävästä Provenance-resurssista viitataan tarpeen mukaan seuraaviin resursseihin, jotka esitetään Provenance-resurssin sisällä olevassa contained-rakenteessa:
- Patient (asiakkaan tiedot, jonka lupaa käsitellään)
- Practitioner/Patient/RelatedPerson (sote-luovutusluvan tallentaja: ammattilainen, asiakas tai puolesta-asioija)
- Device (tiedot tuottanut tietojärjestelmä)
Tallennus ja resurssin looginen tunniste (id), käytettävä HTTP metodi
Tahdonilmaisupalvelu hallinnoi Consent-resurssi-instanssin yksilöivää tunnusta eli FHIR resurssi-instanssin loogista tunnistetta (id). Huom. tämä on eri tunniste kuin Sote-luovutusluvan tietosisällöstä löytyvä tunniste (Consent.identifier).
Sote-luovutuslupaa tallentavan tahon on luotava uuden Sote-luovutusluvan tallennuksen yhteydessä ”väliaikainen” looginen tunniste Consent-resurssi-instanssille ja annettava se Consent-resurssiin liittyvässä Bundle.entry:n fullUrl-elementissä. Tätä loogista tunnistetta fullUrl-elementissä on käytettävä viittauksessa Provenance-resurssista (Provenance.target.reference) Consent-resurssiin.
Tahdonilmaisupalvelu tuottaa tallennuksen yhteydessä Consent-resurssi-instanssille globaalisti yksilöivän tunnuksen ja korvaa tallentavan tahon resurssi-instanssiin fullUrl-elementissä antaman loogisen tunnisteen (id). Tahdonilmaisupalvelun luoma resurssi-instanssin looginen tunniste (id) palautetaan pyynnön vastauksessa onnistuneen tallennuksen yhteydessä (huom. tätä tunnistetta on käytettävä, jos Sote-luovutuslupaa päivitetään).
Molempien resurssien Bundle.entry.request.method-elementtien arvoksi laitetaan POST.
Alla esimerkki tallennuksessa käytettävästä Bundle-resurssista ja viittauksesta Provenance-resurssi-instanssista Consent-resurssi-instanssiin.
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143",
"resource": {
"resourceType": "Consent",
...
},
"request": {
"method": "POST",
"url": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143"
}
},
{
...
"resource": {
"resourceType": "Provenance",
...
"target": {
"reference": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143",
"display": "Sote-luovutuslupa"
},
...
}
"request": {
"method": "POST",
"url": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143"
}
}
],
{
"signature": {
...
}
}
}
Korvaus ja resurssin looginen tunniste (id), käytettävä HTTP metodi
Sote-luovutusluvan korvauksessa Consent-resurssi-instanssin loogisena tunnisteena on käytettävä Tahdonilmaisupalvelun resurssi-instanssille luomaa resurssi-instanssin yksilöivää loogista tunnistetta (id).
Consent-resurssiin liittyvän Bundle.entry.request.ifMatch-elementin arvoksi on annettava resurssi-instanssin viimeisin versionumero eli haun vastaussanomalla resurssin response-elementin etag-kentässä palautettu versionumero (tai tallennuksen vastausanomassa palautunut versionumero jos voi olla varma, että versionumero ei ole ensimmäisen tallennuksen jälkeen muuttunut). Sote-luovutusluvan korvaus onnistuu vain, kun ifMatch-elementissä välitetään versionumero, joka vastaa kyseisen sote-luovutusluvan (eli joko luvan terveydenhuollosta sosiaalihuoltoon tai sosiaalihuollosta terveydenhuoltoon) viimeisintä eli voimassa olevaa versiota Tahdonilmaisupalvelussa. Tahdonilmaisupalvelu huolehtii muuten korvattavan resurssi-instanssin versioinnista.
Consent-Bundle.entry.request.url-elementin arvoksi on annettava viittaus korvattavan Consent-resurssi-instanssin loogiseen tunnisteeseen (id).
Provenance-resurssista luodaan korvaustilanteessa kokonaan uusi instanssi, sitä ei versioida. Näin Provenance-resurssi-instanssit ovat aina Consent-resurssi-instansseihin liittyen versiokohtaisia. Korvauksessa pitää ilmoittaa korvauksen syy ja se välitetään Provenance.activity-elementillä.
Consent-resurssin osalta Bundle.entry.request.method-elementtien arvoksi laitetaan PUT ja Provenance-resurssin osalta POST.
Alla esimerkki korvauksessa käytettävästä Bundle-resurssista ja sen sisällä olevista Consent- ja Provenance-resurssi-instansseista sekä korvauksen osalta merkittävistä tiedoista.
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"resource": {
"resourceType": "Consent",
"id": "ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
...
},
"request": {
"method": "PUT",
"url": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"ifMatch": "W/\"1\""
}
},
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf145"
"resource": {
"resourceType": "Provenance",
...
"target": {
"reference": "Consent/ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/2",
"display": "Sote-luovutuslupa"
},
...
"activity": {
"coding": {
"system": "urn:oid:1.2.246.537.5.40178.2008",
"code": "1",
"display": "Korjaus"
}
}
},
"request": {
"method": "POST",
"url": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf145"
}
}
],
{
"signature": {
...
}
}
}
HTTP vastaus (response)
HTTP vastauksen tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna.
Vastauksen HTTP header
Tallennuksen ja korvauksen HTTP-vastauksen header-osuus noudattaa Kanta-palveluiden yhteistä Kanta FHIR HTTP header määrittelyä ja siinä kuvattuja tietoja ja tietojen pakollisuuksia.
Vastauksen HTTP body
HTTP vastauksen body-osuudessa vastauksena palautuu Bundle-resurssi ja sen tyyppi on transaction-response.
Onnistuneen operaation tuloksena Tahdonilmaisupalvelu palauttaa Bundle-resurssin, joka sisältää jokaista lähetettyä entryä vastaavan responsen. Response-elementissä on seuraavat tiedot:
- status-elementissä ilmoitetaan resurssin tallennuksen HTTP-statuskoodi
- location-elementissä ilmoitetaan tallennetun resurssin tyyppi, Tahdonilmaisupalvelun tuottama yksilöivä tunnus resurssille ja resurssin versionumero
- etag-elementissä ilmoitetaan resurssin versionnumero
Esimerkki Tahdonilmaisupalvelun palauttamasta vastaussanomasta onnistuneessa tallennuksessa
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"response": {
"status": "201 Created",
"location": "Consent/ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/1",
"etag": "W/\"1\""
}
},
{
"fullUrl": "urn:uuid:2639da1f-e03c-4faf-aec0-6007c4de7265",
"response": {
"status": "201 Created",
"location": "Provenance/2639da1f-e03c-4faf-aec0-6007c4de7265/_history/1",
"etag": "W/\"1\""
}
}
]
}
Esimerkki Tahdonilmaisupalvelun palauttamasta vastaussanomasta onnistuneessa korvauksessa
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"response": {
"status": "200 OK",
"location": "Consent/ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/2",
"etag": "W/\"2\""
}
},
{
"fullUrl": "urn:uuid:2639da1f-e03c-4faf-aec0-6007c4de7267",
"response": {
"status": "201 Created",
"location": "Provenance/2639da1f-e03c-4faf-aec0-6007c4de7267/_history/1",
"etag": "W/\"1\""
}
}
]
}
Vastaussanoma virhetilanteessa
Virhetilanteissa vastauksena palautuu HTTP virhestatuskoodi sekä HTTP bodyssa OperationOutcome resurssi-instanssi, jolla ilmoitetaan tarkempi virhe. Tahdonilmaisupalvelussa käytettävää OperationOutcome-resurssia ei ole profiloitu.
Implementointioppaan OperationOutcome-sivulla on kuvattu tarkemmin, miten Tahdonilmaisupalvelu palauttaa virheilmoitukset OperationOutcome-resussilla.