Vai al contenuto

Flusso D — Download referto da T4MED

Operazione: POST /Patient/{cfisc}/$generate-pdf Flusso: D — gt4medServices → T4MED (post-visita)

Contesto

Al termine della televisita, gefidServices richiede a gt4medServices il referto di monitoraggio da T4MED. gt4medServices:

  1. Scarica il PDF di monitoraggio da T4MED
  2. Scarica il referto clinico da MEDWARE
  3. Unisce i due PDF (merge)
  4. Consegna il PDF unito a gefidServices per la firma digitale

Dati del caso di esempio

Campo Valore
T4MED Patient ID (= codice fiscale) RSVDMN11A41H620X
Paziente ROSAVIOLA DALMINA (nome di fantasia)
Data televisita 2026-06-03
T4MED Appointment ID T00450 (da tabella di mappatura, inserita al Flusso A)

Il codice ospedaliero è eliminato. L'unico identificativo del paziente in T4MED è il codice fiscale, usato come {id} nell'URL dell'operazione.

Parametro obbligatorio T4MedAppointmentId

A seguito dei test di integrazione, l'operazione $generate-pdf richiede obbligatoriamente tre parametri:

Parametro Tipo Obbligatorio Descrizione
DateFrom valueDate Sì Inizio del periodo di telemonitoraggio richiesto
DateTo valueDate Sì Fine del periodo di telemonitoraggio richiesto
T4MedAppointmentId valueString Sì T4MED Appointment ID (vedi Flusso A) — limita il telemonitoraggio restituito alla specifica prenotazione

T4MedAppointmentId non sostituisce DateFrom/DateTo: i tre parametri sono usati congiuntamente da T4MED per restringere i dati di telemonitoraggio restituiti alla singola prenotazione indicata, evitando che vengano inclusi dati di monitoraggio riferiti ad altre televisite del medesimo paziente nello stesso intervallo di date.

gt4medServices deve valorizzare T4MedAppointmentId con il T4MED Appointment ID già memorizzato nella tabella di mappatura interna al momento dell'inserimento della prenotazione (Flusso A).

Conformità FHIR R4

Per il Flusso D la specifica T4MED e lo standard FHIR R4 coincidono:

  • $generate-pdf è un'operazione custom FHIR R4 su istanza Patient, identificata dal prefisso $ come previsto dal meccanismo FHIR R4 di estensibilità.
  • I parametri vengono passati tramite risorsa Parameters: uso corretto per le operazioni FHIR R4.
  • La risposta stream PDF con Accept: application/pdf è conforme.

Endpoint e autenticazione

POST https://biocaretest.evisus.it/api/fhir/Patient/RSVDMN11A41H620X/$generate-pdf
Accept: application/pdf
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.

Messaggio di richiesta

REQUEST

POST https://biocaretest.evisus.it/api/fhir/Patient/RSVDMN11A41H620X/$generate-pdf
Accept: application/pdf
Content-Type: application/fhir+json
X-API-Key: <chiave>

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "DateFrom",
      "valueDate": "2026-06-03"
    },
    {
      "name": "DateTo",
      "valueDate": "2026-06-03"
    },
    {
      "name": "T4MedAppointmentId",
      "valueString": "T00450"
    }
  ]
}

RESPONSE ATTESA

HTTP/1.1 200 OK
Content-Type: application/pdf

[stream binario PDF — dati di monitoraggio della televisita del 03/06/2026]

Response di fallimento

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

Nota: anche se la risposta di successo è uno stream binario (Content-Type: application/pdf), la risposta di fallimento resta comunque un OperationOutcome in application/fhir+json — comportamento standard per le $operation FHIR R4.

Patient 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 Patient trovata con id 'RSVDMN11A41H620X'"
      },
      "diagnostics": "POST /Patient/RSVDMN11A41H620X/$generate-pdf"
    }
  ]
}

Intervallo date non valido (DateFrom successivo a DateTo)

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

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "details": {
        "text": "Il parametro 'DateFrom' e' successivo al parametro 'DateTo'"
      },
      "diagnostics": "POST /Patient/RSVDMN11A41H620X/$generate-pdf",
      "expression": [ "Parameters.parameter.where(name='DateFrom').value" ]
    }
  ]
}

Appointment inesistente (T4MedAppointmentId non trovato)

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

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Nessun Appointment trovato con id '9999'"
      },
      "diagnostics": "POST /Patient/RSVDMN11A41H620X/$generate-pdf",
      "expression": [ "Parameters.parameter.where(name='T4MedAppointmentId').value" ]
    }
  ]
}

Appointment appartenente ad altro paziente

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

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "details": {
        "text": "L'Appointment con id '2436' non e' associato al Patient 'RSVDMN11A41H620X'"
      },
      "diagnostics": "POST /Patient/RSVDMN11A41H620X/$generate-pdf",
      "expression": [ "Parameters.parameter.where(name='T4MedAppointmentId').value" ]
    }
  ]
}

In tutti i casi sopra il merge del PDF non può essere completato: gt4medServices restituisce a gefidServices il solo referto MEDWARE, senza l'allegato dei dati di monitoraggio T4MED. gefidServices procede comunque con la firma digitale del referto — lo stesso comportamento previsto per il caso 204 No Content descritto di seguito.

Nessun dato clinico disponibile (204 No Content)

Quando il paziente esiste, i parametri sono formalmente corretti (incluso T4MedAppointmentId valido e associato al paziente), ma nel periodo richiesto non esistono schede di telemonitoraggio, T4MED risponde con:

HTTP/1.1 204 No Content

(nessun body)

Questo non è un errore: è un esito legittimo dell'operazione, distinto dal fallimento (OperationOutcome, 4xx/5xx) e dal successo con contenuto (200 OK, stream PDF).

Azione gt4medServices / lato SINED:

  • Non viene effettuato il merge tra PDF T4MED e referto MEDWARE.
  • Viene pubblicato esclusivamente il referto clinico MEDWARE (senza l'allegato dei dati di monitoraggio T4MED).
  • Il flusso di firma prosegue regolarmente: il 204 No Content non blocca gefidServices — lo stesso comportamento previsto per gli scenari di errore 4xx/5xx descritti sopra.