API för förfrågan om förekomst av prov

Version: 1.0

För övergripande beskrivning av integrationer och anslutningsalternativ, se Anslutningsbeskrivning . Här beskrivs API för sökning på person-id mot LIS-system. Anrop mot detta API sker från SBR vid behov när användare nyttjar systemet.

Integrationen är byggd med REST och skyddas av certifikat. Frågor ställs på på personnivå från SBR till respektive LIS-system.
Om inte SBR får ett korrekt svar tillbaka kommer detta tydligt att visas i gränssnittet. Endast vid korrekta svar (oavsett innehåll) kommer svaret att visas upp för användaren.

Implementation

Integrationen implementeras på så sätt att SBR ställer en fråga till alla anslutna laboratorieinformationssystem som då har möjlighet att svara ja/nej/kanske på huruvida prov finns.
Vi ger också möjlighet att skicka med mer information för att ytterligare kunna förbättra för läkare eller den som hanterar samtyckesförändring, men denna information är inte obligatorisk.

Frågan som ställs kommer att innehålla huvudman, personidentifierare och ett datumintervall för när provet är taget.

Svaret måste innehålla förekomst av prov (ja/nej/kanske) samt enhet där prov hanteras och kan innehålla:

Provtagningsdatum
(för att göra det enklare för behandlande läkare att bedöma om provet är relevant samt för att inte skicka ut begäran om förändring av samtycke på prov som inte berörs av begäran)
Huvudman och klinik där provet togs
(för att inte skicka ut begäran om förändring av samtycke på prov som inte berörs av begäran )
Provmaterial / provtyp
(för att göra det enklare för behandlande läkare att bedöma om provet är relevant samt för att inte skicka ut begäran om förändring av samtycke på prov som inte berörs av begäran)
Anatomisk position
(för att göra det enklare för behandlande läkare att bedöma om provet är relevant)
Samtyckesinformation
(för att inte skicka ut begäran om förändring av samtycke på prov som redan har korrekt samtycke registrerat)

Meddelandestruktur

Fråga

Term	Obligatoriskt	Innehåll	Syfte

Term	Obligatoriskt	Innehåll
principal	Nej	Huvudman som stod för provtagningen. Sträng av minst ett, max 100 tecken från ASCII 33-126
person.personIdType	Ja	Typ av identifierare för provgivare. Någon av: RSV704 RSV707 OTHER “OTHER“ används för reservnummer.
person.personId	Ja	Identifierare för provgivaren. Format bestäms av person.personIdType Notera att för personnummer och samordningsnummer används inte skatteverkets officiella definition. Se personidentifierare nedan För reservnummer gäller att det skall vara en sträng om som mest 20 tecken och som består av bokstäver, siffror eller tecknen - eller +
sample.sampledate.from		Provtagningsdatum i formatet ISO-8601 (se nedan)
sample.sampledate.to		Provtagningsdatum i formatet ISO-8601 (se nedan)

Svar

Term	Obligatoriskt	Innehåll	Syfte

Term	Obligatoriskt	Innehåll	Syfte
sampleAvailable	Ja	Finns prov. Någon av - YES - NO - UNKNOWN
samplesAvailable	Nej	Totalt antal prover	Totalt antal prov som hittats. Används för att avgöra om listade prover är samtliga prover eller om det kan finnas andra
samples	Nej	Lista av prover enligt nedan som hittats

Prov

Term	Obligatoriskt	Innehåll	Syfte

Term	Obligatoriskt	Innehåll	Syfte
sampleDate	Nej	Provtagningsdatum i formatet ISO-8601 (se nedan)	Sökning för vård: avgöra vilket prov som är mest lämpligt vid flera träffar
material_type	Nej	Provmaterial, t.ex. Vävnad, Helblod, Plasma eller Urin Sträng av minst ett, max 50 tecken från ASCII 33-126	Sökning för vård: avgöra om provet är relevant Samtyckeshantering: Avgöra om provet omfattas av begäran om ändring av samtycke.
anatomical_position	Nej	Lista av anatomisk position uttryckt i text där varje element är en sträng av minst ett, max 100 tecken från ASCII 33-126	Sökning för vård: avgöra om provet är relevant
sampleOrigin.principal	Nej	Huvudman som stod för provtagningen Sträng av minst ett, max 100 tecken från ASCII 33-126	Samtyckeshantering: Att se var provet är taget för att avgöra om det omfattas av begäran om ändring av samtycke.
sampleOrigin.careFacility	Nej	Vårdenhet/klinik där provet togs Sträng av minst ett, max 100 tecken från ASCII 33-126
consent.opposeTo	Nej	Lista av de samtycken provgivaren aktivt motsatt sig. Noll eller flera av: CARE_AND_TREATMMENT EDUCATION_DEVELOPMENT_QUALITY RESEARCH PRODUCT	Samtyckeshantering: Att se nuvarande samtycke för att avgöra om det påverkas vid ny begäran om ändring av samtycke.
departmentName	Ja	Nuvarande provförvaringsenhet Sträng av minst ett, max 100 tecken från ASCII 33-126	Sökning för vård: För att kontakta rätt enhet om provet är relevant Samtyckeshantering: För att avgöra vart eventuell förfrågan om samtyckesförändring ska skickas
sampleCollection	Nej	Nuvarande provsamling Sträng av minst ett, max 100 tecken från ASCII 33-126

Datumformat

För samtliga datum används RSV-3339 utan tidszon, t.ex. 1998-06-22.

Personidentifierare

För att identifiera en provgivare används antingen personnummer (RSV704), samordningsnummer (RSV707) eller annat (OTHER)

Personnummer

Formatet ska vara ÅÅÅÅMMDD-NNNN, det vill säga enligt det officiella formatet men med den skillnaden att “-” alltid används (även om personen är äldre än 100 år) och att årtusende och århundrade alltid anges.
Se https://skatteverket.se/privat/folkbokforing/personnummer

Exempel: 19121212-1212

Samordningsnummer

Formatet ska vara ÅÅÅÅMMXX-NNNN, det vill säga enligt det officiella formatet men med den skillnaden att “-” alltid används (även om personen är äldre än 100 år) och att årtusende och århundrade alltid anges. XX är siffran för födelsedag ökad med talet 60.
Se https://skatteverket.se/offentligaaktorer/informationsutbyte/folkbokforingsamordningsnummer

Exempel: 19121272-1219

Annat

Formatet för annat är sträng av minst ett, max 50 tecken från ASCII 33-126. Vid sökning med annat ska alla exakta matchningar, oavsett typ, returneras.

Regler

Om konsumenten anger huvudman men tjänsteproducenten inte håller information om huvudman där provet togs ska producenten returnera… (TODO alla prover som hittas för personen, utan information om sampleOrigin? inga prover?)

Säkerhet och identifiering

Integrationen skyddas av certifikat och kräver att sändande system har ett av Inera utfärdat funktionscertifikat där sändande system identifieras med HSA-id.
Omvänt så identifieras svarande system med ett ssl-certifikat enligt nedan där URI:n garanterar identiteten.

Funktionscertifikatet som används behöver vara utfärdat under något av:

Rot: SITHS e-id Root CA v2
- Mellanliggande: SITHS e-id Function CA v1
Rot: SITHS Root CA v1
- Mellanliggande: SITHS Type 3 CA v1

Se SITHS Funktionscertifikat - Användarguide