API-beskrivning: skicka prov till SBR

Version: 1.0

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 anslutna system.

Skicka prov till SBR - meddelandestruktur

Term	Obligatoriskt	Innehåll	Syfte

Term	Obligatoriskt	Innehåll	Syfte
samplingId	Ja	Id för provtagningstillfället. Unikt inom det system som skickar uppgifterna. Sträng av minst ett, max 50 tecken från ASCII 33-126	Nyckel för att senare uppdatera eller radera informationen.
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 +
person.sex	Ja	Provgivarens biologiska kön. Någon av: - MALE - FEMALE
opposeTo	Ja	Samtyckesinformation. 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.	Anger användning som provgivaren motsätter sig. Om samtliga är angivna betraktas detta som att provet inte ska sparas och information om provet raderas i SBR
samplingOrigin.organisationName	Ja	Sträng som identifierar den huvudman i vilkens regi proverna sparas Exempel: “Region Uppsala”	Används för att identifiera rätt provsamling
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å en avdelning ofta bara har en provsamling, men kan vara olika då flera provsamlingar kan hanteras på samma enhet (labb). Exempel “Patologi/Cytologi”
samples		Lista av prover tagna vid provtagningstillfället. Noll eller flera. Om en tom lista av prover skickas raderas provtagningstillfället.
samples[].identifier	Ja	Identifierare för prov. 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[].registrationDate	Ja	Det datum då provet registrerades i LIS. Får ej vara i framtiden. ISO-8601 (se nedan)
samples[].sampleAnatomicalPositions	Ja om histologi eller cytologiprov	Lista av en eller flera positioner från /anatomical_positions (se nedan)
samples[].sampleMaterialType	Ja	En av typerna från /material_types , se nedan
samples[].samplingDate	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.

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 personnummer (RSV704) , samordningsnummer (RSV707) eller reservnummer.
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.
Identiteten skickas som en sträng i klartext, som mappas mot en intern identifierare i SBR, och måste därmed vara konstant över tid.
Identiteten överenskommes 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 eller samples ä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-certifikat dä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