API- och anslutningsbeskrivning för integration mot SBR

Syfte

Integrationen har två syften:

Hitta prov för vilka provgivare vill förändra samtycke eller se vilka prov som finns bevarade
När en provgivare vill förändra samtycke för ett prov utgår detta från var provet är taget (vilken huvudman). Provet kan dock skickas till andra huvudmän (antingen delar av provet eller provet i sin helhet). För att säkerställa att allt material hittas behöver därför samtliga enheter där provet kan förvaras kontaktas för att säkerställa att förfrågan hanteras korrekt. Idag finns ingen komplett tillgänglig strukturerad dokumentation kring vart prov skickas som kan utnyttjas för detta.
Det viktigaste är att kunna filtrera bort den majoritet av enheter som via denna integration kan garantera att de INTE har något prov givet de aktuella kriterierna för att på så sätt inte överbelasta enheterna med irrelevanta förfrågningar.
Hitta prov för en persons vård och behandling (givet legala förutsättningar under utredning)
Som en del av en persons vård och behandling kan man ibland ha stor nytta av provmaterial taget tidigare. Dessa prov kan vara tagna var som helst i landet (och sedan distribuerats på samma sätt som i punkt 1).
Detta gör att vi behöver fråga varje enskild enhet huruvida de har prov från den aktuella personen för att på så sätt kunna presentera för behandlande läkare var det finns prov, var det kanske finns prov och var det inte finns prov, så att denne kan fortsätta processen genom kontakt med relevanta enheter.

Sökning på prov på individnivå kan också vara aktuellt för forskning exempelvis vid kliniska läkemedelsprövningar.

Generella principer

Integration mot Svenska Biobanksregistret (SBR) kan göras på två olika sätt.

Överföring av data kring biobanksprov till respektive huvudmans del i SBR (mellanlagring)
Slagningar mot LIS-system på enskilda individer från SBR när frågan uppstår

Dessa står inte emot varandra, utan ska ses som två olika möjligheter att uppnå samma mål.
Den första lösningen möjliggör också framtida funktioner för att göra forskningssökningar baserat på egenskaper hos provet.

Integrationen är byggd med REST och skyddas av certifikat. Prover (sample), alternativt provtagningstillfällen (sampling), skickas ett och ett och och OK svar ges endast om meddelandet uppfyller såväl tekniska specifikationer som domänregler (detta dokument samt OpenAPI-specifikation).
Ansvaret för ett meddelande ligger kvar hos sändande part tills dess att ett OK-svar givits av SBR.

Information i integrationen

I sin första (nuvarande) form innehåller integrationen lite information om varje prov. Detta är någonting som kommer att utökas i framtiden i samarbete med sändande system.

Meddelandestruktur

	JSON	Obligatoriskt		Format

	JSON	Obligatoriskt		Format
Provtagningstillfälle
	samplingId	Ja	Unikt id för provtagningstillfället. Det är detta som används för att senare uppdatera eller radera.	Sträng av minst ett, max 50 tecken från ASCII 33-126
Provgivare
	person.personIdType	Ja	Format på identifierare för provgivaren. Någon av: - RSV704 - RSV707 - OTHER
	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 +
	person.sex	Ja	Biologiskt kön. Någon av: - MALE - FEMALE	“MALE”, “FEMALE”
