Vai al contenuto

03 — Analisi conformità API T4MED / FHIR R4

Riferimento: "Bozza specifiche API FHIR R4 - Integrazione Sined"

Quadro di conformità per flusso

Flusso Endpoint T4MED T4MED vs FHIR R4
A POST {base-url} — Bundle transaction CONFORMI — T4MED = R4
B PUT {base-url}/Appointment/{id} CONFORMI — T4MED = R4
C DELETE {base-url}/Appointment/{id} CONFORMI — T4MED = R4
D POST {base-url}/Patient/{cfisc}/$generate-pdf CONFORMI — T4MED = R4
E POST {base-url} — Bundle transaction (prima pubblicazione, v1) CONFORMI — T4MED = R4
F POST {base-url} — Bundle transaction (referto sostitutivo, v>1) CONFORMI — T4MED = R4
G PUT {base-url}/DocumentReference/{id} (annullamento) CONFORMI — T4MED = R4
H PUT {base-url}/DocumentReference/{id} (aggiornamento dei soli metadati) CONFORMI — T4MED = R4

Valutazione di copertura per flusso

Flusso A — Inserimento nuova prenotazione

Endpoint T4MED: POST {base-url} (es. https://biocaretest.evisus.it/api/fhir) Corpo: Bundle transaction FHIR contenente risorsa Patient + risorsa ServiceRequest + risorsa Appointment.

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

La risorsa Patient può contenere i seguenti dati: cognome, nome, data di nascita, sesso, luogo di nascita, codice fiscale, indirizzo di residenza, indirizzo di domicilio, numero di telefono.

I dati obbligatori per la risorsa Patient sono: cognome, nome, data di nascita, sesso e codice fiscale.

Il codice ospedaliero non è più previsto e deve essere eliminato.

T4MED restituisce il T4MED Appointment ID nella location dell'entry Appointment della Bundle transaction-response (es. Appointment/T00450/_history/1). gt4medServices deve estrarlo e memorizzarlo per i Flussi B e C. La risposta è atomica: vedi 06-response-failure.md.

Flusso B — Variazione prenotazione

Endpoint T4MED: PUT {base-url}/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 {base-url}/Appointment/{id}

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

Si mantiene esclusivamente la cancellazione fisica tramite DELETE. Non è prevista alcuna modalità alternativa di cancellazione logica (PUT con status = "cancelled").

Flusso D — Download referto da T4MED

Endpoint T4MED: POST {base-url}/Patient/{cfisc}/$generate-pdf Tipo: Operazione FHIR R4 custom — generazione on-the-fly, senza persistenza.

Valutazione: COPERTO per la parte T4MED. I parametri di input — DateFrom, DateTo e, a seguito dei test di integrazione, T4MedAppointmentId (tutti e tre obbligatori) — e il tipo di risposta (stream PDF, oppure 204 No Content se non esistono dati di telemonitoraggio nel periodo) sono definiti dalla specifica.

Il T4MED Patient ID coincide con il codice fiscale ({cfisc}), es. Patient/RSVDMN11A41H620X. Il codice ospedaliero è eliminato. Il parametro T4MedAppointmentId limita il telemonitoraggio restituito alla specifica prenotazione T4MED (Flusso A). Vedi samples/flusso-d-download-referto.md per i codici di errore (Appointment inesistente, Appointment di altro paziente) e il caso "nessun dato clinico disponibile".

Flussi E/F/G/H — Pubblicazione, sostituzione, annullamento e aggiornamento metadati del referto firmato su T4MED

Endpoint T4MED:

  • Flusso E (prima pubblicazione, v1) e Flusso F (referto sostitutivo, v>1): POST {base-url} — Bundle transaction FHIR contenente risorsa Binary + risorsa DocumentReference
  • Flusso G (annullamento) e Flusso H (aggiornamento dei soli metadati): PUT {base-url}/DocumentReference/{id} — stesso endpoint, distinto solo dal valore di status (entered-in-error per G, current per H) e dai campi effettivamente variati

Valutazione: COPERTO, inclusi i casi di referto sostitutivo, annullativo e aggiornamento dei soli metadati. DocumentReference.identifier contiene lo UniqueDocumentId del referto — semanticamente corretto rispetto a FHIR R4. Il paziente è identificato tramite DocumentReference.subject (Patient/{cfisc}).

T4MED supporta anche la gestione del referto sostitutivo (relatesTo.code = "replaces", Flusso F), annullativo (status = "entered-in-error", Flusso G) e dell'aggiornamento dei soli metadati, senza variare PDF o versione (Flusso H). Tutti e quattro documentati in samples/flusso-e-upload-referto-firmato.md, samples/flusso-f-referto-sostitutivo.md, samples/flusso-g-annullamento-referto.md e samples/flusso-h-aggiornamento-metadati.md, insieme ai metadati di riservatezza/visibilità e al numero di versione del documento (document-version).

A seguito dei test di integrazione è stato definito il formato ufficialmente supportato di DocumentReference.identifier: system = "urn:ietf:rfc:3986", value = "urn:sined:documentid:<tipo>:<valore>" (varianti: vco, guid32, siss15, numeric33; supportato anche il formato di compatibilità urn:uuid:...). Lunghezza massima: 200 caratteri — gli identificativi SINED (fino a ~150 caratteri) sono pienamente compatibili. Vedi samples/flusso-e-upload-referto-firmato.md.

Sistemi OID/URI utilizzati nei messaggi

Tipo OID / URI
Codice fiscale (= T4MED Patient ID) 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
Reparto (Flusso A/B) urn:local:asl-vco:reparto
UniqueDocumentId (Flussi E/F/G/H) urn:ietf:rfc:3986 (valore: urn:sined:documentid:<tipo>:<valore>, oppure urn:uuid:<uuid>)

Il codice ospedaliero e il relativo identifier locale (urn:local:asl-vco:id-paziente) sono stati eliminati.

Priorità di implementazione suggerita

  1. Flusso A — inserimento prenotazione + salvataggio mappatura
  2. Flusso C — cancellazione (usa la mappatura)
  3. Flusso D — download referto da T4MED
  4. Flusso E — upload nuovo referto firmato (v1)
  5. Flusso B — modifica (stessa complessità di Flusso C)
  6. Flusso F — upload referto sostitutivo (v>1) — stessa complessità di Flusso E
  7. Flusso G — annullamento referto — stessa complessità di Flusso B (PUT)
  8. Flusso H — aggiornamento dei soli metadati — stessa complessità di Flusso G (stesso endpoint)