Generata il 6 ottobre 2026

Guida all'integrazione — Medibridge API

Versione 1.0 — ottobre 2026

Medibridge collega il software gestionale al Fascicolo Sanitario Elettronico (FSE 2.0). Il gestionale invia i dati del referto e il PDF; Medibridge genera il documento clinico (CDA), lo inserisce nel PDF, lo firma dove previsto e lo pubblica verso la regione della struttura, nel protocollo di ciascuna regione. Un'unica integrazione vale per tutte le regioni attive, con le stesse chiamate e gli stessi identificativi.

Questa guida descrive l'integrazione dall'attivazione alla prima pubblicazione in produzione. Le particolarità di ogni regione sono nelle pagine per regione. Il dettaglio di ogni campo è nello Swagger di ciascun ambiente (/docs).

Indice

0. In 10 minuti
1. Ambienti
2. Il percorso di attivazione
3. Autenticazione
4. Strutture
5. Pubblicare un referto
6. Dopo la pubblicazione: stato, sostituzione, oscuramento, cancellazione
7. I dati del referto
8. Leggere le risposte
9. Errori: significato e azioni
10. Ritentare in sicurezza
11. Supporto
12. Collaudo
13. Privacy e conservazione
14. Pagine per regione
15. Domande frequenti

0. In 10 minuti

1. Richiesta di attivazione a support@medibridge.it, con ragione sociale e P.IVA della software house.

2. Chiave e richiesta di certificato (CSR) per la sandbox: si generano con i comandi del §3.1 e la CSR si invia a Medibridge, che restituisce il certificato di sandbox.

3. Prima chiamata: con un token firmato (§3.2) si crea una struttura di prova:

   curl -X POST https://staging.medibridge.it/api/customers/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"organization_name": "Poliambulatorio di prova", "piva": "01234567890", "region": "100"}'
   

   Una risposta 201 con il customer_id conferma che chiave, certificato e token sono corretti.

4. Dati regionali: Medibridge completa i dati regionali della struttura (§4.2). Da quel momento è possibile pubblicare il primo referto di prova (§5).

1. Ambienti

I due ambienti sono indipendenti: il certificato di sandbox vale solo in sandbox e quello di produzione solo in produzione, e le strutture create in un ambiente non esistono nell'altro. La sandbox è a disposizione per ogni prova: nessun referto raggiunge il fascicolo di un paziente.

Lo Swagger di ciascun ambiente (/docs) riporta ogni endpoint con campi, tipi e un esempio completo: è il riferimento campo per campo a cui questa guida rimanda.

2. Il percorso di attivazione

Per tutto il percorso è disponibile un referente tecnico Medibridge. Per qualsiasi dubbio, anche in sviluppo, si scrive a support@medibridge.it indicando l'X-Request-ID della chiamata (§11).

3. Autenticazione

Ogni chiamata porta un token JWT firmato dal gestionale con la chiave privata del proprio certificato. Non esistono login né password: il certificato identifica il software, e la chiave privata resta sempre sui sistemi dell'integratore.

3.1 Chiave e certificato

Si genera una coppia di chiavi e una CSR, una per ambiente:

# Sandbox
openssl req -new -newkey rsa:2048 -nodes \
  -keyout medibridge-sandbox.key -out medibridge-sandbox.csr \
  -subj "/C=IT/O=Software House S.r.l./CN=01234567890"

• O è la ragione sociale, CN la P.IVA della software house;
• a Medibridge si invia solo il file .csr; il file .key resta custodito dall'integratore;
• Medibridge restituisce il certificato (.crt, formato PEM), valido 825 giorni.

Per la produzione si ripete lo stesso comando con nomi di file diversi (medibridge-produzione.key / .csr): una chiave distinta per ciascun ambiente.

Il rinnovo prima della scadenza si concorda con Medibridge: è sufficiente una nuova CSR, anche con la stessa chiave.

3.2 Il token di ogni chiamata

