API Rest QualiMedLab

1. Misure

1.1 Inserimento dati

1.1.1 HTTP Request POST: rtc/misure

URL Attributi Metodo Info
rtc/misure
  • {
    • siglalab: integer
    • username: text
    • siglacamp: text
    • id_strumento: text
    • siglaanal: char(2)
    • valore: real
    • siglaunitamis: char(4)
    • siglamet: char(4)
    • dataoramisura: date
  • }
POST Inserisce il valore analitico e le altre informazioni inviate nella tabella misurequant del database.

Dettaglio attributi

  • siglalab: è la sigla (numerica) assegnata al laboratorio;
  • username: nel caso di inserimento automatico il valore è "auto-siglalab", ad esempio "auto-7160", se la sigla del laboratorio è 7160; se l'inserimento avviene via www, lo username coincide con il nome utente utilizzato per effettuare l'accesso alla parte riservata del sito (tipicamente l'indirizzo e-mail);
  • siglacamp: è la sigla campione comunemente usata per riconoscere i campioni (es. "IM300A"). Se su questo parametro viene usato il codice a barre, il sistema genera un errore di mancato riconoscimento codice. Per tradurre da codice a barre a siglacamp è necessario effettuare una chiamata ad una apposita URL (vedi Request GET dizionario/{barcode}/{siglalab});
  • id_strumento: è la label utilizzata in laboratorio per identificare l'analizzatore (es. "Liaison 1", "Roche 2013" ecc.);
  • siglaanal: è la sigla analita codificata da QualiMedLab (es. "FE" = Ferritina, "V2"=1,25(OH)2-vitamina D, ecc.). Consiste in un codice composto da due caratteri alfanumerici, con lettere maiuscole;
  • valore: è il valore della misura riscontrato dall'analizzatore; nel caso di inserimento automatico il valore si ritiene calcolato nell'unità di misura espressa nel campo successivo siglaunitamis;
  • siglaunitamis: parametro opzionale. Se presente, il valore della misura descritto nel campo valore di cui al punto precedente, si ritiene espresso secondo l'unità di misura specificata in questo attributo; se questo attributo non è presente, in caso di inserimento automatico, il valore della misura si ritiene espresso nell'unità di misura comunicata, per ogni analita, dal laboratorio a QualiMedLab durante l'iscrizione al programma RTC; nel caso di inserimento via www, se non presente, si ritiene che il valore della misura sia espresso secondo l'unità default dichiarata da QualiMedLab per ogni analita;
  • siglamet: parametro opzionale. Consiste in un codice alfanumerico di quattro caratteri e rappresenta la sigla di un gruppo strumento/metodica, codificata da QualiMedLab. Nel caso di inserimento automatico, se non presente, l'attributo siglamet viene convenzionalmente inizializzato con la sigla del gruppo strumento/metodica comunicato, per ogni analita, dal laboratorio al provider durante l'iscrizione al programma RTC. Nel caso di inserimento www il parametro siglamet, se non presente viene inizializzato al gruppo di confronto utilizzato dal laboratorio durante l'ultimo invio di dati, per lo stesso analita;
  • dataoramisura: parametro opzionale. Nel caso di inserimento automatico, il parametro (espresso secondo lo standard ISO 8601 [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]±[hh]:[mm]) rappresenta la data/ora in cui l'analizzatore ha terminato la misura di quel particolare analita.

Descrizione

Il sistema prevede che il dato, prima di essere inserito, venga valutato in confronto alle statistiche che QualiMedLab possiede nel proprio database. Le valutazioni (campione incognito, z-score, score, scarto percentuale) sono inserite nel database contestualmente al valore.

Come specificato precedentemente, nel caso dell'inserimento automatico i parametri siglamet e siglaunitamis sono opzionali. Per mappare le informazioni necessarie alla corretta elaborazione dei dati RTC (in particolare, per ogni analita misurato, la sigla del metodo e l'unità di misura usata dal laboratorio), nel database QualiMedLab è presente una tabella che, per ogni laboratorio specifichi la relazione:

  • id strumento (analizzatore);
  • sigla-analita;
  • unità di misura del laboratorio;
  • sigla-metodo.

