03 — Analisi conformità API T4MED / FHIR R4¶

Data: 2026-06-01
Riferimento: "Bozza specifiche API FHIR R4 - Integrazione Sined"

Quadro di conformità per flusso¶

Flusso	Endpoint T4MED	T4MED vs FHIR R4
A	`POST /fhir/Appointment`	DEVIAZIONI [D01][D02]
B	`PUT /fhir/Appointment/{id}`	CONFORMI — T4MED = R4
C	`DELETE /fhir/Appointment/{id}`	CONFORMI — T4MED = R4
D	`POST /fhir/Patient/{id}/$generate-pdf`	CONFORMI — T4MED = R4
E	`POST /fhir`	CONFORMI — T4MED = R4

Le deviazioni esistono solo nel Flusso A (endpoint e formato risposta). Il corpo del Bundle è identico nelle varianti T4MED e FHIR R4.

Valutazione di copertura per flusso¶

Flusso A — Inserimento nuova prenotazione¶

Endpoint T4MED: POST https://api.t4med.it/fhir/Appointment
Corpo: Bundle transaction FHIR contenente risorsa Patient + risorsa Appointment.

Valutazione: COPERTO.
I campi obbligatori (status = "booked", start/end ISO datetime, participant paziente) sono definiti dalla specifica. Il Bundle racchiude Patient e Appointment in un'unica transazione atomica.

Nota: T4MED restituisce il T4MED Appointment ID nel campo id della risorsa restituita (es. "T00450"). gt4medServices deve estrarlo e memorizzarlo per i Flussi B e C. Il formato esatto della risposta è da confermare con TESI (lacuna L1).

Flusso B — Variazione prenotazione¶

Endpoint T4MED: PUT https://api.t4med.it/fhir/Appointment/{id}
Operazione: Sostituzione completa della risorsa Appointment.

Valutazione: COPERTO, a condizione che gt4medServices abbia memorizzato il T4MED Appointment ID restituito al momento dell'inserimento (Flusso A).

Flusso C — Cancellazione prenotazione¶

Endpoint T4MED (DELETE fisico): DELETE https://api.t4med.it/fhir/Appointment/{id}
Endpoint alternativo (cancellazione logica): PUT https://api.t4med.it/fhir/Appointment/{id} con status = "cancelled"

Valutazione: COPERTO.
Stessa condizione del Flusso B: richiede il T4MED Appointment ID dalla tabella di mappatura interna.

Punto critico: alcune implementazioni FHIR R4 non supportano DELETE fisico (HTTP 405 Method Not Allowed). Da chiarire con TESI (lacuna L9).

Flusso D — Download referto da T4MED¶

Endpoint T4MED: POST https://api.t4med.it/fhir/Patient/{id}/$generate-pdf
Tipo: Operazione FHIR R4 custom — generazione on-the-fly, senza persistenza.

Valutazione: COPERTO per la parte T4MED.
I parametri di input (PatientIdentifier, DateFrom, DateTo) e il tipo di risposta (stream PDF) sono definiti dalla specifica.

Punto critico: l'endpoint richiede il T4MED Patient ID nell'URL. Si ipotizza che coincida con il codice ospedaliero (es. Patient/4578934). Da confermare con TESI (lacuna L4).

Flusso E — Upload referto firmato su T4MED¶

Endpoint T4MED: POST https://api.t4med.it/fhir
Corpo: Bundle transaction FHIR contenente risorsa Binary + risorsa DocumentReference.

Valutazione: COPERTO per la prima pubblicazione.
La specifica indica Binary (PDF in base64) e DocumentReference con identifier contenente il codice fiscale del paziente.

Punto critico L10: in FHIR R4, DocumentReference.identifier identifica il documento, non il paziente. Il valore semanticamente corretto è il UniqueDocumentId del referto. Da chiarire con TESI (lacuna L10).
Punto critico L11: la specifica copre solo la prima pubblicazione. I casi di referto sostitutivo (relatesTo.code = "replaces") e annullativo (status = "entered-in-error") non sono documentati e sono punti aperti con TESI (lacuna L11).

Deviazioni T4MED dallo standard FHIR R4¶

[D01] Endpoint POST /fhir/Appointment con body Bundle — NON STANDARD¶


FHIR R4	Bundle transaction → `POST https://api.t4med.it/fhir` (base URL)
T4MED	Bundle transaction → `POST https://api.t4med.it/fhir/Appointment`

Il corpo del Bundle è identico. Solo l'endpoint cambia.
Impatto: gt4medServices codifica l'endpoint T4MED nel client HTTP.