Il token viaggia nell'header:

Authorization: Bearer <token>

vendor e version identificano il software che pubblica verso il FSE: vanno scelti con cura, e version si aggiorna a ogni nuovo rilascio del gestionale.

Un token si può riusare per più chiamate fino alla scadenza; la soluzione più semplice è generarne uno nuovo per ogni chiamata, operazione che richiede pochi millisecondi.

Python (pip install pyjwt cryptography):

import base64
import time

import jwt
from cryptography import x509
from cryptography.hazmat.primitives.serialization import Encoding

with open("medibridge-sandbox.crt", "rb") as f:
    certificate = x509.load_pem_x509_certificate(f.read())
with open("medibridge-sandbox.key", "rb") as f:
    private_key = f.read()

x5c = base64.b64encode(certificate.public_bytes(Encoding.DER)).decode()


def medibridge_token() -> str:
    now = int(time.time())
    return jwt.encode(
        {"sub": "01234567890", "vendor": "GestionaleClinico", "version": "4.2",
         "iat": now, "exp": now + 300},
        private_key,
        algorithm="RS256",
        headers={"x5c": [x5c]},
    )

Node.js (npm install jsonwebtoken, Node 16 o successivo):

const fs = require("fs");
const crypto = require("crypto");
const jwt = require("jsonwebtoken");

const certificate = new crypto.X509Certificate(fs.readFileSync("medibridge-sandbox.crt"));
const x5c = certificate.raw.toString("base64");
const privateKey = fs.readFileSync("medibridge-sandbox.key");

function medibridgeToken() {
  return jwt.sign(
    { sub: "01234567890", vendor: "GestionaleClinico", version: "4.2" },
    privateKey,
    { algorithm: "RS256", expiresIn: "5m", header: { x5c: [x5c] } },
  );
}

3.3 Esiti dell'autenticazione

4. Strutture

Una struttura è un ambulatorio, poliambulatorio o studio per cui il gestionale pubblica referti, identificata dalla sua P.IVA. Ogni referto indica la struttura nel campo piva, e Medibridge ricava dalla struttura registrata tutti i dati regionali: non vanno ripetuti a ogni chiamata.

4.1 Gestione delle strutture

Per creare una struttura bastano tre campi:

{ "organization_name": "Poliambulatorio Rossi", "piva": "01234567890", "region": "100" }

region è il codice della regione in cui opera la struttura (codici nelle pagine per regione).

In blocco:

{
  "customers": [
    { "organization_name": "Poliambulatorio Rossi", "piva": "01234567890", "region": "100" },
    { "organization_name": "Studio Bianchi", "piva": "09876543210", "region": "050" }
  ]
}

Il customer_id restituito serve per modificare o eliminare la struttura.

4.2 I dati regionali della struttura

Per pubblicare, ogni regione richiede i propri identificativi della struttura (codice nel sistema sanitario, azienda sanitaria di riferimento, specialità, ...). La raccolta e l'inserimento di questi dati sono a cura di Medibridge: dopo la creazione della struttura, Medibridge richiede i dati elencati nella pagina della regione, completa la configurazione e comunica quando la struttura è pronta a pubblicare.

5. Pubblicare un referto

Le modalità di pubblicazione sono due, a seconda di chi firma il documento.

5.1 Firma delegata — una sola chiamata

Il documento viene firmato digitalmente da Medibridge per conto della struttura. Un'unica chiamata genera il documento clinico, lo valida, lo firma e lo pubblica:

POST /api/documents/generate/validate-publish-delegated

{
  "pdf": "<PDF del referto, base64>",
  "piva": "01234567890",
  "patient_data": { "...": "..." },
  "document_data": { "...": "..." },
  "author_data": { "...": "..." }
}

Gestionale ──POST /generate/validate-publish-delegated──▶ Medibridge
                                                          ├─ genera il CDA e lo inserisce nel PDF
                                                          ├─ valida presso la regione
                                                          ├─ firma il PDF
                                                          └─ pubblica
