aziendasanitaria-utils 1.2.49 → 1.2.56

package/README.md

@@ -252,6 +252,75 @@ const assistiti = await nar2.getAssistitiFromParams({
     [Nar2.PARAMS.NOME]: 'MARIO',
     [Nar2.PARAMS.AZIENDA]: '205'
 });
+
+// Elenco medici MMG/PLS, con dati dei rapporti individuali e degli indirizzi
+const medici = await nar2.getMediciFromNar2({
+    soloAttivi: true,
+    aggiungiDatiRapporti: true,   // allega `rapporti` e `indirizzi` a ogni medico
+    parallelsRapporti: 10         // richieste eseguite in parallelo
+});
+
+// Solo i rapporti / gli indirizzi di un medico dato il suo pf_id
+const rapporti = await nar2.getRapportiMedicoFromId(5860, 'ME');
+const indirizzi = await nar2.getIndirizziMedicoFromId(5860, 'ME');
+
+// Lookup comuni (cm_id NAR2) per nome/CAP/ISTAT/catastale, con filtro esatto
+// e fallback CAP generico per le città multi-CAP (98167 → 98100)
+const {comune, candidati} = await nar2.getComuneNar2({cap: '98167'}); // → MESSINA (id 83)
+
+// Aggiornamento residenza/domicilio (PUT /pazienti/{id}, dryRun default true).
+// Sorgenti combinabili: daTs (entrambi dal Sistema TS), residenzaDaTs/domicilioDaTs
+// (singola sezione da TS), residenza/domicilio personalizzati {via, civico, cap, comuneId|criterio}
+const dry = await nar2.aggiornaIndirizziAssistito(cf, {daTs: true});            // ispeziona dry.diff/warnings
+const sent = await nar2.aggiornaIndirizziAssistito(cf, {
+    residenzaDaTs: true,
+    domicilio: {via: 'VIA ROMA', civico: '10', cap: '98057'},                   // comune risolto dal CAP
+    dryRun: false
+});
+// Vedi docs/CAMBIO_MEDICO_NAR2.md §5.b — la verifica indirizzi è lo step standard
+// che precede il cambio medico (test interattivo: node ./test-cambio-medico.js)
+```
+
+Ogni rapporto è normalizzato così (include anche i rapporti non attivi; `attivo` è `true` solo se manca la data di fine):
+
+```javascript
+{
+    id: "75337",
+    categoria: "mmg",                 // "mmg" | "pls"
+    tipoRapporto: "MDB",
+    descrizioneRapporto: "Medico di base",
+    email: "...",
+    telefoni: ["3780818127", "3403896880"],   // array, scarta i valori nulli
+    dataInizio: "25/05/2026",         // dd/MM/yyyy
+    dataFine: null,                   // null = rapporto attivo
+    attivo: true,
+    domicilio: {                      // indirizzo studio; null se NAR non fornisce il link
+        comune: "MESSINA",
+        provincia: "ME",
+        cap: "98100",
+        indirizzo: "VIA CENTONZE",
+        numeroCivico: "72"
+    }
+}
+```
+
+Gli indirizzi del medico (legati al medico, non al rapporto) sono restituiti tutti in array, normalizzati così:
+
+```javascript
+{
+    progressivo: "1",
+    descrizione: "RESIDENZA",          // può essere null
+    comune: "CANICATTI'",
+    provincia: "AG",
+    cap: "92024",
+    indirizzo: "VIA S. CORAZZINI, 9",
+    numeroCivico: "1",
+    dataAttivazione: "21/03/2065",     // dd/MM/yyyy
+    dataDisattivazione: null,
+    residenza: true,                   // true se è l'indirizzo di residenza
+    telefoni: [],
+    email: null
+}
 ```
 
 #### Assistiti - Gestione Dati Assistiti

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=14.0.0"
   },
-  "version": "1.2.49",
+  "version": "1.2.56",
   "repository": "deduzzo/aziendasanitaria-utils",
   "description": "Un utility per gestire i flussi sanitari Siciliani e non solo..",
   "main": "index.js",

package/src/narTsServices/Nar2.js

@@ -24,6 +24,8 @@ export class Nar2 {
     static MEDICI_BY_AMBITO_AUTOCOMPLETE = "https://nar2.regione.sicilia.it/services/index.php/api/mediciByAmbito";
     static MOTIVI_OPERAZIONE_FROM_TIPO = "https://nar2.regione.sicilia.it/services/index.php/api/motiviOperazioneFromMotivoRevoca/{tipoOp}";
     static STAMPA_DOCUMENTO_URL = "https://nar2.regione.sicilia.it/services/index.php/api/stampe/{tipo}";
+    static GET_COMUNI_AUTOCOMPLETE = "https://nar2.regione.sicilia.it/services/index.php/api/comuni";
+    static GET_COMUNE_FROM_ID = "https://nar2.regione.sicilia.it/services/index.php/api/anagrafica/comune/{id}";
 
     // Documenti di stampa dell'assistito (endpoint /stampe/{tipo}?paziente={pz_id} → application/pdf).
     // Etichette UI nella pagina medico-di-base (ultimo rapporto, attivo o cessato).
@@ -92,6 +94,26 @@ export class Nar2 {
         PAGINATION: 'pagination'
     };
 
+    // Campi del record paziente inviati dalla UI NAR2 nella PUT /pazienti/{id}
+    // (tracciato di rete della pagina anagrafica, 2026-06-04). Il payload viene
+    // ricostruito prendendo questi campi dal record corrente del GET /pazienti/{id}:
+    // NON vanno inclusi i campi derivati/annidati (comune_residenza, storico_medici, ...).
+    static #CAMPI_PUT_PAZIENTE = [
+        "pz_cogn", "pz_nome", "pz_dt_nas", "pz_cfis", "pz_sesso", "pz_com_nas", "pz_citt",
+        "pz_fcertif", "pz_fcompl", "pz_fstato", "pz_dscadaire", "pz_aire", "pz_ise",
+        "pz_dt_dec", "pz_con_pers", "pz_con_parentela", "pz_con_tele", "pz_email",
+        "pz_tel1", "pz_tel2", "pz_tel3", "pz_tel1_nota", "pz_tel2_nota", "pz_tel3_nota",
+        "pz_flagpriv", "pz_com_dec", "pz_ind_res", "pz_com_res", "pz_nciv_res",
+        "pz_com_dom", "pz_ind_dom", "pz_nciv_dom", "pz_categoria_citt", "pz_asl_app",
+        "pz_reg_res", "pz_doc_dt_ril", "pz_doc_ril_da", "pz_doc_ril_di", "pz_documento",
+        "pz_doc_dt_sca", "pz_doc_tipo", "pz_asl_pro", "pz_com_imm", "pz_com_emi",
+        "pz_dt_emi", "pz_dt_imm", "pz_dis_pro", "pz_dt_ini_ssn", "pz_dt_end_ssn",
+        "pz_asl_ass", "pz_dt_ini_asl", "pz_dt_end_asl", "pz_distretto_ass", "pz_reg_assi",
+        "pz_ts_dt_ini", "pz_dscadtess", "pz_tsan", "pz_ts_asl_emi", "pz_drilstp",
+        "pz_dscadstp", "pz_stp", "pz_drileni", "pz_dscadeni", "pz_eni",
+        "pz_team_dt_ini", "pz_team_dtsca", "pz_team_tes", "pz_team_id", "pz_team_qualben"
+    ];
+
     static #token = null;
     static #tokenPromise = null; // Variabile per la chiamata in corso
 
@@ -193,7 +215,7 @@ export class Nar2 {
     async getSituazioniAssistenzialiAmmesse(codFiscale, config = {}) {
         const {pmId = null, tipoMedico = Nar2.MEDICO_DI_BASE} = config;
         const dati = await this.getDatiAssistitoNar2FromCf(codFiscale);
-        if (!dati || !dati.ok) return {ok: false, data: null};
+        if (!dati || !dati.ok) return {ok: false, data: null, error: dati?.error || "Assistito non trovato su NAR2", errorDetail: dati?.errorDetail ?? null};
         const fullData = dati.fullData.data;
         const eta = moment().diff(moment(fullData.pz_dt_nas, "YYYY-MM-DD HH:mm:ss"), "years");
         const azId = fullData.comune_domicilio?._azienda?.[0]?.az_azie ?? "ME";
@@ -251,13 +273,13 @@ export class Nar2 {
         let sm = sceltaMedico;
         if (!sm) {
             const dati = await this.getDatiAssistitoNar2FromCf(codFiscale);
-            if (!dati || !dati.ok) return {ok: false, data: null};
+            if (!dati || !dati.ok) return {ok: false, data: null, error: dati?.error || "Assistito non trovato su NAR2", errorDetail: dati?.errorDetail ?? null};
             const pazienteId = dati.fullData.data.pz_id;
             const azId = dati.fullData.data.comune_domicilio?._azienda?.[0]?.az_azie ?? "ME";
             const res = await this.#getDataFromUrlIdOrParams(Nar2.GET_DATI_PAZIENTEMEDICO, {
                 replaceFromUrl: {id: pazienteId, tipo_medico: tipoMedico, az_id: azId}
             });
-            if (!res.ok || !res.data?.sceltaMedico) return {ok: false, data: null};
+            if (!res.ok || !res.data?.sceltaMedico) return {ok: false, data: null, error: res.error || "Dati paziente-medico non disponibili su NAR2", errorDetail: res.errorDetail ?? null};
             sm = res.data.sceltaMedico;
         }
         let tipi = Array.isArray(sm.tipoOperazioni_) ? sm.tipoOperazioni_ : [];
@@ -287,18 +309,20 @@ export class Nar2 {
     async getMotiviOperazione(tipoOp = Nar2.TIPO_OP_REVOCA, config = {}) {
         const {semplifica = false, retryVuoto = 3} = config;
         let data = null;
+        let lastRes = null;
         for (let i = 0; i <= retryVuoto; i++) {
             const res = await this.#getDataFromUrlIdOrParams(Nar2.MOTIVI_OPERAZIONE_FROM_TIPO, {
                 replaceFromUrl: {tipoOp},
                 rawResponse: true
             });
+            lastRes = res;
             if (res.ok && Array.isArray(res.data)) {
                 data = res.data;
                 if (data.length > 0) break;        // ok con motivi
             }
             if (i < retryVuoto) await new Promise((r) => setTimeout(r, 300));
         }
-        if (!Array.isArray(data)) return {ok: false, data: null};
+        if (!Array.isArray(data)) return {ok: false, data: null, error: lastRes?.error || "Motivi operazione non disponibili su NAR2", errorDetail: lastRes?.errorDetail ?? null};
         if (semplifica) data = data.map((m) => ({id: m.eg_id, codice: m.eg_cod, descrizione: m.eg_desc1}));
         return {ok: true, data};
     }
@@ -320,7 +344,7 @@ export class Nar2 {
     async getMotiviPerTipoOperazione(codFiscale, config = {}) {
         const {tipoMedico = Nar2.MEDICO_DI_BASE, semplifica = true, gruppo = null} = config;
         const tipiRes = await this.getTipiOperazione(codFiscale, {tipoMedico, semplifica: false, gruppo});
-        if (!tipiRes.ok || !Array.isArray(tipiRes.data)) return {ok: false, data: null};
+        if (!tipiRes.ok || !Array.isArray(tipiRes.data)) return {ok: false, data: null, error: tipiRes.error || "Tipi operazione non disponibili su NAR2", errorDetail: tipiRes.errorDetail ?? null};
 
         const data = await Promise.all(tipiRes.data.map(async (tp) => {
             const motiviRes = await this.getMotiviOperazione(tp.eg_id, {semplifica});
@@ -380,7 +404,9 @@ export class Nar2 {
             dataScelta = moment().format("YYYY-MM-DD"),
             sitAssistenziale = 4
         } = config;
-        const fullData = (await this.getDatiAssistitoNar2FromCf(codFiscaleAssistito)).fullData.data;
+        const dati = await this.getDatiAssistitoNar2FromCf(codFiscaleAssistito);
+        if (!dati || !dati.ok || !dati.fullData?.data) return {ok: false, data: null, error: dati?.error || "Assistito non trovato su NAR2", errorDetail: dati?.errorDetail ?? null};
+        const fullData = dati.fullData.data;
         const azienda = fullData.comune_domicilio?._azienda?.[0]?.az_azie ?? "ME";
         return await this.#getDataFromUrlIdOrParams(Nar2.MEDICI_BY_AMBITO_AUTOCOMPLETE, {
             getParams: {
@@ -458,29 +484,64 @@ export class Nar2 {
         // 1) Dati assistito
         const datiAssistito = await this.getDatiAssistitoNar2FromCf(codFiscale);
         if (!datiAssistito || !datiAssistito.ok) {
-            return {ok: false, dryRun, payload: null, response: null, error: "Assistito non trovato su NAR2"};
+            return {ok: false, dryRun, payload: null, response: null, error: datiAssistito?.error || "Assistito non trovato su NAR2", errorDetail: datiAssistito?.errorDetail ?? null};
         }
         const fullData = datiAssistito.fullData.data;
         const pzId = fullData.pz_id;
         const eta = moment().diff(moment(fullData.pz_dt_nas, "YYYY-MM-DD HH:mm:ss"), "years");
         const azId = fullData.comune_domicilio?._azienda?.[0]?.az_azie ?? "ME";
 
-        // 2) Ambito di domicilio (se non fornito): lo ricavo dai dati paziente o dal catalogo ambiti
-        let ambitoDom = idAmbitoDomicilio;
+        // 2) Ambito di domicilio (se non fornito): SEMPRE dal catalogo CORRENTE
+        // (/ambitoDomTable → sr_id per il comune di domicilio, vedi spec
+        // CAMBIO_MEDICO_NAR2.md §8.1/§12). MAI dallo storico come fonte primaria:
+        // gli id ambito vengono riorganizzati nel tempo da NAR2 (es. scelta del 2000
+        // con dm_ambito_dom=147; oggi l'ambito valido per lo stesso comune è 3748) e
+        // un id stale viene rifiutato dalla POST /pazienti/sceltaMedico con 400.
+        let ambitoDom = idAmbitoDomicilio ?? null;
+        let ambitiRes = null;
         if (!ambitoDom) {
-            const dettStorico = fullData.storico_medici?.[0]?.dett_pazientemedico;
-            ambitoDom = dettStorico?.dm_ambito_dom ?? null;
-            if (!ambitoDom) {
-                // fallback: prendo il primo ambito MMG/Pediatra dalla lista
-                const ambitiRes = await this.getAmbitiDomicilioAssistito(codFiscale, {dividiAmbitiMMGPediatri: true});
-                if (ambitiRes?.ok) {
-                    const lista = tipoMedico === Nar2.PEDIATRA ? ambitiRes.data.ambiti.pediatri : ambitiRes.data.ambiti.mmg;
-                    ambitoDom = lista?.[0]?.sr_id ?? null;
+            ambitiRes = await this.getAmbitiDomicilioAssistito(codFiscale, {dividiAmbitiMMGPediatri: true});
+            const lista = (ambitiRes?.ok
+                ? (tipoMedico === Nar2.PEDIATRA ? ambitiRes.data.ambiti.pediatri : ambitiRes.data.ambiti.mmg)
+                : null) ?? [];
+            const listaIds = lista.map((a) => a?.sr_id?.toString()).filter(Boolean);
+            if (listaIds.length === 1) {
+                ambitoDom = listaIds[0];
+            } else if (listaIds.length > 1) {
+                // Comune con più ambiti: disambiguo con l'ambito del rapporto del
+                // medico scelto, se compare nel catalogo. Su medici/{id} il campo è
+                // lo scalare dett_medico.dm_ambito (verificato live); in altri
+                // contesti la spec mostra l'oggetto annidato dett_medico.ambito
+                // {sr_id,...} — li leggo entrambi per robustezza.
+                const medicoRes = await this.getMedicoFromId(idMedico);
+                const ambitiMedico = (medicoRes?.ok ? (medicoRes.data?.rapporto_individuale ?? []) : [])
+                    .map((ri) => (ri?.dett_medico?.dm_ambito ?? ri?.dett_medico?.ambito?.sr_id)?.toString())
+                    .filter(Boolean);
+                ambitoDom = ambitiMedico.find((a) => listaIds.includes(a)) ?? null;
+                if (!ambitoDom) {
+                    // Continuità: l'ambito della scelta ATTIVA, ma solo se ancora
+                    // presente nel catalogo corrente (altrimenti è stale).
+                    const attiva = (Array.isArray(fullData.storico_medici) ? fullData.storico_medici : [])
+                        .find((s) => s?.pm_fstato === "A" && !s?.pm_dt_disable);
+                    const ambitoAttiva = attiva?.dett_pazientemedico?.dm_ambito_dom?.toString() ?? null;
+                    ambitoDom = (ambitoAttiva && listaIds.includes(ambitoAttiva)) ? ambitoAttiva : listaIds[0];
                 }
             }
+            // Last resort (catalogo non disponibile): ambito della scelta attiva,
+            // potenzialmente stale ma meglio di niente. NB: scelta ATTIVA, non
+            // storico_medici[0] (l'array non è ordinato).
+            if (!ambitoDom) {
+                const attiva = (Array.isArray(fullData.storico_medici) ? fullData.storico_medici : [])
+                    .find((s) => s?.pm_fstato === "A" && !s?.pm_dt_disable);
+                ambitoDom = attiva?.dett_pazientemedico?.dm_ambito_dom ?? null;
+            }
         }
         if (!ambitoDom) {
-            return {ok: false, dryRun, payload: null, response: null, error: "Impossibile determinare l'ambito di domicilio"};
+            return {
+                ok: false, dryRun, payload: null, response: null,
+                error: ambitiRes?.error || "Impossibile determinare l'ambito di domicilio",
+                errorDetail: ambitiRes?.errorDetail ?? null
+            };
         }
         const ambitoScelta = idAmbitoScelta ?? ambitoDom;
 
@@ -512,7 +573,7 @@ export class Nar2 {
         // 4) Situazione assistenziale + motivo + tipo operazione (dal catalogo)
         const sitAmmesse = await this.getSituazioniAssistenzialiAmmesse(codFiscale, {tipoMedico});
         if (!sitAmmesse || !sitAmmesse.ok || !Array.isArray(sitAmmesse.data)) {
-            return {ok: false, dryRun, payload: null, response: null, error: "Impossibile recuperare situazioni assistenziali ammesse"};
+            return {ok: false, dryRun, payload: null, response: null, error: sitAmmesse?.error || "Impossibile recuperare situazioni assistenziali ammesse", errorDetail: sitAmmesse?.errorDetail ?? null};
         }
         let situazioneScelta;
         if (idSituazioneAssistenziale) {
@@ -577,7 +638,380 @@ export class Nar2 {
             payload,
             response: result.fullResponse,
             data: result.data,
-            error: result.ok ? undefined : "Errore durante la POST /pazienti/sceltaMedico"
+            error: result.ok ? undefined : (result.error || "Errore durante la POST /pazienti/sceltaMedico"),
+            errorDetail: result.ok ? undefined : (result.errorDetail ?? null)
+        };
+    }
+
+    /**
+     * Ricerca comuni via autocomplete NAR2.
+     *
+     * Endpoint: GET /comuni?start=0&autocomplete=true&searchKey=...
+     * La ricerca è "contains" su nome (cm_desc), CAP (cm_ccap), codice ISTAT
+     * (cm_cistat) e codice catastale (cm_cfis). NB (verificato live):
+     *  - searchKey vuota → 0 risultati (serve almeno un carattere);
+     *  - il CAP in tabella è UNO solo per comune (il generico: Messina=98100),
+     *    i CAP specifici delle città multi-CAP non matchano (vedi getComuneNar2).
+     *
+     * @param {string} searchKey - Chiave di ricerca (nome parziale, CAP, ISTAT, catastale).
+     * @param {Object} [config={}]
+     * @param {boolean} [config.semplifica=true] - Se true ritorna {id, nome, cap, provincia, istat, catastale, regione}; se false i record grezzi cm_*.
+     * @returns {Promise<{ok:boolean, data:Array|null, count:number|null}>} `count` = totale lato server (la pagina restituita può essere più corta).
+     */
+    async getComuni(searchKey, config = {}) {
+        const {semplifica = true} = config;
+        const res = await this.#getDataFromUrlIdOrParams(Nar2.GET_COMUNI_AUTOCOMPLETE, {
+            getParams: {start: 0, autocomplete: true, searchKey: (searchKey ?? "").toString().trim()},
+            rawResponse: true // serve l'envelope completo per leggere anche `count`
+        });
+        if (!res.ok) return {ok: false, data: null, count: null, error: res.error, errorDetail: res.errorDetail ?? null};
+        const body = res.data ?? {};
+        if (body.status?.toString() !== "true" || !Array.isArray(body.result)) {
+            return {ok: false, data: null, count: null, error: Nar2.#extractErrorMessage(body) || "Risposta /comuni non valida", errorDetail: null};
+        }
+        const data = semplifica
+            ? body.result.map((c) => ({
+                id: c.cm_id,
+                nome: c.cm_desc,
+                cap: c.cm_ccap,
+                provincia: c.cm_prov,
+                istat: c.cm_cistat,
+                catastale: c.cm_cfis,
+                regione: c.cm_reg
+            }))
+            : body.result;
+        return {ok: true, data, count: body.count ?? data.length};
+    }
+
+    /**
+     * Risolve un comune NAR2 (cm_id) a partire da UN criterio: nome, CAP,
+     * codice ISTAT (6 cifre con zero iniziale) o codice catastale/Belfiore.
+     * Applica un filtro ESATTO lato client sul criterio usato: la searchKey del
+     * server è "contains" su più campi e produce falsi positivi (es. CAP 98057
+     * matcha anche TERRANOVA DEI PASSERINI per l'ISTAT 098057).
+     *
+     * CAP delle città multi-CAP: la tabella NAR2 ha solo il CAP generico
+     * (98167 → 0 risultati). Se il CAP esatto non trova nulla si riprova col
+     * CAP generalizzato (ultime 2 cifre → "00": 98167→98100) e il risultato
+     * viene marcato `capGenerico: true`.
+     *
+     * Precedenza criteri (dal più univoco): catastale > istat > cap > nome.
+     *
+     * @param {Object} [criteri={}]
+     * @param {string} [criteri.nome] - Nome (anche parziale; match esatto se esiste, altrimenti i parziali).
+     * @param {string} [criteri.cap] - CAP a 5 cifre.
+     * @param {string} [criteri.istat] - Codice ISTAT 6 cifre (es. "083049").
+     * @param {string} [criteri.catastale] - Codice catastale (es. "F206").
+     * @returns {Promise<{ok:boolean, comune:Object|null, candidati:Array, capGenerico?:boolean}>}
+     *          `comune` valorizzato solo se il match è univoco; `candidati` per la scelta interattiva.
+     */
+    async getComuneNar2(criteri = {}) {
+        const norm = (s) => (s ?? "").toString().trim().toUpperCase();
+        const {nome = null, cap = null, istat = null, catastale = null} = criteri;
+        const ricerca = async (searchKey, campo, valore) => {
+            const res = await this.getComuni(searchKey);
+            if (!res.ok) return res;
+            return {ok: true, data: res.data.filter((c) => norm(c[campo]) === norm(valore))};
+        };
+
+        let candidati = null;
+        let capGenerico = false;
+        let lastRes = null;
+        if (catastale) {
+            lastRes = await ricerca(catastale, "catastale", catastale);
+            candidati = lastRes.ok ? lastRes.data : null;
+        } else if (istat) {
+            lastRes = await ricerca(istat, "istat", istat);
+            candidati = lastRes.ok ? lastRes.data : null;
+        } else if (cap) {
+            lastRes = await ricerca(cap, "cap", cap);
+            candidati = lastRes.ok ? lastRes.data : null;
+            if (lastRes.ok && candidati.length === 0 && /^\d{5}$/.test(norm(cap))) {
+                // CAP specifico di città multi-CAP: riprovo col CAP generico (98167 → 98100)
+                const generico = `${norm(cap).substring(0, 3)}00`;
+                if (generico !== norm(cap)) {
+                    lastRes = await ricerca(generico, "cap", generico);
+                    if (lastRes.ok && lastRes.data.length > 0) {
+                        candidati = lastRes.data;
+                        capGenerico = true;
+                    }
+                }
+            }
+        } else if (nome) {
+            const res = await this.getComuni(nome);
+            lastRes = res;
+            if (res.ok) {
+                const esatti = res.data.filter((c) => norm(c.nome) === norm(nome));
+                candidati = esatti.length > 0 ? esatti : res.data;
+            }
+        } else {
+            return {ok: false, comune: null, candidati: [], error: "Nessun criterio di ricerca fornito (nome, cap, istat o catastale)"};
+        }
+
+        if (!candidati) return {ok: false, comune: null, candidati: [], error: lastRes?.error || "Ricerca comuni fallita", errorDetail: lastRes?.errorDetail ?? null};
+        if (candidati.length === 0) return {ok: false, comune: null, candidati: [], error: `Nessun comune trovato per ${JSON.stringify(criteri)}`};
+        return {ok: true, comune: candidati.length === 1 ? candidati[0] : null, candidati, ...(capGenerico ? {capGenerico} : {})};
+    }
+
+    /**
+     * Dettaglio di un comune per cm_id.
+     *
+     * Endpoint: GET /anagrafica/comune/{id} → record cm_* completo, incluso
+     * `uc_asl` (ASL di competenza territoriale, es. "281"), usato per il
+     * warning di coerenza ASL in aggiornaIndirizziAssistito.
+     *
+     * @param {string|number} cmId - cm_id interno NAR2.
+     * @returns {Promise<{ok:boolean, data:Object|null}>}
+     */
+    async getComuneFromId(cmId) {
+        return await this.#getDataFromUrlIdOrParams(Nar2.GET_COMUNE_FROM_ID, {replaceFromUrl: {id: cmId}});
+    }
+
+    /**
+     * Compone la stringa indirizzo nel formato usato dal Sistema TS / NAR2:
+     * "PACE SALITA BISIGNANI 3 ,  98167  MESSINA  (ME)"
+     * (via civico, spazio-virgola-doppio spazio, CAP, doppio spazio, comune,
+     * doppio spazio, provincia tra parentesi; tutto maiuscolo).
+     * Il CAP è quello reale dell'indirizzo (es. 98167), non per forza il cm_ccap.
+     *
+     * @param {Object} p
+     * @param {string} p.via - Via/denominazione (es. "PACE SALITA BISIGNANI").
+     * @param {string|number|null} [p.civico=null] - Numero civico (accodato alla via).
+     * @param {string|number} p.cap - CAP a 5 cifre.
+     * @param {string} p.nomeComune - Nome comune (es. "MESSINA").
+     * @param {string} p.provincia - Sigla provincia (es. "ME").
+     * @returns {string} Indirizzo formattato.
+     */
+    static formattaIndirizzoNar2({via, civico = null, cap, nomeComune, provincia}) {
+        const clean = (v) => (v === null || typeof v === "undefined") ? "" : v.toString().trim();
+        const viaCivico = [clean(via), clean(civico)].filter((x) => x !== "").join(" ");
+        return `${viaCivico} ,  ${clean(cap)}  ${clean(nomeComune)}  (${clean(provincia)})`.toUpperCase();
+    }
+
+    /**
+     * Risolve un parametro indirizzo di aggiornaIndirizziAssistito in
+     * `{indirizzo, comuneId, comune}` pronti per il payload. Accetta:
+     *  - {indirizzo: "già formattato", comuneId} → passa-through;
+     *  - {via, civico?, cap, comuneId} → comune da id, stringa composta;
+     *  - {via, civico?, cap, catastale|istat|nome} → comune risolto univocamente
+     *    (il cap viene usato come criterio se non c'è altro), stringa composta.
+     *
+     * @param {Object} param - Parametro indirizzo (vedi sopra).
+     * @param {string} etichetta - "residenza" o "domicilio" (per i messaggi di errore).
+     * @returns {Promise<{ok:boolean, indirizzo?:string, comuneId?:string, comune?:Object, candidati?:Array}>}
+     */
+    async #risolviParametroIndirizzo(param, etichetta) {
+        if (!param || typeof param !== "object")
+            return {ok: false, error: `Parametro ${etichetta} mancante o non valido`};
+
+        // comune: da id diretto o da criteri
+        let comune = null;
+        if (param.comuneId) {
+            const det = await this.getComuneFromId(param.comuneId);
+            if (!det.ok || !det.data)
+                return {ok: false, error: `Comune ${etichetta} non trovato per id=${param.comuneId}${det.error ? `: ${det.error}` : ""}`, errorDetail: det.errorDetail ?? null};
+            comune = {
+                id: det.data.cm_id, nome: det.data.cm_desc, cap: det.data.cm_ccap,
+                provincia: det.data.cm_prov, istat: det.data.cm_cistat,
+                catastale: det.data.cm_cfis, regione: det.data.cm_reg
+            };
+        } else {
+            const criteri = {};
+            if (param.catastale) criteri.catastale = param.catastale;
+            else if (param.istat) criteri.istat = param.istat;
+            else if (param.nome) criteri.nome = param.nome;
+            else if (param.cap) criteri.cap = param.cap;
+            if (Object.keys(criteri).length === 0)
+                return {ok: false, error: `Comune ${etichetta} non determinabile: fornire comuneId oppure catastale/istat/nome/cap`};
+            const res = await this.getComuneNar2(criteri);
+            if (!res.ok) return {ok: false, error: `Comune ${etichetta}: ${res.error}`, errorDetail: res.errorDetail ?? null};
+            if (!res.comune) {
+                return {
+                    ok: false,
+                    error: `Comune ${etichetta} ambiguo per ${JSON.stringify(criteri)}: ${res.candidati.map((c) => `${c.nome} (${c.provincia}, id=${c.id})`).join("; ")}`,
+                    candidati: res.candidati
+                };
+            }
+            comune = res.comune;
+        }
+
+        // stringa indirizzo: passa-through o composizione nel formato TS
+        let indirizzo;
+        if (typeof param.indirizzo === "string" && param.indirizzo.trim() !== "") {
+            indirizzo = param.indirizzo.trim().toUpperCase();
+        } else {
+            if (!param.via || !param.cap)
+                return {ok: false, error: `Indirizzo ${etichetta} incompleto: servono almeno via e cap (oppure la stringa già formattata in 'indirizzo')`};
+            indirizzo = Nar2.formattaIndirizzoNar2({
+                via: param.via, civico: param.civico ?? null, cap: param.cap,
+                nomeComune: comune.nome, provincia: comune.provincia
+            });
+        }
+        return {ok: true, indirizzo, comuneId: comune.id?.toString(), comune};
+    }
+
+    /**
+     * Aggiorna residenza e/o domicilio di un assistito su NAR2 replicando la PUT
+     * della pagina anagrafica: PUT /pazienti/{pz_id} con il record completo
+     * (whitelist #CAMPI_PUT_PAZIENTE presa dal record corrente) e i soli campi
+     * indirizzo modificati (pz_ind_res/pz_com_res/pz_nciv_res, pz_ind_dom/
+     * pz_com_dom/pz_nciv_dom). Come la UI: civico dentro la stringa, pz_nciv_*=null,
+     * pz_com_* = cm_id interno NAR2 (NON il codice ISTAT).
+     *
+     * Sorgenti combinabili per ciascuna sezione (residenza, domicilio):
+     *  - {daTs: true}            → scorciatoia: residenza E domicilio = indirizzo del Sistema TS
+     *                              (p801recapitoTessera; comune dal catastale TS, fallback ISTAT)
+     *  - {residenzaDaTs: true}   → la sola residenza dall'indirizzo TS
+     *  - {domicilioDaTs: true}   → il solo domicilio dall'indirizzo TS
+     *  - {residenza: {...}}      → residenza da parametro
+     *  - {domicilio: {...}}      → domicilio da parametro
+     * Es.: {residenzaDaTs: true, domicilio: {...}} = residenza da TS + domicilio manuale.
+     * Conflitti (daTs con altri; *DaTs con il parametro della stessa sezione) → ok:false.
+     *
+     * Parametro indirizzo (residenza/domicilio): vedi #risolviParametroIndirizzo.
+     *
+     * Nessun campo ASL/regione viene toccato (comportamento identico alla UI):
+     * se l'ASL di competenza del comune (uc_asl) differisce da pz_asl_app viene
+     * aggiunto un warning non bloccante in `warnings[]`.
+     *
+     * @param {string} codFiscale - Codice fiscale dell'assistito.
+     * @param {Object} [config={}]
+     * @param {boolean} [config.dryRun=true] - DEFAULT TRUE: ritorna payload e diff senza inviare.
+     * @param {boolean} [config.daTs=false] - Residenza E domicilio dall'indirizzo TS (scorciatoia).
+     * @param {boolean} [config.residenzaDaTs=false] - La sola residenza dall'indirizzo TS.
+     * @param {boolean} [config.domicilioDaTs=false] - Il solo domicilio dall'indirizzo TS.
+     * @param {Object|null} [config.residenza=null] - Indirizzo residenza da parametro.
+     * @param {Object|null} [config.domicilio=null] - Indirizzo domicilio da parametro.
+     * @returns {Promise<{ok:boolean, dryRun:boolean, payload:Object|null, diff:Object|null, warnings:string[], response:Object|null, error?:string}>}
+     *          `diff` = {campo: {da, a}} dei soli campi che cambiano rispetto al record corrente.
+     */
+    async aggiornaIndirizziAssistito(codFiscale, config = {}) {
+        const {dryRun = true, daTs = false, residenzaDaTs = false, domicilioDaTs = false, residenza = null, domicilio = null} = config;
+        const warnings = [];
+        const ko = (error, extra = {}) => ({ok: false, dryRun, payload: null, diff: null, warnings, response: null, error, ...extra});
+
+        if (!daTs && !residenzaDaTs && !domicilioDaTs && !residenza && !domicilio)
+            return ko("Nessuna modifica richiesta: specificare daTs, residenzaDaTs, domicilioDaTs e/o residenza/domicilio");
+        if (daTs && (residenzaDaTs || domicilioDaTs || residenza || domicilio))
+            return ko("daTs è esclusivo: non combinare con residenzaDaTs/domicilioDaTs/residenza/domicilio");
+        if (residenzaDaTs && residenza)
+            return ko("residenzaDaTs e residenza sono alternativi");
+        if (domicilioDaTs && domicilio)
+            return ko("domicilioDaTs e domicilio sono alternativi");
+
+        // 1) Record corrente NAR2
+        const datiAssistito = await this.getDatiAssistitoNar2FromCf(codFiscale);
+        if (!datiAssistito || !datiAssistito.ok)
+            return ko(datiAssistito?.error || "Assistito non trovato su NAR2", {errorDetail: datiAssistito?.errorDetail ?? null});
+        const fullData = datiAssistito.fullData.data;
+
+        // 2) Indirizzo dal Sistema TS (se richiesto)
+        let nuovaResidenza = null; // {indirizzo, comuneId, comune}
+        let nuovoDomicilio = null;
+        if (daTs || residenzaDaTs || domicilioDaTs) {
+            const sogei = await this.getDatiAssistitoFromCfSuSogeiNew(codFiscale);
+            const tsData = sogei?.fullData?.data ?? null;
+            const indirizzoTs = (typeof tsData?.p801recapitoTessera === "string" && tsData.p801recapitoTessera.trim() !== "")
+                ? tsData.p801recapitoTessera.trim() : null;
+            if (!sogei?.ok || sogei?.data?.okTs !== true || !indirizzoTs)
+                return ko(sogei?.data?.erroreTs || "Indirizzo Sistema TS non disponibile per l'assistito");
+            // comune TS: catastale (univoco su NAR2), fallback ISTAT
+            const catastaleTs = (tsData.p801codiceComuneResidenza ?? "").toString().trim();
+            const istatTs = (tsData.p801codiceistatiComuneResidenza ?? "").toString().trim();
+            let comuneRes = catastaleTs ? await this.getComuneNar2({catastale: catastaleTs}) : {ok: false, comune: null};
+            if (!comuneRes.ok || !comuneRes.comune)
+                comuneRes = istatTs ? await this.getComuneNar2({istat: istatTs}) : comuneRes;
+            if (!comuneRes.ok || !comuneRes.comune)
+                return ko(`Comune TS non risolvibile su NAR2 (catastale='${catastaleTs}', istat='${istatTs}')${comuneRes.error ? `: ${comuneRes.error}` : ""}`);
+            // normalizza nel formato concordato: l'API Sogei usa spaziatura semplice
+            // ("VIA X 3, 98167 MESSINA (ME)"), il formato target è quello della UI
+            // ("VIA X 3 ,  98167  MESSINA  (ME)") — scompongo e ricompongo
+            let indirizzoTsNormalizzato;
+            const m = indirizzoTs.match(/^(.+?)\s*,\s*(\d{5})\s+(.+?)\s+\(([A-Za-z]{2})\)\s*$/);
+            if (m) {
+                indirizzoTsNormalizzato = Nar2.formattaIndirizzoNar2({
+                    via: m[1], cap: m[2],
+                    nomeComune: comuneRes.comune.nome, provincia: comuneRes.comune.provincia
+                });
+            } else {
+                indirizzoTsNormalizzato = indirizzoTs.toUpperCase();
+                warnings.push(`Indirizzo TS non scomponibile ("${indirizzoTs}"): usato così com'è`);
+            }
+            const daSistemaTs = {indirizzo: indirizzoTsNormalizzato, comuneId: comuneRes.comune.id?.toString(), comune: comuneRes.comune};
+            if (daTs || residenzaDaTs) nuovaResidenza = daSistemaTs;
+            if (daTs || domicilioDaTs) nuovoDomicilio = daSistemaTs;
+        }
+
+        // 3) Indirizzi da parametro
+        if (residenza) {
+            const r = await this.#risolviParametroIndirizzo(residenza, "residenza");
+            if (!r.ok) return ko(r.error, {errorDetail: r.errorDetail ?? null, ...(r.candidati ? {candidati: r.candidati} : {})});
+            nuovaResidenza = r;
+        }
+        if (domicilio) {
+            const d = await this.#risolviParametroIndirizzo(domicilio, "domicilio");
+            if (!d.ok) return ko(d.error, {errorDetail: d.errorDetail ?? null, ...(d.candidati ? {candidati: d.candidati} : {})});
+            nuovoDomicilio = d;
+        }
+
+        // 4) Payload: whitelist dei campi della PUT UI + override dei soli campi toccati
+        const payloadData = {};
+        for (const campo of Nar2.#CAMPI_PUT_PAZIENTE)
+            payloadData[campo] = typeof fullData[campo] === "undefined" ? null : fullData[campo];
+        if (nuovaResidenza) {
+            payloadData.pz_ind_res = nuovaResidenza.indirizzo;
+            payloadData.pz_com_res = nuovaResidenza.comuneId;
+            payloadData.pz_nciv_res = null;
+        }
+        if (nuovoDomicilio) {
+            payloadData.pz_ind_dom = nuovoDomicilio.indirizzo;
+            payloadData.pz_com_dom = nuovoDomicilio.comuneId;
+            payloadData.pz_nciv_dom = null;
+        }
+
+        // diff: prima → dopo dei soli campi modificati
+        const diff = {};
+        for (const campo of ["pz_ind_res", "pz_com_res", "pz_nciv_res", "pz_ind_dom", "pz_com_dom", "pz_nciv_dom"]) {
+            const da = typeof fullData[campo] === "undefined" ? null : fullData[campo];
+            if ((da ?? null) !== (payloadData[campo] ?? null)) diff[campo] = {da, a: payloadData[campo]};
+        }
+
+        // 5) Warning coerenza ASL (best effort, non bloccante)
+        const daVerificare = [];
+        if (nuovaResidenza) daVerificare.push({etichetta: "residenza", ...nuovaResidenza});
+        if (nuovoDomicilio && nuovoDomicilio.comuneId !== nuovaResidenza?.comuneId)
+            daVerificare.push({etichetta: "domicilio", ...nuovoDomicilio});
+        for (const {etichetta, comuneId, comune} of daVerificare) {
+            try {
+                const det = await this.getComuneFromId(comuneId);
+                const ucAsl = det.ok ? (det.data?.uc_asl ?? null) : null;
+                if (!ucAsl)
+                    warnings.push(`ASL di competenza del comune di ${etichetta} (${comune?.nome ?? comuneId}) non determinabile`);
+                else if (fullData.pz_asl_app && ucAsl.toString() !== fullData.pz_asl_app.toString())
+                    warnings.push(`Il comune di ${etichetta} (${comune?.nome ?? comuneId}) ricade nell'ASL ${ucAsl}, diversa dall'ASL di appartenenza dell'assistito (${fullData.pz_asl_app}): i campi ASL NON vengono modificati`);
+            } catch (e) {
+                warnings.push(`Verifica ASL ${etichetta} non riuscita: ${e.message}`);
+            }
+        }
+
+        const payload = {data: payloadData};
+
+        // 6) Dry-run: ritorna senza inviare
+        if (dryRun) return {ok: true, dryRun: true, payload, diff, warnings, response: null};
+
+        // 7) Submit: PUT /pazienti/{pz_id}
+        const result = await this.#postDataToUrl(Nar2.GET_ASSISTITO_NAR_FROM_ID, payload, {
+            method: "put",
+            replaceFromUrl: {id: fullData.pz_id}
+        });
+        return {
+            ok: result.ok,
+            dryRun: false,
+            payload, diff, warnings,
+            response: result.fullResponse,
+            data: result.data,
+            error: result.ok ? undefined : (result.error || "Errore durante la PUT /pazienti/{id}"),
+            errorDetail: result.ok ? undefined : (result.errorDetail ?? null)
         };
     }
 
