Haun vastaussanomat

Kanta-palvelut palauttaa vastauksena HTTP-vastauksen (response), jossa tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna.

HTTP-vastauksen header

HTTP-vastauksen header-osuus noudattaa Kanta-palvelujen yhteistä Kanta FHIR HTTP header määrittelyä. Potilastietovarannon palauttaman HTTP-vastauksen tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta FHIR HTTP-header taulukon 3.1 Kanta-palveluiden HTTP pyynnön header kentät sarakkeessa PTA ja Sosiaalihuollon asiakastietovarannon palauttaman HTTP-vastauksen sarakkeessa SHA.

HTTP-vastauksen body

Onnistuneessa haussa Kanta-palvelut palauttaa HTTP-statuskoodin 200 OK ja vastauksen HTTP-bodyssa Bundle-resurssi-instanssin, jonka tyyppi (type) on searchset tai history. Bundle-resurssi-instanssin tyyppi on searchset, kun hakeva järjestelmä on hakenut viimeisimmät versiot search-interaktiolla ja history, kun hakeva järjestelmä on hakenut kaikki versiot history-interaktiolla. Sosiaalihuollon asiakastietovarannon palauttaman Bundle-resurssi-instanssin tyyppi on aina searchset.

Kanta-palvelut ilmoittaa palautettujen hakutulosten määrän Bundlen total-elementissä. Merkinnän toimintakyvystä ja toimintakykyarvioiden tiedot palautetaan Observation-resursseissa ja niihin liittyvät metatiedot Provenance-resursseissa, jotka ovat Bundlen entry-elementin sisällä.

Alla on esimerkki Bundle resurssi-instanssista, jonka sisällä palautetaan kaksi Observation-resurssia ja niiden metatiedot Provenance-resursseilla.

Esimerkki Kanta-palvelujen palauttamasta vastaussanomasta onnistuneessa haussa

{
  "resourceType" : "Bundle",
  "id" : "92685db0-1b58-4cea-b1fa-289e8ab58811",
  "type" : "searchset",
  "total" : 2,
  "link" : [{
    "relation" : "self",
    "url" : "https://example.com/base/Observation?patient=347&_include=Observation.provenance&_count=2"
  },
  {
    "relation" : "next",
    "url" : "https://example.com/base/Observation?patient=347&searchId=ff15fd40-ff71-4b48-b366-09c706bed9d0&page=2"
  }
  ],
  "entry" : [{
    "resource" : {
      "resourceType" : "Observation",
      "id" : "1234"
    },
    "search" : {
      "mode" : "match"
    }
  },
  {
    "resource" : {
      "resourceType" : "Provenance",
      "id" : "2345"
    },
    "search" : {
      "mode" : "include"
    }
  },
    {
    "resource" : {
      "resourceType" : "Observation",
      "id" : "3456"
    },
    "search" : {
      "mode" : "match"
    }
    },
    {
    "resource" : {
      "resourceType" : "Provenance",
      "id" : "4567"
    },
    "search" : {
      "mode" : "include"
    }
  }
 ]
}

Jos Kanta-palvelut on suorittanut haun onnistuneesti, mutta haku ei tuota hakutuloksia, Kanta-palvelut palauttaa HTTP-statuskoodin 200 OK ja Bundle-resurssin, jossa hakutulosten määrä (total) on 0. Alla on esimerkki Bundle-resurssista, joka ei palauta hakutuloksia.

Esimerkki Kanta-palvelujen palauttamasta vastaussanomasta onnistuneessa haussa, joka ei tuota hakutuloksia

{
    "resourceType": "Bundle",
    "id": "073ce2b1-4c39-4cae-a479-ca59c8f74fef",
    "type": "searchset",
    "total": 0,
}

Sivutettu vastaus

Sivutetun haun vastauksessa Kanta-palvelut palauttaa hakevalle järjestelmälle tarvittaessa tiedot next ja previous jatkohaun muodostamista varten.

