Flusso F — Pubblicazione referto sostitutivo su T4MED (versione > 1)¶

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

Contesto¶

Il Flusso F è una variante del Flusso E (pubblicazione nuovo referto): si applica quando un referto già pubblicato su T4MED deve essere sostituito da una nuova versione — ad esempio a seguito di una correzione del contenuto clinico dopo la prima pubblicazione.

Il referto sostitutivo:

ha un nuovo identifier (UniqueDocumentId della versione N, assegnato da SINED/REPO);
riporta document-version = N (con N > 1);
dichiara esplicitamente di sostituire il documento precedente tramite relatesTo.code = "replaces".

Richiede il T4MedDocumentId del DocumentReference originale, cioè quello che nel contesto della sostituzione prende il nome di ParentT4MedDocumentId. Come chiarito in Flusso E — "Relazione tra gli identificativi", questo id non è derivabile dallo UniqueDocumentId del documento originale — anche se T4MED fosse libero di assegnarne uno uguale o derivato, gt4medServices non deve assumerlo: il ParentT4MedDocumentId è il T4MedDocumentId già acquisito dalla response di T4MED al momento della pubblicazione originale (Flusso E) e memorizzato insieme allo UniqueDocumentId corrispondente — non richiede quindi una nuova chiamata dedicata a T4MED, ma nemmeno un calcolo a partire da altri campi.

Ordine delle operazioni: identico al Flusso E — l'upload su T4MED avviene sempre dopo la conferma di pubblicazione del referto sostitutivo su 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)
UniqueDocumentId (versione 1, originale)	`urn:uuid:e7c3f91b-8a42-4d5e-9f16-3b8c7a2e5d41`
T4MedDocumentId (versione 1) = ParentT4MedDocumentId	`DOC-T4MED-000123` (acquisito dalla response del Flusso E, non derivato dallo UniqueDocumentId)
T4MedBinaryId (versione 1)	`BIN-T4MED-000123` (acquisito dalla response del Flusso E)
UniqueDocumentId (versione 2, sostitutivo)	`urn:uuid:d5f92c38-1b64-4a7e-8c35-2e9d8f4b7a61`
Numero di versione documento	`2`
Codice Azione SINED	`RPD`

Conformità allo standard FHIR R4¶

Il Flusso F aderisce completamente allo standard FHIR R4: stesso endpoint del Flusso E, stesso tipo di Bundle (transaction), con l'aggiunta dell'elemento relatesTo sulla risorsa DocumentReference per dichiarare la relazione di sostituzione con il documento originale.

Per il formato dell'identificativo (DocumentReference.identifier), i metadati di riservatezza/visibilità e il limite di lunghezza, vedi le sezioni corrispondenti nel Flusso E — si applicano invariati anche al Flusso F.

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.

Referto sostitutivo (versione N > 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:b2d84a19-5c73-4f8e-a291-7c4b9e3d6f52",
      "resource": {
        "resourceType": "Binary",
        "contentType": "application/pdf",
        "data": "<PDF_SOSTITUTIVO_FIRMATO_IN_BASE64>"
      },
      "request": {
        "method": "POST",
        "url": "Binary"
      }
    },

    {
      "fullUrl": "urn:uuid:d5f92c38-1b64-4a7e-8c35-2e9d8f4b7a61",
      "resource": {
        "resourceType": "DocumentReference",
        "status": "current",
        "identifier": [
          {
            "system": "urn:ietf:rfc:3986",
            "value": "urn:uuid:d5f92c38-1b64-4a7e-8c35-2e9d8f4b7a61"
          }
        ],
        "relatesTo": [
          {
            "code": "replaces",
            "target": {
              "reference": "DocumentReference/DOC-T4MED-000123"
            }
          }
        ],
        "type": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "11488-4",
              "display": "Consult note"
            }
          ]
        },
        "subject": {
          "reference": "Patient/RSVDMN11A41H620X",
          "display": "ROSAVIOLA DALMINA"
        },
        "date": "2026-06-03T14:30: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": 2
          }
        ],

        "content": [
          {
            "attachment": {
              "contentType": "application/pdf",
              "url": "urn:uuid:b2d84a19-5c73-4f8e-a291-7c4b9e3d6f52",
              "title": "Referto televisita nefrologica - 03/06/2026 (sostitutivo)"
            }
          }
        ],
        "context": {
          "related": [
            {
              "reference": "Appointment/T00450"
            }
          ]
        }
      },
      "request": {
        "method": "POST",
        "url": "DocumentReference"
      }
    }

  ]
}

Il riferimento al documento sostituito è relatesTo.target.reference (il ParentT4MedDocumentId). Il campo target.identifier non è utilizzato: in FHIR R4 Reference.identifier è opzionale (0..1) e qui ridondante, dato che target.reference identifica già univocamente la risorsa tramite il T4MedDocumentId.

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-000456/_history/1"
      }
    },
    {
      "response": {
        "status": "201 Created",
        "location": "DocumentReference/DOC-T4MED-000456/_history/1"
      }
    }
  ]
}

Binary/BIN-T4MED-000456 e DocumentReference/DOC-T4MED-000456 sono entrambi id genuinamente assegnati da T4MED — non c'è garanzia che coincidano con l'UniqueDocumentId della versione 2 (urn:uuid:d5f92c38-...), vedi Flusso E — "Relazione tra gli identificativi".

Azione gt4medServices dopo la risposta:

Estrarre e salvare T4MedDocumentId (DOC-T4MED-000456) e T4MedBinaryId (BIN-T4MED-000456) da entry[].response.location, associati allo UniqueDocumentId della versione 2 — necessari per eventuali ulteriori sostituzioni o per un successivo annullamento (Flusso G). Non memorizzare alcun identificativo definitivo prima del completamento positivo della transazione.
Registrare ParentT4MedDocumentId = DOC-T4MED-000123 in corrispondenza della versione 2, per tracciare la catena di sostituzione.
Il documento di versione 1 resta collegato al nuovo documento tramite relatesTo (lato T4MED). Se e come T4MED aggiorni internamente lo stato del documento precedente (es. a superseded) è una scelta interna di T4MED, che non richiede conferma né azione da parte di gt4medServices.

Response di fallimento¶

Per il formato generale e l'elenco completo degli scenari di errore vedi 06-response-failure.md. Gli scenari di errore sono gli stessi del Flusso E (campo obbligatorio mancante, paziente non trovato), con l'aggiunta del seguente scenario specifico del Flusso F:

Documento originale (relatesTo.target) non trovato

HTTP/1.1 404 Not Found
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Nessuna risorsa DocumentReference trovata con id '<id-t4med-del-documento-originale>'"
      },
      "diagnostics": "Bundle entry[1] (DocumentReference) - relatesTo.target non risolvibile",
      "expression": [ "Bundle.entry[1].resource.relatesTo[0].target" ]
    }
  ]
}

In tutti i casi, per l'atomicità della Bundle transaction (vedi 06-response-failure.md), né Binary né DocumentReference vengono creati su T4MED. Il referto sostitutivo risulterà pubblicato su REPO/FSE ma non su T4MED: da segnalare per allineamento manuale (vedi Eccezione E2 in 05-vincoli-e-eccezioni.md).