@@ -604,9 +1038,9 @@ export class Nar2 {
                 if (includeFullData)
                     out.data.fullData = data.data;
                 return out;
-            } else return {ok: false, data: null};
+            } else return {ok: false, data: null, error: data?.error || "Dati paziente-medico non disponibili su NAR2", errorDetail: data?.errorDetail ?? null};
         } catch (e) {
-            return {ok: false, data: null};
+            return {ok: false, data: null, error: e.message, errorDetail: null};
         }
     }
 
@@ -637,7 +1071,7 @@ export class Nar2 {
         let result = fullData;
         if (!result) {
             const datiRes = await this.getDatiAssistitoNar2FromCf(codFiscale);
-            if (!datiRes || !datiRes.ok) return {ok: false, data: null};
+            if (!datiRes || !datiRes.ok) return {ok: false, data: null, error: datiRes?.error || "Assistito non trovato su NAR2", errorDetail: datiRes?.errorDetail ?? null};
             result = datiRes.fullData.data;
         }
 
@@ -751,7 +1185,7 @@ export class Nar2 {
         let result = fullData;
         if (!result) {
             const datiRes = await this.getDatiAssistitoNar2FromCf(codFiscale);
-            if (!datiRes || !datiRes.ok) return {ok: false, data: null};
+            if (!datiRes || !datiRes.ok) return {ok: false, data: null, error: datiRes?.error || "Assistito non trovato su NAR2", errorDetail: datiRes?.errorDetail ?? null};
             result = datiRes.fullData.data;
         }
         return {ok: true, data: Nar2.estraiRapportoMedicoAttivo(result, {categoria})};
@@ -808,7 +1242,7 @@ export class Nar2 {
                 return {ok: true, data: out};
             }
         }
-        return {ok: false, data: null};
+        return {ok: false, data: null, error: data?.error || "Ambiti di domicilio non disponibili su NAR2", errorDetail: data?.errorDetail ?? null};
     }
 
 