1.1.2 HTTP Response

  • [
    • {
      • "analita": text
      • "siglaanal": char(2)
      • "nomemet": text
      • "siglamet": char(4)
      • "siglacamp": text
      • "unitamis": text
      • "siglaunitamis": char(4)
      • "valore": real
      • "target": real
      • "scartperc": real
      • "limmin": real
      • "limmax": real
      • "zscore": real
      • "score": integer
    • }
  • ]

Dettaglio attributi

  • analita: denominazione analita;
  • siglaanal: sigla analita codificata da QualiMedLab;
  • nomemet: denominazione del gruppo strumento/metodica di confronto;
  • siglamet: sigla gruppo strumento/metodica codificata da QualiMedLab;
  • siglacamp: sigla campione nella codifica usuale, non codice a barre (es "IM300A");
  • unitamis: unità di misura con cui sono espressi i valori degli attributi valore, target, limmin, limmax;
  • siglaunitamis: sigla unità di misura codificata da QualiMedLab;
  • valore: valore inviato dal laboratorio;
  • target: valore obiettivo (media del gruppo strumento/metodica di cui sopra);
  • scartperc: scarto del valore inviato dal target espresso come differenza percentuale (può assumere valori negativi);
  • limmin: limite di accettabilità inferiore (-2 deviazioni standard dal target);
  • limmax: limite di acettabilità superiore (+2 deviazioni standard dal target);
  • zscore: scarto del valore inviato dal laboratorio dal target espresso in unità di deviazioni standard (può assumere valori negativi);
  • score: punteggio, da 0 a 4.

Descrizione

In caso di invio e inserimento effettuati correttamente, il messaggio di risposta consiste in una struttura dati che contiene il valore inviato dal laboratorio con le relative valutazioni analitiche.

1.2 Errori

In caso di errori presenti nel messaggio di richiesta (ad esempio siglalab inesistente, siglaanal non riconosciuta, siglaanal non misurabile sul campione, siglacamp insesistente ecc.) il messaggio di risposta conterrà nell'header uno status code 4xx, ed una descrizione dell'errore significativa, nel body.

Codice header Descrizione errore
Status Code: 404 Not Found Sigla laboratorio non riconosciuta
Status Code: 404 Not Found Sigla campione non esistente
Status Code: 404 Not Found Sigla analita non esistente
Status Code: 404 Not Found Analita non misurabile nel campione
Status Code: 404 Not Found Codifica valore errata
Status Code: 404 Not Found Sigla unità di misura non riconosciuta
Status Code: 404 Not Found Unità di misura non associata all'analita
Status Code: 404 Not Found Sigla metodo non esistente
Status Code: 404 Not Found Sigla metodo non associata all'analita
Status Code: 405 Method Not Allowed Metodo HTTP usato non previsto

2. Analiti

2.1 Lista e codici analiti

2.1.1 HTTP Request GET: analiti

URL Attributi Metodo Info
analiti GET Interrogazione dell'intera collezione analiti

Descrizione

Il sistema accetta interrogazioni della collezione "Analiti": una GET alla URL "analiti" provoca la restituzione di un messaggio Response contenente la lista di tutti gli analiti con le rispettive sigle codificate da QualiMedLab.

2.1.2 HTTP Response

Una Request ben formata alla URL analiti restituisce una Response che contiene la lista degli analiti con i relativi codici.

Status Code: 200 OK

  • [
    • {
      • "analita": text
      • "siglaanal": char(2)
    • }
    • {
      • "analita": text
      • "siglaanal": char(2)
    • }
    • ...
  • ]

Dettaglio attributi

  • analita: denominazione analita;
  • siglaanal: sigla analita nella codifica di QualiMedLab.

Descrizione

