Salta al contenuto
FibonacciEsteticaAccediProva gratis

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 https pubblico 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.

PermessoChe cosa potete fareChe cosa non vedete
agenda-letturaleggere e cercare Schedule, Slot, Location; leggere un Appointment per codicenome, telefono ed email del paziente, trattamento, motivo, note dell'appuntamento
agenda-scritturacreare un Appointment e cambiarne orario o stato, solo negli stati booked, pending, cancelledcome sopra; non si cancella, non si cerca
richiestecreare un Appointment in stato pending: lo studio lo trova fra le richieste e decidenon si rilegge, non si modifica
recapitileggere un Patient per codicetutto tranne nome, telefono ed email (niente data di nascita, codice fiscale, indirizzo)
fatture-letturaleggere e cercare Invoicele 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 Collega accanto 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:

ParametroChe cos'è
client_idil codice della vostra app in quello studio: ogni studio ha il suo
issla base FHIR dello studio, per esempio https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4
token_urldove chiedere il token: https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token
stateil 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:

CampoValore
issil client_id dello studio
subil client_id dello studio
audil token_url dello studio, esattamente come vi è arrivato
iatadesso, in secondi Unix
expal massimo 5 minuti dopo iat
jtiun 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 cosaCome
leggere per codiceGET <Tipo>/<id> per Schedule, Slot, Location, Appointment, Patient, Invoice
cercareGET Schedule?, Slot?, Location?, Invoice? con i parametri della tabella sotto
creare un appuntamentoPOST Appointment
modificare un appuntamentoPUT Appointment/<id> (mandate la risorsa che avete letto, con i campi cambiati)
capacità del serverGET metadata
TipoParametri di ricerca ammessi
Scheduleactor, active, date, _id, _count, _offset, _sort, _lastUpdated
Slotschedule, start, status, _id, _count, _offset, _sort, _lastUpdated
Locationstatus, _id, _count, _offset
Invoicedate, 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

RispostaChe cosa vuol dire
400 dal token, invalid_requestil 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_typeserve client_credentials con client_assertion; un client_secret non basta
401token scaduto: chiedetene uno nuovo
400 con Authentication errorlo 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-ammessola chiamata non è fra quelle del punto 3.4
403 senza codicela chiamata è ammessa ma il permesso no: lo studio non l'ha concesso
405 con metodo-non-ammessoverbo HTTP non previsto per quel tipo
503 con registro-non-disponibilenon 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).