@@ -858,7 +1292,7 @@ export class Nar2 {
             }
             return {ok: true, data: out};
         }
-        return {ok: false, data: []};
+        return {ok: false, data: [], error: data?.error || "Medici per ambito non disponibili su NAR2", errorDetail: data?.errorDetail ?? null};
     }
 
 
@@ -873,6 +1307,11 @@ export class Nar2 {
      * @param {boolean} [config.soloMMG=false] - Flag indicating whether to include only MMG records.
      * @param {string} [config.asl="281"] - The ASL code to filter the records (default is "281" for Messina).
      * @param {string} [config.azienda="ME"] - The company code to filter the records (default is "ME" for Messina).
+     * @param {boolean} [config.aggiungiDatiRapporti=false] - Se true, per ogni medico recupera (con una sola
+     *        chiamata `medici/{id}`) sia l'elenco dei rapporti individuali (categoria, email, telefoni, date,
+     *        domicilio/indirizzo studio), allegato al campo `rapporti`, sia gli indirizzi del medico, allegati
+     *        al campo `indirizzi`. Include tutti i rapporti, anche quelli non attivi.
+     * @param {number} [config.parallelsRapporti=10] - Numero di richieste rapporti eseguite in parallelo.
      *
      * @return {Promise<Object>} A promise that resolves to the retrieved medical data.
      */
