Pour les développeurs : connecter votre application à Fibonacci
9 minutes de lectureMis à jour le 15 novembre 2026
Ce guide s’adresse aux entreprises qui veulent connecter l’un de leurs programmes (un standard téléphonique, une prise de rendez-vous en ligne, une application de comptabilité ou de rappels) aux cabinets qui utilisent Fibonacci. Le cabinet voit votre application dans Réglages, Connexions, appuie sur Connecter, lit ce qu’elle pourra faire et confirme. À partir de là, votre application obtient un jeton et appelle les API du cabinet, uniquement pour ce que le cabinet a accordé. Le cabinet peut la déconnecter quand il veut, et dès cet instant vos jetons cessent de fonctionner.
Nous utilisons les standards, sans protocole maison : OAuth 2.0 avec le profil SMART Backend Services (un JWT signé avec votre clé privée, RFC 7523) et les API FHIR R4. Aucun secret partagé ne circule entre nous et vous.
1. Enregistrer l’application
Pour l’instant, nous enregistrons et approuvons les applications nous-mêmes, une par une. Écrivez-nous depuis la page Partner ou à info@fibonaccimedica.it avec :
- le nom de l’application et la raison sociale de l’entreprise, tels que le cabinet les verra ;
- le site et un contact d’assistance (un e-mail, et une page s’il y en a une) : le cabinet les lit sur l’écran de consentement ;
- une description en deux lignes de ce que l’application fait pour le cabinet, en italien (et dans les autres langues, si vous en avez) ;
- une ou plusieurs adresses de retour
https: là où le navigateur revient après le consentement ; - l’adresse
httpspublique de vos clés publiques (JWKS, RFC 7517) ; - les autorisations dont vous avez besoin, parmi celles du point 2, et pourquoi.
Quand l’application est approuvée, nous la mettons d’abord dans un cabinet de test avec des données fictives (point 6), et ce n’est qu’ensuite que les cabinets la voient.
Les adresses de retour se comparent caractère par caractère : pas de préfixes, pas de paramètres en plus. Une adresse différente de celles enregistrées fait échouer la connexion.
2. Les autorisations
Il y en a cinq, et la liste est fermée. Le cabinet les voit écrites en mots simples avant de confirmer. Aucune donnée clinique ne sort : anamnèse, consultations, traitements, photos, consentements et comptes rendus restent à l’intérieur.
| Autorisation | Ce que vous pouvez faire | Ce que vous ne voyez pas |
|---|---|---|
agenda-lettura | lire et chercher Schedule, Slot, Location ; lire un Appointment par code | nom, téléphone et e-mail du patient, traitement, motif, notes du rendez-vous |
agenda-scrittura | créer un Appointment et en changer l’horaire ou l’état, seulement dans les états booked, pending, cancelled | comme ci-dessus ; pas de suppression, pas de recherche |
richieste | créer un Appointment à l’état pending : le cabinet le trouve parmi les demandes et décide | on ne le relit pas, on ne le modifie pas |
recapiti | lire un Patient par code | tout sauf nom, téléphone et e-mail (ni date de naissance, ni code fiscal, ni adresse) |
fatture-lettura | lire et chercher Invoice | les lignes de la facture (elles disent le traitement), les notes, les extensions (code fiscal, paiement), le médecin |
Les champs masqués n’apparaissent pas dans les réponses. Quand vous modifiez un rendez-vous, Medplum remet les champs masqués comme ils étaient : ne les effacez pas en envoyant la ressource sans eux.
3. La connexion, pas à pas
3.1 Le cabinet vous connecte
Le parcours peut partir de deux endroits.
-
Depuis votre site. Envoyez la personne qui administre le cabinet vers :
https://app.fibonaccimedica.it/impostazioni/collegamenti/app/<vostra-app>?redirect_uri=<indirizzo-di-ritorno>&state=<valore-casuale>stateest une valeur aléatoire de votre côté, d’au plus 200 caractères parmi lettres, chiffres et-._~: elle revient identique et sert à reconnaître la requête (contre la falsification de requêtes inter-sites). -
Depuis Fibonacci. Le cabinet appuie sur
Connecterà côté de votre application. Dans ce cas il n’y a pas destate, et le retour se fait vers la première adresse enregistrée.
Si la personne qui ouvre le lien n’est pas connectée, Fibonacci lui demande de se connecter puis la ramène à l’écran de consentement. Seule la personne qui administre le cabinet peut confirmer.
3.2 Le retour
Une fois le consentement confirmé, le navigateur revient à votre adresse de retour avec quatre paramètres :
| Paramètre | Ce que c’est |
|---|---|
client_id | le code de votre application dans ce cabinet : chaque cabinet a le sien |
iss | la base FHIR du cabinet, par exemple https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4 |
token_url | où demander le jeton : https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token |
state | votre valeur, si vous en aviez envoyé une |
Vérifiez state, puis enregistrez client_id, iss et token_url à côté du compte du cabinet dans votre système. Aucun des trois n’est un secret : sans votre clé privée, ils ne servent à personne.
3.3 Le jeton
Signez un JWT avec votre clé privée (algorithmes ES256, ES384, ES512, RS256, RS384, RS512 ; ES256 ou ES384 recommandés), avec kid dans l’en-tête égal à une clé de votre JWKS :
| Champ | Valeur |
|---|---|
iss | le client_id du cabinet |
sub | le client_id du cabinet |
aud | le token_url du cabinet, exactement tel qu’il vous est parvenu |
iat | maintenant, en secondes Unix |
exp | au plus 5 minutes après iat |
jti | une valeur unique pour chaque JWT |
Puis :
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 réponse est un jeton Bearer qui dure une heure. Il n’y a pas de jeton de renouvellement : quand il expire, on en demande un autre avec un nouveau JWT. Un secret partagé (client_secret) n’est pas accepté.
Un exemple en Python, avec la bibliothèque 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 Les appels
Avec le jeton, vous appelez la base iss du cabinet :
curl -H "Authorization: Bearer $TOKEN" "$ISS/Slot?schedule=Schedule/<id>&start=ge2026-12-01"
curl -H "Authorization: Bearer $TOKEN" "$ISS/Appointment/<id>"
Le jeton vaut uniquement sur les adresses de ce cabinet (.../projects/<studio>/...). Les appels permis sont ceux-ci :
| Quoi | Comment |
|---|---|
| lire par code | GET <Type>/<id> pour Schedule, Slot, Location, Appointment, Patient, Invoice |
| chercher | GET Schedule?, Slot?, Location?, Invoice? avec les paramètres du tableau ci-dessous |
| créer un rendez-vous | POST Appointment |
| modifier un rendez-vous | PUT Appointment/<id> (envoyez la ressource que vous avez lue, avec les champs modifiés) |
| capacités du serveur | GET metadata |
| Type | Paramètres de recherche admis |
|---|---|
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 de 1 à 100. Les recherches chaînées (patient.name=), les modificateurs (:missing, :text), _include, _revinclude, _has, les opérations $, _history et les requêtes batch ne sont pas admis : ils répondent 403. Sur Appointment et Patient, il n’y a pas de recherche, volontairement : même sans montrer un champ, une recherche sur ce champ dirait s’il y est ou non.
Pour savoir quels rendez-vous existent sans les chercher, utilisez les notifications (point 4).
4. Les notifications
Quand un rendez-vous est créé, change d’horaire ou d’état, ou est annulé, Fibonacci peut envoyer un message signé à une adresse https de votre côté, avec le type d’événement (appuntamento.creato, appuntamento.modificato, appuntamento.annullato), les codes et les dates. Le message ne contient pas le nom du patient. La signature se trouve dans l’en-tête X-Fibonacci-Firma (HMAC-SHA256 de l’heure et du corps exact).
Pour l’instant, l’adresse est ajoutée par le cabinet, depuis Réglages, Personnes et autorisations, Accès pour programmes externes, Notifications, et le secret de signature ne lui est montré qu’une seule fois. Le format et la vérification de la signature figurent dans le guide technique des accès externes, que nous vous envoyons avec l’enregistrement. Que les notifications s’activent d’elles-mêmes avec la connexion de l’application, c’est l’étape suivante, pas encore faite.
5. Les erreurs
| Réponse | Ce que cela signifie |
|---|---|
400 du jeton, invalid_request | le JWT ne va pas : aud différent de token_url, exp expiré ou trop lointain, signature qui ne correspond pas à votre JWKS, ou l’application n’est plus connectée |
400 du jeton, unsupported_grant_type | il faut client_credentials avec client_assertion ; un client_secret ne suffit pas |
401 | jeton expiré : demandez-en un nouveau |
400 avec Authentication error | le cabinet a déconnecté l’application : le jeton ne vaut plus, et on n’en obtient plus d’autres (Client not found au jeton) |
403 avec percorso-non-ammesso, tipo-non-ammesso, parametro-non-ammesso | l’appel ne fait pas partie de ceux du point 3.4 |
403 sans code | l’appel est permis mais l’autorisation ne l’est pas : le cabinet ne l’a pas accordée |
405 avec metodo-non-ammesso | verbe HTTP non prévu pour ce type |
503 avec registro-non-disponibile | nous n’avons pas pu inscrire l’accès au registre, et sans registre les données ne sortent pas : réessayez dans un instant |
Les erreurs FHIR arrivent sous forme d’OperationOutcome, avec le code dans issue[0].details.text.
6. Le cabinet de test
Avant un vrai cabinet, votre application se connecte à un cabinet de test avec des données fictives : nous le préparons quand nous enregistrons l’application, et vous y faites tout le parcours (consentement, retour, jeton, appels, déconnexion). Aucun vrai patient, aucune vraie donnée.
7. Ce qui reste enregistré
Chaque jeton que votre application obtient et chaque appel qu’elle fait sont inscrits dans le journal des accès du cabinet, au nom de votre application : quoi, quand, avec quel résultat, et pour quel patient quand il y en a un. Le cabinet le lit dans son journal. La connexion et la déconnexion sont aussi enregistrées, avec le nom de la personne qui les a faites.
8. Confidentialité et contrat
Le cabinet est responsable des données de ses patients ; votre application les traite pour son compte. Avant qu’un vrai cabinet vous connecte, il faut un accord entre vous et le cabinet sur le traitement des données (art. 28 du RGPD) : l’écran de consentement le rappelle au cabinet. Ne demandez et ne conservez que les données dont vous avez besoin.
9. Assistance
Pour l’enregistrement, le cabinet de test et tout doute technique : info@fibonaccimedica.it. Indiquez le nom de l’application et, si l’erreur concerne un cabinet, le client_id (jamais la clé privée ni un jeton).