Für Entwickler: die eigene App mit Fibonacci verbinden
8 Minuten LesezeitAktualisiert am 15. November 2026
Diese Anleitung richtet sich an Unternehmen, die eines ihrer Programme (eine Telefonzentrale, eine Online-Terminbuchung, eine Buchhaltungs- oder Erinnerungs-App) mit den Praxen verbinden wollen, die Fibonacci nutzen. Die Praxis sieht Ihre App unter Einstellungen, Verbindungen, drückt Verbinden, liest, was sie tun kann, und bestätigt. Ab dann erhält Ihre App ein Token und ruft die APIs der Praxis auf, nur für das, was die Praxis erlaubt hat. Die Praxis kann sie jederzeit trennen, und von diesem Moment an funktionieren Ihre Tokens nicht mehr.
Wir verwenden Standards, ohne eigene Protokolle: OAuth 2.0 mit dem Profil SMART Backend Services (ein mit Ihrem privaten Schlüssel signiertes JWT, RFC 7523) und die FHIR-R4-APIs. Zwischen uns und Ihnen läuft kein gemeinsames Geheimnis.
1. Die App registrieren
Vorerst registrieren und genehmigen wir die Apps selbst, eine nach der anderen. Schreiben Sie uns über die Seite Partner oder an info@fibonaccimedica.it mit:
- dem Namen der App und der Firma des Unternehmens, so wie die Praxis sie sehen wird;
- der Website und einem Support-Kontakt (eine E-Mail und, falls vorhanden, eine Seite): Die Praxis liest sie auf dem Zustimmungsbildschirm;
- einer Beschreibung in zwei Zeilen, was die App für die Praxis tut, auf Italienisch (und in den anderen Sprachen, falls vorhanden);
- einer oder mehreren
https-Rückkehradressen: dorthin kehrt der Browser nach der Zustimmung zurück; - der öffentlichen
https-Adresse Ihrer öffentlichen Schlüssel (JWKS, RFC 7517); - den Berechtigungen, die Sie brauchen, aus denen in Punkt 2, und warum.
Ist die App genehmigt, setzen wir sie zuerst in eine Testpraxis mit erfundenen Daten (Punkt 6), und erst danach sehen die Praxen sie.
Rückkehradressen werden Zeichen für Zeichen verglichen: keine Präfixe, keine zusätzlichen Parameter. Eine Adresse, die von den registrierten abweicht, lässt die Verbindung scheitern.
2. Die Berechtigungen
Es sind fünf, und die Liste ist geschlossen. Die Praxis sieht sie vor der Bestätigung in einfachen Worten. Klinische Daten verlassen die Praxis nicht: Anamnese, Besuche, Behandlungen, Fotos, Einwilligungen und Befunde bleiben drinnen.
| Berechtigung | Was Sie tun können | Was Sie nicht sehen |
|---|---|---|
agenda-lettura | Schedule, Slot, Location lesen und suchen; einen Appointment per Kennung lesen | Name, Telefon und E-Mail des Patienten, Behandlung, Grund, Notizen zum Termin |
agenda-scrittura | einen Appointment anlegen und seine Zeit oder seinen Status ändern, nur in den Zuständen booked, pending, cancelled | wie oben; kein Löschen, keine Suche |
richieste | einen Appointment im Zustand pending anlegen: Die Praxis findet ihn unter den Anfragen und entscheidet | er wird nicht wieder gelesen und nicht geändert |
recapiti | einen Patient per Kennung lesen | alles außer Name, Telefon und E-Mail (weder Geburtsdatum noch Steuernummer noch Adresse) |
fatture-lettura | Invoice lesen und suchen | die Rechnungspositionen (sie verraten die Behandlung), die Notizen, die Erweiterungen (Steuernummer, Zahlung), den Arzt |
Verborgene Felder erscheinen nicht in den Antworten. Wenn Sie einen Termin ändern, setzt Medplum die verborgenen Felder so zurück, wie sie waren: Löschen Sie sie nicht, indem Sie die Ressource ohne sie senden.
3. Die Verbindung, Schritt für Schritt
3.1 Die Praxis verbindet Sie
Der Ablauf kann an zwei Stellen beginnen.
-
Von Ihrer Website. Schicken Sie die Person, die die Praxis verwaltet, zu:
https://app.fibonaccimedica.it/impostazioni/collegamenti/app/<vostra-app>?redirect_uri=<indirizzo-di-ritorno>&state=<valore-casuale>stateist ein zufälliger Wert von Ihnen, höchstens 200 Zeichen aus Buchstaben, Ziffern und-._~: Er kommt unverändert zurück und dient dazu, die Anfrage wiederzuerkennen (gegen das Fälschen von Anfragen zwischen Websites). -
Von Fibonacci. Die Praxis drückt
Verbindenneben Ihrer App. In diesem Fall gibt es keinstate, und die Rückkehr geht an die erste registrierte Adresse.
Ist die Person, die den Link öffnet, nicht angemeldet, bittet Fibonacci sie, sich anzumelden, und bringt sie dann zum Zustimmungsbildschirm zurück. Nur wer die Praxis verwaltet, kann bestätigen.
3.2 Die Rückkehr
Nach der bestätigten Zustimmung kehrt der Browser mit vier Parametern zu Ihrer Rückkehradresse zurück:
| Parameter | Was es ist |
|---|---|
client_id | die Kennung Ihrer App in dieser Praxis: Jede Praxis hat ihre eigene |
iss | die FHIR-Basis der Praxis, zum Beispiel https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4 |
token_url | wo das Token angefordert wird: https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token |
state | Ihr Wert, falls Sie einen mitgeschickt hatten |
Prüfen Sie state, dann speichern Sie client_id, iss und token_url neben dem Konto der Praxis in Ihrem System. Keines der drei ist ein Geheimnis: Ohne Ihren privaten Schlüssel nützen sie niemandem.
3.3 Das Token
Signieren Sie ein JWT mit Ihrem privaten Schlüssel (Algorithmen ES256, ES384, ES512, RS256, RS384, RS512; empfohlen ES256 oder ES384), mit kid im Header gleich einem Schlüssel Ihres JWKS:
| Feld | Wert |
|---|---|
iss | die client_id der Praxis |
sub | die client_id der Praxis |
aud | die token_url der Praxis, genau so, wie sie bei Ihnen angekommen ist |
iat | jetzt, in Unix-Sekunden |
exp | höchstens 5 Minuten nach iat |
jti | ein eindeutiger Wert für jedes JWT |
Dann:
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"
Die Antwort ist ein Bearer-Token, das eine Stunde gilt. Ein Refresh-Token gibt es nicht: Läuft es ab, fordert man mit einem neuen JWT ein anderes an. Ein gemeinsames Geheimnis (client_secret) wird nicht akzeptiert.
Ein Beispiel in Python, mit der Bibliothek 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 Die Aufrufe
Mit dem Token rufen Sie die iss-Basis der Praxis auf:
curl -H "Authorization: Bearer $TOKEN" "$ISS/Slot?schedule=Schedule/<id>&start=ge2026-12-01"
curl -H "Authorization: Bearer $TOKEN" "$ISS/Appointment/<id>"
Das Token gilt nur auf den Adressen dieser Praxis (.../projects/<studio>/...). Erlaubt sind diese Aufrufe:
| Was | Wie |
|---|---|
| per Kennung lesen | GET <Typ>/<id> für Schedule, Slot, Location, Appointment, Patient, Invoice |
| suchen | GET Schedule?, Slot?, Location?, Invoice? mit den Parametern aus der Tabelle unten |
| einen Termin anlegen | POST Appointment |
| einen Termin ändern | PUT Appointment/<id> (senden Sie die gelesene Ressource mit den geänderten Feldern) |
| Fähigkeiten des Servers | GET metadata |
| Typ | Zulässige Suchparameter |
|---|---|
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 reicht von 1 bis 100. Verkettete Suchen (patient.name=), Modifikatoren (:missing, :text), _include, _revinclude, _has, $-Operationen, _history und batch-Anfragen sind nicht zulässig: Sie antworten mit 403. Bei Appointment und Patient gibt es absichtlich keine Suche: Auch ohne ein Feld zu zeigen, würde eine Suche auf dieses Feld verraten, ob es da ist oder nicht.
Um zu wissen, welche Termine existieren, ohne sie zu suchen, nutzen Sie die Benachrichtigungen (Punkt 4).
4. Die Benachrichtigungen
Wenn ein Termin entsteht, Zeit oder Status ändert oder abgesagt wird, kann Fibonacci eine signierte Nachricht an eine https-Adresse von Ihnen senden, mit dem Ereignistyp (appuntamento.creato, appuntamento.modificato, appuntamento.annullato), den Kennungen und den Daten. Die Nachricht enthält nicht den Namen des Patienten. Die Signatur steht im Header X-Fibonacci-Firma (HMAC-SHA256 aus Zeit und exaktem Body).
Derzeit fügt die Praxis die Adresse hinzu, unter Einstellungen, Personen und Berechtigungen, Zugänge für externe Programme, Benachrichtigungen, und das Signaturgeheimnis sieht sie nur ein einziges Mal. Das Format und die Prüfung der Signatur stehen im technischen Leitfaden zu den externen Zugängen, den wir Ihnen mit der Registrierung schicken. Dass sich die Benachrichtigungen mit der Verbindung der App von selbst aktivieren, ist der nächste Schritt und noch nicht getan.
5. Die Fehler
| Antwort | Was sie bedeutet |
|---|---|
400 vom Token, invalid_request | das JWT stimmt nicht: aud weicht von token_url ab, exp abgelaufen oder zu weit entfernt, Signatur passt nicht zu Ihrem JWKS, oder die App ist nicht mehr verbunden |
400 vom Token, unsupported_grant_type | nötig ist client_credentials mit client_assertion; ein client_secret genügt nicht |
401 | Token abgelaufen: Fordern Sie ein neues an |
400 mit Authentication error | Die Praxis hat die App getrennt: Das Token gilt nicht mehr, und es gibt keine neuen (Client not found beim Token) |
403 mit percorso-non-ammesso, tipo-non-ammesso, parametro-non-ammesso | der Aufruf gehört nicht zu denen aus Punkt 3.4 |
403 ohne Code | der Aufruf ist erlaubt, die Berechtigung aber nicht: Die Praxis hat sie nicht erteilt |
405 mit metodo-non-ammesso | HTTP-Verb für diesen Typ nicht vorgesehen |
503 mit registro-non-disponibile | wir konnten den Zugriff nicht ins Protokoll schreiben, und ohne Protokoll verlassen die Daten das System nicht: Versuchen Sie es gleich noch einmal |
FHIR-Fehler kommen als OperationOutcome, mit dem Code in issue[0].details.text.
6. Die Testpraxis
Vor einer echten Praxis verbindet sich Ihre App mit einer Testpraxis mit erfundenen Daten: Wir bereiten sie vor, wenn wir die App registrieren, und dort durchlaufen Sie den ganzen Ablauf (Zustimmung, Rückkehr, Token, Aufrufe, Trennung). Keine echten Patienten, keine echten Daten.
7. Was protokolliert bleibt
Jedes Token, das Ihre App erhält, und jeder Aufruf, den sie macht, landen im Zugriffsprotokoll der Praxis, im Namen Ihrer App: was, wann, mit welchem Ergebnis und für welchen Patienten, wenn es einen gibt. Die Praxis liest es in ihrem Protokoll. Auch Verbinden und Trennen werden festgehalten, mit dem Namen der Person, die sie vorgenommen hat.
8. Datenschutz und Vertrag
Die Praxis ist für die Daten ihrer Patienten verantwortlich; Ihre App verarbeitet sie in ihrem Auftrag. Bevor eine echte Praxis Sie verbindet, braucht es zwischen Ihnen und der Praxis einen Vertrag zur Auftragsverarbeitung (Art. 28 DSGVO): Der Zustimmungsbildschirm erinnert die Praxis daran. Fragen Sie nur die Daten ab und bewahren Sie nur die auf, die Sie brauchen.
9. Support
Für die Registrierung, die Testpraxis und jede technische Frage: info@fibonaccimedica.it. Nennen Sie den Namen der App und, wenn der Fehler eine Praxis betrifft, die client_id (nie den privaten Schlüssel und nie ein Token).