Diagramma di sequenza — gt4medServices / Integrazione T4MED¶

Se il diagramma non viene visualizzato correttamente, aprilo direttamente su mermaid.live:

Endpoint di base T4MED (TEST): https://biocaretest.evisus.it/api/fhir Copertura: Flusso A, B, C (prenotazioni) — Flusso D (firma referto) — Flussi E, F, G, H (pubblicazione, sostituzione, annullamento e aggiornamento metadati del referto su T4MED) Paziente di riferimento: ROSAVIOLA DALMINA — CF RSVDMN11A41H620X — Prenotazione CUP 26B001956 — T4MED T00450

Script Mermaid¶

sequenceDiagram
    participant CUP
    participant MIR as MIRTH
    participant GT as gt4medServices
    participant MW as MEDWARE
    participant T4M as T4MED
    participant GEF as gefidServices
    participant GRE as grepoServices
    participant REPO
    participant FSE

    rect rgb(210, 230, 255)
    Note over CUP,T4M: FLUSSO A — Nuova prenotazione televisita
    CUP->>MIR: HL7 OMG^O19 (ins. prenotazione 26B001956)
    MIR->>MW: Scrive prenotazione in tabella prenotazioni
    MIR->>GT: Chiama gt4medServices (inserimento)
    GT->>T4M: POST {base-url} — Bundle transaction {Patient + ServiceRequest + Appointment}
    T4M-->>GT: 200 OK — Bundle transaction-response (Appointment/T00450/_history/1)
    GT->>GT: Salva mappatura: 26B001956 → T00450
    end

    rect rgb(255, 240, 210)
    Note over CUP,T4M: FLUSSO B — Variazione prenotazione
    CUP->>MIR: HL7 OMG^O19 (var. prenotazione 26B001956)
    MIR->>MW: Aggiorna prenotazione in tabella prenotazioni
    MIR->>GT: Chiama gt4medServices (variazione)
    GT->>GT: Legge mappatura: 26B001956 → T00450
    GT->>T4M: PUT {base-url}/Appointment/T00450 — Appointment aggiornata
    T4M-->>GT: 200 OK
    end

    rect rgb(255, 220, 220)
    Note over CUP,T4M: FLUSSO C — Cancellazione prenotazione
    CUP->>MIR: HL7 OMG^O19 (canc. prenotazione 26B001956)
    MIR->>MW: Cancella prenotazione in tabella prenotazioni
    MIR->>GT: Chiama gt4medServices (cancellazione)
    GT->>GT: Legge mappatura: 26B001956 → T00450
    GT->>T4M: DELETE {base-url}/Appointment/T00450
    T4M-->>GT: 200 OK / 204 No Content
    GT->>GT: Invalida mappatura: 26B001956 → T00450
    end

    rect rgb(220, 255, 235)
    Note over MW,GEF: FLUSSO D — Firma referto post-visita
    MW->>GEF: Medico clicca "firma" — innesca gefidServices
    GEF->>GT: Richiesta referto T4MED (CF: RSVDMN11A41H620X, Appointment: T00450, data: 2026-06-03)
    GT->>T4M: POST {base-url}/Patient/RSVDMN11A41H620X/$generate-pdf — Parameters {DateFrom, DateTo, T4MedAppointmentId}
    alt Dati di monitoraggio presenti
    T4M-->>GT: 200 OK — stream PDF monitoraggio
    GT->>MW: Download referto clinico MEDWARE
    MW-->>GT: stream PDF referto visita
    GT->>GT: Merge PDF (T4MED accodato al referto MEDWARE)
    GT-->>GEF: PDF unito
    else Nessun dato di monitoraggio nel periodo
    T4M-->>GT: 204 No Content
    GT->>MW: Download referto clinico MEDWARE
    MW-->>GT: stream PDF referto visita
    GT-->>GEF: PDF solo MEDWARE (nessun merge)
    end
    GEF->>GEF: Firma digitale SINED
    end

    rect rgb(200, 245, 220)
    Note over GRE,FSE: FLUSSI E/F/G/H — Pubblicazione schedulata e upload/annullamento/aggiornamento su T4MED
    Note over GRE,FSE: grepoServices schedulato ogni 10 min circa
    GRE->>REPO: Upload referto firmato / sostitutivo / richiesta annullamento / aggiornamento metadati
    REPO-->>GRE: Pubblicato / annullato / aggiornato su REPO
    REPO->>FSE: Pubblicazione / annullamento / aggiornamento su FSE
    FSE-->>REPO: OK
    REPO-->>GRE: Pubblicato / annullato / aggiornato su FSE
    alt Flusso E — prima pubblicazione (v1)
    GRE->>GT: Upload nuovo referto firmato su T4MED
    GT->>T4M: POST {base-url} — Bundle transaction {Binary + DocumentReference}
    T4M-->>GT: 200 OK — Bundle transaction-response
    else Flusso F — referto sostitutivo (v>1)
    GRE->>GT: Upload referto sostitutivo su T4MED
    GT->>T4M: POST {base-url} — Bundle transaction {Binary + DocumentReference (relatesTo=replaces)}
    T4M-->>GT: 200 OK — Bundle transaction-response
    else Flusso G — annullamento
    GRE->>GT: Richiesta annullamento referto su T4MED
    GT->>T4M: PUT {base-url}/DocumentReference/{id} — status=entered-in-error
    T4M-->>GT: 200 OK
    else Flusso H — aggiornamento dei soli metadati
    GRE->>GT: Richiesta aggiornamento metadati referto su T4MED
    GT->>T4M: PUT {base-url}/DocumentReference/{id} — status=current, stesso PDF/versione
    T4M-->>GT: 200 OK
    end
    GT-->>GRE: Operazione T4MED completata
    end

