Per chi sviluppa: collegare la propria app
8 minuti di letturaAggiornato il 15 novembre 2026
Questa guida è per le aziende che vogliono collegare un loro programma (un centralino, una prenotazione online, un'app di contabilità o di promemoria) agli studi che usano Fibonacci. Lo studio vede la vostra app in Impostazioni, Collegamenti, preme Collega, legge che cosa potrà fare e conferma. Da lì la vostra app ottiene un token e chiama le API dello studio, solo per quello che lo studio ha concesso. Lo studio la può scollegare quando vuole, e da quel momento i vostri token smettono di funzionare.
Usiamo gli standard, senza protocolli nostri: OAuth 2.0 con il profilo SMART Backend Services (un JWT firmato con la vostra chiave privata, RFC 7523) e le API FHIR R4. Nessun segreto condiviso passa fra noi e voi.
1. Registrare l'app
Per ora le app le registriamo e le approviamo noi, una per una. Scriveteci dalla pagina Partner o a info@fibonaccimedica.it con:
- nome dell'app e ragione sociale dell'azienda, come li vedrà lo studio;
- sito e contatto per l'assistenza (un'email, e se c'è una pagina): lo studio li legge nella schermata di consenso;
- una descrizione in due righe di che cosa fa l'app per lo studio, in italiano (e nelle altre lingue, se le avete);
- uno o più indirizzi di ritorno
https: dove torna il browser dopo il consenso; - l'indirizzo
httpspubblico delle vostre chiavi pubbliche (JWKS, RFC 7517); - i permessi che vi servono, fra quelli del punto 2, e perché.
Quando l'app è approvata, la mettiamo prima in uno studio di prova con dati finti (punto 6), e solo dopo la vedono gli studi.
Gli indirizzi di ritorno si confrontano carattere per carattere: niente prefissi, niente parametri in più. Un indirizzo diverso da quelli registrati fa fallire il collegamento.
2. I permessi
Sono cinque e chiusi. Lo studio li vede scritti in parole semplici prima di confermare. Nessun dato clinico esce: anamnesi, visite, trattamenti, foto, consensi, referti restano dentro.
| Permesso | Che cosa potete fare | Che cosa non vedete |
|---|---|---|
agenda-lettura | leggere e cercare Schedule, Slot, Location; leggere un Appointment per codice | nome, telefono ed email del paziente, trattamento, motivo, note dell'appuntamento |
agenda-scrittura | creare un Appointment e cambiarne orario o stato, solo negli stati booked, pending, cancelled | come sopra; non si cancella, non si cerca |
richieste | creare un Appointment in stato pending: lo studio lo trova fra le richieste e decide | non si rilegge, non si modifica |
recapiti | leggere un Patient per codice | tutto tranne nome, telefono ed email (niente data di nascita, codice fiscale, indirizzo) |
fatture-lettura | leggere e cercare Invoice | le righe della fattura (dicono il trattamento), le note, le estensioni (codice fiscale, pagamento), il medico |
I campi nascosti non compaiono nelle risposte. Quando modificate un appuntamento, Medplum rimette i campi nascosti com'erano: non li cancellate mandando la risorsa senza.
3. Il collegamento, passo per passo
3.1 Lo studio vi collega
Il giro può partire da due posti.
-
Dal vostro sito. Mandate chi amministra lo studio a:
https://app.fibonaccimedica.it/impostazioni/collegamenti/app/<vostra-app>?redirect_uri=<indirizzo-di-ritorno>&state=<valore-casuale>stateè un valore casuale vostro, di al massimo 200 caratteri fra lettere, cifre e-._~: vi torna uguale e serve a riconoscere la richiesta (contro la falsificazione di richieste fra siti). -
Da Fibonacci. Lo studio preme
Collegaaccanto alla vostra app. In questo caso non c'èstate, e il ritorno è il primo indirizzo registrato.
Se chi apre il collegamento non è entrato, Fibonacci gli chiede di entrare e poi lo riporta alla schermata di consenso. Solo chi amministra lo studio può confermare.
3.2 Il ritorno
Confermato il consenso, il browser torna al vostro indirizzo di ritorno con quattro parametri:
| Parametro | Che cos'è |
|---|---|
client_id | il codice della vostra app in quello studio: ogni studio ha il suo |
iss | la base FHIR dello studio, per esempio https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4 |
token_url | dove chiedere il token: https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token |
state | il vostro valore, se l'avevate mandato |
Controllate state, poi salvate client_id, iss e token_url accanto all'account dello studio sul vostro sistema. Nessuno di questi tre è un segreto: senza la vostra chiave privata non servono a nessuno.
3.3 Il token
Firmate un JWT con la vostra chiave privata (algoritmi ES256, ES384, ES512, RS256, RS384, RS512; consigliato ES256 o ES384), con kid nell'intestazione uguale a una chiave del vostro JWKS:
| Campo | Valore |
|---|---|
iss | il client_id dello studio |
sub | il client_id dello studio |
aud | il token_url dello studio, esattamente come vi è arrivato |
iat | adesso, in secondi Unix |
exp | al massimo 5 minuti dopo iat |
jti | un valore unico per ogni JWT |
Poi:
curl -X POST "$TOKEN_URL" \
-d grant_type=client_credentials \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
-d client_assertion="$JWT"
La risposta è un token Bearer che dura un'ora. Non c'è un token di rinnovo: quando scade se ne chiede un altro con un JWT nuovo. Un segreto condiviso (client_secret) non è accettato.
Un esempio in Python, con la libreria PyJWT:
import time, uuid, jwt, httpx
def token(client_id: str, token_url: str, chiave_privata_pem: str, kid: str) -> str:
ora = int(time.time())
assertion = jwt.encode(
{"iss": client_id, "sub": client_id, "aud": token_url, "iat": ora, "exp": ora + 240, "jti": uuid.uuid4().hex},
chiave_privata_pem, algorithm="ES256", headers={"kid": kid},
)
r = httpx.post(token_url, data={
"grant_type": "client_credentials",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": assertion,
})
r.raise_for_status()
return r.json()["access_token"]
3.4 Le chiamate
Con il token, chiamate la base iss dello studio:
curl -H "Authorization: Bearer $TOKEN" "$ISS/Slot?schedule=Schedule/<id>&start=ge2026-12-01"
curl -H "Authorization: Bearer $TOKEN" "$ISS/Appointment/<id>"
Il token vale solo sugli indirizzi di quello studio (.../projects/<studio>/...). Le chiamate permesse sono queste:
| Che cosa | Come |
|---|---|
| leggere per codice | GET <Tipo>/<id> per Schedule, Slot, Location, Appointment, Patient, Invoice |
| cercare | GET Schedule?, Slot?, Location?, Invoice? con i parametri della tabella sotto |
| creare un appuntamento | POST Appointment |
| modificare un appuntamento | PUT Appointment/<id> (mandate la risorsa che avete letto, con i campi cambiati) |
| capacità del server | GET metadata |
| Tipo | Parametri di ricerca ammessi |
|---|---|
Schedule | actor, active, date, _id, _count, _offset, _sort, _lastUpdated |
Slot | schedule, start, status, _id, _count, _offset, _sort, _lastUpdated |
Location | status, _id, _count, _offset |
Invoice | date, status, identifier, type, _id, _count, _offset, _sort, _lastUpdated |
_count va da 1 a 100. Ricerche concatenate (patient.name=), modificatori (:missing, :text), _include, _revinclude, _has, operazioni $, _history e richieste batch non sono ammesse: rispondono 403. Su Appointment e Patient la ricerca non c'è di proposito: anche senza mostrare un campo, una ricerca su quel campo direbbe se c'è o no.
Per sapere quali appuntamenti esistono senza cercarli, usate le notifiche (punto 4).
4. Le notifiche
Quando un appuntamento nasce, cambia orario o stato, o viene annullato, Fibonacci può mandare un messaggio firmato a un vostro indirizzo https, con il tipo di evento (appuntamento.creato, appuntamento.modificato, appuntamento.annullato), i codici e le date. Il messaggio non contiene il nome del paziente. La firma sta nell'intestazione X-Fibonacci-Firma (HMAC-SHA256 dell'ora e del corpo esatto).
Oggi l'indirizzo lo aggiunge lo studio, da Impostazioni, Persone e permessi, Accessi per programmi esterni, Notifiche, e il segreto della firma lo vede una volta sola. Il formato e la verifica della firma sono nella guida tecnica degli accessi esterni, che vi mandiamo con la registrazione. Che le notifiche si attivino da sole con il collegamento dell'app è il passo successivo, non ancora fatto.
5. Gli errori
| Risposta | Che cosa vuol dire |
|---|---|
400 dal token, invalid_request | il JWT non va: aud diverso da token_url, exp scaduto o troppo lontano, firma che non corrisponde al vostro JWKS, oppure l'app non è più collegata |
400 dal token, unsupported_grant_type | serve client_credentials con client_assertion; un client_secret non basta |
401 | token scaduto: chiedetene uno nuovo |
400 con Authentication error | lo studio ha scollegato l'app: il token non vale più, e non se ne ottengono altri (Client not found dal token) |
403 con percorso-non-ammesso, tipo-non-ammesso, parametro-non-ammesso | la chiamata non è fra quelle del punto 3.4 |
403 senza codice | la chiamata è ammessa ma il permesso no: lo studio non l'ha concesso |
405 con metodo-non-ammesso | verbo HTTP non previsto per quel tipo |
503 con registro-non-disponibile | non abbiamo potuto scrivere l'accesso nel registro, e senza registro i dati non escono: riprovate fra poco |
Gli errori FHIR arrivano come OperationOutcome, con il codice in issue[0].details.text.
6. Lo studio di prova
Prima di uno studio vero, la vostra app si collega a uno studio di prova con dati finti: lo prepariamo noi quando registriamo l'app, e lì fate tutto il giro (consenso, ritorno, token, chiamate, scollegamento). Nessun paziente vero, nessun dato vero.
7. Che cosa resta registrato
Ogni token che la vostra app ottiene e ogni chiamata che fa finiscono nel registro accessi dello studio, a nome della vostra app: che cosa, quando, con che esito, e per quale paziente quando c'è. Lo studio lo legge dal suo registro. Anche il collegamento e lo scollegamento sono registrati, con il nome di chi li ha fatti.
8. Privacy e contratto
Lo studio è il titolare dei dati dei suoi pazienti; la vostra app li tratta per suo conto. Prima che uno studio vero vi colleghi serve un accordo fra voi e lo studio sul trattamento dei dati (art. 28 del GDPR): la schermata di consenso lo ricorda allo studio. Chiedete e conservate solo i dati che vi servono.
9. Assistenza
Per la registrazione, lo studio di prova e qualsiasi dubbio tecnico: info@fibonaccimedica.it. Indicate il nome dell'app e, se l'errore riguarda uno studio, il client_id (mai la chiave privata né un token).