@@ -885,6 +1324,8 @@ export class Nar2 {
             soloMMG = false,
             asl = "281", // messina,
             azienda = "ME", //messina
+            aggiungiDatiRapporti = false,
+            parallelsRapporti = 10,
         } = config;
         let getParams = {
             "tipo_rapporto": "Medico_base",
@@ -917,6 +1358,24 @@ export class Nar2 {
             if (nascondiCessati)
                 medici = medici.filter(m => m && (m.fine_rapporto === null || typeof m.fine_rapporto === "undefined"));
 
+            if (aggiungiDatiRapporti) {
+                const concorrenza = Math.max(1, parallelsRapporti);
+                for (let i = 0; i < medici.length; i += concorrenza) {
+                    const blocco = medici.slice(i, i + concorrenza);
+                    await Promise.all(blocco.map(async (m) => {
+                        // Una sola chiamata medici/{id} fornisce sia rapporti che indirizzi
+                        const datiMedico = m.pf_id ? await this.getMedicoFromId(m.pf_id, azienda) : null;
+                        if (datiMedico && datiMedico.ok) {
+                            m.rapporti = this.#estraiRapportiDaDatiMedico(datiMedico.data);
+                            m.indirizzi = this.#estraiIndirizziDaDatiMedico(datiMedico.data);
+                        } else {
+                            m.rapporti = [];
+                            m.indirizzi = [];
+                        }
+                    }));
+                }
+            }
+
             return {ok: true, data: medici};
         }
         return data;
@@ -929,6 +1388,7 @@ export class Nar2 {
             assistito = new Assistito();
         let datiAssistito = null;
         let datiIdAssistito;
+        let lastException = null;
         const retry = 3;
         for (let i = 0; i < retry; i++) {
             try {
@@ -956,6 +1416,7 @@ export class Nar2 {
                     }
                 }
             } catch (e) {
+                lastException = e;
                 console.log("[getDatiAssistitoNar2FromCf] Eccezione durante recupero Nar2:", e.message);
             }
             if (datiAssistito && datiAssistito.ok) break;
@@ -1012,9 +1473,19 @@ export class Nar2 {
             };
         } else {
             console.log(`[getDatiAssistitoNar2FromCf] Nar2 fallito dopo ${retry} tentativi per CF: ${codiceFiscale?.substring(0, 6)}***`);
-            assistito.erroreNar2 = "Nessun assistito trovato con il codice fiscale fornito";
+            // Determina il motivo più specifico possibile del fallimento (additivo, non cambia lo shape)
+            const numRisultati = (!fallback && datiIdAssistito?.ok && Array.isArray(datiIdAssistito.data)) ? datiIdAssistito.data.length : null;
+            const errMessage = datiAssistito?.error || datiIdAssistito?.error ||
+                (numRisultati !== null && numRisultati !== 1 ? `La ricerca per codice fiscale su NAR2 ha restituito ${numRisultati} risultati` : null) ||
+                (lastException ? `Eccezione durante il recupero da NAR2: ${lastException.message}` : null) ||
+                "Nessun assistito trovato con il codice fiscale fornito";
+            assistito.erroreNar2 = errMessage;
             assistito.okNar2 = false;
-            return {ok: false, data: null, fullData: datiIdAssistito};
+            return {
+                ok: false, data: null, fullData: datiIdAssistito,
+                error: errMessage,
+                errorDetail: datiAssistito?.errorDetail || datiIdAssistito?.errorDetail || null
+            };
         }
     }
 
