Flusso E — Pubblicazione nuovo referto su T4MED (versione 1)¶

Operazione: POST {base-url} — Bundle FHIR R4 transaction Flusso: E — grepoServices → gt4medServices → T4MED

Contesto¶

Dopo che gefidServices ha firmato digitalmente il PDF unito (T4MED + MEDWARE), consegna il documento a grepoServices. grepoServices pubblica il referto sul repository aziendale (REPO) e sul FSE. Solo dopo la conferma di pubblicazione su REPO/FSE, grepoServices chiama gt4medServices per caricare il referto firmato anche su T4MED tramite un Bundle transaction contenente Binary e DocumentReference.

Il Flusso E copre la prima pubblicazione (versione 1) di un referto. Le pubblicazioni successive dello stesso referto sono gestite da due flussi distinti:

Flusso F — pubblicazione del referto sostitutivo (versione > 1)
Flusso G — annullamento di un referto già pubblicato

Ordine delle operazioni:

gefidServices → grepoServices (PDF firmato)
grepoServices → REPO → FSE (pubblicazione)
grepoServices → gt4medServices → T4MED (upload, solo dopo OK da REPO/FSE)

Dati del caso di esempio¶

Campo	Valore
T4MED Appointment ID	`T00450`
Codice fiscale (= T4MED Patient ID)	`RSVDMN11A41H620X`
Paziente	ROSAVIOLA DALMINA (nome di fantasia)
Data televisita	`2026-06-03`
UniqueDocumentId (versione 1)	`urn:uuid:e7c3f91b-8a42-4d5e-9f16-3b8c7a2e5d41` (assegnato da SINED/REPO al momento della pubblicazione)
Numero di versione documento	`1`

Il codice ospedaliero è eliminato. Il paziente è identificato solo tramite codice fiscale (subject.reference = "Patient/RSVDMN11A41H620X"), come in tutti gli altri flussi.

Conformità allo standard FHIR R4¶

Il Flusso E aderisce completamente allo standard FHIR R4:

l'endpoint è quello base (POST {base-url}, lo stesso usato dal Flusso A) per Bundle transaction;
la risposta è un Bundle transaction-response;
DocumentReference.identifier contiene lo UniqueDocumentId del documento, cioè il business identifier del documento stesso — semanticamente corretto rispetto a FHIR R4. Il paziente è identificato tramite DocumentReference.subject, non tramite identifier. Questa è l'unica modalità documentata.

Endpoint e autenticazione¶

POST https://biocaretest.evisus.it/api/fhir
Content-Type: application/fhir+json
X-API-Key: <chiave>

Endpoint di TEST. In PROD: https://biocaresuite.evisus.it/api/fhir. Autenticazione tramite header custom X-API-Key.

Formato dell'identificativo del documento (`DocumentReference.identifier`)¶

A seguito dei test di integrazione, è stato definito il formato ufficialmente supportato per DocumentReference.identifier:

identifier.system = urn:ietf:rfc:3986
identifier.value = urn:sined:documentid:<tipo>:<valore>

Il segmento <tipo> individua la codifica dell'identificativo prodotto da SINED. Sono supportate le seguenti varianti:

Esempio VCO¶

{
  "resourceType": "DocumentReference",
  "status": "current",
  "identifier": [
    {
      "system": "urn:ietf:rfc:3986",
      "value": "urn:sined:documentid:vco:RVS26G15674956401"
    }
  ]
}

GUID senza trattini¶

{
  "resourceType": "DocumentReference",
  "status": "current",
  "identifier": [
    {
      "system": "urn:ietf:rfc:3986",
      "value": "urn:sined:documentid:guid32:0217AC608EC04D91B95114B84EB72158"
    }
  ]
}

Codifica SISS Lombardia¶

{
  "resourceType": "DocumentReference",
  "status": "current",
  "identifier": [
    {
      "system": "urn:ietf:rfc:3986",
      "value": "urn:sined:documentid:siss15:REF260000000001"
    }
  ]
}

Identificativo numerico a 33 cifre¶