Samtyckesinformation
	opposeTo	Ja	Lista av noll eller flera av: - CARE_AND_TREATMENT - EDUCATION_DEVELOPMENT_QUALITY - RESEARCH - PRODUCT Om provgivaren inte har någon registrerad begränsning skickas en tom lista, alltså att provgivaren inte motsatt sig något syfte. Om samtliga är angivna betraktas detta som att provet inte ska sparas och information om provet raderas i SBR	[“CARE_AND_TREATMENT”,”EDUCATION_DEVELOPMENT_QUALITY”, “RESEARCH”,”PRODUCT”
Avsändare
	samplingOrigin.organisationName	Ja	Sträng som odentifierar den huvudman i vilkens regi proverna sparas Exempel: “Region Uppsala”
	samplingOrigin.departmentName	Ja	Sträng som identifierar den avdelning i vilkens regi proverna sparas Exempel: “Patologi/Cytologi”
	samplingOrigin.sampleCollection	Ja	Sträng som identifierar specifik provsamling där proverna sparas. Är ofta samma som departmentName då de ofta har en egen provsamling i SBR men kan vara olika då flera provsamlingar kan hanteras på samma enhet (labb). Exempel “Patologi/Cytologi”
Provinformation			Lista av prover tagna vid provtagningstillfället. Noll eller flera. Om en tom lista av prover skickas raderas provtagningstillfället
	samples[].identifier	Ja	Unikt per provsamling	Sträng av minst ett, max 50 tecken från ASCII 33-126
	samples[].label	Nej	Sträng som används för att personalen ska kunna hitta provet, alltså samma som det fysiska provet är märkt med.	Sträng av minst ett, max 50 tecken från ASCII 33-126
	samples[].registration_date	Ja	Det datum då provet registrerades i LIS. Får ej vara i framtiden. ISO-8601 (se nedan)	Se datumformat nedan
	samples[].anatomical_position	Ja omm histologi eller cytologiprov	Lista av en eller flera positioner från /anatomical_positions (se nedan)	Lista av strängar, se Anatomical positions nedan
	samples[].material_type	Ja	En av typerna från /material_types	Sträng, se Material types nedan
	samples[].sampling_date	Nej	Datum då proverna togs. Får ej vara j framtiden. Denna är tänkt att ersätta sample.registration_date när alla LIS-system kan skicka den.	Se datumformat nedan

Exempel

{
    "samplingId": "12341234",
    "person": {
        "personIdType": "RSV704",
        "personId": "191212121212",
        "sex": "MALE"
    },
    "opposeTo": [
        "RESEARCH"
    ],
    "samplingOrigin": {
        "organisationName": "Region_Uppsala",
        "departmentName": "Patologi",
        "sampleCollection": "Patologi"
    },
    "samples": [
        {
        "identifier": "1234",
        "label": "A778",
        "registrationDate": "2022-04-20",
        "sampleAnatomicalPositions": [
            "T02"
        ],
        "sampleMaterialType": "Vävnad",
        "samplingDate": "2022-04-20"
    },
        {
        "identifier": "2345",
        "label": "A779",
        "registrationDate": "2022-04-20",
        "sampleAnatomicalPositions": [
            "T03"
        ],
        "sampleMaterialType": "Vävnad",
        "samplingDate": "2022-04-20"
    }
    ]
}

Datumformat

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

Personidentifierare

För att identifiera en provgivare används antingen personnummer (RSV704) eller samordningsnummer (RSV707)
Personer som inte kan identifieras med någon av dessa identifierare exkuderas ur integrationen. Notera att detta även gäller barn som saknar personnummer, de ska inte registreras på mammans personnumer utan exkluderas tills dess att de fått personnummer.

Personnummer

Formatet ska vara ÅÅÅÅMMDDNNNN, det vill säga enligt det officiella formatet men med den skillnaden att “-”/”+” inte 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: 191212121212

Samordningsnummer

Formatet ska vara ÅÅÅÅMMXXNNNN, det vill säga enligt det officiella formatet men med den skillnaden att “-”/”+” inte 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: 191212721219

Reservnummer

Formatet skall vara en sträng om som mest 20 tecken ::= {A-Ö|a-ö|0-9|-+}

Anatomical Positions

Lista av giltiga anatomiska positioner (“T-koder”) finns på /anatomical_positions

Material Type

Lista av giltiga materialtyper finns på /material_types. Endast typer definerade här får användas, andra strängar ger felmeddelande.
Ett prov kan endast ha en materialtyp. De är definerade hierarkiskt så att t.ex. serum, plasma och helblod är underordnade blod.

Avsändare

För att korrekt hantera provtagningen behöver vi kunna identifiera avsändaren.
Det som skickas mappas i SBR, så inga SBR-specifika identifierare krävs, däremot behöver de vara konstanta över tid.
Dessa kommuniceras med fördel i förväg mellan sändande och mottagande part så att SBR kan konfigureras korrekt från start.
Notera att system inte är med då detta hämtas ur certifikatet (HSA-ID).

Url:er och endpoints

Demo-/testmiljö: https://samples.sbr.demo.biobanksverige.se/integration/sample/v1

Se nedan hur man kan ansluta till demo-miljön med ett test-certifikat.

Det finns även kopior av samtliga endpoints, utan krav på certifiktat, på https://insecure.samples.sbr.demo.biobanksverige.se/integration/sample/v1

Produktionsmiljö: https://samples.sbr.biobanksverige.se/integration/sample/v1

OpenApi specifikation finns på https://samples.sbr.demo.biobanksverige.se/integration/api-docs/sample/v1 (att ansluta dit kräver klient-certifikat, men specifikationen kan också nås utan certifikat på den öppna endpointen: https://insecure.samples.sbr.demo.biobanksverige.se/integration/api-docs/sample/v1)

Url	Metod	Syfte

Url	Metod	Syfte
/	delete	ta bort prov identifierat av personidentifierare och provtagningsid
/	post	registrera eller uppdatera flera prover (eller ta bort om samtycke är tomt)
/anatomical_positions	get	listar alla anatomiska positioner (T-kod) som vi accepteerar
/material_types	get	lista alla provmaterial (kod) som vi accepterar

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å identifierar sig samples.sbr.biobanksverige.se med ett ssl-certifikatdär URI:n garanterar identiteten.

Ett system (HSA:id) kan kopplas till flera huvudmän, avdelningar och även provsamlingar.
För att skicka data till en provsamling (i praktiken samma som enhet/labb) behöver följande kommuniceras till SBR så att korrekt mappning kan göras:

HSA:id för sändande system (samma som i certifikatet)
Namn/id på huvudmannen som avses
Namn/id på den enhet (det laboratorium) där provet hanteras
Namn/id på den provsamling som provet ska förvaras i (i normalfallet samma som enhetsnamnet, detta finns framförallt för att i framtiden möjliggöra flera provsamlingar på samma enhet)

Dessa namn/id:n behöver kommuniceras med SBR i förväg.

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 https://inera.atlassian.net/wiki/spaces/IAM/pages/448103163/SITHS+Funktionscertifikat+-+Anv+ndarguide

Identifiering, testmiljö

För att testa att anslut till testmiljön ( https://samples.sbr.demo.biobanksverige.se/integration/sample/v1/) med ett klient-certifikat, kan man använda följande certifikat-filer. Dessa filer identifierar sändande system som ett system som kan registrera prover med “sampleOrigin”: "organisationName": "Region_Uppsala",
"departmentName": "Patologi",
"sampleCollection": "Patologi".

Följande curl-anrop fungerar och kan användas som mall för en lösning som behöver implementera klient-certifikats-identifiering:

curl -v --cert testClient.crt --key testClient.key -X POST -H "Content-Type: application/json" https://samples.sbr.demo.biobanksverige.se/integration/sample/v1/ -d @sample-import06.json

Registrera ny information

Integrationen är uppbyggd kring provtagning (sampling). Denna håller information om personen som givit prov, samtyckesinformation och själva proverna.

Provtagning är den minsta enheten att registrera och uppdatera och identifieras av ett provtagningsid (sampling_id)

För att registrera ett nytt prov behöver utöver tabellen ovan följande regler var uppfyllda (alla regler gällande krockar gäller endast inom samma provsamling/integration):

Samplingid får inte vara skickat tidigare
Samtliga datum måste vara senast dagens datum
Providentifierare måste vara unika inom ett provtagningstilfälle
Om prov är ett vävnadsprov så måste minst en korrekt formaterad t-kod finnas
Samtliga t-koder måste vara tagna ur listan med giltiga t-koder

Uppdatera befintlig information

SamplingId och person.personId identiferar tillsammans hela sampling. Om det kommer en ny tas den gamla bort och ersätts av den nya.

Om befintligt samplingId skickas med nytt personid kommer det att avvisas (se specifikt exempel Byta personidentifierare nedan).

Specifika fall och exempel

Ta bort ett provtagningstillfälle helt

För att radera ett provtagningstillfälle skickas ett anrop enligt samma format som vid nyregistrering men som inte innehåller några prover. Samtyckesinformationen kommer inte att beaktas.

Byta personidentifierare på ett provtagningstillfälle

För att byta personnummer på ett provtagningstillfälle raderas först det befintliga (se ovan), sedan skickas en ny registrering av provtagningstillfället med den nya personidentifieraren. Detta kan ske både vid misstag eller vid t.ex. byte från sammordningsnummer till svenskt personnummer.

Uppdatera samtyckesinformation

För att uppdatera samtyckesinformationen skickas hela provtagningstillfället om, inklusive prover, med den nya samtyckesinformationen.
Notera att om samtycke inte finns så kommer provtagningstillfället att raderas .

Svar

Om allt går bra svarar applikationen med 200 OK.

Om någonting inte fungerar svarar applikationen antingen med en generell felkod, eller i de fall data som skickats inte går igenom valideringen, men en specifik felkod. Se lista nedan.

Generella felkoder

HTTP-statuskod	Felmeddelande	Betydelse

HTTP-statuskod	Felmeddelande	Betydelse
400	Standard HTTP	Klienten har inte presenterat ett betrott certifikat.
401	Standard HTTP	Saknad behörighet. Klienten har presenterat ett betrott certifikat men identifierad maskin har inte behörighet att utföra åtgärden för berörd huvudman.
500	Standard HTTP	Internt fel hos SBR. Hanteras av SBR via loggövervakning och behöver inte rapporteras in av sändande part.
503	Standard HTTP	Tekniskt fel i överföringen. Detta ska rapporteras till SBRs förvaltning.

SBR-specifika felkoder

HTTP-statuskod	Felkod	Felmeddelande	Betydelse

HTTP-statuskod	Felkod	Felmeddelande	Betydelse
422		registrationDate får inte vara tidigare än högst ett år före födelsedatum
		registrationDate får inte vara i framtiden
		samplingDate får inte vara i framtiden
		The sampling identifier has already been used with different person id
		The sample identifier has already been used with different person id
		The sample identifier must follow the format RSV704
		The sample identifier must follow the format RSV707
		Unknown anatomical position
		Anatomical position can not be empty for pathology/cytology
		Unknown material description
		Numret är inget samordningsnummer
		Numret är inget personnummer