@@ -1040,7 +1511,7 @@ export class Nar2 {
      * @param {Object} [config.replaceFromUrl] - Sostituzioni nei placeholder URL.
      * @param {Object} [config.getParams] - Eventuali query params.
      * @param {string} [config.method="post"] - Metodo HTTP (es. "post", "put"). `aggiornaSceltaMedico` richiede PUT.
-     * @returns {Promise<{ok:boolean, data:any, fullResponse:Object|null}>}
+     * @returns {Promise<{ok:boolean, data:any, fullResponse:Object|null, error:string|null, errorDetail:Object|null}>}
      */
     async #postDataToUrl(url, body, config = {}) {
         const {replaceFromUrl = null, getParams = null, method = "post"} = config;
@@ -1057,7 +1528,8 @@ export class Nar2 {
                 finalUrl = finalUrl.replace(`{${key}}`, (value === null || typeof value === "undefined") ? "null" : value.toString());
         }
 
-        let out = {ok: false, data: null, fullResponse: null};
+        let out = {ok: false, data: null, fullResponse: null, error: null, errorDetail: null};
+        let lastError = null;
         for (let i = 0; i < this._maxRetry && !out.ok; i++) {
             try {
                 await this.getToken();
@@ -1072,15 +1544,33 @@ export class Nar2 {
                 });
                 if (!response?.data?.status || response.data.status.toString() !== "true" ||
                     /token is (invalid|expired)/i.test(response.data.status.toString())) {
+                    // NAR2 risponde 200 con status != true: errore business (o token scaduto)
+                    lastError = {
+                        type: "nar2",
+                        statusCode: response.status ?? null,
+                        message: Nar2.#extractErrorMessage(response?.data) || `Risposta NAR2 con status='${response?.data?.status ?? "assente"}'`,
+                        response: response?.data ?? null
+                    };
                     await this.getToken({newToken: true});
                 } else {
-                    out = {ok: true, data: response.data.result, fullResponse: response.data};
+                    out = {ok: true, data: response.data.result, fullResponse: response.data, error: null, errorDetail: null};
                 }
             } catch (e) {
-                console.log(`[#postDataToUrl] Errore ${httpMethod.toUpperCase()} ${finalUrl}: ${e.message}`);
+                lastError = {
+                    type: "http",
+                    statusCode: e.response?.status ?? null,
+                    message: Nar2.#extractErrorMessage(e.response?.data) || e.message,
+                    response: e.response?.data ?? null
+                };
+                console.log(`[#postDataToUrl] Errore ${httpMethod.toUpperCase()} ${finalUrl}: ${lastError.message}`);
                 await this.getToken({newToken: true});
             }
         }
