Aller au contenu
FibonacciEsthétiqueConnexionEssai gratuit

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

AutorisationCe que vous pouvez faireCe que vous ne voyez pas
agenda-letturalire et chercher Schedule, Slot, Location ; lire un Appointment par codenom, téléphone et e-mail du patient, traitement, motif, notes du rendez-vous
agenda-scritturacréer un Appointment et en changer l’horaire ou l’état, seulement dans les états booked, pending, cancelledcomme ci-dessus ; pas de suppression, pas de recherche
richiestecréer un Appointment à l’état pending : le cabinet le trouve parmi les demandes et décideon ne le relit pas, on ne le modifie pas
recapitilire un Patient par codetout sauf nom, téléphone et e-mail (ni date de naissance, ni code fiscal, ni adresse)
fatture-letturalire et chercher Invoiceles 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>
    

    state est 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 de state, 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ètreCe que c’est
client_idle code de votre application dans ce cabinet : chaque cabinet a le sien
issla base FHIR du cabinet, par exemple https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4
token_urloù demander le jeton : https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token
statevotre 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 :

ChampValeur
issle client_id du cabinet
suble client_id du cabinet
audle token_url du cabinet, exactement tel qu’il vous est parvenu
iatmaintenant, en secondes Unix
expau plus 5 minutes après iat
jtiune 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 :

QuoiComment
lire par codeGET <Type>/<id> pour Schedule, Slot, Location, Appointment, Patient, Invoice
chercherGET Schedule?, Slot?, Location?, Invoice? avec les paramètres du tableau ci-dessous
créer un rendez-vousPOST Appointment
modifier un rendez-vousPUT Appointment/<id> (envoyez la ressource que vous avez lue, avec les champs modifiés)
capacités du serveurGET metadata
TypeParamètres de recherche admis
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 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éponseCe que cela signifie
400 du jeton, invalid_requestle 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_typeil faut client_credentials avec client_assertion ; un client_secret ne suffit pas
401jeton expiré : demandez-en un nouveau
400 avec Authentication errorle 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-ammessol’appel ne fait pas partie de ceux du point 3.4
403 sans codel’appel est permis mais l’autorisation ne l’est pas : le cabinet ne l’a pas accordée
405 avec metodo-non-ammessoverbe HTTP non prévu pour ce type
503 avec registro-non-disponibilenous 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).