GipoNext API

Italiano

English

Italiano

English

Appearance

Integrazione RIS-PACS FHIR ​

Questa pagina descrive come integrare GipoNext con un sistema RIS-PACS usando lo standard FHIR.

L'obiettivo è rendere chiaro:

  • quali risorse implementare;
  • come gestire autenticazione e autorizzazione;
  • quali endpoint usare nei flussi principali.

Standard e formato ​

Lo standard di riferimento è FHIR Release 3 (STU v3.0.1).

Tutte le comunicazioni devono avvenire su endpoint HTTPS pubblici.

Autenticazione e autorizzazione ​

L'endpoint ricevente del PACS può usare una delle opzioni seguenti:

  • Bearer token / ApiKey via header Authorization (Bearer XXXXXXXXX)
  • Basic authentication via header Authorization (obsoleto)

Per la ricezione referti, GipoNext supporta:

  • Bearer token / ApiKey
  • OAuth 2.0 con token Bearer ottenuto dai flussi OAuth 2.0 documentati nelle API GipoNext

Risorse coinvolte ​

Risorse da implementare su RIS-PACS ​

Risorsa implementata su GipoNext ​

Flussi operativi ​

Flusso all'accettazione ​

GipoNext invia verso RIS-PACS:

  1. PUT Patient
  2. POST ProcedureRequest

Flusso ricezione esiti (facoltativo) ​

RIS-PACS invia verso GipoNext:

  1. POST DiagnosticReport

Endpoint di ricezione su GipoNext ​

Il formato endpoint è:

https://api.giponext.it/fhir/r3/{userId}/{resource}/{id?}

Dove:

  • {userId}: identificativo cliente GipoNext (fornito in fase di attivazione)
  • {resource}: nome risorsa (esempio DiagnosticReport)
  • {id?}: identificativo risorsa (facoltativo, usato per GET, PUT, DELETE)

Limitazioni ​

  • Una volta creata una ProcedureRequest, la risorsa non è modificabile.

Esempi ​

