Zum Inhalt springen
FibonacciÄsthetikAnmeldenKostenlos testen

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.

BerechtigungWas Sie tun könnenWas Sie nicht sehen
agenda-letturaSchedule, Slot, Location lesen und suchen; einen Appointment per Kennung lesenName, Telefon und E-Mail des Patienten, Behandlung, Grund, Notizen zum Termin
agenda-scritturaeinen Appointment anlegen und seine Zeit oder seinen Status ändern, nur in den Zuständen booked, pending, cancelledwie oben; kein Löschen, keine Suche
richiesteeinen Appointment im Zustand pending anlegen: Die Praxis findet ihn unter den Anfragen und entscheideter wird nicht wieder gelesen und nicht geändert
recapitieinen Patient per Kennung lesenalles außer Name, Telefon und E-Mail (weder Geburtsdatum noch Steuernummer noch Adresse)
fatture-letturaInvoice lesen und suchendie 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>
    

    state ist 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 Verbinden neben Ihrer App. In diesem Fall gibt es kein state, 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:

ParameterWas es ist
client_iddie Kennung Ihrer App in dieser Praxis: Jede Praxis hat ihre eigene
issdie FHIR-Basis der Praxis, zum Beispiel https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4
token_urlwo das Token angefordert wird: https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token
stateIhr 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:

FeldWert
issdie client_id der Praxis
subdie client_id der Praxis
auddie token_url der Praxis, genau so, wie sie bei Ihnen angekommen ist
iatjetzt, in Unix-Sekunden
exphöchstens 5 Minuten nach iat
jtiein 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:

WasWie
per Kennung lesenGET <Typ>/<id> für Schedule, Slot, Location, Appointment, Patient, Invoice
suchenGET Schedule?, Slot?, Location?, Invoice? mit den Parametern aus der Tabelle unten
einen Termin anlegenPOST Appointment
einen Termin ändernPUT Appointment/<id> (senden Sie die gelesene Ressource mit den geänderten Feldern)
Fähigkeiten des ServersGET metadata
TypZulässige Suchparameter
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 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

AntwortWas sie bedeutet
400 vom Token, invalid_requestdas 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_typenötig ist client_credentials mit client_assertion; ein client_secret genügt nicht
401Token abgelaufen: Fordern Sie ein neues an
400 mit Authentication errorDie 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-ammessoder Aufruf gehört nicht zu denen aus Punkt 3.4
403 ohne Codeder Aufruf ist erlaubt, die Berechtigung aber nicht: Die Praxis hat sie nicht erteilt
405 mit metodo-non-ammessoHTTP-Verb für diesen Typ nicht vorgesehen
503 mit registro-non-disponibilewir 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).