[D02] Risposta al Bundle transaction del Flusso A — ASSUNZIONE NON CONFERMATA¶


FHIR R4	Risposta = Bundle `"transaction-response"` con entry per ogni entry della request
Assunzione T4MED	Risposta = singola risorsa `Appointment` con campo `"id"`

Da confermare con TESI (lacuna L1).
Impatto: il parser di gt4medServices deve essere adattato al formato confermato.

Elementi conformi alle specifiche T4MED¶

ID	Descrizione
S01	Endpoint `POST /fhir/Appointment` per inserimento prenotazione (Flusso A)
S02	Bundle transaction contenente Patient + Appointment
S03	`Appointment.status = "booked"` obbligatorio
S04	`Appointment.start` e `end` in formato ISO datetime, obbligatori
S05	`Appointment.participant` contenente almeno il paziente, obbligatorio
S06	Endpoint `PUT /fhir/Appointment/{id}` per aggiornamento (Flusso B)
S07	Endpoint `DELETE /fhir/Appointment/{id}` per cancellazione (Flusso C)
S08	Endpoint `POST /fhir/Patient/{id}/$generate-pdf` per download PDF (Flusso D)
S09	Parametri `$generate-pdf`: PatientIdentifier, DateFrom, DateTo
S10	Risposta `$generate-pdf`: `Accept: application/pdf` → 200 OK, stream PDF
S11	Endpoint `POST /fhir` per upload referto via Bundle transaction (Flusso E)
S12	Bundle upload: risorsa `Binary` (PDF in base64) + risorsa `DocumentReference`
S13	`DocumentReference` con identifier contenente il codice fiscale paziente (semantica non FHIR R4 — lacuna L10)
S14	`Content-Type: application/fhir+json` per tutti i messaggi JSON
S15	Autenticazione via API Key con restrizione IP di origine

Elementi non specificati / "inventati"¶

Corretti per FHIR R4 e per il contesto italiano, ma non presenti nella spec T4MED:

ID	Descrizione
I01	Struttura dettagliata della risorsa Patient — campi seguono buone pratiche HL7 italiane
I02	Sistemi OID/URI per gli identifier (CF, NRE, ASL, presidio, prestazioni)
I03	Risorsa `ServiceRequest` nel Bundle (Flusso A esteso) — trasporta NRE e codice prestazione
I04	`Appointment.identifier` per l'ID prenotazione CUP — buona pratica FHIR
I05	`Appointment.serviceType` con codice prestazione 89.01.B
I06	`Appointment.basedOn` (collegamento Appointment → ServiceRequest)
I07	Partecipanti aggiuntivi nell'Appointment (HealthcareService, Location)
I08	`ifNoneExist` nel request del Patient (conditional create) — evita duplicati
I09	`urn:uuid:` come fullUrl per riferimenti interni nel Bundle (UUID RFC 4122)
I10	Risorsa `Parameters` per i parametri di `$generate-pdf`
I11	Struttura completa di `DocumentReference` (Flusso E): tipo LOINC, subject, context
I12	`Binary.contentType = "application/pdf"` — obbligatorio in FHIR R4
I13	`cancelationReason` nell'Appointment (Flusso C, cancellazione logica)

Sistemi OID/URI utilizzati nei messaggi¶

Tipo	OID / URI
Codice fiscale	`urn:oid:2.16.840.1.113883.2.9.4.3.2`
NRE / ricetta	`urn:oid:2.16.840.1.113883.2.9.4.3.8`
ASL (FLS11)	`urn:oid:2.16.840.1.113883.2.9.4.1.1`
Presidio (STS11)	`urn:oid:2.16.840.1.113883.2.9.4.1.3`
Prestazioni Piemonte	`urn:oid:2.16.840.1.113883.2.9.2.10.6.11`
Cod. ospedaliero	`urn:local:asl-vco:id-paziente` (locale, da definire con TESI)

Correzioni FHIR R4 applicate¶

ID	Descrizione
C01	Estensione `patient-birthPlace` posizionata a livello `Patient.extension` (non `_birthDate`)
C02	`fullUrl` sostituiti con UUID v4 RFC 4122 casuali e sintatticamente validi

Priorità di implementazione suggerita¶

Flusso A — inserimento prenotazione + salvataggio mappatura
Flusso C — cancellazione (usa la mappatura)
Flusso D — download referto da T4MED
Flusso E — upload referto firmato
Flusso B — modifica (stessa complessità di Flusso C)