{
  "resourceType": "DocumentReference",
  "status": "current",
  "identifier": [
    {
      "system": "urn:ietf:rfc:3986",
      "value": "urn:sined:documentid:numeric33:268349502715843920174683529410532"
    }
  ]
}

Compatibilità con UUID¶

Per compatibilità, è supportato anche il formato UUID standard (urn:uuid:...), senza il prefisso sined:documentid. È il formato usato negli esempi di questo documento (vedi UniqueDocumentId in "Dati del caso di esempio").

{
  "resourceType": "DocumentReference",
  "status": "current",
  "identifier": [
    {
      "system": "urn:ietf:rfc:3986",
      "value": "urn:uuid:e7c3f91b-8a42-4d5e-9f16-3b8c7a2e5d41"
    }
  ]
}

Limite di lunghezza¶

DocumentReference.identifier.value viene trattato da T4MED come una stringa libera.
Lunghezza massima supportata: 200 caratteri.
Gli identificativi prodotti da SINED (fino a circa 150 caratteri) sono pienamente compatibili con questo limite.

Relazione tra gli identificativi (UniqueDocumentId, T4MedDocumentId, T4MedBinaryId)¶

Ogni pubblicazione di un referto coinvolge tre identificativi distinti, da non confondere tra loro:

Identificativo	Assegnato da	Significato
UniqueDocumentId	SINED/REPO	Identificativo di business del documento, assegnato al momento della pubblicazione. È il valore di `DocumentReference.identifier` (vedi formato sopra). Ogni nuova pubblicazione con un nuovo contenuto documentale ha un nuovo UniqueDocumentId.
T4MedDocumentId	T4MED	Identificativo della risorsa FHIR `DocumentReference` nel repository T4MED. Restituito nella response della creazione, nel campo `entry[].response.location` (es. `DocumentReference/DOC-T4MED-000123/_history/1` → `T4MedDocumentId = DOC-T4MED-000123`; la parte `/_history/1` è la versione tecnica FHIR e non ne fa parte). Governa le operazioni successive sul documento: i Flussi F (`RPD`), G (`CAD`) e H (`UPM`) operano tramite `PUT /DocumentReference/{T4MedDocumentId}`.
T4MedBinaryId	T4MED	Identificativo della risorsa FHIR `Binary` che contiene il PDF. Restituito nella response della creazione (`entry[].response.location`, es. `Binary/BIN-T4MED-000123/_history/1` → `T4MedBinaryId = BIN-T4MED-000123`). Serve a mantenere il collegamento tra `DocumentReference` e PDF pubblicato, a recuperarne il contenuto (`GET /Binary/{T4MedBinaryId}`) e a preservare il riferimento al PDF esistente nei Flussi F/G/H senza reinviare il file in Base64. Non identifica il documento clinico nel suo complesso e non è usato per governarne il ciclo di vita — per quello si usa il `T4MedDocumentId`. Ogni nuovo PDF determina un nuovo `T4MedBinaryId`.

Il T4MedDocumentId può (non deve) coincidere con lo UniqueDocumentId: la scelta è di T4MED. gt4medServices tratta i due identificativi come indipendenti e acquisisce sempre il T4MedDocumentId dalla response (entry[].response.location), anche qualora il valore restituito risultasse uguale o derivato dallo UniqueDocumentId — non lo assume né lo calcola mai a priori. Lo stesso vale per il T4MedBinaryId, assegnato da T4MED e non derivabile da alcun campo SINED.

Tra UniqueDocumentId e T4MedDocumentId esiste una corrispondenza uno-a-uno per la singola pubblicazione, ma non è previsto che i rispettivi valori siano identici: entrambi vanno memorizzati esplicitamente da gt4medServices, insieme al T4MedBinaryId, in corrispondenza dell'UniqueDocumentId.

Per il referto sostitutivo (Flusso F) si aggiunge un quarto valore, il ParentT4MedDocumentId: il T4MedDocumentId del documento sostituito, già acquisito al momento della sua pubblicazione — non ricavato dal suo UniqueDocumentId.

Metadati di riservatezza, visibilità e versionamento¶