Note sul diagramma¶

{base-url} indica l'endpoint di base T4MED. Ambiente di TEST: https://biocaretest.evisus.it/api/fhir; ambiente di PROD: https://biocaresuite.evisus.it/api/fhir. Tutte le chiamate sono autenticate tramite header custom X-API-Key: <chiave>.
La mappatura CUP-ID → T4MED-ID è persistita su DB interno di gt4medServices e usata dai Flussi B, C, D, E, F, G, H.
Flussi A/B/C: il messaggio HL7 OMG^O19 del CUP arriva a MIRTH, che scrive in MEDWARE e chiama gt4medServices per replicare l'operazione su T4MED.
Il Flusso D è innescato dal medico che clicca il pulsante "firma" in MEDWARE. gefidServices coordina il recupero del referto tramite gt4medServices (download da T4MED + MEDWARE, merge) e firma digitalmente il PDF unito. A seguito dei test di integrazione, l'operazione $generate-pdf richiede obbligatoriamente anche T4MedAppointmentId, oltre a DateFrom/DateTo. Se T4MED risponde 204 No Content (nessun dato di telemonitoraggio nel periodo) oppure con un errore 4xx/5xx (es. Appointment inesistente o di altro paziente), non si effettua il merge: si procede comunque con il solo referto MEDWARE, che viene comunque firmato digitalmente.
I Flussi E/F/G/H sono gestiti da grepoServices, servizio schedulato (~10 min), non direttamente innescato da gefidServices. grepoServices pubblica/sostituisce/annulla/aggiorna i referti firmati su REPO/FSE e, solo dopo conferma, chiama gt4medServices per l'operazione corrispondente su T4MED: prima pubblicazione (Flusso E, POST Bundle transaction), referto sostitutivo (Flusso F, POST Bundle transaction con relatesTo=replaces), annullamento (Flusso G, PUT /DocumentReference/{id} con status=entered-in-error), aggiornamento dei soli metadati (Flusso H, PUT /DocumentReference/{id} con status=current, stesso PDF e stessa versione).
L'upload/annullamento/aggiornamento del referto su T4MED avviene sempre DOPO la pubblicazione/annullamento/aggiornamento su REPO/FSE.
Il Flusso A usa POST {base-url} con Bundle transaction contenente Patient + ServiceRequest + Appointment, conforme allo standard FHIR R4.
Il Flusso C prevede esclusivamente la cancellazione fisica tramite DELETE. Non è prevista alcuna modalità alternativa di cancellazione logica.
Per il formato delle risposte di fallimento (OperationOutcome) su tutti e otto i flussi, vedi 06-response-failure.md.