PUT Patient (GipoNext → RIS-PACS)
json
{
  "resourceType": "Patient",
  "id": "101",
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/patient-birthPlace",
      "valueAddress": {
        "extension": [
          {
            "url": "https://api.giponext.it/fhir/birthPlace/codice-istat-comune",
            "valueCoding": {
              "system": "https://www.istat.it/it/archivio/6789",
              "code": "015146",
              "display": "Milano"
            }
          }
        ],
        "city": "Milano",
        "country": "IT"
      }
    }
  ],
  "identifier": [
    {
      "system": "https://www.giponext.it",
      "value": "101"
    },
    {
      "system": "urn:oid:2.16.840.1.113883.2.9.4.3.2",
      "value": "RSSMRA80B12X876P"
    },
    {
      "system": "RISPACS",
      "value": "1"
    }
  ],
  "active": true,
  "name": [
    {
      "family": "Rossi",
      "given": [
        "Mario"
      ]
    }
  ],
  "telecom": [
    {
      "system": "email",
      "value": "mario.rossi@test.it",
      "use": "home"
    },
    {
      "system": "phone",
      "value": "+39333000000",
      "use": "mobile"
    },
    {
      "system": "phone",
      "value": "+3902148874",
      "use": "home"
    },
    {
      "system": "phone",
      "value": "+390211112",
      "use": "work"
    }
  ],
  "gender": "male",
  "birthDate": "1980-02-12",
  "address": [
    {
      "extension": [
        {
          "url": "https://api.giponext.it/fhir/address/codice-istat-comune",
          "valueCoding": {
            "system": "https://www.istat.it/it/archivio/6789",
            "code": "015146",
            "display": "Milano"
          }
        }
      ],
      "line": [
        "Via Bartolomeo D'Alviano"
      ],
      "city": "Milano",
      "district": "MI",
      "state": "MI",
      "postalCode": "20146",
      "country": "IT"
    }
  ]
}
POST ProcedureRequest (GipoNext → RIS-PACS)
json
{
  "resourceType": "ProcedureRequest",
  "id": "A100R98I1",
  "identifier": [
    {
      "system": "https://www.giponext.it",
      "value": "A100R98I1"
    }
  ],
  "requisition": {
    "system": "https://www.giponext.it",
    "value": "100"
  },
  "authoredOn": "2019-07-16T12:41:51.0519077+02:00", // facoltativo, eventuale data/ora di accettazione (se presente)
  "status": "active",
  "intent": "order",
  "category": [
    // facoltativo eventuali branche/specialità (un elemento per specialità)
    {
      "coding": [
        // codifica della specialità
        {
          "system": "https://www.giponext.it",
          "code": "BR10", // codice specialità di giponext
          "userSelected": true // true per la specialità selezionata dall'utente (se più di una presente)
        },
        {
          "system": "https://www.giponext.it",
          "code": "BR11",
          "userSelected": false
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "RISPACS",
        "code": "X10010",
        "display": "Prestazione di esempio 1"
      },
      {
        "system": "https://www.giponext.it",
        "code": "0"
      },
      {
        "system": "sistemats.nomenclatore",
        "code": "N",
        "display": "Codifica nomenclatore regionale"
      },
      {
        "system": "sistemats.codice",
        "code": "XXXXX", // Codice prestazione specialistica secondo il tariffario della regione (facoltativa)
        "display": "Codifica nomenclatore nazionale"
      }
    ]
  },
  "subject": {
    "reference": "Patient/101",
    "identifier": {
      "system": "https://www.giponext.it",
      "value": "101"
    },
    "extension": [
      {
        "url": "https://www.giponext.it",
        "valueString": "101"
      },
      {
        "url": "urn:oid:2.16.840.1.113883.2.9.4.3.2",
        "valueString": "RSSMRA80B12X876P"
      },
      {
        "url": "RISPACS",
        "valueString": "1"
      }
    ]
  },
  "occurrenceDateTime": "2026-02-27T11:38:27.4525418+01:00",
  "requester": {
    "agent": {
      "reference": "User/testuser",
      "display": "testuser"
    }
  },
  "note": [
    {
      "text": "Note ordine"
    }
  ],
  "performer": {
    "reference": "Doctors/doctorid", // Tecnico GipoNext collegato (facoltativo)
    "display": "testuser",
    "identifier": {
      "system": "urn:oid:2.16.840.1.113883.2.9.4.3.2",
      "value": "ABCDEF86H12K897O" // codice fiscale del medico / tecnico
    }
  },
  "supportingInfo": [
    {
      "reference": "Prescription/123456789123456", // impegnativa collegata (rif)
      "display": "Impegnativa",
      "identifier": {
        "system": "urn:oid:2.16.840.1.113883.2.9.4.3.8", // oid ricette dematerializzate
        "value": "123456789123456" // numero impegnativa
      },
      "extension": [
        {
          "url": "https://api.giponext.it/fhir/impegnativa/oscurato", // valore per l'oscuramento
          "valueBoolean": true
        },
        {
          "url": "https://api.giponext.it/fhir/impegnativa/totale-impegnativa", // costo totale dell'impegnativa
          "valueDecimal": 36.15
        },
        {
          "url": "https://api.giponext.it/fhir/impegnativa/totale-prestazioni", // costo totale sostenuto dal SSN
          "valueDecimal": 52.3
        },
        {
          "url": "https://api.giponext.it/fhir/impegnativa/esente", // flag se l'impegnativa è esente
          "valueBoolean": false
        },
        {
          "url": "https://api.giponext.it/fhir/impegnativa/codice-asl", // codice ASL/AUSL/USL/ULSS/ASP dell'assistito
          "valueString": "201"
        },
        {
          "url": "https://api.giponext.it/fhir/impegnativa/codice-regione", // codice regione dell'assistito
          "valueString": "080"
        }
      ]
    }
  ],
  "extension": [
    {
      "url": "https://api.giponext.it/fhir/assignedReporter", // facoltativo, medico refertante assegnato (se presente)
      "valueReference": {
        "reference": "Doctors/doctorid", // medico GipoNext collegato
        "display": "testuser",
        "identifier": {
          "system": "urn:oid:2.16.840.1.113883.2.9.4.3.2",
          "value": "ABCDEF86H12K897O" // codice fiscale del medico
        }
      }
    }
  ]
}
POST DiagnosticReport (RIS-PACS → GipoNext) - Optional
json
{
  "resourceType": "DiagnosticReport",
  "id": "REPORT-001", // identificativo univoco del referto nel sistema inviante
  "extension": [
    {
      "url": "https://api.giponext.it/fhir/availableOnline", // extension facoltativa, impostarla a true se il referto deve essere reso disponibili nel portale Referti.OnLine
      "valueBoolean": true
    }
  ],
  "basedOn": [
    {
      "reference": "ProcedureRequest/A1230R354I1" // Impostare lo stesso riferimento della ProcedureRequest di origine nel formato "ProcedureRequest/XXXXXX" dove XXXXX è il suo id
    },
    {
      "reference": "ProcedureRequest/A1230R355I1"
    }
  ],
  "status": "final",
  "code": {
    "coding": [
      {
        "system": "RISPACS", // coding del sistema inviante, facoltativo
        "code": "X123456"
      },
      {
        "system": "http://loinc.org",
        "code": "18748-4" // codice LOINC (facoltativo, es: https://loinc.org/18748-4/)
      }
    ]
  },
  "subject": {
    "reference": "Patient/123465789" // stesso identificativo inviatovi in fase di creazione ProcedureRequest
  },
  "issued": "2019-10-22T10:00:00+00:00", // data referto
  "performer": [
    // lista dei medici
    {
      "actor": {
        "reference": "Doctor/102", // codice del medico nel sistema inviante
        "identifier": {
          "system": "urn:oid:2.16.840.1.113883.2.9.4.3.2",
          "value": "ABCDEF86H12K897O" // codice fiscale del medico (usato per effettuare matching in GipoNext)
        },
        "display": "Dott. Rossi"
      },
      "role": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/v2/0912",
            "code": "SPRF"
          }
        ],
        "text": "Refertante"
      }
    },
    {
      "role": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/v2/0912",
            "code": "PRF"
          }
        ],
        "text": "Tecnico"
      },
      "actor": {
        "reference": "Doctor/103",
        "identifier": {
          "system": "urn:oid:2.16.840.1.113883.2.9.4.3.2",
          "value": "XYZABC90A01H501Z"
        },
        "display": "Dott. Bianchi"
      }
    }
  ],
  "presentedForm": [
    // elenco referti PDF
    {
      "title": "TAC", // titolo del documento PDF (viene visualizzato in interfaccia utente)
      "contentType": "application/pdf", // supportato soltanto application/pdf
      "data": "AAAA", // file PDF in base64 (da usare solo se non si usa "url")
      "url": "http://test.test.com/test.pdf" // url da impostare per scaricare il referto (da usare solo se non si usa "data")
    }
  ]
}

Note pratiche per integrazione ​

  • Concorda prima i dettagli di autenticazione con il referente tecnico del PACS.
  • Verifica sempre Content-Type: application/fhir+json.
  • Parti con test su Patient e ProcedureRequest, poi abilita il flusso esiti (DiagnosticReport).

Risorse utili ​