Flusso H — Aggiornamento dei soli metadati del referto¶

Operazione: PUT /DocumentReference/{id} Flusso: H — grepoServices → gt4medServices → T4MED

Contesto¶

Il Flusso H si applica quando cambia solo un metadato di riservatezza/visibilità di un referto già pubblicato su T4MED (es. lo stato di pagamento ticket passa da N a P, oppure cambia la visibilità al cittadino), senza variare il PDF né il numero di versione del documento.

È un caso distinto sia dal Flusso F (che pubblica un nuovo PDF con una nuova versione) sia dal Flusso G (che revoca il documento impostando status = "entered-in-error"): qui il PDF resta lo stesso, la versione (document-version) resta invariata e status resta "current".

Il Flusso H riusa lo stesso endpoint PUT /DocumentReference/{id} del Flusso G — nessun endpoint dedicato aggiuntivo è previsto da T4MED. La differenza rispetto al Flusso G è esclusivamente nel contenuto della risorsa inviata: qui status resta "current" e cambia solo il valore di uno o più metadati.

Richiede il T4MedDocumentId del DocumentReference da aggiornare e il T4MedBinaryId del PDF già pubblicato. Come chiarito in Flusso E — "Relazione tra gli identificativi", nessuno dei due è derivabile dallo UniqueDocumentId del documento pubblicato (Flusso E): entrambi sono valori genuinamente assegnati da T4MED, già acquisiti dalla response al momento della pubblicazione originale e conservati da gt4medServices — non richiedono una nuova chiamata dedicata a T4MED per il recupero, ma nemmeno un calcolo a partire da altri campi.

Dati del caso di esempio¶

Campo	Valore
T4MED Appointment ID	`T00450`
Codice fiscale (= T4MED Patient ID)	`RSVDMN11A41H620X`
Paziente	ROSAVIOLA DALMINA (nome di fantasia)
UniqueDocumentId (documento già pubblicato)	`urn:uuid:e7c3f91b-8a42-4d5e-9f16-3b8c7a2e5d41`
T4MedDocumentId	`DOC-T4MED-000123` (acquisito dalla response del Flusso E, non derivato dallo UniqueDocumentId)
T4MedBinaryId	`BIN-T4MED-000123` (acquisito dalla response del Flusso E; salvato al momento della prima pubblicazione)
Metadato variato	`ticket-payment-status`: da `N` (non pagato) a `P` (pagato)
Numero di versione documento	`1` (invariato)
Codice Azione SINED	`UPM` (classificazione interna, non trasmessa a T4MED)

Conformità allo standard FHIR R4¶

Per il Flusso H la specifica T4MED e lo standard FHIR R4 coincidono: PUT /DocumentReference/{id} con sostituzione completa della risorsa è il meccanismo standard FHIR R4 per aggiornare una risorsa esistente, incluso il solo aggiornamento di metadati non clinici.

Il PUT FHIR R4 richiede la rappresentazione completa della risorsa DocumentReference (non solo i campi variati), ma non richiede di ripresentare il Binary: content.attachment.url fa riferimento al Binary già esistente (Binary/{T4MedBinaryId}), senza includere nuovamente il campo data (PDF in base64).

Per il formato dell'identificativo (DocumentReference.identifier) e il limite di lunghezza, vedi le sezioni corrispondenti nel Flusso E — si applicano invariati anche al Flusso H.

Endpoint e autenticazione¶

PUT https://biocaretest.evisus.it/api/fhir/DocumentReference/DOC-T4MED-000123
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.

Aggiornamento dei soli metadati (stesso PDF, stessa versione)¶

REQUEST¶

PUT https://biocaretest.evisus.it/api/fhir/DocumentReference/DOC-T4MED-000123
Content-Type: application/fhir+json
X-API-Key: <chiave>

{
  "resourceType": "DocumentReference",
  "id": "DOC-T4MED-000123",
  "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": "Binary/BIN-T4MED-000123",
        "title": "Referto televisita nefrologica - 03/06/2026"
      }
    }
  ],
  "context": {
    "related": [
      {
        "reference": "Appointment/T00450"
      }
    ]
  }
}

RESPONSE ATTESA¶

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

{
  "resourceType": "DocumentReference",
  "id": "DOC-T4MED-000123",
  "...": "(rappresentazione aggiornata della risorsa)"
}

Nell'esempio sopra l'unica differenza rispetto alla risorsa pubblicata in "Prima pubblicazione" (Flusso E) è il valueCode dell'extension ticket-payment-status (da N a P); tutti gli altri campi — incluso document-version, che resta 1 — sono ripresentati invariati, come richiesto dalla semantica "sostituzione completa" del PUT FHIR R4 (vedi anche Flusso B, PUT /Appointment/{id}).

Azione gt4medServices dopo la risposta:

Nessuna nuova mappatura da salvare: T4MedDocumentId = DOC-T4MED-000123 e T4MedBinaryId = BIN-T4MED-000123 restano invariati rispetto alla pubblicazione precedente.

Response di fallimento¶

Per il formato generale e l'elenco completo degli scenari di errore vedi 06-response-failure.md.

DocumentReference originale 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-DocumentReference>'"
      },
      "diagnostics": "PUT /DocumentReference/<id-DocumentReference>"
    }
  ]
}

Documento già annullato (status già entered-in-error) — non aggiornabile

HTTP/1.1 409 Conflict
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "conflict",
      "details": {
        "text": "Il DocumentReference '<id-DocumentReference>' e' nello stato 'entered-in-error' e non puo' essere aggiornato"
      },
      "diagnostics": "PUT /DocumentReference/<id-DocumentReference>"
    }
  ]
}

AZIONE gt4medServices: su 404/409 non ritentare; segnalare il disallineamento per verifica (vedi Eccezione E2 in 05-vincoli-e-eccezioni.md) — il metadato risulterà aggiornato lato SINED ma non correttamente riflesso su T4MED.