+        if (!out.ok && lastError) {
+            out.error = lastError.message;
+            out.errorDetail = {...lastError, method: httpMethod.toUpperCase(), url: finalUrl, tentativi: this._maxRetry};
+            out.fullResponse = lastError.response;
+        }
         return out;
     }
 
@@ -1092,8 +1582,9 @@ export class Nar2 {
             replaceFromUrl = null,
             rawResponse = false, // se true, accetta risposte non incapsulate in {status, result}
         } = config;
-        let out = {ok: false, data: null};
+        let out = {ok: false, data: null, error: null, errorDetail: null};
         let ok = false;
+        let lastError = null;
 
         // Build URL with get parameters if provided
         let finalUrl = url;
@@ -1132,32 +1623,196 @@ export class Nar2 {
                     // se contiene un messaggio "token is invalid" rinnovo
                     const asStr = typeof response?.data === "string" ? response.data : JSON.stringify(response?.data ?? "");
                     if (/token is (invalid|expired)/i.test(asStr)) {
+                        lastError = {
+                            type: "nar2",
+                            statusCode: response.status ?? null,
+                            message: "Token NAR2 non valido o scaduto",
+                            response: response?.data ?? null
+                        };
                         await this.getToken({newToken: true});
                     } else {
                         ok = true;
-                        out = {ok: true, data: response.data};
+                        out = {ok: true, data: response.data, error: null, errorDetail: null};
                     }
                 } else if (!response?.data?.status || response.data.status.toString() !== "true" ||
                     /token is (invalid|expired)/i.test(response.data.status.toString())) {
+                    // NAR2 risponde 200 con status != true: errore business (o token scaduto)
+                    lastError = {
+                        type: "nar2",
+                        statusCode: response.status ?? null,
+                        message: Nar2.#extractErrorMessage(response?.data) || `Risposta NAR2 con status='${response?.data?.status ?? "assente"}'`,
+                        response: response?.data ?? null
+                    };
                     await this.getToken({newToken: true});
                 } else {
                     ok = true;
-                    out = {ok: true, data: response.data.result};
+                    out = {ok: true, data: response.data.result, error: null, errorDetail: null};
                 }
             } catch (e) {
+                lastError = {
+                    type: "http",
+                    statusCode: e.response?.status ?? null,
+                    message: Nar2.#extractErrorMessage(e.response?.data) || e.message,
+                    response: e.response?.data ?? null
+                };
                 await this.getToken({newToken: true});
             }
         }
 
