English

Italiano

English

Italiano

Appearance

RIS-PACS FHIR integration ​

This page describes how to integrate GipoNext with a RIS-PACS system using the FHIR standard.

The goal is to clarify:

  • which resources to implement;
  • how to handle authentication and authorization;
  • which endpoints to use in the main flows.

Standard and format ​

The reference standard is FHIR Release 3 (STU v3.0.1).

All communication must occur over public HTTPS endpoints.

Authentication and authorization ​

The receiving PACS endpoint can use one of the following options:

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

For receiving reports, GipoNext supports:

  • Bearer token / ApiKey
  • OAuth 2.0 with Bearer token obtained from the OAuth 2.0 flows documented in the GipoNext APIs

Resources involved ​

Resources to implement on RIS-PACS ​

Resource implemented on GipoNext ​

Operational flows ​

Intake flow ​

GipoNext sends to the RIS-PACS:

  1. PUT Patient
  2. POST ProcedureRequest

Outcome reception flow (optional) ​

RIS-PACS sends to GipoNext:

  1. POST DiagnosticReport

Endpoints on GipoNext for receiving ​

The endpoint format is:

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

Where:

  • {userId}: GipoNext client identifier (provided during activation)
  • {resource}: resource name (e.g. DiagnosticReport)
  • {id?}: resource identifier (optional, used for GET, PUT, DELETE)

Limitations ​

  • Once a ProcedureRequest is created, the resource cannot be modified.

Samples ​

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")
    }
  ]
}

Practical integration notes ​

  • Agree with the PACS technical contact on authentication details before starting.
  • Always verify Content-Type: application/fhir+json.
  • Start with tests on Patient and ProcedureRequest, then enable the outcome flow (DiagnosticReport).

Useful resources ​