Gestionale ◀──────── esito + identificativoDoc + workflowInstanceId

5.2 Firma del medico — due chiamate

Il medico firma il referto con la propria firma qualificata (PAdES). Il FSE richiede che la firma copra anche il documento clinico inserito nel PDF: per questo la firma avviene dopo la validazione, sul PDF restituito da Medibridge.

Passo A — validazione

POST /api/documents/generate/validate

Stesso corpo della firma delegata, con il PDF non firmato. In caso di validazione riuscita la risposta contiene:

{
  "status": 201,
  "data": { "workflowInstanceId": "...", "...": "..." },
  "document_pdf": "<PDF con il CDA incorporato, base64 — da far firmare al medico>"
}

Il medico firma esattamente document_pdf, senza rigenerarlo: la pubblicazione verifica che il documento firmato sia quello validato.

Passo B — pubblicazione del PDF firmato

POST /api/documents/generate/publish-signed

{
  "pdf": "<PDF firmato dal medico, base64>",
  "piva": "01234567890",
  "patient_data": { "...": "..." },
  "document_data": { "...": "...", "workflowInstanceId": "<dal passo A>" }
}

Gestionale ──POST /generate/validate──▶ Medibridge ──▶ validazione regionale
Gestionale ◀── document_pdf + workflowInstanceId
Medico        firma document_pdf (PAdES)
Gestionale ──POST /generate/publish-signed──▶ Medibridge ──▶ pubblicazione
Gestionale ◀── esito + identificativoDoc

Nota: il passo B è indipendente dal passo A. Le due chiamate non condividono stato: publish-signed riceve nel corpo tutto ciò che gli serve e può seguire anche una validazione eseguita fuori da Medibridge, ad esempio da un gestionale che genera e valida il documento clinico per conto proprio. In questo caso:

• il workflowInstanceId deve essere quello restituito dal Gateway FSE per la validazione di questo stesso documento, nello stesso ambiente (sandbox o produzione). Una validazione solo locale (XSD, schematron) non produce un workflowInstanceId e non basta;
• il PDF deve contenere già il documento clinico, e la firma PAdES deve coprirlo: Medibridge non genera né modifica nulla, pubblica il file così com'è;
• l'elemento <id> del documento clinico deve coincidere con l'identificativoDoc che Medibridge ricava da document_data (sez. 5.4), altrimenti la regione rifiuta il documento. L'anteprima (sez. 5.3) mostra il valore atteso;
• patient_data e document_data vanno inviati comunque completi: da essi si compongono i metadati di pubblicazione;

5.3 Anteprima del documento

POST /api/documents/generate/pdf

Restituisce il PDF con il documento clinico incorporato, senza inviarlo alla regione: in sviluppo consente di controllare i dati, e il documento è identico a quello che verrebbe pubblicato.

5.4 La risposta di una pubblicazione

{
  "status": 202,
  "data": { "...": "risposta della regione, così come inviata" },
  "identificativoDoc": "<radice OID della regione>^<identificativo del referto>",
  "workflowInstanceId": "<identificativo dell'operazione>"
}

6. Dopo la pubblicazione

Ogni operazione successiva identifica il referto con il suo identificativoDoc, nello stesso modo in tutte le regioni: le differenze di protocollo fra regioni sono gestite da Medibridge. Le operazioni attive in ciascuna regione sono indicate nella pagina regionale.

L'identificativoDoc contiene ^ e va inserito nel path codificato (percent-encoding), ad esempio con urllib.parse.quote(identificativo, safe="") in Python o encodeURIComponent in JavaScript.

6.1 Verificare l'esito

In alcune regioni la pubblicazione è asincrona: la risposta 202 conferma la presa in carico, e l'indicizzazione nel fascicolo segue dopo pochi secondi. Lo stato si legge con:

GET /api/documents/status/{workflowInstanceId}?piva=01234567890

{
  "status": 200,
  "data": { "...": "eventi restituiti dalla regione" },
  "verdict": "SUCCESS",
  "checked_event": "SEND_TO_INI",
  "event_status": "SUCCESS"
}

Anche il workflowInstanceId va codificato nel path. È disponibile anche la ricerca per traceId: GET /api/documents/status/search/{traceId}?piva=....

6.2 Sostituire un referto

PUT /api/documents/generate/update/{identificativoDoc}

Stesso corpo della firma delegata (§5.1), con il PDF e i dati della nuova versione. La risposta ha la forma di una pubblicazione e contiene l'identificativoDoc della nuova versione, da conservare al posto del precedente.

Con "documentoAnnullativo": true nel corpo, la nuova versione annulla la precedente invece di correggerla.

6.3 Oscurare un referto pubblicato

PUT /api/documents/{identificativoDoc}/metadata

{
  "piva": "01234567890",
  "patient_data": { "...": "..." },
  "document_type": "RSA",
  "document_data": { "...": "dati del referto, come inviati alla pubblicazione" },
  "confidentiality": "V"
}

confidentiality: "V" oscura il referto, "N" lo rende di nuovo visibile. document_data è lo stesso inviato alla pubblicazione: i metadati richiesti dalla regione vengono composti da Medibridge a partire da questi dati e dalla struttura registrata.

6.4 Cancellare un referto

DELETE /api/documents/{identificativoDoc}

{
  "piva": "01234567890",
  "patient_data": { "...": "..." },
  "document_type": "RSA",
  "workflowInstanceIdUpdate": "<workflowInstanceId della pubblicazione>"
}

La cancellazione ha un corpo JSON, come le altre chiamate, e rimuove il referto dal fascicolo. Nelle regioni asincrone la risposta riporta il workflowInstanceId della cancellazione, con cui verificarne l'esito (§6.1).

Nota: nelle Marche la cancellazione funziona diversamente. La Regione Marche non ammette la cancellazione con i soli dati qui sopra: per annullare un referto si invia un documento annullativo, cioè la copia del referto con la dicitura «Annullato», firmata dal medico. La chiamata resta DELETE /api/documents/{identificativoDoc}, ma riceve anche il PDF annullativo firmato: il gestionale deve quindi prevedere una firma del medico anche per annullare. I dettagli sono nella pagina Marche.

7. I dati del referto

Il corpo delle chiamate è JSON; i PDF viaggiano come stringa base64 all'interno del JSON.

7.1 Tipi di referto

Ogni pagina regionale indica i tipi attivi nella regione.

7.2 Campi principali

• documentNumber: il numero del referto nel gestionale. Deve essere unico per struttura: diventa parte dell'identificativoDoc.
• submissionId: un progressivo numerico diverso a ogni invio (pubblicazione o sostituzione), ad esempio un contatore o un timestamp in millisecondi. Alcune regioni rifiutano come duplicato un invio con un submissionId già usato.
• confidentiality: N (normale) o V (oscurato: visibile solo al paziente e a chi ha il suo consenso esplicito).
• consent (in patient_data): consenso del paziente all'alimentazione del fascicolo.
• action: CREATE per pubblicazione e validazione, UPDATE per la sostituzione.
• workflowInstanceId: solo nel passo B della firma del medico (§5.2).

Lo Swagger di ciascun ambiente riporta ogni campo con tipo, valori ammessi e un esempio completo per ogni tipo di referto.

8. Leggere le risposte

Ogni risposta ha due livelli:

1. lo status HTTP, che segue l'esito dell'operazione: 2xx indica un'operazione riuscita, 4xx/5xx un'operazione non riuscita;
2. il corpo, con status e data restituiti dalla regione così come inviati.

Lo status HTTP è quindi sufficiente per sapere se un'operazione è riuscita; il corpo ne spiega il motivo. Le letture dello stato (§6.1) rispondono sempre 200: l'esito dell'operazione verificata è in verdict.