+        if (!out.ok && lastError) {
+            out.error = lastError.message;
+            out.errorDetail = {...lastError, method: "GET", url: finalUrl, tentativi: this._maxRetry};
+        }
         return out;
     }
 
+    /**
+     * Estrae un messaggio d'errore leggibile da un body di risposta NAR2/HTTP.
+     * Accetta stringhe (troncate a 500 char) o oggetti con i campi comuni
+     * message/error/msg/errore/result.
+     *
+     * @param {any} data - Body della risposta.
+     * @returns {string|null} Messaggio estratto, o null se non determinabile.
+     */
+    static #extractErrorMessage(data) {
+        if (data === null || typeof data === "undefined") return null;
+        if (typeof data === "string") {
+            const s = data.trim();
+            return s.length === 0 ? null : (s.length > 500 ? `${s.slice(0, 500)}…` : s);
+        }
+        if (typeof data !== "object") return String(data);
+        const candidate = data.message || data.error || data.msg || data.errore ||
+            (typeof data.result === "string" ? data.result : null);
+        if (candidate) return typeof candidate === "string" ? candidate : JSON.stringify(candidate);
+        if (data.status && data.status.toString() !== "true") return `status='${data.status}'`;
+        return null;
+    }
+
     async getAssistitoFromId(id) {
         return await this.#getDataFromUrlIdOrParams(Nar2.GET_ASSISTITO_NAR_FROM_ID, {urlId: id});
     }
 