In aggiunta ai metadati "clinici" (tipo documento, paziente, data, collegamento all'Appointment), la risorsa DocumentReference riporta i metadati di riservatezza/visibilità e il numero di versione del documento.

Concetto	Rappresentazione FHIR R4	Valori
Confidentiality Code	`DocumentReference.securityLabel` — CodeSystem `v3-Confidentiality`	`N` (Normal) \| `R` (Restricted) \| `V` (Very Restricted)
Oscuramenti	extension ripetibile `document-oscuramento` (`valueCode`) — assente se nessun oscuramento	modello Piemonte/Affinity Domain Italia (di riferimento): `P97` \| `P98` \| `P99`; modello Lombardia (alternativo): `HIV` \| `IVG` \| `SERD` \| `VIOLENZA` \| `RICHIESTA_CITTADINO`
Visibilità al cittadino (FSE)	extension `patient-visibility-authorized` (`valueCode`)	`S` (sì) \| `N` (no)
Stato pagamento ticket	extension `ticket-payment-status` (`valueCode`)	`P` (pagato) \| `E` (esente) \| `N` (non pagato) \| `U` (sconosciuto)
Numero di versione documento	extension `document-version` (`valueInteger`)	`1` per la prima pubblicazione; `> 1` per sostitutivi e annullativi

Versionamento del documento¶

Versione	Descrizione	Flusso	Codice Azione SINED	`DocumentReference.identifier`	`document-version`	Meccanismo aggiuntivo
Prima pubblicazione	Nuovo referto, mai pubblicato in precedenza	E (questo documento)	`NWD`	UniqueDocumentId della v1	`1`	—
Sostitutivo	Sostituisce un referto già pubblicato	F	`RPD`	UniqueDocumentId della nuova versione	`> 1`	`relatesTo.code = "replaces"` → DocumentReference originale (ParentT4MedDocumentId)
Annullativo	Revoca un referto già pubblicato	G	`CAD`	UniqueDocumentId del documento annullativo	`> 1` (riportato per uniformità, anche se non strettamente necessario per l'annullamento)	`DocumentReference.status = "entered-in-error"` (richiede `PUT` sull'originale)
Aggiornamento metadati	Cambia un metadato senza toccare PDF o versione	H	`UPM`	Invariato	Invariato	`PUT` sull'originale, `status` invariato

T4MED supporta anche la gestione del referto sostitutivo (Flusso F) e annullativo (Flusso G). Se invece cambia solo un metadato (es. lo stato di pagamento ticket), senza toccare PDF o versione, si applica il Flusso H — aggiornamento dei soli metadati.

Prima pubblicazione (versione 1)¶

REQUEST¶

POST https://biocaretest.evisus.it/api/fhir
Content-Type: application/fhir+json
X-API-Key: <chiave>

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [

    {
      "fullUrl": "urn:uuid:f4e72b38-9d16-4c5a-8f73-6b2e1a9d4c87",
      "resource": {
        "resourceType": "Binary",
        "contentType": "application/pdf",
        "data": "<PDF_FIRMATO_DIGITALMENTE_IN_BASE64>"
      },
      "request": {
        "method": "POST",
        "url": "Binary"
      }
    },

    {
      "fullUrl": "urn:uuid:a8c35f71-4b92-4e6d-b184-9f7e2c5a8d13",
      "resource": {
        "resourceType": "DocumentReference",
        "status": "current",
        "identifier": [
          {
            "system": "urn:ietf:rfc:3986",
            "value": "urn:uuid:e7c3f91b-8a42-4d5e-9f16-3b8c7a2e5d41"
          }
        ],
        "type": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "11488-4",
              "display": "Consult note"
            }
          ]
        },
        "subject": {
          "reference": "Patient/RSVDMN11A41H620X",
          "display": "ROSAVIOLA DALMINA"
        },
        "date": "2026-06-03T11:00:00+02:00",

        "securityLabel": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                "code": "R",
                "display": "restricted"
              }
            ]
          }
        ],

        "extension": [
          {
            "url": "http://t4med.it/fhir/StructureDefinition/patient-visibility-authorized",
            "valueCode": "S"
          },
          {
            "url": "http://t4med.it/fhir/StructureDefinition/ticket-payment-status",
            "valueCode": "P"
          },
          {
            "url": "http://t4med.it/fhir/StructureDefinition/document-version",
            "valueInteger": 1
          }
        ],

        "content": [
          {
            "attachment": {
              "contentType": "application/pdf",
              "url": "urn:uuid:f4e72b38-9d16-4c5a-8f73-6b2e1a9d4c87",
              "title": "Referto televisita nefrologica - 03/06/2026"
            }
          }
        ],
        "context": {
          "related": [
            {
              "reference": "Appointment/T00450"
            }
          ]
        }
      },
      "request": {
        "method": "POST",
        "url": "DocumentReference"
      }
    }

  ]
}

