Organisaatiolle osoitettujen asiakirjojen haku
Sosiaali- ja terveydenhuollon ulkopuolinen organisaatio voi hakea sille osoitettuja asiakirjoja. Voit lukea tästä lisää käyttötapauksesta: Hae organisaatiolle osoitetut asiakirjat.
Asiakirjahaun HTTP-pyyntö
Asiakirjahaku lähetetään Kysely- ja välityspalvelulle HTTP POST-hakupyyntönä. Hakuparametrit lähetetään url-enkoodattuna. Hakupyynnössä tulee olla parametri _query, jonka arvo on get-all-documents:
POST [base]/Communication/_search
Content-Type: application/x-www-form-urlencoded
_query=get-all-documents
Esimerkki
POST https://example.org/baseR4/Communication/_search
Content-Type: application/x-www-form-urlencoded
_query=get-all-documents
Mikäli välitettäviä asiakirjoja on paljon (yli 20), eivät kaikki välitettävät asiakirjat välttämättä mahdu yhteen vastaukseen. Tällöin vastauksessa ilmoitetaan jatkohaun endpoint. Vastauksen rakenteesta ja haun jatkamisesta on kerrottu tarkemmin Asiakirjahakujen vastaus- sivulla.
Esimerkki
https://example.org/baseR4/Communication/_search
Content-Type: application/x-www-form-urlencoded
_query=get-all-documents&organization=urn:oid:1.2.246.10.123456789&viewCode=urn:oid:1.2.246.537.6.12.2002|151&_lastUpdated=ge2025-10-01&_lastUpdated=le2025-10-15&reload=true&result_set_key=1873699d-db2f-4a6d-897e-b0f6c6839928
URL:in muoto noudattaa FHIR määrittelyjä (Style Guide). Eri ympäristöjen käytettävät juuret ilmoitetaan erikseen eikä niitä julkisteta tässä implementointioppaassa.
Asiakirjahaun parametrit
| Parametri | Hakuparametrin tyyppi | Pakollisuus | Toistuvuus | Kuvaus |
|---|---|---|---|---|
| _query | string | Pakollinen | 1..1 | Hakuoperaation nimi. Arvon oltava aina get-all-documents |
| organization | token | Pakollinen | 1..1 | Organisaatio, jolle osoitettuja asiakirjoja haetaan. Hakuparametrissä käytettävä Sanoman vastaanottaja ilmoitettua vastaanottavan organisaation koodia. Muoto: urn:oid: + vastaanottajan koodi. Esimerkki: urn:oid:1.2.246.10.123456789. Hakuparametrin system-osalla hakemista ei tueta. |
| viewCode | token | Ei pakollinen | 0..1 | Asiakirjan näkymätunnus. Hakuparametrissä käytettävä Näkymätunnus ilmoitettuja koodistoja ja niiden arvoja. |
| _lastUpdated | date | Ei pakollinen | 0..2 | Asiakirjan välityspyynnön luontiaika. Tukee prefixejä: eq, le, ge. |
| reload | token | Ei pakollinen | 0..1 | true tai false (default false) - Palautetaanko uudelleen jo haetut mutta kuittaamattomat todistukset |
| result_set_key | token | Ei pakollinen | 0..1 | Seuraavan sivun hakemiseen käytettävä avain. Käytetään vain seuraavan sivun hakemiseen. |
Asiakirjan välityspyynnön luontiajalla tarkoitetaan päivämäärää, jona Kysely- ja välityspalvelu on vastaanottanut potilastietojärjestelmältä pyynnön asiakirjan välittämisestä. Käyttämällä hakuparametria _lastUpdated voidaan tulosjoukkoa tarvittaessa rajata välityspyynnön luontiajankohdan perusteella.
Haku palauttaa aiemmin hakemattomat asiakirjat silloin, kun reload-parametria ei ole annettu tai sen arvo on false. Mikäli aiemmin jo haettu (kuittaamaton) asiakirja halutaan hakea uudelleen, tulee reload-parametri antaa ja sen arvona olla true. Tällöin haku palauttaa sen ehtoja vastaavat asiakirjat, jotka on jo aiemmin haettu, mutta joita ei vielä ole kuitattu. Tämä voi olla tarpeellista esimerkiksi tilanteessa, jossa haetun asiakirjan käsittely epäonnistuu vastaanottajan päädyssä.
FHIR-standardin hakua ohjaavia parametreja _count ja _offset ei tueta, eikä niiden käytöllä ole vaikutusta vastaukseen.
HTTP-pyynnön header
HTTP-pyynnön header-tiedot on kuvattu Kanta-palvelujen yhteisessä FHIR- ja REST-soveltamisoppaassa. Voit lukea lisää oppaan sivulla Kanta HTTP header-tiedot FHIR-rajapinnassa
Kannattaa kuitenkin huomioida erityisesti headerin kenttä X-Request-Id, jonka arvo on oltava yksilöllinen jokaiselle http-pyynnölle. X-Request-Id -headerin tulee olla joko UUID tai OID - muotoinen. Tehtäessä kutsua palveluväylän kautta myös X-Road-Client kenttä on pakollinen. Kutsu tehdään FHIR POST Searchin mukaisesti joten Content-Type header tulee antaa ja sen arvon on oltava x-www-form-urlencoded.
HTTP-pyynnön header esimerkki
POST [base][api] HTTP/1.1
Accept: application/fhir+json
X-Road-Client: FI-TEST/GOV/0246246-0/AsiakirjojenHakuTestClient
X-Request-Id: 1.2.246.10.1.20241208102307.93.2023.11023072024880604629
Content-Type: application/x-www-form-urlencoded
HTTP-pyynnön body
Hakupyynnön parametrit välitetään HTTP pyynnön body-osuudessa url-enkoodattuna kuten ylläolevassa pyynnön esimerkissä.
HTTP-pyynnön body esimerkki
_query=get-all-documents&organization=1.2.246.10.123456789&viewCode=urn:oid:1.2.246.537.6.12.2002|151&_lastUpdated=ge2025-10-01&_lastUpdated=le2025-10-15&reload=true&result_set_key=1873699d-db2f-4a6d-897e-b0f6c6839928
Sekvenssikaavio
Vastaussanoma virhetilanteessa
Virhetilanteissa vastauksena palautuu HTTP-virhestatuskoodi sekä HTTP-bodyssa OperationOutcome resurssi-instanssi, jolla ilmaistaan tarkempi virhe.
Vastaussanoma virhetilanteessa-sivulla on kuvattu tarkemmin, miten Kysely- ja välityspalvelu palauttaa virheilmoitukset OperationOutcome-resurssilla.