-    async getMedicoFromId(id) {
-        return await this.#getDataFromUrlIdOrParams(Nar2.GET_DATI_MEDICO_FROM_ID, {urlId: id});
+    async getMedicoFromId(id, azienda = null) {
+        const config = {urlId: id};
+        if (azienda) config.getParams = {azienda};
+        return await this.#getDataFromUrlIdOrParams(Nar2.GET_DATI_MEDICO_FROM_ID, config);
+    }
+
+    /**
+     * Estrae l'elenco normalizzato dei rapporti individuali dai dati grezzi di un medico
+     * (risultato di `getMedicoFromId` / endpoint `medici/{id}`).
+     *
+     * Include tutti i rapporti, anche quelli non attivi. Un rapporto è considerato attivo
+     * solo se non ha data di fine (`ri_dt_disable` nullo).
+     *
+     * @param {Object} datiMedico - Oggetto restituito da `getMedicoFromId(...).data`.
+     * @return {Array<Object>} Elenco rapporti normalizzati.
+     */
+    #estraiRapportiDaDatiMedico(datiMedico) {
+        const indirizziMedico = Array.isArray(datiMedico?.indirizzi) ? datiMedico.indirizzi : [];
+        const rapporti = Array.isArray(datiMedico?.rapporto_individuale) ? datiMedico.rapporto_individuale : [];
+        const fmt = (d) => d ? moment(d, "YYYY-MM-DD HH:mm:ss").format("DD/MM/YYYY") : null;
+
+        return rapporti.map(r => {
+            let categoria = null;
+            if (r.ri_categoria === Nar2.CAT_MMG) categoria = "mmg";
+            else if (r.ri_categoria === Nar2.CAT_PEDIATRI) categoria = "pls";
+
+            const telefoni = [r.ri_telefono1, r.ri_telefono2, r.ri_telefono3]
+                .map(t => (t ?? "").toString().trim())
+                .filter(t => t !== "");
+
+            // Il domicilio (indirizzo studio) è collegato all'indirizzo del medico tramite il progressivo.
+            // Quando NAR non fornisce il link, il domicilio resta null.
+            const progr = r.indirizzo?.rd_progr ?? null;
+            const ind = progr ? (indirizziMedico.find(i => i.pr_progr === progr) ?? null) : null;
+            const comune = ind?.comune ?? null;
+            const domicilio = ind ? {
+                comune: comune?.cm_desc ?? null,
+                provincia: comune?.cm_prov ?? null,
+                cap: ind.pr_cap ?? comune?.cm_ccap ?? null,
+                indirizzo: ind.pr_indi ?? null,
+                numeroCivico: ind.pr_nciv ?? null,
+            } : null;
+
+            return {
+                id: r.ri_id ?? null,
+                categoria,
+                tipoRapporto: r.ri_rapporto ?? r.tipo_rapporto?.ra_cod ?? null,
+                descrizioneRapporto: r.tipo_rapporto?.ra_desc ?? null,
+                email: r.ri_email ?? null,
+                telefoni,
+                dataInizio: fmt(r.ri_dt_enable),
+                dataFine: fmt(r.ri_dt_disable),
+                attivo: !r.ri_dt_disable,
+                domicilio,
+            };
+        });
+    }
+
+    /**
+     * Recupera l'elenco normalizzato dei rapporti individuali di un medico dato il suo id NAR2.
+     *
+     * @param {string|number} id - Id persona del medico (`pf_id`).
+     * @param {string} [azienda="ME"] - Codice azienda.
+     * @return {Promise<Array<Object>>} Elenco rapporti normalizzati (vuoto in caso di errore).
+     */
+    async getRapportiMedicoFromId(id, azienda = "ME") {
+        const datiMedico = await this.getMedicoFromId(id, azienda);
+        if (datiMedico && datiMedico.ok)
+            return this.#estraiRapportiDaDatiMedico(datiMedico.data);
+        return [];
+    }
+
+    /**
+     * Estrae l'elenco normalizzato degli indirizzi del medico dai dati grezzi
+     * (risultato di `getMedicoFromId` / endpoint `medici/{id}`).
+     *
+     * Gli indirizzi sono legati al medico (non al rapporto). Corrispondono alla scheda
+     * "Indirizzi" del portale NAR2 (`/operatore/medici/{id}/dati/indirizzi`).
+     *
+     * @param {Object} datiMedico - Oggetto restituito da `getMedicoFromId(...).data`.
+     * @return {Array<Object>} Elenco indirizzi normalizzati.
+     */
+    #estraiIndirizziDaDatiMedico(datiMedico) {
+        const indirizzi = Array.isArray(datiMedico?.indirizzi) ? datiMedico.indirizzi : [];
+        const fmt = (d) => d ? moment(d, "YYYY-MM-DD HH:mm:ss").format("DD/MM/YYYY") : null;
+
+        return indirizzi.map(ind => {
+            const comune = ind?.comune ?? null;
+            const telefoni = [ind.pr_telefono1, ind.pr_telefono2, ind.pr_telefono3]
+                .map(t => (t ?? "").toString().trim())
+                .filter(t => t !== "");
+
+            return {
+                progressivo: ind.pr_progr ?? null,
+                descrizione: ind.pr_desc ?? null,
+                comune: comune?.cm_desc ?? null,
+                provincia: comune?.cm_prov ?? null,
+                cap: ind.pr_cap ?? comune?.cm_ccap ?? null,
+                indirizzo: ind.pr_indi ?? null,
+                numeroCivico: ind.pr_nciv ?? null,
+                dataAttivazione: fmt(ind.pr_dt_enable),
+                dataDisattivazione: fmt(ind.pr_dt_disable),
+                residenza: ind.pr_residenza === "S",
+                telefoni,
+                email: ind.pr_email ?? null,
+            };
+        });
+    }
+
+    /**
+     * Recupera l'elenco normalizzato degli indirizzi di un medico dato il suo id NAR2.
+     *
+     * @param {string|number} id - Id persona del medico (`pf_id`).
+     * @param {string} [azienda="ME"] - Codice azienda.
+     * @return {Promise<Array<Object>>} Elenco indirizzi normalizzati (vuoto in caso di errore).
+     */
+    async getIndirizziMedicoFromId(id, azienda = "ME") {
+        const datiMedico = await this.getMedicoFromId(id, azienda);
+        if (datiMedico && datiMedico.ok)
+            return this.#estraiIndirizziDaDatiMedico(datiMedico.data);
+        return [];
     }
 
     async getNumAssistitiMedico(id) {
@@ -1331,7 +1986,7 @@ export class Nar2 {
 
         const datiAssistito = await this.getDatiAssistitoNar2FromCf(codFiscale);
         if (!datiAssistito || !datiAssistito.ok) {
-            return {ok: false, dryRun, payload: null, response: null, error: "Assistito non trovato su NAR2"};
+            return {ok: false, dryRun, payload: null, response: null, error: datiAssistito?.error || "Assistito non trovato su NAR2", errorDetail: datiAssistito?.errorDetail ?? null};
         }
         const full = datiAssistito.fullData.data;
         const storico = Array.isArray(full.storico_medici) ? full.storico_medici : [];
@@ -1394,7 +2049,8 @@ export class Nar2 {
             payload,
             response: result.fullResponse,
             data: result.data,
-            error: result.ok ? undefined : "Errore durante la PUT /pazienti/aggiornaSceltaMedico"
+            error: result.ok ? undefined : (result.error || "Errore durante la PUT /pazienti/aggiornaSceltaMedico"),
+            errorDetail: result.ok ? undefined : (result.errorDetail ?? null)
         };
     }
 
@@ -1413,10 +2069,11 @@ export class Nar2 {
         let {pzId = null} = config;
         if (pzId == null) {
             const dati = await this.getDatiAssistitoNar2FromCf(codFiscale);
-            if (!dati || !dati.ok) return {ok: false, pdf: null, tipo};
+            if (!dati || !dati.ok) return {ok: false, pdf: null, tipo, error: dati?.error || "Assistito non trovato su NAR2", errorDetail: dati?.errorDetail ?? null};
             pzId = dati.fullData.data.pz_id;
         }
         const url = Nar2.STAMPA_DOCUMENTO_URL.replace("{tipo}", tipo);
+        let lastError = null;
         for (let i = 0; i < this._maxRetry; i++) {
             try {
                 await this.getToken();
@@ -1429,13 +2086,15 @@ export class Nar2 {
                 if (resp.status === 200 && /pdf/i.test(ct)) {
                     return {ok: true, pdf: Buffer.from(resp.data), tipo};
                 }
+                lastError = {type: "nar2", statusCode: resp.status ?? null, message: `Risposta non PDF (content-type: ${ct || "assente"})`, response: null};
                 await this.getToken({newToken: true});
             } catch (e) {
+                lastError = {type: "http", statusCode: e.response?.status ?? null, message: e.message, response: null};
                 console.log(`[getDocumentoPdf] Errore stampe/${tipo}: ${e.message}`);
                 await this.getToken({newToken: true});
             }
         }
-        return {ok: false, pdf: null, tipo};
+        return {ok: false, pdf: null, tipo, error: lastError?.message || null, errorDetail: lastError ? {...lastError, method: "GET", url, tentativi: this._maxRetry} : null};
     }
 
     /**
@@ -1459,7 +2118,7 @@ export class Nar2 {
         } = config;
 
         const dati = await this.getDatiAssistitoNar2FromCf(codFiscale);
-        if (!dati || !dati.ok) return {ok: false, unico: null, documenti: [], error: "Assistito non trovato su NAR2"};
+        if (!dati || !dati.ok) return {ok: false, unico: null, documenti: [], error: dati?.error || "Assistito non trovato su NAR2", errorDetail: dati?.errorDetail ?? null};
         const pzId = dati.fullData.data.pz_id;
 
         const risultati = [];
@@ -1497,11 +2156,16 @@ export class Nar2 {
             }
         }
 
+        if (!ok) {
+            const primoErrore = risultati.find((r) => !r.ok && r.error);
+            return {ok, unico, documenti: risultati, error: primoErrore?.error || "Nessun documento disponibile su NAR2", errorDetail: primoErrore?.errorDetail ?? null};
+        }
         return {ok, unico, documenti: risultati};
     }
 
     async getDatiAssistitoFromCfSuSogeiNew(cf, assistito = null, fallback = false) {
         let ok = false;
+        let risultato = null; // valore di ritorno del ramo di successo (fix: prima non veniva mai ritornato)
         const nullArray = (data) => {
             return Array.isArray(data) && data.length === 0 ? "" : data;
         };
@@ -1583,7 +2247,7 @@ export class Nar2 {
                     assistito.setTs(DATI.DATA_DECESSO, deceduto ? nullArray(out.data.data.p801dataDecesso) : null);
                     assistito.okTs = true;
                     assistito.fullDataTs = out.data;
-                    out = {
+                    risultato = {
                         ok: true,
                         fullData: out.data,
                         data: assistito
@@ -1602,6 +2266,7 @@ export class Nar2 {
                 data: assistito
             };
         }
+        return risultato;
     }