Specifiche per l integrazione dei software di cartella clinica con i servizi Web esposti dalla Regione Lazio 23/06/2017 1
Status del Documento Rev. Data Descrizione Modifica 1 17/11/2016 Prima versione 2 12/01/2017 Modifica endpoint di test per tutti i servizi. Modifiche nei dati di DB di test 3 09/06/2017 Accesso Servizi 4 23/06/2017 Precisazione Accesso Servizi 2
Indice 1 INTRODUZIONE... 4 1.1 GLOSSARIO... 4 2 DESCRIZIONE DEI SERVIZI DI INTEGRAZIONE... 5 1.2 AUTENTICAZIONE PER L ACCESSO AI SERVIZI... 5 1.3 PROCEDURA DI RICHIESTA DELLE CREDENZIALI... 5 3 SERVIZI DISPONIBILI... 7 1.4 ANAGRAFICA MEDICO UCP... 7 1.4.1 Accesso al servizio... 7 1.4.2 Descrizione del servizio... 7 1.5 ANAGRAFICA ASSISTITO... 9 1.5.1 Accesso al servizio... 9 1.5.2 Descrizione messaggio... 9 1.6 ESENZIONI ASSISTITO... 12 1.6.1 Accesso al servizio... 12 1.6.2 Descrizione messaggio... 12 1.7 SERVIZIO COORTI... 14 1.7.1 Accesso al servizio... 14 1.7.2 Descrizione messaggio... 14 4 NOTE TECNICHE... 16 4.1 CRITERI DI PAGINAZIONE DEI RISULTATI... 16 4.2 CRITERI DI ORDINAMENTO DEI RISULTATI... 16 5 AMBIENTE DI TEST E SERVIZI... 17 1.8 URL SERVIZI... 17 1.9 ACCESSO SERVIZI... 17 1.10 ACCESSO SERVIZI... 17 1.11 DATI DB DI TEST... 18 3
1 Introduzione Il presente documento descrive le specifiche tecniche per tutti gli attori interessati (produttori di software di Cartella Clinica per gli studi medici MMG e PLS) per l integrazione tramite i servizi web predisposti. 1.1 Glossario ASUR CNIPA CNS DIT DPCM MEF NRE RGS SAC SAR SASN SPC SSN Anagrafe Sanitaria Unica Regionale Centro Nazionale Informatica Pubblica Amministrazione Carta Nazionale dei Servizi dei servizi Dipartimento Innovazioni tecnologiche della Presidenza del consiglio dei ministri Decreto Presidente consiglio dei ministri Ministero dell economia e della finanze Numero Ricetta Elettronica Ragioneria Generale dello Stato Sistema di Accoglienza Centrale, che rappresenta l infrastruttura tecnologica del Ministero dell economia e delle finanze, per la ricezione dei dati delle ricette mediche trasmessi dagli utenti. Sistema di Accoglienza Regionale Servizio Assistenza Sanitaria personale Navigante Sistema Pubblico Connettività Servizio Sanitario Nazionale 4
2 Descrizione dei Servizi di integrazione I servizi esposti sono destinati ai Studi di MMG e PLS, che continueranno utilizzare il proprio software di Cartella Clinica dello studio Tutti i servizi web sono sviluppati seguendo le linee guida e impostazioni tecniche prodotte dal MEF SOGEI riguardo al progetto Tessera Sanitaria Elettronica e Medici in Rete. Di seguito i servizi web esposti: Servizio Anagrafica medico UCP Anagrafica assistito Esenzioni Assistito Servizio Coorti Descrizione Tramite questo servizio è possibile ricercare medici MMG/PLS associati in UCP al medico fruitore del servizio. Tramite questo servizio è possibile ricercare all interno dell archivio degli assistiti di propria competenza (sia UCP che studio medico) Tramite questo servizio è possibile avere i dettagli delle esenzioni dell assistito di propria competenza. Tramite questo servizio è possibile ricercare una coorte per codice ed averne l elenco degli assistiti afferenti 1.2 Autenticazione per l accesso ai servizi L accesso ai servizi Web di Integrazione, esposti dal sistema, avviene tramite i sistemi di autenticazione standard del protocollo HTTPS e BASIC Authentication. La procedura per invocare i servizi web esposti prevede nel caso di studi medici che utilizzano i software di terzi parti di utilizzare l utente e password del medico MMG e PLS configurati nel sistema regionale di Access Management. 1.3 Procedura di richiesta delle credenziali In ambiente di produzione, per gli studi medici di MMG e PLS, le credenziali per accedere ai Servizi Web di Integrazione sono le stesse che utilizza il medico per accedere al Portale Regionale della Sanità (www.poslazio.it). 5
In ambiente di test saranno fornite sia le credenziali specifiche, che potranno essere utilizzate da tutti gli attori che dovranno invocare i servizi web esposti, sia i codici fiscali specifici per effettuare le prove di trasmissione. 6
3 Servizi Disponibili 1.4 Anagrafica medico UCP 1.4.1 Accesso al servizio L indirizzo per accedere al servizio di test è: https://qservice.regione.lazio.it/medbase-ws/ws/medicoucp Si ricorda che i WSDL di definizione dei servizi devono essere scaricati dal https://qservice.regione.lazio.it/medbase-ws sezione downloads Pacchetto wsdl (01/06/2017) Sarà comunicato ad avvenuto collaudo l indirizzo per raggiungere i servizi esposti in ambiente di produzione. 1.4.2 Descrizione del servizio Tramite questo servizio è possibile effettuare ricerche nell archivio dei medici MMG/PLS associati in UCP al medico fruitore del servizio. E possibile ricercare anche la lista dei codici fiscali dei medici appartenenti alla stessa UCP di appartenenza. 1.4.2.1 Campi di input Descrizione degli elementi costitutivi del messaggio di richiesta ricerca (ricercamedicirequest): 7
Nome Campo Contenuto Tipo codicefiscale ordinamento Codice fiscale del medico da ricercare. Se non specificato verrà restituito l elenco dei medici appartenenti alla UCP di competenza del medico fruitore Campi per i quali effettuare l ordinamento dei dati. Per maggiori dettagli sulla sintassi da utilizzare per il campo di ordinamento fare riferimento alla relativa sezione del documento facoltativo facoltativo (Valori ammessi: codicefiscale cognome nome) Campi relativi alla paginazione (vedere apposita sezione del documento) inizio Numero del record di inizio facoltativo fine Numero del record di fine facoltativo 1.4.2.2 Campi di output Descrizione degli elementi costitutivi del messaggio di risposta ricerca (ricercamediciresponse): Nome Campo Contenuto codiceesito Codice dell esito della ricerca. Valori possibili: -1 Elaborazione fallita 0 Elaborazione completata con successo 1 Elaborazione completata con presenza di warning descrizioneesito Descrizione dell esito della ricerca totale Numero totale dei record che soddisfano i criteri di ricerca impostati Ripetizione di Medico codicefiscale Codice fiscale del medico cognome Cognome del medico nome Nome del medico sesso Sesso del medico (M o F) datanascita Data di nascita del medico comunenascita Comune di nascita del medico categoria Categoria del medico (MMG o PLS) asl Codice e descrizione della asl di competenza del medico distretto Codice e descrizione del distretto di competenza del medico 8
Nome Campo Contenuto Ripetizione di Messaggio codice value level Codice del messaggio diagnostico Testo del messaggio Livello di importanza del messaggio. Uno tra TRACE, DEBUG, INFO, WARNING, ERROR, FATAL parametri Corrisponde ai parametri di ricerca (RicercaMediciRequest) forniti in input 1.5 Anagrafica assistito 1.5.1 Accesso al servizio L indirizzo per accedere al servizio di test è: https://qservice.regione.lazio.it/medbase-ws/ws/assistito Si ricorda che i WSDL di definizione dei servizi devono essere scaricati dal https://qservice.regione.lazio.it/medbase-ws sezione downloads Pacchetto wsdl (01/06/2017) Sarà comunicato ad avvenuto collaudo l indirizzo per raggiungere i servizi esposti in ambiente di produzione. 1.5.2 Descrizione messaggio Tramite questo servizio è possibile effettuare ricerche nell archivio degli assistiti di propria competenza sia per UCP che per studio medico. 1.5.2.1 Campi di input Descrizione degli elementi costitutivi del messaggio di richiesta ricerca (ricercaassistitirequest): Nome Campo Contenuto Tipo codicefiscale Codice fiscale dell assistito da ricercare facoltativo 9
Nome Campo Contenuto Tipo codicestraniero Codice STP/ENI dell assistito da ricercare facoltativo codicefiscalemedico Codice fiscale del medico curante dell assistito. Per avere la lista dei proprio assistiti un medico deve impostare questo campo con il proprio codice fiscale. Per avere la lista degli assistiti di un altro medico, qui va impostato il codice fiscale del medico di interesse. Il sistema rifiuterà codici fiscali diversi dal proprio se tali codici fiscali non sono associati in UCP al medico fruitore del servizio obbligatorio ordinamento Campi per i quali effettuare l ordinamento dei dati. Per maggiori dettagli sulla sintassi da utilizzare per il campo di ordinamento fare riferimento alla relativa sezione del documento facoltativo (Valori ammessi: codicefiscale cognome nome Campi relativi alla paginazione (vedere apposita sezione del documento) inizio Numero del record di inizio facoltativo fine Numero del record di fine facoltativo 1.5.2.2 Campi di output Descrizione degli elementi costitutivi del messaggio di risposta ricerca (ricercaassistitiresponse): codiceesito Nome Campo Contenuto Codice dell esito della ricerca. Valori possibili: -1 Elaborazione fallita 0 Elaborazione completata con successo 1 Elaborazione completata con presenza di warning descrizioneesito totale codiceregionale validitacodiceregionale codicefiscale validitacodicefiscale cognome nome Descrizione dell esito della ricerca Numero totale dei record che soddisfano i criteri di ricerca impostati Ripetizione di Paziente Codice regionale dell assistito Data di decorrenza validità codice regionale Codice fiscale dell assistito Data di decorrenza validità codice fiscale Cognome dell assistito Nome dell assistito 10
Nome Campo Contenuto sesso Sesso dell assistito (M o F) datanascita Data di nascita dell assistito comunenascita Comune di nascita dell assistito (codice e descrizione) nazionenascita Nazione di nascita dell assistito (codice e descrizione) nazionecittadinanza Nazione di cittadinanza dell assistito (codice e descrizione) codicestraniero Codice STP/ENI dell assistito datainiziocodicestraniero Data di inizio validità codice straniero datafinecodicestraniero Data di fine validità codice straniero datadecesso Data di decesso dell assistito comunedecesso Comune di decesso dell assistito (codice e descrizione) indirizzoresidenza Indirizzo di residenza dell assistito civicoresidenza Civico di residenza dell assistito capresidenza Cap di residenza dell assistito comuneresidenza Comune di residenza dell assistito (codice e descrizione) nazioneresidenza Nazione di residenza dell assistito (codice e descrizione) municipioresidenza Numero del municipio di residenza dell assistito datainizioresidenza Data di inizio validità dei dati di residenza datafineresidenza Data di fine validità dei dati di residenza indirizzodomicilio Indirizzo di domicilio dell assistito civicodomicilio Civico del domicilio dell assistito capdomicilio Cap del domicilio dell assistito comunedomicilio Comune di domicilio dell assistito (codice e descrizione) municipiodomicilio Numero del municipio di domicilio dell assistito datainiziodomicilio Data di inizio validità dei dati di domicilio datafinedomicilio Data di fine validità dei dati di domicilio email Indirizzo email dell assistito telefono1 Recapito telefonico dell assistito telefono2 Recapito telefonico dell assistito telefono3 Recapito telefonico dell assistito datainiziomandatoassistenziale Data di inizio del mandato assistenziale datafinemandatoassistenziale Data di fine del mandato assistenziale aslresidenza Asl di residenza dell assistito (codice e descrizione) distrettoresidenza Distretto di residenza dell assistito (codice e descrizione) asldomicilio Asl di domicilio dell assistito (codice e descrizione) distrettodomicilio Distretto di domicilio dell assistito (codice e descrizione) tiposcelta Tipo di scelta medico (codice e descrizione) medico Il medico curante dell assistito (sono riportati i campi indicati dal servizio datainizioscelta datafinescelta datascadenzascelta motivorevoca anagrafica medico) Data di assegnazione del medico Data di revoca del medico Data di scadenza dell assegnazione del medico Motivo di revoca (codice e descrizione) Ripetizione di Messaggio 11
Nome Campo Contenuto Codice value level parametri Codice del messaggio diagnostico Testo del messaggio Livello di importanza del messaggio. Uno tra TRACE, DEBUG, INFO, WARNING, ERROR, FATAL Corrisponde ai parametri di ricerca (RicercaAssistitiRequest) forniti in input 1.6 Esenzioni Assistito 1.6.1 Accesso al servizio L indirizzo per accedere al servizio di test è: https://qservice.regione.lazio.it/medbase-ws/ws/esenzioneassistito Si ricorda che i WSDL di definizione dei servizi devono essere scaricati dal https://qservice.regione.lazio.it/medbase-ws sezione downloads Pacchetto wsdl (01/06/2017) Sarà comunicato ad avvenuto collaudo l indirizzo per raggiungere i servizi esposti in ambiente di produzione. 1.6.2 Descrizione messaggio Tramite questo servizio è possibile ricercare un assistito di propria competenza tramite codice fiscale ed avere accesso alle informazioni sulle esenzioni a lui assegnate. 1.6.2.1 Campi di input Descrizione degli elementi costitutivi del messaggio di richiesta ricerca (ricercaesenzioniassistitorequest): Nome Campo Contenuto Tipo codicefiscale Codice fiscale dell assistito da estrarre obbligatorio 12
Nome Campo Contenuto Tipo perreddito Flag per estrarre solo le esenzioni da reddito o solo quelle per facoltativo patologia sensibile Campo per futuro utilizzo facoltativo datariferimento Data di riferimento per stabilire la validità dell esenzione facoltativo (di default viene considerata la data odierna) 1.6.2.2 Campi di output Descrizione degli elementi costitutivi del messaggio di risposta ricerca (ricercaassistitoresponse): codiceesito Nome Campo Contenuto Codice dell esito della ricerca. Valori possibili: -1 Elaborazione fallita 0 Elaborazione completata con successo 1 Elaborazione completata con presenza di warning descrizioneesito codicefiscale cognome nome Descrizione dell esito della ricerca Dati esente Codice fiscale dell assistito Cognome dell assistito Nome dell assistito sesso Sesso dell assistito (M o F) datanascita Data di nascita dell assistito comunenascita Comune di nascita dell assistito (codice e descrizione) Ripetizione di Esenzione codice Codice dell esenzione secondo il catalogo regionale delle esenzioni codicets Codice dell esenzione secondo il catalogo del sistema TS descrizione Descrizione dell esenzione datainizio Data di inizio assegnazione dell esenzione datafine Data di scadenza assegnazione dell esenzione datacessazione Data di cessazione anticipata dell assegnazione dell esenzione perreddito Flag che indica se si tratta di una esenzione da reddito Ripetizione di Messaggio codice Codice del messaggio diagnostico value Testo del messaggio 13
Nome Campo Contenuto level parametri Livello di importanza del messaggio. Uno tra TRACE, DEBUG, INFO, WARNING, ERROR, FATAL Corrisponde ai parametri di ricerca (ricercaesenzioniassistitorequest) forniti in input 1.7 Servizio Coorti 1.7.1 Accesso al servizio L indirizzo per accedere al servizio di test è: https://qservice.regione.lazio.it/medbase-ws/ws/coorte Si ricorda che i WSDL di definizione dei servizi devono essere scaricati dal https://qservice.regione.lazio.it/medbase-ws sezione downloads Pacchetto wsdl (01/06/2017) Sarà comunicato ad avvenuto collaudo l indirizzo per raggiungere i servizi esposti in ambiente di produzione. 1.7.2 Descrizione messaggio Tramite questo servizio è possibile ricercare una coorte tramite codice ed avere accesso alle informazioni sugli assistiti ad essa afferenti. 1.7.2.1 Campi di input Descrizione degli elementi costitutivi del messaggio di richiesta ricerca (ricercacoorterequest) : codicecoorte Il codice coorte da ricercare obbligatorio 14
ordinamento Campi per i quali effettuare l ordinamento dei dati. Per maggiori dettagli sulla sintassi da utilizzare per il campo di ordinamento fare riferimento alla relativa sezione del documento facoltativo (Valori ammessi: codicefiscale cognome nome) Campi relativi alla paginazione (vedere apposita sezione del documento) inizio Numero del record di inizio facoltativo fine Numero del record di fine facoltativo 1.7.2.2 Campi di output Descrizione degli elementi costitutivi del messaggio di risposta ricerca (ricercacoorteresponse): codiceesito Codice dell esito della ricerca. Valori possibili: -1 Elaborazione fallita 0 Elaborazione completata con successo 1 Elaborazione completata con presenza di warning descrizioneesito codice descrizione codicefiscale cognome nome Descrizione dell esito della ricerca Dati coorte Codice coorte Descrizione coorte Ripetizione di paziente Codice fiscale dell assistito Cognome dell assistito Nome dell assistito sesso Sesso dell assistito (M o F) datanascita Data di nascita dell assistito comunenascita Comune di nascita dell assistito (codice e descrizione) Ripetizione di Messaggio codice Codice del messaggio diagnostico value Testo del messaggio level Livello di importanza del messaggio. parametri Uno tra TRACE, DEBUG, INFO, WARNING, ERROR, FATAL Corrisponde ai parametri di ricerca (ricercacoorterequest) forniti in input 15
4 Note tecniche 4.1 Criteri di paginazione dei risultati I servizi che prevedono i parametri di paginazione offrono la possibilità di recuperare le informazioni un po' per volta. Questo garantisce una risposta più rapida e diminuisce notevolmente il traffico di rete per singola chiamata. Inoltre alcuni servizi, trattando potenzialmente una mole di dati eccessiva per per singola richiesta, impongono un limite massimo di record restituibili dal servizio. Per ovviare a tale problema pertanto il fruitore del servizio è tenuto a ridurre il resultset restituito dal server o impostando dei parametri di ricerca più stringenti o sfruttando i criteri di paginazione. Un esempio classico è quello della ricerca degli assistiti di una UCP. In una UCP gli assistiti possono essere migliaia ed il webservice non sarebbe in grado di restituire l elenco completo in una singola chiamata. Pertanto una possibilità sarebbe quella di restringere i parametri di ricerca impostando per esempio il cognome dell assistito, ma questo potrebbe non essere in linea con le necessità del software che intende integrarsi. Una soluzione migliore è quella di ricercare con i criteri di paginazione. Ad esempio impostando i campi inizio = 0 e fine = 9 si otterranno i primi 10 risultati della ricerca, impostando inizio = 10 e fine = 19 si otterranno i secondi 10 risultati e così via. Ovviamente in questo caso potrebbe essere di fondamentale importanza avere i risultati ordinati secondo un determinato criterio. I criteri di ordinamento dei risultati sono descritti nella prossima sezione. Resta inteso che questa funzionalità deve essere usata con criterio e non al solo scopo di aggirare i limiti imposti dal webservice. In tal senso non devono essere effettuate chiamate in serie per poter estrarre l intero resultset dei dati. 4.2 Criteri di ordinamento dei risultati I servizi che prevedono i parametri di ordinamento offrono la possibilità di recuperare le informazioni ordinate secondo determinati criteri. I campi per i quali è possibile applicare l ordinamento sono elencati nelle specifiche di ogni servizio che li prevede. E possibile ordinare per più campi sia in ordine crescente che decrescente. La sintassi da utilizzare nel parametro di ordinamento è la seguente (+ -)nomecampo1,(+ -)nomecampo2,(+ -)nomecampon esempio1: per ordinare in ordine crescente per i campi cognome e nome il campo ordinamento dovrà assumere il seguente valore: +cognome,+nome esempio2: per ordinare in ordine crescente per il campo cognome e descrescente per il campo nome il campo ordinamento dovrà assumere il seguente valore: +cognome,-nome 16
5 Ambiente di test e servizi 1.8 URL Servizi Di seguito URL di accesso ai servizi in ambiente di test: https://qservice.regione.lazio.it/medbase-ws Servizio Anagrafica medico UCP Anagrafica assistito Esenzioni Assistito Servizio Coorti Descrizione https://qservice.regione.lazio.it/medbase-ws/ws/medicoucp https://qservice.regione.lazio.it/medbase-ws/ws /assistito https://qservice.regione.lazio.it/medbase-ws/ws/esenzioneassistito https://qservice.regione.lazio.it/medbase-ws/ws/coorte Si ricorda che i WSDL di definizione dei servizi devono essere scaricati dal https://qservice.regione.lazio.it/medbase-ws sezione downloads Pacchetto wsdl (01/06/2017) 1.9 Accesso Servizi Attualmente i servizi sono accessibili senza autenticazione con l utenza fissa che corrisponde al CF del medico FGLMSM55B02H501Y. 1.10 Accesso Servizi Per effettuare l accesso ai servizi esposti, tramite basic authentication è presente l utenza valida per tutti gli attori interessati all integrazione: Utente: FGLMSM55B02H501Y Password: WsSAR001 17
1.11 Dati DB di test I dati presenti sul DB di test possono essere così riepilogati: Servizio Anagrafica Medico UCP: esiste una sola UCP con i medici con i CF: FGLMSM55B02H501Y LNEMRN59C70H501K. Servizio Anagrafica assistito: ci sono assistiti per i medici in UCP di cui sopra. Servizio Esenzioni assistito: ci sono varie tipologie di esenzione per l'assistito con CF RSSNMR24A48F023E. Servizio Coorti: esiste una sola Coorte (codice=cor001) con 4 assistiti. Anche se Codici Fiscali possono risultare corretti (ai fini di controlli che effettua SOGEI sulle ricette anche in ambiente di Test), i dati anagrafici associati a questi assistiti sono di fantasia. 18