Il sistema restituisce, in caso di richiesta corretta, il codice ed il nome degli analiti.

2.2 Dettaglio analita (riconoscimento tramite sigla analita)

2.2.1 HTTP Request GET: analiti/{siglaanal}

URL Attributi Metodo Info
analiti/{siglaana} GET Dettaglio dello specifico analita, riconosciuto tramite la sigla

Descrizione

Una GET alla URL "analiti/{siglaanal}" provoca la restituzione di un messaggio Response contenente le informazioni particolareggiate relative all'analita interrogato (interrogazione basata sulla sigla analita).

  • siglaanal: char(2). Il codice analita secondo la codifica QualiMedLab;

2.2.2 HTTP Response

Nel caso di Request ben formata alla URL "analiti/{siglaanal}" il sistema restituisce:

Status Code: 200 OK

  • [
    • {
      • "analita": text
      • "siglaanal": char(2)
      • "unitamis": text
      • "siglaunitamis": char(4)
      • "cint": integer
      • "cdec": integer
      • "sogliamin": real
      • "sogliamax": real
      • "cvsdabasso": real
      • "cvsdamedio": real
      • "cvsdaalto": real
      • "sogliaminprec": real
      • "sogliamaxprec": real
      • "cvsdabassoprec": real
      • "cvsdamedioprec": real
      • "cvsdaaltoprec": real
      • "sogliastat": integer
      • "datasoglia": date
      • "unitamis_sec": text
      • "siglaunitamis_sec": text
      • "fattconv": real
      • "perc_classi": real
      • "sensibilita": real
      • "othermethods": boolean
    • }
  • ]