{
    "resourceType": "Bundle",
    "type": "searchset",
    "link": [
        {
            "relation": "self",
            "url": ...
        },
        {
            "relation": next",
            "url": ...
        },
        {
            "relation": "previous",
            "url": ...
        }
    ],
    ...
}

Tarkennukset Sosiaalihuollon asiakastietovarannon palauttamaan hakuvastaukseen

Toimintakykytietojen haussa Sosiaalihuollon asiakastietovarannosta asiakastietovaranto lisää palautettavien Observation-resurssien Observation.meta.security-elementtiin tiedot toimintakykytiedon näyttämisen rajoituksista asiakkaalle tai hänen huoltajalleen, jos asiakas on alaikäinen. Asiakastietovaranto lisää Observation.meta.security-elementtiin seuraavat tiedot:

1. Huoltajaa koskevasta luovutuskielto (AuthorizationConsent), jos asiakas on alaikäinen. Huoltajaa koskeva luovutuskielto on sama tieto kuin Provenance.extension.ProvenanceAuthorizationConsent.extension.AuthorizationConsent -laajennoksessa ilmoitettu tieto. Merkinnän toimintakyvystä ja toimintakykyarvion näyttämisen säännöt alaikäisen asiakkaan huoltajalle on kuvattu Kanta-palvelujen käsikirjassa sosiaalihuollon toimijoille luvussa 5.4 Lapsen asiakirjojen näyttäminen puolesta-asioivalle huoltajalle.

2. Asiakirjan näyttämisen viivästämisen perustelu (ReasonForRestriction), jos merkinnän toimintakyvystä tai toimintakykyarvion näyttäminen kansalaiselle on viivästetytty. Tieto on sama kuin Provenance.extension.ProvenanceReleaseForPatientViewing.extension.ReasonForRestriction-laajennoksessa ilmoitettu perustelu. Merkinnän toimintakyvystä ja toimintakykyarvion näyttämisen säännöt asiakkaalle on kuvattu Kanta-palvelujen käsikirjassa sosiaalihuollon toimijoille luvussa 5.3 Tilannekohtaiset rajoitukset asiakastietojen näyttämiseen.

3. Erityissisältö-tiedon perustelu (SpecialContent). Tieto on sama kuin Provenance.extension.ProvenanceSpecialContent.extension.ReasonForRestriction-laajennoksessa ilmoitettu perustelu. Merkinnän toimintakyvystä ja toimintakykyarvion näyttämisen säännöt asiakkaalle on kuvattu Kanta-palvelujen käsikirjassa sosiaalihuollon toimijoille luvussa 5.3 Tilannekohtaiset rajoitukset asiakastietojen näyttämiseen.

Mitätöityjen toimintakykytietojen palautuminen hauissa

Sosiaalihuollon asiakastietovaranto ei palauta haussa asiakastietojärjestelmälle mitätöityjä merkintöjä toimintakyvystä tai toimintakykyarvioita. Sosiaalihuollossa rekisterinpitäjä voi hakea omassa rekisterissään olevat mitätöidyt merkinnät toimintakyvystä tai toimintakykyarviot Sosiaalihuollon asiakastietovarannon arkistonhoitajan käyttöliittymästä.

Potilastietovarannossa mitätöidyt merkinnät toimintakyvystä tai toimintakykyarviot palautetaan history-interaktiolla tehtävässä haussa. Potilastietovarannon määrittely tarkentuu vuonna 2026.

Vastaussanoma virhetilanteessa

Virhetilanteessa Kanta-palvelut palauttaa Bundle-resurssin entry-elementissä HTTP-virhestatuskoodin ja OperationOutcome-resurssin, jolla ilmoitetaan tarkempi virhe. Kanta-palvelujen virhetilanteessa palauttama vastausssanoma on kuvattu Kanta yhteisten FHIR- ja REST-rajapintamäärittelyjen soveltamisoppaassa sivulla Kanta-rajapinnan virhevastaus.