Nell'esempio non sono presenti oscuramenti (document-oscuramento assente nell'array extension). Qualora uno o più oscuramenti siano applicati, va aggiunta un'occorrenza di document-oscuramento (valueCode) per ciascuna tipologia.

RESPONSE ATTESA¶

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "Bundle",
  "type": "transaction-response",
  "entry": [
    {
      "response": {
        "status": "201 Created",
        "location": "Binary/BIN-T4MED-000123/_history/1"
      }
    },
    {
      "response": {
        "status": "201 Created",
        "location": "DocumentReference/DOC-T4MED-000123/_history/1"
      }
    }
  ]
}

Binary/BIN-T4MED-000123 e DocumentReference/DOC-T4MED-000123 sono entrambi placeholder: i due id (T4MedBinaryId e T4MedDocumentId) sono assegnati da T4MED e non prevedibili — non c'è alcuna garanzia che coincidano con l'UniqueDocumentId della request (urn:uuid:e7c3f91b-...), anche se T4MED fosse libero di sceglierli uguali o derivati. La parte /_history/1 è la versione tecnica FHIR e non fa parte dell'id.

Azione gt4medServices dopo la risposta:

Estrarre e salvare T4MedBinaryId (da Binary/BIN-T4MED-000123/_history/1 → BIN-T4MED-000123) e T4MedDocumentId (da DocumentReference/DOC-T4MED-000123/_history/1 → DOC-T4MED-000123) da entry[].response.location: entrambi assegnati da T4MED, da acquisire sempre dalla response — vedi "Relazione tra gli identificativi" sopra. Non memorizzare alcun identificativo definitivo prima del completamento positivo della transazione (vedi 06-response-failure.md).
Associare entrambi gli id allo UniqueDocumentId urn:uuid:e7c3f91b-...: la terna (UniqueDocumentId, T4MedDocumentId, T4MedBinaryId) è necessaria per i successivi referti sostitutivi (Flusso F) e annullativi (Flusso G), e per gli aggiornamenti dei soli metadati (Flusso H).

Response di fallimento¶

Per il formato generale e l'elenco completo degli scenari di errore vedi 06-response-failure.md. Esempi pertinenti al Flusso E:

DocumentReference.identifier (UniqueDocumentId) assente

HTTP/1.1 400 Bad Request
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "required",
      "details": {
        "text": "DocumentReference.identifier (UniqueDocumentId del referto) e' obbligatorio"
      },
      "diagnostics": "Bundle entry[1] (DocumentReference) - validazione fallita",
      "expression": [ "Bundle.entry[1].resource.identifier" ]
    }
  ]
}

Paziente non trovato per il codice fiscale indicato in subject

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "details": {
        "text": "Nessun Patient trovato con id 'RSVDMN11A41H620X'"
      },
      "diagnostics": "Bundle entry[1] (DocumentReference) - subject non risolvibile",
      "expression": [ "Bundle.entry[1].resource.subject" ]
    }
  ]
}

In entrambi i casi la transazione viene annullata (atomicità — vedi 06-response-failure.md): né Binary né DocumentReference vengono creati su T4MED. Il referto risulterà pubblicato su REPO/FSE ma non su T4MED: da segnalare per allineamento manuale (vedi Eccezione E2 in 05-vincoli-e-eccezioni.md).