Dettaglio attributi

  • analita: denominazione analita;
  • siglaanal: sigla analita nella codifica di QualiMedLab;
  • unitamis: unità misura analita;
  • siglaunitamis: sigla unità misura;
  • cint: n. cifre intere (max previste per l'analita);
  • cdec: n. cifre decimali (max previste per l'analita);
  • sogliamin: soglia concentrazione bassa;
  • sogliamax: soglia concentrazione alta;
  • cvsdabasso: coefficiente di variazione "stato dell'arte" al livello concentrazione basso;
  • cvsdamedio: coefficiente di variazione "stato dell'arte" al livello concentrazione medio;
  • cvsdaalto: coefficiente di variazione "stato del'arte" al livello di concentrazione alto;
  • sogliaminprec: soglia concentazione bassa precedente;
  • sogliamaxprec: soglia concentrazione alta precdedente;
  • cvsdabassoprec: coefficiente di variazione "stato dell'arte" al livello concentrazione basso precedente;
  • cvsdamedioprec: coefficiente di variazione "stato dell'arte" al livello concentrazione medio precedente;
  • cvsdaaltoprec: coefficiente di variazione "stato dell'arte" al livello concentrazione alto precedente;
  • datasoglia: data attivazione nuove soglie e coefficienti di variazione;
  • sogliastat: soglia calcolo statistiche;
  • unitamis_sec: unità di misura secondaria;
  • siglaunitamis_sec: sigla unità di misura secondaria;
  • fattconv: fattore di conversione da unitamis_sec primaria a;
  • perc_classi: percentuale per suddividere i valori dei laboratori in gruppo nell'istogramma;
  • sensibilita: soglia sensibilità strumenti (LDL Low Detection Limit);
  • othermethods: flag per analiti qualitativi.

Descrizione

Il sistema restituisce, in caso di richiesta corretta, le informazioni dettagliate dell'analita richiesto.

2.3 Dettaglio analita (riconoscimento tramite denominazione)

2.3.1 HTTP Request GET: analiti/nome/{analita}

URL Attributi Metodo Info
analiti/nome/{analita} GET Dettaglio dello specifico analita riconosciuto tramite la denominazione

Descrizione

Una GET alla URL "analiti/nome/{analita}" provoca la restituzione di un messaggio Response contenente le informazioni particolareggiate relative all'analita interrogato (interrogazione basata sul nome analita).

  • analita: text. Il nome analita.

2.3.2 HTTP Response

Descrizione

Nel caso di Request ben formata alla URL "analiti/nome/{analita}" il sistema restituisce la stessa Response descritta nel paragrafo relativ alla URL "analiti/{siglaanal}".

2.4 Analiti/Metodi

2.4.1 HTTP Request GET: analiti/{siglaanal}/metodi

URL Attributi Metodo Info
analiti/{siglaanal}/metodi GET Lista metodi associati all'analita.

Descrizione

La URL restituisce la lista dei metodi associati all'analita.

  • siglaanal: text. La sigla analita.

2.4.2 HTTP Response

Nel caso di Request ben formata il sistema restituisce:

Status Code: 200 OK

  • [
    • {
      • "nomemet": text
      • "siglamet": char(4)
    • }
    • {
      • "nomemet": text
      • "siglamet": char(4)
    • }
    • ...
  • ]

Dettaglio attributi

  • nomemet: denominazione del metodo associato all'analita;
  • siglamet: sigla del metodo secondo la codifica di QualiMedLab.

Descrizione

Il sistema restituisce, in caso di richiesta corretta, la lista dei codici metodo e la relativa denominazione, associati all'analita.

2.5 Errori

In caso di errori presenti nel messaggio di richiesta il messaggio di risposta conterrà nell'header uno status code 4xx appropriato, ed una descrizione dell'errore significativa, nel body.

Codice header Descrizione errore
Status Code: 404 Not Found Sigla analita non esistente
Status Code: 404 Not Found Nome analita non riconosciuto
Status Code: 405 Method Not Allowed Metodo HTTP usato non previsto

3. Metodi

3.1 Lista e codifica metodi

3.1.1 HTTP Request GET: metodi

URL Attributi Metodo Info
metodi GET Interrogazione dell'intera collezione metodi

Descrizione

Una GET alla URL "metodi" provoca la restituzione di un messaggio Response contenente la lista di tutti i metodi codificati con le rispettive sigle.

3.1.2 HTTP Response

Nel caso di Request ben formata alla URL metodi il sistema restituisce:

Status Code: 200 OK

  • [
    • {
      • "nomemet": text
      • "siglamet": char(2)
    • }
    • {
      • "nomemet": text
      • "siglamet": char(2)
    • }
    • ...
  • ]

Dettaglio attributi

  • nomemet: denominazione metodo;
  • siglamet: sigla metodo nella codifica di QualiMedLab;

Descrizione

Il sistema restituisce, in caso di richiesta corretta, la lista dei metodi associati ad un analita, e la codifica usuale di questi.

3.2 Dettaglio metodo

3.2.1 HTTP Request GET: metodi/{siglamet}

URL Attributi Metodo Info
metodi/{siglamet} GET Dettaglio di un metodo

Descrizione

Una GET alla URL "metodi/{siglamet}" provoca la restituzione di un messaggio Response contenente il nome e la sigla del metodi interrogato (interrogazione basata sulla sigla metodo).

  • siglamet: char(4). La sigla bel metodo secondo la codifica di QualiMedLab.

3.2.2 HTTP Response

Nel caso di Request ben formata alla URL metodi/{siglamet} il sistema restituisce:

Status Code: 200 OK

  • [
    • {
      • "nomemet": text
      • "siglamet": char(2)
    • }
  • ]

Dettaglio attributi

  • nomemet: denominazione metodo;
  • siglamet: sigla metodo nella codifica di QualiMedLab;

Descrizione

Il sistema restituisce, in caso di richiesta corretta, il nome metodo ed il codice usato da QualiMedLab per identificarlo.

3.3 Lista analiti associati ad un metodo

3.3.1 HTTP Request GET: metodi/{siglamet}/analiti

URL Attributi Metodo Info
metodi/{siglamet}/analiti GET Lista degli analiti associati ad un metodo

Descrizione

Una GET alla URL "metodi/{siglamet}/analiti" provoca la restituzione di un messaggio Response contenente la lista degli analiti (siglaanal, nome) misurabili con quel particolare metodo.

  • siglamet: char(4). La sigla bel metodo secondo la codifica di QualiMedLab.

3.3.2 HTTP Response

Nel caso di Request ben formata alla URL metodi/{siglamet}/analiti il sistema restituisce:

Status Code: 200 OK

  • [
    • {
      • "analita": text
      • "siglaanal": char(2)
    • }
    • {
      • "analita": text
      • "siglaanal": char(2)
    • }
    • ...
  • ]

Dettaglio attributi

  • nome: denominazione analita;
  • siglaanal: sigla metodo nella codifica di QualiMedLab;

Descrizione

Il sistema restituisce, in caso di richiesta corretta, la lista degli analiti (ed il relativo codice) associati al metodo.

3.4 Errori

In caso di errori presenti nel messaggio di richiesta (ad esempio siglalab inesistente, barcode non riconosciuto, barcode non associato alla siglalab ecc.) il messaggio di risposta conterrà nell'header uno status code 4xx appropriato, ed una descrizione dell'errore significativa, nel body.

Codice header Descrizione errore
Status Code: 404 Not Found Sigla metodo non esistente
Status Code: 405 Method Not Allowed Metodo HTTP usato non previsto

4. Dizionari

4.1 Tabella corrispondenze sigla analita QML / sigla analita laboratorio

4.1.1 HTTP Request GET: dizionario/analiti/{siglalab}

URL Attributi Metodo Info
dizionario/analiti/{siglalab} GET Lista corrispondenza delle codifiche delle sigle analita per il laboratorio {siglalab}: sigla analita QML / sigla analita laboratorio.

Descrizione

La URL restituisce la lista delle corrispondenze tra le sigle analita QML e le relative codifiche usate all'interno del laboratorio. all'analita.

  • siglalab: integer. La sigla del laboratorio.

4.1.2 HTTP Response

Nel caso di Request ben formata il sistema restituisce:

Status Code: 200 OK

  • [
    • {
      • "siglaanal": text
      • "siglaanal_lab": text
    • }
    • {
      • "siglaanal": text
      • "siglaanal_lab": text
    • }
    • ...
  • ]

Dettaglio attributi

  • siglaanal: sigla analita nella codifica usata dal provider;
  • siglaanal_lab: sigla analita nella codifica usata dal laboratorio.

Descrizione

Il sistema restituisce, in caso di richiesta corretta, la lista delle sigle analita nella codifica QML in relazione alla corrispondente sigla nella codifica usata dal laboratorio.

4.2 Tabella corrispondenze sigla analita QML / sigla analita laboratorio: dettaglio

4.2.1 HTTP Request GET: dizionario/analiti/{siglalab}/{siglaanal_lab}

URL Attributi Metodo Info
dizionario/analiti/{siglalab}/{siglaanal_lab} GET Corrispondenza della codifica, per il laboratorio {siglalab}, della sigla analita usata in laboratorio {siglaanal_lab}, con la relativa codifica dell'analita usata dal provider.

Descrizione

La URL restituisce la corrispondenza sigla analita QML con la sigla analita usata dal laboratorio.

  • siglalab: integer. La sigla del laboratorio.
  • siglaanal_lab: text. La sigla dell'analita nella codifica usata dal laboratorio.

4.2.2 HTTP Response

Nel caso di Request ben formata il sistema restituisce:

Status Code: 200 OK

  • [
    • {
      • "siglaanal": text
      • "siglaanal_lab": text
    • }
  • ]

Dettaglio attributi

  • siglaanal: sigla analita nella codifica usata dal provider;
  • siglaanal_lab: sigla analita nella codifica usata dal laboratorio.

Descrizione

Il sistema restituisce, in caso di richiesta corretta, la lista delle sigle analita nella codifica QML in relazione alla corrispondente sigla nella codifica usata dal laboratorio.

4.3 Tabella corrispondenze sigla campione QML / codice a barre campione

4.3.1 HTTP Request GET: dizionario/barcode/{siglalab}

URL Attributi Metodo Info
dizionario/barcode/{siglalab} GET Interrogazione dell'intera collezione campioni relativa al laboratorio codice siglalab

Descrizione

Il sistema prevede il riconoscimento dei campioni tramite il codice "tradizionale". Per "tradurre" il codice a barre talvolta presente sui campioni di controllo con il codice campione standard, è necessario specificare, oltre al codice a barre, anche la sigla del laboratorio che possiede tale campione.

  • siglalab: integer. La sigla del laboratorio

4.3.2 HTTP Response

Una Request ben formata alla URL dizionario/barcode/{siglalab} restituisce una Response che contiene la lista dei campioni con i relativi codici assegnati al laboratorio.

Status Code: 200 OK

  • [
    • {
      • "siglalab": integer
      • "barcode": text
      • "siglacamp": text
    • }
    • {
      • "siglalab": integer
      • "barcode": text
      • "siglacamp": text
    • }
    • ...
  • ]

Dettaglio attributi

  • siglalab: la sigla del laboratorio;
  • barcode: codice a barre del campione;
  • siglacamp: la sigla del campione nella codifica usuale.

Descrizione

Il sistema restituisce, in caso di richiesta corretta, la lista dei campioni assegnati al laboratorio e la codifica usuale di questi.

4.4 Tabella corrispondenze sigla campione QML / codice a barre: dettaglio barcode campione

4.4.1 HTTP Request GET: dizionario/barcode/{siglalab}/{barcode}

URL Attributi Metodo Info
dizionario/barcode/{siglalab}/{barcode} GET Interrogazione per ottenere la siglacamp "tradizionale" (es. IM200A) a partire da un codice a barre (es. 1234567890) e da una siglalaboratorio (es. 7160)

Descrizione

La URL è utile per conoscere la sigla campione "tradizionale" associata ad uno specifico codice a barre.

  • siglalab: integer. La sigla del laboratorio
  • barcode: text. Il codice a barre del campione riportato sul flacone.

4.4.2 HTTP Response

Una Request ben formata alla URL dizionario/barcode/{siglalab}/{barcode} restituisce una Response che contiene il codice campione "tradizionale".

Status Code: 200 OK

  • [
    • {
      • "siglalab": integer
      • "barcode": text
      • "siglacamp": text
    • }
  • ]

Dettaglio attributi

  • siglalab: la sigla del laboratorio;
  • barcode: codice a barre del campione;
  • siglacamp: la sigla del campione nella codifica usuale.

Descrizione

Il sistema restituisce, in caso di richiesta corretta, la codifica usuale del campione richiesto.

4.5 Errori

4.5.1 Errori corrispondenze sigla analita QML / sigla analita laboratorio

In caso di errori presenti nel messaggio di richiesta il messaggio di risposta conterrà nell'header uno status code 4xx appropriato, ed una descrizione dell'errore significativa, nel body.

Codice header Descrizione errore
Status Code: 404 Not Found Sigla laboratorio non esistente
Status Code: 404 Not Found Sigla analita nella codifica del laboratorio non riconosciuto
Status Code: 405 Method Not Allowed Metodo HTTP usato non previsto

4.5.2 Errori corrispondenze sigla campione QML / barcode

In caso di errori presenti nel messaggio di richiesta (ad esempio siglalab inesistente, barcode non riconosciuto, barcode non associato alla siglalab ecc.) il messaggio di risposta conterrà nell'header uno status code 4xx appropriato, ed una descrizione dell'errore significativa, nel body.

Codice header Descrizione errore
Status Code: 403 Forbidden Sigla laboratorio specificata nella URL Request non coincidente con la siglalab del client
Status Code: 404 Not Found Barcode non esistente
Status Code: 405 Method Not Allowed Metodo HTTP usato non previsto