Ogni risposta, anche di errore, porta l'header X-Request-ID (§11).

9. Errori

400 — formato dei dati. Un elenco leggibile delle correzioni necessarie:

{ "validation_errors": ["body -> document_data -> confidentiality: Input should be 'N' or 'V'"] }

410 / 420 — documento clinico. Lo stadio di validazione e le regole non rispettate:

{ "detail": { "stage": "Schematron", "message": "...", "failures": ["..."] } }

402 — account. Il campo reason indica la causa:

Il 402 riguarda solo le nuove pubblicazioni: cancellazioni e letture dello stato restano sempre disponibili.

10. Ritentare in sicurezza

• Timeout: almeno 120 secondi. Una pubblicazione comprende generazione del documento, firma e due chiamate alla regione.
• Errori 4xx: la stessa richiesta darebbe lo stesso risultato; si correggono i dati e si invia una nuova richiesta.
• Errori 5xx o timeout su una pubblicazione: prima di ripubblicare si verifica lo stato (§6.1). Un secondo invio con lo stesso documentNumber viene rifiutato dalla regione come duplicato.
• Disservizi regionali: nuovi tentativi con attese crescenti (1, 5, 15 minuti). Per i disservizi prolungati Medibridge invia una comunicazione.

11. Supporto

Ogni risposta porta l'header X-Request-ID, un codice univoco della chiamata: con questo codice il supporto ritrova in pochi secondi la chiamata, il suo esito e la risposta della regione.

Ogni segnalazione relativa a una chiamata riporta:

• l'X-Request-ID;
• l'ambiente (sandbox o produzione) e l'ora approssimativa.

I dati del paziente e il PDF non sono necessari: l'X-Request-ID è sufficiente.

Contatti: support@medibridge.it.

12. Collaudo

Prima del passaggio in produzione si eseguono in sandbox i casi seguenti, per ogni tipo di referto previsto, e si inviano a Medibridge gli X-Request-ID di ciascuno. Medibridge li verifica e conferma il passaggio in produzione.

Le pagine regionali indicano gli eventuali casi aggiuntivi richiesti da ciascuna regione.

13. Privacy e conservazione

• I dati del paziente e i PDF vengono elaborati nella sola chiamata e restituiti al gestionale: Medibridge non li conserva.
• Del traffico si conserva un registro tecnico a fini di supporto (ora, endpoint, esito, durata, messaggio d'errore con i codici fiscali mascherati), cancellato dopo 90 giorni.
• La conservazione dei referti e dei loro identificativi (identificativoDoc, workflowInstanceId) è a cura del gestionale, sistema di riferimento della struttura.

14. Pagine per regione

Per le altre regioni, i tempi di attivazione si concordano con Medibridge.

15. Domande frequenti

Una struttura appena creata può pubblicare? Dopo il completamento dei dati regionali (§4.2), che Medibridge comunica.

Come si verifica che un referto sia nel fascicolo? Uno status HTTP 2xx indica che la regione ha accettato il referto. Nelle regioni asincrone la conferma finale è verdict: SUCCESS nel recupero stato (§6.1).

Il modo di chiamare le API cambia da regione a regione? No: endpoint, corpi delle richieste e identificativi sono gli stessi in tutte le regioni. Cambiano solo i dati regionali della struttura, gestiti da Medibridge, e le operazioni attive, indicate nelle pagine regionali.

Che differenza c'è tra /generate/public e /generate/validate-publish-delegated? Nessuna: sono lo stesso flusso di firma delegata. Si raccomanda /generate/validate-publish-delegated.

Il certificato di sandbox vale anche in produzione? No: i certificati sono due, uno per ambiente (§1).

I dati della struttura vanno inviati a ogni chiamata? No: basta la piva. Gli altri dati vengono ricavati dalla struttura registrata.

Storico delle versioni