Dokumentation

Alles, was Sie brauchen, um mit Genkō sicher loszulegen.

Sie haben bereits ein Konto? Anmelden →

Auf dieser Seite

Erste Schritte

Dashboard-Übersicht

Nach der Registrierung und dem Abschluss des Onboarding-Assistenten gelangen Sie zu Ihrem Praxis-Dashboard. Die linke Seitenleiste bietet schnellen Zugriff auf jeden Bereich: Overview, Appointments, Patients, Providers und Settings.

Die Seite Overview ist Ihre Steuerzentrale. Sie zeigt:

  • Stats bar — heutige Termine, diese Woche, gesamte Patienten und Mitarbeiter — jeweils mit einem Nutzungsindikator relativ zu Ihren Planlimits
  • Today's schedule — eine Live-Liste der Termine für den aktuellen Tag mit Patientenname, Uhrzeit, Typ, Provider und Status
  • Upcoming — die nächsten 5 Termine über die folgenden 7 Tage
  • Platform features (nur Group+ Admins) — Live-Statusindikatoren für Analytics, WhatsApp, HubSpot und AI Assistant, mit direkten Links zur Konfiguration
  • Quick actions — Shortcuts zum Erstellen von Terminen, Hinzufügen von Patienten, Verwalten von Providern und Navigieren zu Analytics
  • Plan info — Ihr aktueller Plan und Abonnementstatus
Layout anpassen: Klicken Sie auf die Schaltfläche Customise (oben rechts in der Übersicht), um Dashboard-Abschnitte anzuzeigen, auszublenden oder neu anzuordnen. Die Einstellungen werden automatisch in Ihrem Browser gespeichert.
Dashboard-Übersicht mit Statistiken und bevorstehenden Terminen

Checkliste für die ersten Schritte

Neu bei Genkō? Folgen Sie diesen Schritten in der Reihenfolge, um vollständig eingerichtet zu sein. Rechnen Sie mit 10–15 Minuten:

  1. Fügen Sie Ihre Dienstleistungen hinzu — Gehen Sie zu Settings → Services und erstellen Sie mindestens einen Termintyp. Beispiele: “Initial Consultation (60 min)”, “Follow-up (30 min)”, “Assessment (45 min)”.
    Dienstleistungen definieren die Dauer und helfen Patienten zu verstehen, was sie erwarten können. Sie können später weitere hinzufügen.
  2. Fügen Sie einen Provider hinzu — Gehen Sie zu Providers und senden Sie entweder einen Invite Provider Magic Link oder verwenden Sie Assign myself as Provider. Klicken Sie dann auf Edit Schedule, um deren wöchentliche Verfügbarkeit zu definieren.
  3. Fügen Sie einen Patienten hinzu — Gehen Sie zu Patients und klicken Sie auf Add Patient. Full name ist erforderlich; E-Mail und Telefon helfen bei Kommunikation und Erinnerungen.
  4. Buchen Sie Ihren ersten Termin — Gehen Sie zu Appointments → New Appointment. Wählen Sie Patient, Provider, Dienstleistung, Datum und Uhrzeit. Ihre erste Buchung hilft Ihnen, den Kalender zu verstehen.
  5. Aktivieren Sie das Patientenportal (optional) — Gehen Sie zu Settings → Portal, um die Self-Service-Buchung zu aktivieren. Sie erhalten einen öffentlichen Link zum Teilen mit Patienten.
    Nächster Schritt nach der Einrichtung: Laden Sie Ihre Teammitglieder über Settings → Members ein, damit sie bei der Verwaltung von Terminen helfen können.

Termine

Einen Termin buchen

Klicken Sie auf New Appointment oben rechts auf der Appointments-Seite. Ein Dialog öffnet sich, in dem Sie Folgendes ausfüllen:

  • Patient — Suche nach Name oder E-Mail. Wenn der Patient nicht existiert, können Sie ihn inline hinzufügen.
  • Provider — Es werden nur Provider mit Verfügbarkeit am gewählten Datum angezeigt.
  • Service — der Termintyp, der die Standarddauer bestimmt (bei Bedarf anpassbar).
  • Date & Time — Der Datumsauswahlpicker hebt Tage mit verfügbaren Slots hervor. Nicht verfügbare Zeiten sind ausgegraut.
  • Notes — Interne Notizen, die für Ihr Team sichtbar, aber nicht für den Patienten angezeigt werden.

Nach dem Speichern erscheint der Termin im Kalender. Bestätigungs-E-Mails werden automatisch an Patient und Provider gesendet (wenn E-Mail-Benachrichtigungen in den Einstellungen aktiviert sind).

Konfliktvermeidung: Genkō verhindert Doppelbuchungen in Echtzeit. Wenn sich ein Provider-Slot füllt, während Sie buchen, werden Sie benachrichtigt.
Dialog für neuen Termin mit Feldern für Patient, Provider, Service und Uhrzeit
Demo: Durchlaufen Sie den Buchungsablauf für Termine vom Dashboard aus.

Kalenderansichten

Wechseln Sie zwischen drei Ansichten mithilfe der Steuerelemente oben auf der Appointments-Seite:

  • Day view — Konzentrieren Sie sich auf einen einzelnen Tag, Stunde für Stunde. Ideal für detaillierte Planung.
  • Week view — Sehen Sie die gesamte Woche auf einen Blick. Am besten zum Erkennen von Lücken und Verwalten mehrerer Provider.
  • Month view — Überblick über den gesamten Monat. Gut für Langzeitplanung.

Sie können auch nach Provider filtern, um sich auf den Zeitplan eines einzelnen Praktikers zu konzentrieren, oder alle Provider zusammen anzeigen. Ihre letzte Ansichtspräferenz wird gespeichert, sodass Sie nach dem Navigieren zur gleichen Ansicht zurückkehren.

Verwenden Sie Week view als Standard – sie bietet ein ausgewogenes Verhältnis von Detail und Übersicht für die meisten Praxen.

Konflikterkennung

Genkō verhindert automatisch Doppelbuchungen. Das System überprüft jede Buchung in Echtzeit:

  • Wenn Sie versuchen, einen Provider zu einer Zeit zu planen, zu der er bereits gebucht ist, sehen Sie einen Fehler und der Slot wird nicht gespeichert.
  • Konflikte werden auf dem Server geprüft, sodass auch mehrere Mitarbeiter, die gleichzeitig buchen, sicher sind – nur einer gelingt.
  • Der Kalender graut nicht verfügbare Zeiten aus und verhindert so Fehler, bevor sie passieren.

Buffer minutes (verfügbar ab dem Practice-Plan) fügen eine Pause zwischen Terminen hinzu, damit Provider Zeit haben, sich vorzubereiten, Notizen zu schreiben oder eine Pause zu machen. Zum Beispiel bedeutet ein 60-Minuten-Termin mit 10 Minuten Puffer, dass der nächste Slot erst 70 Minuten später beginnen kann.

Terminstatus

Jeder Termin durchläuft einen Lebenszyklus mit vier möglichen Zuständen:

  • Scheduled — der Termin ist bestätigt und erscheint im Kalender. Dies ist der Ausgangszustand.
  • Completed — markieren Sie dies, nachdem der Besuch stattgefunden hat. Nützlich zur Verfolgung der Provider-Stunden und Praxisproduktivität.
  • Cancelled — der Termin wurde vom Personal oder vom Patienten über das Portal storniert. Der Zeitslot wird für eine Neubuchung freigegeben.
  • No-show — der Patient ist nicht erschienen. Dies ist getrennt von einer Stornierung und hilft, Anwesenheitsmuster zu verfolgen.

Personal, Provider und Admins können den Status in der Termindetailansicht aktualisieren. Nur Owners und Admins können Termine löschen. Stornierte und No-Show-Termine blockieren nicht die Provider-Verfügbarkeit – der Slot ist sofort für neue Buchungen verfügbar.

No-Shows verfolgen: Überwachen Sie Ihre No-Show-Rate im Overview-Dashboard. Hohe No-Show-Raten können auf die Notwendigkeit von Terminerinnerungen oder Patientennachverfolgung hinweisen.

Patienten

Patienten hinzufügen

Gehen Sie zu Patients in der Seitenleiste und klicken Sie auf Add Patient. Füllen Sie aus:

  • Full name — erforderlich. Wird verwendet, um den Patienten überall in Genkō zu identifizieren.
  • Email — optional, aber empfohlen. Wird zum Senden von Terminbestätigungen und Erinnerungen verwendet.
  • Phone — optional. Hilfreich für schnelle Nachverfolgungen oder Bestätigungsanrufe.
  • Date of Birth — optional. Nützlich für klinischen Kontext und altersbezogene Notizen.
  • Notes — optional. Fügen Sie relevante Krankengeschichte, Allergien oder Präferenzen hinzu, die für Ihr Personal sichtbar sind.
Massenimport: Verwenden Sie die Schaltfläche Import, um eine CSV-Datei (in Excel: Speichern unter → CSV) hochzuladen, wenn Sie vorhandene Patientenakten nach Genkō übertragen.
Dialog zum Hinzufügen von Patienten mit Feldern für Name, E-Mail, Telefon und Notizen
Demo: Fügen Sie einen Patienten aus der Liste hinzu und springen Sie dann zu seinem vollständigen Profil.

Patientenakten

Klicken Sie auf den Namen eines Patienten, um seine Detailseite zu öffnen. Hier können Sie:

  • Kontaktinformationen anzeigen und aktualisieren
  • Den vollständigen Terminverlauf einsehen (vergangene, bevorstehende, stornierte)
  • Notizen hinzufügen oder bearbeiten, die nur für Ihr Team sichtbar sind
  • Ihre Nutzung gegen Ihre Planlimits überprüfen

Berechtigungen: Owners und Admins können Patientenakten bearbeiten und löschen. Provider und Personal haben schreibgeschützten Zugriff, was die Privatsphäre der Patienten schützt.

Patienten entfernen: Ein Patient mit Historie wird beim Entfernen archiviert, seine Akte bleibt erhalten. Siehe Aufbewahrung und Archivierung.

Planlimits

Jeder Plan beinhaltet ein Patientenlimit. Wenn Sie das Limit Ihres Plans erreichen, müssen Sie upgraden, bevor Sie weitere Patienten hinzufügen können. Die aktuelle Nutzung ist in Settings → Billing sichtbar.

  • Free — bis zu 100 Patienten
  • Solo — bis zu 250 Patienten
  • Starter — bis zu 750 Patienten
  • Group — bis zu 2.000 Patienten
  • Practice — bis zu 7.500 Patienten
  • Network — bis zu 10.000 Patienten pro Organisation

Patientenakte (EMR)

Überblick und Pläne

Genkō führt die klinische Akte jedes Patienten direkt neben seinen Terminen: Notizen zum Besuch, eine codierte Problemliste, Vitalwerte, fachspezifische Vorlagen, Dokumente und Anamnesebögen. Die Regeln, die die Akte verlässlich machen (Signatur, Nachträge, Aufbewahrung), setzt die Datenbank für jeden Benutzer und jede Integration durch, nicht nur die Oberfläche.

Wer sie sieht: Owner und Admins immer. Provider und Personal brauchen die Berechtigungen View patients und Chart notes (Settings → Members → Permissions), und auf der Terminseite bearbeitet ein Provider nur Notizen zu seinen eigenen Terminen. Patienten sehen eine Notiz nur, wenn eine behandelnde Person eine signierte Notiz mit ihnen teilt.

Genkō ist ein EMR für die Akten Ihrer eigenen Praxis. Es tauscht keine Akten mit Systemen anderer Organisationen aus; codierte Listen und Vitalwerte lassen sich als FHIR R4 exportieren, und die vollständige Akte jedes Patienten lässt sich herunterladen.

FunktionPlan
Klinische Notizen, Signatur, Nachträge, „Irrtümlich erfasst“, DruckansichtStarter+
Problemliste mit ICD-10-CM-Suche, Allergien, Medikamente, VitalwerteStarter+
Longitudinale Akte mit Suche und VitalwertverlaufStarter+
Aktendownload und BesuchszusammenfassungenStarter+
Archivierung und AktenaufbewahrungAlle Pläne
Fachspezifische NotizvorlagenGroup+
Patientendokumente (5 GB · 25 GB bei Practice · 100 GB bei Network)Group+
Vorbesuchsformular (Prüfung und Freigabe ab Practice)Group+
Klinische Daten über REST-API und MCP (nur Entwürfe)Network
Integrationen: Mit den Scopes clinical:read und clinical:write (Network) liest die REST-API Notizen, Anamnesebögen, Dokumente und die Akte und schreibt Notiz- und Nachtragsentwürfe. Siehe Endpunkte.

Klinische Notizen und SignaturStarter+

Provider und Mitglieder mit Chart notes schreiben Notizen zu jedem Termin auf der Terminseite. Es gibt vier Notiztypen:

  • SOAP: Abschnitte Subjektiv, Objektiv, Beurteilung und Plan
  • Verlauf: eine frei formulierte Aktualisierung
  • Anamneseprüfung: Kommentare zu einem eingereichten Formular
  • Entlassung: eine Zusammenfassung zum Behandlungsende

Vom Entwurf zur Signatur

  1. Eine neue Notiz ist ein Entwurf. Die verfassende Person kann ihn bearbeiten oder verwerfen; Owner und Admins können ihn ebenfalls verwerfen.
  2. Ist sie fertig, signiert die verfassende Person sie, nachdem sie die Erklärung im Signaturdialog bestätigt hat. Genkō speichert diese Erklärung, den Namen der signierenden Person und den Zeitpunkt mit der Notiz.
  3. Eine signierte Notiz kann von niemandem mehr bearbeitet oder gelöscht werden: Die Datenbank lehnt jede Änderung ab, gleich von wem, auch von Ownern, API-Schlüsseln und Genkōs eigenem Server.
  4. Um eine signierte Notiz zu korrigieren oder zu ergänzen, schreiben Sie einen Nachtrag. Er hängt am Original, kann als Entwurf bleiben und wird genauso signiert.
  5. Wurde eine Notiz beim falschen Patienten oder Besuch erfasst, markiert ein Owner oder Admin sie mit Begründung als irrtümlich erfasst. Sie bleibt gekennzeichnet in der Akte, mit Angabe, wer das wann getan hat.

Abzeichen zeigen den Status jeder Notiz: Draft, Signed, Signed (migrated) und Entered in error. Notizen aus der Zeit vor der Signaturfunktion erscheinen als Signed (migrated): Sie wurden im Namen ihrer Verfasser zum Zeitpunkt der letzten Bearbeitung signiert.

Jede signierte Notiz hat eine Druckansicht (Druck auf Papier oder als PDF über den Browser) mit ihren signierten Nachträgen, der Erklärung und der Angabe, wer gedruckt hat.

Hat die signierende Person eine cédula profesional (mexikanische Berufszulassung) im Behandlerprofil, zeigen die signierte Notiz, ihre Druckansicht und der Aktendownload sie neben der Signatur. Genkō übernimmt sie im Moment der Signatur, eine spätere Profiländerung ändert also nie eine signierte Notiz.

Jede ab jetzt signierte Notiz trägt einen SHA-256-Fingerabdruck ihres Inhalts, den die Datenbank im Moment der Signatur berechnet (der eines Nachtrags umfasst auch den der ursprünglichen Notiz). Er erscheint an der Notiz, in der Druckansicht, im Akten-Download und in der Besuchszusammenfassung für den Patienten; Inhaber und Admins können ihn mit Erneut prüfen neu berechnen.

e.firma (Mexiko): In Praxen in Mexiko kann eine Behandlerin oder ein Behandler mit der eigenen e.firma der mexikanischen Steuerbehörde SAT signieren statt nur mit der Bestätigung. Im Signaturdialog werden die Dateien .cer und .key gewählt und das Passwort des Schlüssels eingegeben: Schlüssel und Passwort bleiben im Browser und werden nie an Genkō gesendet. Genkō prüft, dass das Zertifikat eine persönliche, von der SAT ausgestellte und beim Signieren gültige e.firma ist, fragt bei der SAT nach einem Widerruf und speichert Zertifikat, Signatur und Fingerabdruck; die Notiz zeigt dann Elektronisch signiert (e.firma) · Zertifikat … · RFC …. Antwortet der SAT-Dienst nicht, bleibt die Notiz ein Entwurf. Die erste e.firma-Signatur hinterlegt die RFC der Person in der Praxis, eine andere RFC wird danach abgelehnt (der Inhaber kann sie zurücksetzen). Der Inhaber kann unter Settings → Compliance die e.firma für jede Notiz und jeden Nachtrag verlangen.

Passkey-Prüfung vor dem Signieren (optional): unter Einstellungen → Sicherheit kann eine signierende Person eine Passkey-Prüfung einschalten. Solange sie aktiv ist, verlangt jede Signatur (die Erklärung, ein in einem Schritt signierter Nachtrag und die e.firma) zuerst die Bestätigung per Face ID, Fingerabdruck, Windows Hello oder PIN des Geräts, und der Server signiert ohne sie nicht. Das ist eine zusätzliche Anwesenheitsprüfung und nimmt nichts weg: das e.firma-Passwort wird weiterhin jedes Mal eingegeben und von Genkō nie gespeichert. Das Ein- und Ausschalten verlangt dieselbe Bestätigung, und bei aktiver Prüfung gibt es kein „bereits entsperrt“-Zeitfenster. Auf dem Smartphone lassen sich die e.firma-Dateien aus der Dateien-App, einem Cloud-Laufwerk oder einem E-Mail-Anhang wählen.

API-Schlüssel, MCP und der KI-Assistent schreiben nur Entwürfe. Sie können Notiz- und Nachtragsentwürfe anlegen und bearbeiten; Signieren und das Markieren als irrtümlich erfasst erfordern immer eine angemeldete behandelnde Person im Dashboard. Eine Anfrage zum Veröffentlichen (is_draft: false) wird mit 403 NOTE_SIGN_REQUIRES_CLINICIAN abgelehnt, und jede Änderung an einer signierten Notiz liefert 409 NOTE_LOCKED.

Fachspezifische VorlagenGroup+

Wählen Sie beim Anlegen einer Notiz eine Vorlage. Ihre Felder erscheinen im Editor neben den SOAP-Abschnitten, werden mit dem Entwurf gespeichert und mit der Signatur gesperrt.

VorlageWas sie erfasst
ZahnschemaBleibende und Milchzähne in FDI- oder Universal-Nummerierung; Befunde je Fläche; geplante oder erledigte Behandlungen.
Psychopathologischer BefundJeder Befundbereich, Risikoeinschätzung und klinischer Eindruck, optional mit PHQ-9 und GAD-7.
PHQ-9 · GAD-7Die Fragebögen einzeln, für Folgetermine.
Physiotherapeutischer BefundKörperregionen, Bewegungsausmaß je Gelenk und Bewegung (Seite, aktiv und passiv, in Grad), Outcome-Messungen, Befund und Plan.
AugenuntersuchungSehschärfe je Auge in Snellen (Meter oder Fuß), dezimal oder logMAR, mit berechnetem logMAR; Augeninnendruck mit Messmethode; objektive und subjektive Refraktion.
Tierärztliche UntersuchungTierart, Rasse, Geschlecht und Kastrationsstatus, Body Condition Score (9-Punkte-Skala), Befund und Plan. Das Gewicht des Besuchs wird gegen die Tierart geprüft.
Ästhetische BehandlungBehandlungsarten, Einwilligung, je behandelter Zone eine Zeile mit Produkt, Charge, Verfallsdatum und Menge (Einheiten oder mL), Technik und Nachsorge.
Allgemeine NotizenStrukturierte SOAP-Konsultation (Systemanamnese und Untersuchung nach Systemen), Eingriffsnotiz, Konsil/Überweisung und Entlassbericht — für jede Praxis.
TherapienotizenVerlaufsnotiz (Interventionen, Reaktion, Fortschritt bei den Zielen, Risiko), biopsychosoziale Erstaufnahme, Behandlungsplan mit messbaren Zielen und eine klinisch eingeschätzte Risikobewertung (keine validierte Skala).
Mehr je FachgebietZahnärztlicher Behandlungsplan und Eingriffe je Zahn · Physiotherapie-Sitzung (Techniken, Sätze und Wiederholungen) und Abschluss · Impfnachweis und OP-/Anästhesieprotokoll · Laser-/Geräteparameter und ästhetische Beratung · Kontaktlinsenanpassung und Glaukom-Verlaufskontrolle.
Ernährung, Chiropraktik, Sprache & ErgotherapieErnährung: ADIME-Assessment, Verlauf, 24-Stunden-Protokoll, Plan mit Tageszielen, Laborbefunde. Chiropraktik: Erstuntersuchung, Behandlungstermin und Nachuntersuchung mit anklickbarer Wirbelsäulenkarte, Verletzungsbericht. Sprache & Ergotherapie: Befund, Sitzungsnotiz mit Zieldaten, Versorgungsplan, Verlaufsbeurteilung. Körper- oder Wirbelsäulenregionen werden mit Befunden auf einer interaktiven Karte markiert und bleiben durchsuchbar.
WundversorgungWundassessment (Ätiologie, Dekubitusgrad oder Wagner-Grad, Lokalisation auf einer Körperkarte, Maße und Gewebe je Wunde, Exsudat, Wundumgebung, Infektionszeichen, Knöchel-Arm-Index und Sensibilität, Behandlungsplan), Verbandwechsel-Besuch, Débridement-Protokoll und Abschlussbericht. Wundfotos gehören in die Patientendokumente.
MexikoAnamnese (historia clínica) in der Reihenfolge der mexikanischen Regeln für die Patientenakte: Vorstellungsgrund, Familienanamnese, nicht-pathologische, pathologische und gynäkologisch-geburtshilfliche Anamnese (angeboten für Patientinnen und für Patienten mit Geschlecht „divers“ oder ohne Angabe), aktuelle Beschwerden, Systemanamnese, Untersuchung, Befunde, Diagnosen, Therapie und Prognose; Konsilnotiz (nota de interconsulta); Überweisungs-/Verlegungsnotiz (nota de referencia / traslado) mit der aufnehmenden Einrichtung und ihrer optionalen CLUES. Identifikation und Vitalwerte kommen aus der Akte und der Notiz und werden nicht doppelt abgefragt. Mit * markierte Felder müssen vor der Signatur ausgefüllt sein. Für Praxen in Mexiko standardmäßig aktiv; jede Praxis kann die Gruppe unter Settings → Clinical einschalten. Die allgemeine Vorlage für Konsil/Überweisung bleibt daneben verfügbar.

Welche Vorlagengruppen und einzelnen Vorlagen die Auswahl anbietet, legen Sie unter Settings → Clinical fest (neue Praxen wählen ihre Praxisart im Einrichtungsassistenten). Eine deaktivierte Gruppe oder Vorlage ist nur für neue Notizen ausgeblendet: bestehende und signierte Notizen sowie API-Integrationen sind nicht betroffen.

Genkō berechnet Gesamtwerte und Schweregrade der Fragebögen beim Speichern und markiert PHQ-9-Item 9, sodass die signierte Notiz genau das enthält, was die behandelnde Person gesehen hat. Schweregrade sind Screeningwerte, keine Diagnosen, und jeder Fragebogen wird mit der Nennung seiner Autoren angezeigt.

Vorlagenantworten sind über die Patientenakte durchsuchbar, etwa eine Zahnnummer in beiden Nummerierungen oder ein PHQ-9-Schweregrad. Notizen mit Vorlage bleiben in jedem Plan lesbar; eine Vorlage für eine neue Notiz zu wählen erfordert Group oder höher.

Problemliste, Allergien, Medikamente und VitalwerteStarter+

  • Problemliste: Geben Sie eine Erkrankung ein und wählen Sie einen ICD-10-CM-Vorschlag, um sie zu codieren, oder belassen Sie sie als Freitext. Jeder Eintrag hat einen Status (aktiv, wiederkehrend, Rückfall, inaktiv, Remission oder abgeklungen) und optional einen Beginn. Der ICD-10-CM-Katalog ist in Genkō enthalten; Ihre Eingaben werden nie an einen anderen Dienst gesendet. Die Bezeichnungen sind englisch. Ein Eintrag behält das Codesystem, mit dem er codiert wurde; die API akzeptiert neben ICD-10-CM auch CIE-10 (das in Mexiko verwendete WHO-ICD-10, System http://hl7.org/fhir/sid/icd-10).
  • Allergien (mit Schweregrad) und Medikamente (mit Dosis und Häufigkeit) sind Freitext.
  • Neue Einträge werden mit Person und Zeitpunkt versehen. Die Listen bearbeiten Owner und Admins.
  • Vitalwerte in jeder Notiz: Blutdruck, Herzfrequenz, Atemfrequenz, Temperatur, SpO₂, Gewicht, Größe und Schmerz (0–10). Der BMI wird aus Gewicht und Größe berechnet. Temperatur, Gewicht und Größe lassen sich in °C oder °F, kg, g oder lb sowie cm oder in eingeben. Jeder Wert wird mit LOINC-Code und UCUM-Einheit gespeichert und mit der Notiz gesperrt.
  • Mexikanische Kennungen (optional): eine CURP beim Patienten (Format geprüft; Praxen in Mexiko sehen bei leerem Feld einen Hinweis, nie einen Fehler), angezeigt beim Patienten, in der Druckansicht der Notiz und im Aktendownload. Über die REST-API ist die CURP ein klinisches Feld (clinical:read/clinical:write, Network). Der Inhaber hinterlegt CLUES und RFC der Einrichtung unter Settings → Compliance; die CLUES erscheint im Kopf der Notiz.
  • SIS-Datei für die DGIS (Mexiko, Group+, vom Inhaber aktiviert): Eine Praxis in der Region Mexiko kann die SIS-Leitfäden Consulta Externa und Salud Bucal unter Settings → Compliance aktivieren, einen Monat in einem Bericht prüfen, der je Datensatz nennt, was fehlt, und die Datei (TXT oder ZIP) herunterladen. Ein Besuch braucht Personaltyp, CURP und Leistungsschlüssel des Behandelnden, Namensteile und Geburtsdaten der Patientin bzw. des Patienten und im Block SIS (DGIS) der Notiz bis zu drei Diagnoseschlüssel (bei Salud Bucal zusätzlich die Mundgesundheitsmaßnahmen); der Block wird mit der Notiz beim Signieren gesperrt. Nichts davon ist für Buchung, Dokumentation oder Signatur nötig: Ein Besuch ohne diese Angaben ist nur nicht exportierbar. Die DGIS-Kataloge sind nicht enthalten, daher wird eine Diagnose nicht auf Geschlecht, Alter oder Personaltyp geprüft und ihr Schlüssel von Hand eingegeben. Das verschlüsselte Format (CIF) wird nicht angeboten, und Genkō lädt die Datei nicht hoch: Das macht die Praxis selbst bei Cargas SINBA der DGIS. Im Block Salud Bucal schlägt Mit den Notizen dieses Besuchs füllen Antworten aus dem gespeicherten Zahnschema, der Hygienenotiz, der zahnärztlichen Untersuchung und der Extraktionsnotiz des Besuchs vor (Versiegelungen, Extraktionen, Wurzelbehandlungen, Hygienemaßnahmen, Untersuchung der Mundgewebe, Oralchirurgie). Es füllt nur leere Felder, ersetzt nie eine Antwort und schlägt nie ein „Nein“ vor; das Füllungsmaterial wird nicht erfasst und von Ihnen eingetragen. Exportiert wird erst, wenn Sie die Notiz speichern.

Die Patientenakte zeigt die Vitalwerte signierter Notizen im Zeitverlauf, auch als Tabelle. Der FHIR-R4-Export in den Einstellungen enthält die codierten Einträge der Problem-, Allergie- und Medikamentenliste sowie die Vitalwerte signierter Notizen als Observations.

VorbesuchsformularGroup+

Ist das Vorbesuchsformular aktiviert, erhalten Patienten vor ihrem Termin einen Link zu einem Formular. Es erfasst:

  • Besuchsgrund und Hauptbeschwerde
  • Beginn und Beschreibung der Symptome sowie Schmerzskala (0–10)
  • Aktuelle Medikamente, bekannte Allergien und relevante Erkrankungen
  • Bestätigung von Adresse, Notfallkontakt und hinterlegter Versicherung

Patienten können einen Entwurf speichern und später weitermachen oder alles auf einmal absenden. Nach dem Absenden erscheint das Formular beim Termin für Ihr Team.

Formular für den Patienten erfassen: Owner, Admins und Provider (sowie Rollen mit View intake forms) öffnen den Tab Intake des Termins und wählen Enter intake for the patient. Das Formular wird als vom Personal im Namen des Patienten erfasst gekennzeichnet und hält fest, wer es erfasst hat. Provider können das nur für eigene Termine.

Prüfung (Practice+): Owner, Admins und Provider geben ein eingereichtes Formular mit Prüfnotizen frei oder lehnen es ab. Ein freigegebenes Formular ist endgültig: Antworten und Prüfung ändern sich nicht mehr. Ein abgelehntes kann nur für die Überarbeitung durch den Patienten wieder geöffnet werden und braucht danach eine neue Prüfung.

PatientendokumenteGroup+

  • Fügen Sie Laborbefunde, Bildgebung, Einwilligungen, Überweisungen und Korrespondenz in der Patientenakte hinzu (Documents), optional einem Besuch zugeordnet.
  • PDF, JPEG, PNG, HEIC oder WebP, bis 25 MB je Datei. Genkō prüft vor dem Ablegen den tatsächlichen Dateityp und eine Prüfsumme.
  • Dateien liegen in privatem Speicher. Beim Öffnen entsteht ein Link, der 60 Sekunden gültig ist.
  • Ein Dokument wird nie bearbeitet oder gelöscht. Ein Owner oder Admin kann es mit Begründung ungültig machen; es bleibt als ungültig gelistet.
  • Speicher pro Organisation: 5 GB bei Group, 25 GB bei Practice, 100 GB bei Network.

Owner, Admins und Mitglieder mit View patients und Chart notes sehen und ergänzen Dokumente. Patienten können nichts hochladen. Über die REST-API lassen sich Dokumente auflisten und lesen (Network, clinical:read), nicht hochladen.

Longitudinale AkteStarter+

Öffnen Sie View patient record an einem Termin, um die ganze Geschichte des Patienten in Reihenfolge zu sehen: jeden Termin mit Notizen und Nachträgen, Anamneseantworten (Group+), Vitalwerten und den dem Besuch zugeordneten Dokumenten.

Die Suche findet Wörter in Notiztexten, Vorlagenantworten, Terminarten, Providern und Buchungsnotizen. Alle Wörter müssen passen; Groß-/Kleinschreibung und Akzente werden ignoriert. Mitglieder ohne Chart notes sehen keine Notizen, und die Suche lässt sie ebenfalls aus.

Aufbewahrung und ArchivierungAlle Pläne

  • Remove löscht einen Patienten nur, wenn er keine Historie hat. Ein Patient mit Termin, Notiz, Formular oder Dokument wird stattdessen archiviert: aus den Listen ausgeblendet, kommende Termine storniert, die Akte aufbewahrt und weiterhin herunterladbar.
  • Eine archivierte Akte wird bis zu ihrem Datum Kept until gehalten: letzte klinische Aktivität plus Ihre Aufbewahrungsfrist. Der Owner legt die Frist unter Settings → Compliance → Record retention fest (5 bis 30 Jahre, Standard 10; Admins sehen sie schreibgeschützt). Bei Minderjährigen beginnt die Frist mit der Volljährigkeit, und wo Genkō ein gesetzliches Minimum für das Land der Praxis kennt, ist die Frist nie kürzer.
  • Owner und Admins sehen archivierte Patienten in der Ansicht Archived, mit Archivdatum und Kept until, und können sie wiederherstellen. Ein archivierter Patient erhält bis zur Wiederherstellung keine neuen Termine, Notizen oder Dokumente und zählt nicht zum Patientenlimit Ihres Plans. Im Patientenexport bleiben archivierte Patienten enthalten, mit dem Archivdatum in einer Spalte Archived (CSV/Excel) und active: false (FHIR); deaktivierte Provider werden ebenfalls mit active: false exportiert.
  • Ein Provider mit Terminhistorie wird deaktiviert statt gelöscht: nicht mehr im Buchungsportal, Historie unverändert.

Genkō löscht eine aufbewahrte Akte nie automatisch. Eine Organisation mit Terminhistorie kann geschlossen, aber nicht gelöscht werden.

Aktendownload und BesuchszusammenfassungenStarter+

Aktendownload

Download record auf der Aktenseite öffnet die vollständige Akte des Patienten als druckbare Seite. Drucken Sie sie oder speichern Sie sie über den Druckdialog des Browsers als PDF. Sie enthält:

  • Stammdaten, Kontakt, Versicherung und die allgemeinen Notizen der Praxis
  • Problemliste mit Codes, Allergien, Medikamente und Vitalwerte
  • Die vollständige Terminhistorie, jede signierte Notiz mit Nachträgen (irrtümlich erfasste gekennzeichnet) und Vorlagenantworten
  • Freigegebene Anamneseantworten, sofern Sie Anamnesebögen sehen dürfen
  • Das Dokumentenverzeichnis (Titel, Kategorien und Daten, ohne die Dateien)

Entwürfe und Buchungsnotizen sind nicht enthalten. Auch archivierte Patienten lassen sich herunterladen. Herunterladen dürfen Owner, Admins und Mitglieder mit View patients und Chart notes; jeder Download wird im Audit-Log erfasst.

Besuchszusammenfassungen im Patientenportal

Bei einer signierten Notiz können die signierende Person oder ein Owner oder Admin Share with patient wählen:

  • Der Patient sieht in seinem Portal eine schreibgeschützte Besuchszusammenfassung: die Notiz, ihre signierten Nachträge, Vorlagenantworten, Vitalwerte und wer signiert hat.
  • Entwürfe, unsignierte Nachträge und andere Notizen bleiben privat.
  • Stop sharing entfernt sie aus dem Portal; eine als irrtümlich erfasst markierte Notiz verschwindet von selbst aus dem Portal.
  • Jedes Teilen und Beenden wird im Audit-Log erfasst. Der Patient wird nicht automatisch benachrichtigt.

Provider

Provider hinzufügen

Es gibt zwei übliche Möglichkeiten, Provider hinzuzufügen:

  • Invite Provider — Senden Sie eine Magic-Link-Einladung von der Providers-Seite, wenn Sie einen Teammitarbeiter onboarden.
  • Assign myself as Provider — Owners können sich selbst hinzufügen, wenn sie auch direkt Patienten sehen.

Eingeladene Provider treten mit der Rolle Provider bei und erscheinen dann in Ihren Planungsansichten, sobald sie ihre Fachrichtung und Verfügbarkeit festgelegt haben.

Verwenden Sie Fachrichtungen und Biografien, um Personal und Patienten bei der Auswahl des richtigen Klinikers zu helfen, insbesondere wenn Self-Booking aktiviert ist.
Dialog zur Einladung eines Providers mit Feldern für vollständigen Namen und E-Mail

Verfügbarkeit festlegen

Öffnen Sie eine Provider-Karte und klicken Sie auf Edit Schedule, um deren wöchentliche Verfügbarkeit zu definieren. Genkō nutzt dies, um nur buchbare Slots beim Erstellen von Terminen oder im Patientenportal anzuzeigen.

So funktioniert es:

  • Legen Sie die Verfügbarkeit für jeden Wochentag fest (Montag bis Sonntag)
  • Geben Sie für jeden Arbeitstag Start- und Endzeit an (z. B. "9:00 AM - 5:00 PM")
  • Provider, die an einem Tag nicht arbeiten, können als nicht verfügbar markiert werden
  • Das System blockiert Buchungen außerhalb dieser Stunden
Beispiel: Wenn Dr. Smith Montag–Donnerstag 9–18 Uhr und Freitag 9–12 Uhr arbeitet, würden Sie die Verfügbarkeit für jeden Tag entsprechend einstellen.
Provider-Zeitplan-Editor mit Wochentagsschaltern und Feldern für Start- und Endzeit
Demo: Vorschau des Provider-Einladungsablaufs und anschließende Aktualisierung des wöchentlichen Zeitplans eines bestehenden Klinikers.

Erweiterte Planungsregeln

Praxen mit dem Practice-Plan und höher können fein abgestimmte Regeln pro Provider konfigurieren, um Ihre Planungsrichtlinien durchzusetzen:

  • Buffer minutes — fügt eine Lücke zwischen aufeinanderfolgenden Terminen hinzu. Beispiel: 60-Min-Termin + 10-Min-Puffer = nächster Slot beginnt 70 Minuten später. Großartig für Notizen oder Vorbereitungszeit.
  • Max appointments per day — begrenzt die Gesamtzahl der Buchungen für einen Provider an einem bestimmten Tag. Beispiel: Max 8 Termine verhindert Überbuchung.
  • Booking window — begrenzt, wie weit im Voraus Patienten buchen können. Beispiel: “bis zu 60 Tage im Voraus” verhindert weit in der Zukunft liegende Buchungen. Nützlich für Praxen, die die Planung flexibel halten möchten.
  • Day-of-week restrictions — begrenzen Sie, an welchen Tagen ein Provider über das Patientenportal buchbar ist (Personal kann sie an eingeschränkten Tagen weiterhin buchen). Nützlich für Spezialisten, die begrenzte Stunden arbeiten.
Best Practice: Beginnen Sie einfach. Fügen Sie erweiterte Regeln nur hinzu, wenn Sie einen Planungsschmerzpunkt identifizieren – fügen Sie beispielsweise Pufferminuten hinzu, wenn Provider Verwaltungszeit zwischen Patienten benötigen.

Dienstleistungen

Termintypen

Dienstleistungen (auch Termintypen genannt) definieren die Arten von Besuchen, die Ihre Praxis anbietet. Jede Dienstleistung hat:

  • Name — der Termintyp, der Personal und Patienten angezeigt wird (z. B. "Initial Consultation")
  • Duration — Standardlänge in Minuten. Wenn Sie einen Termin mit dieser Dienstleistung buchen, wird die Dauer vorab ausgefüllt (bei Bedarf pro Buchung anpassbar).
  • Description — optional. Erklärt, was der Termin beinhaltet. Wird Patienten im Portal angezeigt, um Erwartungen zu setzen.
Beispieldienste: "Initial Consultation (60 min)", "Follow-up Visit (30 min)", "Assessment (45 min)", "Lab Work (15 min)"

Dienstleistungen verwalten

Gehen Sie zu Settings → Services, um Dienstleistungen zu erstellen, zu bearbeiten oder zu archivieren. Sie können:

  • Neue Dienstleistungen erstellen — klicken Sie auf Add Service und füllen Sie Name, Dauer und optionale Beschreibung aus.
  • Dienstleistungen bearbeiten — klicken Sie auf das Stiftsymbol neben einer beliebigen Dienstleistung, um deren Details zu ändern.
  • Dienstleistungen archivieren — blenden Sie alte oder ungenutzte Dienstleistungen aus, ohne sie zu löschen. Archivierte Dienstleistungen können nicht gebucht werden, erscheinen aber in historischen Aufzeichnungen.

Berechtigungen: Owners und Admins können Dienstleistungen verwalten; Provider und Personal haben schreibgeschützten Zugriff.

Plandetails: Free beinhaltet eine Dienstleistung. Solo und höher schalten mehrere Dienstleistungen, optionale Termingebühren, Google Calendar-Synchronisierung und Stripe-betriebene bezahlte Buchung frei. Practice und höher fügen auch pro Service Pufferzeit hinzu.

Dienstleistungsseite mit Termintypen, Dauern und Aktionen zum Hinzufügen und Bearbeiten
Demo: Erstellen Sie eine neue Dienstleistung mit Dauer, Beschreibung, Preisgestaltung und Markenfarbe.

Teammitglieder

Teammitglieder einladen

Gehen Sie zu Settings → Members und klicken Sie auf Invite Member. Geben Sie deren vollständigen Namen, E-Mail und Rolle ein. So funktioniert es:

  • Eine Einladungs-E-Mail wird an den Posteingang des Teammitglieds mit einem Magic Link gesendet (kein Passwort erforderlich)
  • Sie klicken auf den Link und erhalten sofortigen Zugriff auf Ihre Praxis
  • Einladungen laufen nach 72 Stunden aus Sicherheitsgründen ab. Sie können ausstehende Einladungen auf der Members-Seite überprüfen und widerrufen.
  • Teammitgliederlimits werden gemäß Ihrem Plan durchgesetzt (siehe Abrechnung unten)
Tipp: Laden Sie Teammitglieder zuerst mit der niedrigsten erforderlichen Rolle ein. Sie können sie später bei Bedarf immer noch befördern.
Dialog zur Einladung eines Teammitglieds mit Feldern für vollständigen Namen, E-Mail und Rolle
Members-Seite mit Teamliste und ausstehenden Einladungen
Demo: Senden Sie eine Mitgliedereinladung und bestätigen Sie, dass sie in Pending invitations erscheint.

Rollen & Berechtigungen

Genkō hat vier Personalrollen. Jede Rolle hat unterschiedliche Zugriffsebenen:

  • Owner — vollständiger Zugriff auf alles, einschließlich Abrechnung, Organisationseinstellungen und Teamverwaltung. Jede Organisation hat genau einen Owner. Kann Eigentum übertragen oder die Organisation löschen.
  • Admin — gleicher Zugriff wie Owner, außer dass er kein Eigentum übertragen, die Organisation löschen, das Stripe-Auszahlungskonto verbinden oder ändern oder auf erweiterte Compliance-Funktionen zugreifen kann. Gut für Praxismanager.
  • Provider — kann ihren eigenen Zeitplan und Termine anzeigen und verwalten. Kann Patientenakten lesen, aber keine Mitglieder, Abrechnung oder Organisationseinstellungen ändern. Gut für Kliniker, die die Praxis nicht verwalten.
  • Staff — kann Termine verwalten und Patienten-/Provider-Informationen lesen. Kann keine Mitglieder, Abrechnung, Einstellungen oder Provider-Informationen ändern. Gut für Planer und Verwaltungsassistenten.

Teamlimits: Ihr Plan beinhaltet eine maximale Anzahl von Personalmitgliedern; der Owner zählt dabei mit. Owners und Admins können die Rolle eines Mitglieds ändern oder es jederzeit von der Members-Seite entfernen.

Patientenprivatsphäre: Jede Rolle ist auf angemessene Informationen beschränkt. Patienten können keine Personaldetails sehen – nur Provider-Namen und Fachrichtungen (falls im Patientenportal).

Pläne & Abrechnung

Verfügbare Pläne

Genkō bietet sechs Stufen, die mit Ihrer Praxis wachsen. Jeder Plan enthält Terminplanung mit Echtzeit-Konflikterkennung, Provider-Verfügbarkeitsverwaltung, rollenbasierte Zugriffskontrolle und ein Patientenportal (in Free nur lesend; ab Solo können Patienten selbst buchen).

PlanMonatlichJährlichPatientenPersonalOrganisationen
Free$0—10031
Solo$49$49025041
Starter$79$79075081
Group$139$1.3902.000155
Practice$279$2.7907.5004010
Network$549$5.49010.000Unbegrenzt25

Erweiterte Funktionen werden freigeschaltet, wenn Sie skalieren; jeder Plan enthält alles aus den darunterliegenden Plänen:

  • Solo und höher: Mehrere Dienstleistungen, Termingebühren und Stripe-Zahlungserfassung, Self-Service-Buchung für Patienten, Terminbestätigungen per E-Mail, Google Calendar-Synchronisierung (jeder Provider verbindet seinen eigenen) und ein 90-Tage-Audit-Log
  • Starter und höher: Klinische Notizen, longitudinale Patientenakten, WhatsApp-Bestätigungen und -Erinnerungen, auf die Patienten antworten können (bestätigen oder einen Link zum Verschieben/Absagen erhalten), und HubSpot-CRM-Synchronisierung
  • Group und höher: Analytics, Intake-Formulare vor dem Besuch, der Dashboard-KI-Assistent sowie die REST-API und die MCP-API (nur lesend, je 1 Schlüssel pro Art)
  • Practice und höher: Terminerinnerungen per E-Mail und SMS, Prüfung und Freigabe von Intake-Formularen, der KI-Assistent im Patientenportal, das einbettbare Chat-Widget für Ihre Website, erweiterte Planungsregeln sowie Lese- und Schreibzugriff auf REST- und MCP-API (je 3 Schlüssel pro Art)
  • Network: Klinische Datensätze, Patientenlöschung, Batch-Endpunkte und signierte Webhooks in der REST-API, Admin-Schlüssel ohne Schlüssellimit, bis zu 25 Organisationen, ein granulares Audit-Log über 365 Tage, dediziertes Onboarding und SLA-gestützter Support
Jahresrabatt: Zahlen Sie für 10 Monate, erhalten Sie 12 – rund 17 % Ersparnis (zwei Monate gratis) bei Jahresplänen.

Upgrade oder Downgrade

Gehen Sie zu Settings → Billing, um Ihren Plan zu verwalten. Nur der Owner der Organisation kann diese Seite öffnen. Der Plan gehört Ihnen als Owner: Neue Organisationen, die Sie anlegen, starten mit Ihrem aktuell höchsten Plan und teilen dessen Abonnement, sodass eine Planänderung für alle Organisationen dieses Abonnements gilt (Patienten- und Personallimits werden weiterhin pro Organisation gezählt).

  • Upgrade: Klicken Sie beim gewünschten Plan auf Upgrade to <plan>. Bei Ihrem ersten kostenpflichtigen Plan werden Sie zu Stripe Checkout geleitet; haben Sie bereits ein Abonnement, bestätigen Sie die Änderung, sie gilt sofort und die anteilige Differenz wird direkt berechnet.
  • Downgrade: Klicken Sie bei einem niedrigeren kostenpflichtigen Plan auf Downgrade to <plan>. Auch das gilt sofort und Stripe berechnet anteilig. Es ist blockiert, solange Ihre aktuelle Nutzung (Patienten oder Personal) über den Limits des neuen Plans liegt – reduzieren Sie sie zuerst. Für Free gibt es keinen Downgrade-Button: Kündigen Sie das Abonnement im Abrechnungsportal (unten).
  • Abrechnungsintervall: Nutzen Sie den Schalter Monthly / Yearly über den Plänen; das gewählte Intervall gilt, wenn Sie einen Plan auswählen.
Vor dem Downgrade: Überprüfen Sie Ihre aktuelle Nutzung. Wenn Sie 600 Patienten haben und auf Solo (250 Limit) downgraden, müssen Sie die Patientenanzahl reduzieren oder erneut upgraden.

Abrechnungsportal

Nach dem Abonnieren verwalten Sie Abrechnungsdetails über das Stripe-Abrechnungsportal, das von Settings → Billing → Manage Subscription zugänglich ist:

  • Aktualisieren Sie Ihre Zahlungsmethode
  • Rechnungen und Quittungen anzeigen und herunterladen
  • Abonnement kündigen (Zugriff bleibt bis Periodenende bestehen)
  • Abrechnungsverlauf und bevorstehende Gebühren anzeigen

Berechtigungen: Nur der Owner der Organisation kann die Abrechnungseinstellungen (Plan, Zahlungsmethoden und Rechnungen) öffnen; Admins können das nicht. So bleiben die Zahlungsinformationen bei der Person, der das Abonnement gehört.

Patientenportal

Portal aktivieren

Das Patientenportal ermöglicht es Patienten, Termine selbst zu buchen, ohne dass Personal involviert ist, was den Verwaltungsaufwand reduziert und die Patientenfreundlichkeit verbessert.

So aktivieren Sie es:

  1. Gehen Sie zu Settings → Portal
  2. Schalten Sie Enable Patient Portal ein
  3. Ihre Praxis erhält eine eindeutige öffentliche Buchungs-URL: https://www.getgenko.com/portal/your-slug
  4. Teilen Sie diesen Link mit Patienten per E-Mail, Website, Terminbestätigungen oder anderswo
Portal-URL: Ihr Slug basiert auf Ihrem Organisationsnamen. Sie können ihn in den Portaleinstellungen anpassen.
Portaleinstellungsseite des Patienten mit Aktivierungsschalter und öffentlicher Buchungs-URL

Patienten-Selbstbuchung

Wenn Patienten Ihren Portallink besuchen, folgen sie einem einfachen Ablauf:

  1. Angebote durchsuchen: Verfügbare Dienstleistungen mit Beschreibungen und Provider mit Fachrichtungen/Biografien ansehen
  2. Dienstleistung & Provider auswählen: Wählen Sie, welche Dienstleistung sie möchten und wen sie bevorzugen (oder automatisch zuweisen)
  3. Datum & Uhrzeit wählen: Kalender zeigt nur verfügbare Slots basierend auf Provider-Verfügbarkeit und Planungsregeln. Schon vor der Auswahl ist jeder Tag nach Verfügbarkeit eingefärbt: grün hat freie Termine, bernsteinfarben nur noch wenige, ausgegraute Tage sind nicht buchbar
  4. Kontaktinformationen eingeben: Vorname, Nachname, E-Mail, Telefon. Kontoerstellung ist nicht erforderlich.
  5. Bestätigung: Patient erhält eine E-Mail mit Termindetails; Buchung erscheint sofort in Ihrem Kalender

Intelligente Zuordnung: Wenn die E-Mail des Patienten bereits in Ihrer Datenbank vorhanden ist, wird die Buchung automatisch mit seinem vorhandenen Datensatz verknüpft. Andernfalls wird ein neuer Patientendatensatz erstellt.

No-Shows reduzieren: Erinnerungen gehen am Vortag raus: per WhatsApp ab Starter (nach Aktivierung unter Settings → Notifications) sowie per E-Mail und SMS (an Patienten mit Einwilligung) ab Practice. Portalbuchungen senden ab Solo eine Bestätigungs-E-Mail.
Demo: Öffnen Sie die Portalvorschau aus den Einstellungen und gehen Sie dann durch den öffentlichen Buchungsablauf.

Buchungs-Widget & Buchungsbutton

Patienten können direkt auf Ihrer Website buchen, nicht nur im Portal. Beide Optionen öffnen denselben Buchungsablauf wie Ihr Portal – mit Ihren Leistungen, Providern, Verfügbarkeitsfarben und Planungsregeln.

Öffnen Sie Settings → Integrations → Online-Buchung. Wählen Sie optional eine Leistung und/oder einen Provider vor und kopieren Sie den Code. Ihr Patientenportal muss aktiviert sein.

Buchungs-Widget (eingebettet)

Fügen Sie dies dort ein, wo der Buchungsablauf erscheinen soll. Er lädt in einem Frame auf Ihrer Seite und passt seine Höhe jedem Schritt an:

<div data-genko-book="your-slug"></div>
<script src="https://www.getgenko.com/book.js" async></script>

Wenn Ihr Website-Baukasten Script-Tags entfernt, verwenden Sie ein einfaches iframe (feste Höhe):

<iframe src="https://www.getgenko.com/embed/book/your-slug" title="Book an appointment" loading="lazy" style="display:block;width:100%;height:820px;border:0"></iframe>

Bei einer Buchung löst das Widget das DOM-Ereignis genko:booked an seinem Container aus (event.detail.paymentRequired zeigt, ob noch eine Zahlung offen ist). Anmeldung, Passwort-Reset und Online-Zahlung öffnen sich in einem neuen Tab. Das Widget läuft immer abgemeldet und nutzt nie die Genkō-Sitzung eines Besuchers.

Buchungsbutton

Ein gestalteter Link, der Ihre Buchungsseite in einem neuen Tab öffnet – ohne Script, daher funktioniert er in jedem Website-Baukasten, jeder E-Mail-Signatur und jeder Link-in-Bio-Seite. Text, Farben, Stil, Form, Größe und Sprache der Buchungsseite wählen Sie im Editor:

<a href="https://www.getgenko.com/portal/your-slug/book" target="_blank" rel="noopener" style="display:inline-block;padding:12px 24px;border-radius:8px;border:2px solid #4f46e5;background:#4f46e5;color:#ffffff;font:600 16px/1.2 system-ui,-apple-system,BlinkMacSystemFont,Roboto,Helvetica,Arial,sans-serif;text-decoration:none;cursor:pointer">Book an appointment</a>
Online-Buchung, Widget und Button sind ab dem Solo-Tarif verfügbar.

Benachrichtigungen

Inhaber und Admins legen unter Settings → Notifications fest, welche WhatsApp-Nachrichten die Praxis sendet und welche Aktionen ein Patient per Antwort ausführen darf. Es ändert sich nichts, bis Sie es ändern: Alle Nachrichten und alle Antwortaktionen sind standardmäßig aktiv.

Welche Nachrichten gesendet werden

Der WhatsApp-Schalter (ab Starter, mit der Bestätigung zum Umgang mit Patientendaten) aktiviert den Nachrichtenversand der Praxis; er wurde aus Settings → Integrations hierher verschoben. Ist er aktiv, hat jede Nachrichtenart einen eigenen Schalter (ab Starter):

NachrichtWann sie gesendet wird
BuchungsbestätigungDirekt nach der Buchung eines Termins
Erinnerung am VortagAm Morgen vor dem Termin
Erinnerung am TermintagEinige Stunden vor dem Termin
Hinweis zur VerschiebungWenn ein Termin verschoben wird
Hinweis zur AbsageWenn ein Termin abgesagt wird

Schalten Sie eine Art aus, entfällt diese Nachricht per WhatsApp und ihr SMS-Fallback in Tarifen, die einen haben (ab Practice). Der Bereich E-Mail hat für jede Termin-E-Mail einen eigenen Schalter: Buchungsbestätigung, Erinnerung am Vortag, Erinnerung am selben Tag, Hinweis auf Verschiebung und Hinweis auf Absage. Die Schalter sind in jedem Tarif verfügbar und können eine E-Mail nur verhindern: Wer sich von E-Mails abgemeldet hat, erhält nie eine, egal was eingestellt ist. Konto-, Sicherheits-, Einladungs-, Beleg- und Besuchszusammenfassungs-E-Mails lassen sich nicht ausschalten.

Die Einstellung gilt für die ganze Praxis, nicht für einzelne Behandler oder Leistungen.

Was Patienten per Antwort tun können

Ab dem Tarif Group legen drei Schalter fest, welche Aktionen ein Patient per Antwort, Nachrichtenschaltfläche, Listenauswahl oder über den sicheren Link ausführen darf:

  • Den Termin bestätigen
  • Ihn verschieben (der Patient wählt einen neuen Zeitpunkt aus den freien Terminen)
  • Ihn absagen

Bei Starter und Solo sind sie auf „aktiv“ gesperrt: Patienten können alle drei nutzen, wie bisher. Der Tarif wird bei jeder eingehenden Nachricht geprüft, ein Downgrade gilt also sofort.

Der sichere Link und was Patienten sehen

Nachrichten und E-Mails enthalten einen persönlichen Link, /portal/ihre-praxis/appointment/…, der einen Termin ohne Login öffnet, damit der Patient ihn bestätigen, einen neuen Zeitpunkt wählen oder absagen kann.

  • Eine deaktivierte Aktion wird auf der Link-Seite ausgeblendet, und die Seite erklärt, dass die Praxis sie direkt erledigt.
  • Antwortet ein Patient mit einer deaktivierten Aktion, ändert sich nichts. Er erhält eine höfliche Nachricht mit dem Namen Ihrer Praxis und, falls hinterlegt, Ihrer Telefonnummer und E-Mail-Adresse. Der Link wird nur beigefügt, wenn noch eine andere Aktion erlaubt ist.
  • Im Patientenportal angemeldete Patienten können dort weiterhin bis 24 Stunden vorher absagen; diese Schalter steuern das nicht.
Änderungen werden mit den geänderten Schlüsseln im Audit-Protokoll festgehalten. Für diese Einstellungen gibt es keinen REST- oder MCP-Endpunkt; sie werden im Dashboard verwaltet.

Analytics & Insights

Das Analytics-Dashboard bietet Ihnen Echtzeit-Einblick in die Leistung Ihrer Praxis. Verfolgen Sie Terminmuster, Provider-Produktivität, No-Show-Raten, Patientenwachstum und mehr über jeden Datumsbereich. Alle Daten sind als CSV oder Excel exportierbar für tiefere Analysen oder Integration mit externen Reporting-Tools.

Plananforderung: Analytics ist ab dem Group-Plan verfügbar. Free-, Solo- und Starter-Pläne haben keinen Zugriff auf Analytics.

Dashboard-Übersicht

Die Analytics-Seite befindet sich unter Overview → Analytics (oder direkt über die Schnelllinks in Ihrem Dashboard). Sie zeigt sieben Schlüsselleistungsindikatoren oben, gefolgt von interaktiven Aufschlüsselungen Ihrer Daten.

Hauptbereich: Zeigt eine Vorschau der Daten für den ausgewählten Datumsbereich. Klicken Sie auf View full analytics, um zu erweitern und alle verfügbaren Metriken und Filter anzuzeigen.

Datumsbereich und Voreinstellungen

Analytics unterstützt zwei Möglichkeiten, einen Datumsbereich auszuwählen:

  • Voreinstellungen: Schnelle Shortcuts für gängige Perioden — Today, Yesterday, Last 7 days, Last 30 days, Last 90 days, This month, Last month, This year
  • Benutzerdefinierter Bereich: Wählen Sie beliebige Start- und Enddaten, um bestimmte Perioden zu vergleichen (z. B. Vergleich zweier Monate oder Vergleich der Leistung vor/nach einer Prozessänderung)

Das Dashboard aktualisiert sich sofort, wenn Sie den Datumsbereich ändern.

Schlüsselleistungsindikatoren

Der obere Bereich zeigt sieben KPIs für Ihren ausgewählten Zeitraum:

  • Total appointments: Anzahl aller Termine im Zeitraum (einschließlich abgeschlossener, No-Shows und stornierter)
  • Completed appointments: Anzahl erfolgreich abgeschlossener Besuche
  • No-shows: Anzahl der als No-Show markierten Termine
  • Cancelled appointments: Anzahl stornierter Besuche (durch Personal oder Patient)
  • Completion rate: Prozentsatz der Gesamttermine, die abgeschlossen wurden (abgeschlossen ÷ gesamt)
  • No-show rate: Prozentsatz der Gesamttermine, die No-Shows waren (No-Shows ÷ gesamt)
  • New patients: Anzahl neuer Patientenregistrierungen im Zeitraum

Aufschlüsselungen und Filter

Unterhalb der KPIs können Sie Daten aufgeschlüsselt nach:

  • By day: Ein Liniendiagramm zeigt Terminvolumen und Abschlussraten für jeden Tag im ausgewählten Bereich
  • By appointment type: Sehen Sie, welche Dienstleistungen am beliebtesten sind und deren No-Show-Raten
  • By provider: Vergleichen Sie Provider-Produktivität, Abschlussraten und No-Show-Raten
  • By status: Aufschlüsselung der Termine nach Status (abgeschlossen, No-Show, storniert, geplant)

Jede Aufschlüsselung ist interaktiv – klicken Sie auf ein Segment, um tiefer zu gehen oder das gesamte Dashboard nach diesem Wert zu filtern.

Daten exportieren

Alle Analytics-Daten können für externe Analysen, Berichte oder Integration exportiert werden:

  1. Klicken Sie auf Export oben rechts
  2. Wählen Sie Format: CSV (öffnet in Tabellenkalkulationen wie Excel) oder Excel (erstellt eine herunterladbare .xlsx-Datei)
  3. Die Datei enthält alle KPIs und Aufschlüsselungsdaten für den ausgewählten Zeitraum
Externe Analyse: Exportieren Sie nach CSV oder Excel und verwenden Sie dann Tools wie Google Sheets, Power BI oder Tableau, um benutzerdefinierte Berichte oder Visualisierungen über das hinaus zu erstellen, was in Genkō verfügbar ist.

Integrationen

Google Calendar-Synchronisierung

Jeder Provider verbindet seinen eigenen Google Calendar. Genkō synchronisiert dann die diesem Provider zugewiesenen Termine mit diesem Kalender, sodass der Zeitplan an einem Ort steht, egal ob er Genkō oder Google Calendar öffnet.

So verbinden Sie (jeder Provider für sich selbst):

  1. Gehen Sie zu Settings → Integrations
  2. Klicken Sie auf Meinen Kalender verbinden und melden Sie sich mit dem Google-Konto an, mit dem Sie synchronisieren möchten
  3. Gewähren Sie Genkō die Berechtigung, Ereignisse in Ihrem Kalender zu erstellen und zu ändern — die Synchronisierung beginnt mit dem nächsten Termin

Wer verbinden kann: Owner, Admins und Provider mit einem Provider-Profil in der Praxis. Mitarbeitende (Staff) können das nicht, ebenso wenig Owner oder Admins ohne Provider-Profil — für ihren Kalender gäbe es nichts zu synchronisieren.

Was synchronisiert wird (in eine Richtung, von Genkō zu Google): nach dem Verbinden gebuchte Termine, Zeitänderungen und Stornierungen. Wird ein Termin einem anderen Provider zugewiesen, wechselt das Ereignis in dessen Kalender. Ein Provider ohne verbundenen Kalender erhält keine Ereignisse; einen gemeinsamen Praxiskalender gibt es nicht.

Was ein Ereignis enthält: standardmäßig nur Termin — Name Ihrer Praxis und die Uhrzeit. Kein Patientenname, keine Notizen, und der Patient wird nicht per E-Mail eingeladen. Ein Admin kann unter Settings → Integrations Vollständige Patientendetails in Kalenderereignissen aktivieren; dann enthalten Ereignisse den Patientennamen, die Leistung und die Notizen, und der Patient erhält eine Kalendereinladung.

Das persönliche Google-Konto eines Providers wird von den Vereinbarungen Ihrer Praxis nicht abgedeckt. Aktivieren Sie die vollständigen Details nur, wenn Ihre Compliance-Richtlinie Patienteninformationen dort erlaubt.

Plananforderung: Google Calendar-Synchronisierung ist ab dem Solo-Plan verfügbar. Sie wird beim Verbinden und bei jeder Synchronisierung geprüft; bei einem Downgrade pausiert die Synchronisierung und die Verbindungen bleiben erhalten.

Trennen: Jeder kann den eigenen Kalender unter Settings → Integrations trennen; Owner und Admins können außerdem die Verbindung jedes Mitglieds einsehen und trennen. Ein Kalender wird automatisch getrennt, wenn sein Inhaber die Praxis verlässt, in eine Rolle wechselt, die keinen Kalender verbinden darf, oder sein Konto löscht. Vergangene Ereignisse in Google Calendar bleiben unberührt.

Integrationsseite mit der Google Calendar-Verbindungskarte

REST-API (v1)

Was ist die REST-API?

Mit der Genkō-REST-API können Ihr ERP, EHR, Abrechnungssystem oder Ihre Skripte dieselben Terminplanungsdaten lesen und schreiben, die Sie im Dashboard sehen: Patienten, Termine, Leistungen und Provider-Zeitpläne. Sie spricht JSON über HTTPS unter https://www.getgenko.com/api/v1 und wird mit einem API-Schlüssel authentifiziert.

Sie folgt den gleichen Datenregeln wie MCP (nächster Abschnitt), verwendet aber eigene Schlüssel: ein REST-API-Schlüssel funktioniert nur unter /api/v1, ein MCP-Schlüssel nur unter /api/mcp. REST-API-Schlüssel werden unter Settings → Developers → REST API keys erstellt.

Eine maschinenlesbare Beschreibung aller Endpunkte, Schemas und Fehler wird als OpenAPI 3.1 unter https://www.getgenko.com/api/v1/openapi.json bereitgestellt. Importieren Sie sie in Postman oder Insomnia oder erzeugen Sie eine Client-Bibliothek in Ihrer Sprache. Sie wird aus der API selbst generiert und ist daher immer aktuell.

Plananforderungen: Lesen ist ab dem Group-Plan möglich, Schreiben ab Practice; klinische Datensätze, das Löschen von Patienten und die Batch-Endpunkte erfordern Network. Der Plan wird bei jeder Anfrage geprüft, ein Downgrade wirkt also innerhalb einer Minute: der Schlüssel wird nicht widerrufen, die Endpunkte stehen nur nicht mehr zur Verfügung.

Authentifizierung und Bereiche

Senden Sie den Schlüssel im Authorization-Header. Ein Schlüssel in der URL wird abgelehnt, weil URLs in Logs landen; falls Sie je einen Schlüssel in eine URL gesetzt haben, widerrufen Sie ihn.

curl "https://www.getgenko.com/api/v1/patients?limit=10" \
  -H "Authorization: Bearer genko_YOUR_KEY_HERE"
Nur REST-API-Schlüssel: ein MCP-Schlüssel (genko_mcp_…), der an /api/v1 gesendet wird, wird mit 401 UNAUTHORIZED und details.key_kind: "mcp" abgelehnt. Das Schlüssellimit gilt pro Art: Group 1, Practice 3, Network unbegrenzt viele REST-API-Schlüssel – zusätzlich zu Ihren MCP-Schlüsseln.

Schlüssel laufen nach 365 Tagen ab, sofern Sie kein früheres Datum wählen. Eine Anfrage außerhalb der Bereiche eines Schlüssels liefert 403 FORBIDDEN mit details.required_scope, der den fehlenden Bereich nennt:

  • Read-Schlüssel: scheduling:read, patients:read, services:read, providers:read (Group+)
  • Read & Write-Schlüssel: zusätzlich scheduling:write, patients:write, services:write, providers:write (Practice+)
  • Admin-Schlüssel: zusätzlich patients:delete, clinical:read und clinical:write (Network)

Beim Erstellen eines Schlüssels können Sie statt eines Presets auch einzelne Bereiche wählen, ihn auf bestimmte IP-Adressen beschränken (eine Liste von Adressen oder CIDR-Bereichen; Anfragen von anderswo erhalten 403 FORBIDDEN) und ihm ein eigenes Limit an Anfragen pro Minute geben (1–10.000; Schreibzugriffe erhalten ein Fünftel davon, und die organisationsweite Obergrenze gilt weiterhin). Ein Bereich, den Ihr Plan nicht enthält, kann nicht gewählt werden.

GET /api/v1 liefert, wem der Schlüssel gehört, welche Bereiche jetzt funktionieren und welche Limits gelten.

Klinische Felder: Name, Kontaktdaten und Geburtsdatum sind für jeden Schlüssel verfügbar, der Patienten lesen darf. Notizen, Allergien, Diagnosen, Medikamente, Versicherung, Notfallkontakt und Adresse sind klinisch: sie werden nur mit clinical:read / clinical:write zurückgegeben bzw. geschrieben. Einträge zu Allergien, Diagnosen und Medikamenten sind Freitext (name) mit optionaler Kodierung: code + system gemeinsam, dazu display, status, onset, abatement (Diagnosen und Medikamente), recorded_at und recorded_by. Diagnosen kodieren Sie mit ICD-10-CM (system: "http://hl7.org/fhir/sid/icd-10-cm", Code mit Punkt wie J45.909). Jede Liste ersetzt die gespeicherte.

Anfragen, Antworten und Fehler

Jede Antwort ist JSON im selben Envelope, mit Cache-Control: no-store und einer X-Request-Id, die Sie dem Support nennen können:

{ "data": { … }, "error": null, "meta": { "request_id": "…" } }
{ "data": null, "error": { "code": "NOT_FOUND", "message": "Patient not found" }, "meta": { "request_id": "…" } }
  • Senden Sie Content-Type: application/json. Bodies sind auf 1 MB begrenzt.
  • Unbekannte Felder und unbekannte Query-Parameter werden abgelehnt (400 VALIDATION_ERROR), statt ignoriert zu werden, damit ein Tippfehler nie stillschweigend etwas Falsches bewirkt.
  • Zeitstempel sind ISO-8601 in UTC. Bereiche sind halboffen: from ist inklusive, to exklusive, sodass angrenzende Bereiche nie doppelt zählen.
  • Verzweigen Sie nach error.code, nie nach der Meldung: VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, PLAN_LIMIT, NOT_FOUND, CONFLICT, DUPLICATE, INVALID_TRANSITION, DAILY_LIMIT_REACHED, PRECONDITION_FAILED, RATE_LIMITED, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_PROGRESS, INTERNAL. Veröffentlichte Codes werden nie umbenannt.
  • Tarifnamen: enterprise ist der stabile Bezeichner des Network-Tarifs (er stammt aus der Zeit vor der Umbenennung). Das steht in details.required_plan eines PLAN_LIMIT-Fehlers und im Feld plan von GET /api/v1; diese Werte werden nie umbenannt.
  • Ein Datensatz einer anderen Organisation ist von einem nicht existierenden nicht zu unterscheiden: beide liefern 404.
  • Idempotenz: senden Sie bei jedem POST, PATCH oder DELETE einen Idempotency-Key-Header (1-128 Zeichen). Eine Wiederholung mit demselben Schlüssel und derselben Anfrage liefert die ursprüngliche Antwort (markiert mit Idempotent-Replayed: true), ohne die Arbeit zu wiederholen; derselbe Schlüssel mit anderer Anfrage ergibt 422 IDEMPOTENCY_KEY_REUSED; ein Duplikat, das eintrifft, solange die erste Anfrage läuft, ergibt 409 IDEMPOTENCY_IN_PROGRESS. Nur erfolgreiche Antworten werden 24 Stunden gespeichert, eine fehlgeschlagene Anfrage kann also einfach wiederholt werden. Ist der Idempotenz-Speicher nicht erreichbar, antwortet die API mit 503, statt ein doppeltes Schreiben zu riskieren: versuchen Sie es kurz danach erneut. Das Anlegen eines Datensatzes mit bereits vorhandener external_id liefert den vorhandenen Datensatz, auch ohne den Header.
  • Ratenlimits pro Schlüssel und Minute: Group 60 Lese- / 12 Schreibzugriffe, Practice 300 / 60, Network 600 / 180, dazu eine organisationsweite Obergrenze für alle Schlüssel. Jede Antwort enthält RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset; bei Überschreitung folgt 429 mit Retry-After.

Paginierung und Synchronisierung

Listen verwenden Keyset-Cursor, nie Offsets: Seite 1.000 kostet dasselbe wie Seite 1, und Zeilen werden bei sich ändernden Daten weder übersprungen noch wiederholt. Übergeben Sie limit (Standard 100, maximal 500) und folgen Sie meta.next_cursor, bis meta.has_more false ist. Ein Cursor ist an seine Filter gebunden; Änderungen ergeben 400 INVALID_CURSOR: ohne Cursor neu beginnen.

  • Erstabgleich: blättern Sie GET /patients?limit=500 und GET /appointments?limit=500 bis zum Ende durch.
  • Inkrementeller Abgleich: merken Sie sich das höchste gesehene updated_at und fragen Sie beim nächsten Mal ?updated_since=<dieser Wert minus 60 Sekunden> ab. Überlappen Sie immer um 60 Sekunden und führen Sie ein Upsert per id oder external_id durch: eine Transaktion, die vor Ihrem letzten Lesen begann, kann danach committen.
  • Löschungen erscheinen nicht in updated_since. Abonnieren Sie die Webhooks patient.deleted und appointment.deleted und gleichen Sie gelegentlich ab, indem Sie ?fields=id&limit=500 durchblättern und mit Ihrer Kopie vergleichen. Archivierungen erscheinen dagegen (archived_at wird gesetzt, updated_at ändert sich), archivierte Patienten fehlen aber in Listen, außer mit include_archived=true; patient.archived und patient.restored melden sie.
  • external_id ist Ihre Kennung für Patienten, Termine, Leistungen und Provider; sie ist innerhalb Ihrer Organisation eindeutig und dient zum Filtern, Anlegen und Upsert.

Endpunkte

Alle Pfade sind relativ zu /api/v1. Lesen erfordert den passenden :read-Bereich, Schreiben den :write-Bereich, sofern nicht anders angegeben.

Patienten

  • GET /patients — Liste, mit q (mind. 3 Zeichen), email, phone, mrn, external_id, updated_since, sort, fields
  • GET /patients/:id — ein Patient
  • POST /patients — anlegen; eine vorhandene external_id liefert diesen Patienten
  • PATCH /patients/:id — ändert nur, was Sie senden; null leert ein Feld
  • POST /patients/upsert — anlegen oder aktualisieren per external_id
  • POST /patients/batch — bis zu 500 Patienten pro Aufruf mit Ergebnis je Element (Network)
  • DELETE /patients/:id — klinische Unterlagen bleiben erhalten: Ein Patient mit Terminen oder klinischen Daten wird archiviert (aus Listen ausgeblendet, kommende Termine storniert, Akte bis retain_until aufbewahrt); ein Patient ohne Vorgeschichte wird gelöscht. Die Antwort nennt das Ergebnis (result). cascade ist veraltet und wird ignoriert (Verhaltensänderung, Oktober 2026). Network, patients:delete

Termine

  • GET /appointments — Liste, mit provider_id, patient_id, service_id, status, from, to, updated_since, external_id, expand
  • GET /appointments/:id — ein Termin
  • POST /appointments — buchen (konfliktgeprüft); notify, external_id und status zum Import von Verlaufsdaten
  • PATCH /appointments/:id — Status ändern oder verschieben, optional abgesichert mit If-Match: <updated_at> (412, wenn er sich geändert hat)
  • POST /appointments/:id/cancel — stornieren; Wiederholen ist harmlos
  • POST /appointments/batch — bis zu 500 Termine pro Aufruf, Upsert per external_id (Network)

Leistungen und Provider

  • GET|POST /services — Leistungstypen auflisten und anlegen
  • GET|PATCH|DELETE /services/:id — lesen, ändern, löschen; eine von Terminen genutzte Leistung zu löschen erfordert ?force=true
  • GET /providers, GET /providers/:id — Name, Fachrichtung, Zeitzone, Wochenzeiten und Buchungsregeln (nie Benutzer-IDs oder E-Mails)
  • PATCH /providers/:id — Zeiten, Buchungsregeln und external_id aktualisieren (Provider werden im Dashboard per Einladung angelegt)
  • GET /providers/:id/availability — ?from=&to=&duration=&service_id=: freie Slots über bis zu 31 Tage mit einer Abfrage

Klinische Datensätze (Network, Admin-Schlüssel)

  • GET /patients/:id/record — die Besuche eines Patienten mit Notizen und Intake-Formularen
  • GET /patients/:id/documents — die Dokumente eines Patienten (Laborbefunde, Bildgebung, Einwilligungen, Überweisungen, Korrespondenz): nur Metadaten, neueste zuerst, stornierte Dokumente eingeschlossen und markiert. Dokumente lädt das Praxisteam im Dashboard hoch; über die API gibt es keinen Upload
  • GET /patients/:id/documents/:documentId — ein Dokument mit einer signierten Download-url, 60 Sekunden gültig (url_expires_at): sofort abrufen, nie speichern. Jeder Abruf wird im Audit-Log protokolliert (document.viewed)
  • GET|POST /appointments/:id/notes — klinische Notizen auflisten und anlegen. Eine Notiz kann vitals enthalten (Blutdruck, Herz- und Atemfrequenz, Temperatur, SpO₂, Gewicht, Größe, Schmerz 0–10): Zahlen oder { value, unit } senden; Genkō speichert jeden Wert mit UCUM-Einheit und LOINC-Code und berechnet den BMI. Vitalwerte sind nach der Signatur mit der Notiz gesperrt. Eine Notiz kann außerdem mit einer Fachvorlage geschrieben werden: template_key (dental.tooth-chart@1, mental-health.mse@1, mental-health.phq9@1, mental-health.gad7@1, physio.assessment@1, optometry.eye-exam@1, vet.exam@1, medspa.treatment@1) mit den zugehörigen template_data, die gegen das Schema der Vorlage geprüft werden (NoteTemplateData im OpenAPI-Dokument); Genkō berechnet die PHQ-9- und GAD-7-Summen und Schweregrade sowie den logMAR jeder Sehschärfe, prüft vitals.weight einer vet.exam@1-Notiz gegen die Tierart, und die Vorlage ist nach der Signatur mit der Notiz gesperrt
  • GET|PATCH|DELETE /appointments/:id/notes/:noteId — eine Notiz lesen; einen Entwurf bearbeiten oder verwerfen (eine im Dashboard signierte Notiz ist gesperrt: 409 NOTE_LOCKED)
  • POST /appointments/:id/notes/:noteId/addenda — einer signierten Notiz einen Nachtrag als Entwurf hinzufügen. Schlüssel schreiben nur Entwürfe; Fachkräfte signieren im Dashboard
  • GET /appointments/:id/intake, POST /appointments/:id/intake/review — ein eingereichtes Intake-Formular lesen, genehmigen oder ablehnen

Webhooks (Network, webhooks:manage)

  • GET|POST /webhooks — Endpunkte auflisten und anlegen (das Signatur-Secret wird einmal zurückgegeben)
  • GET|PATCH|DELETE /webhooks/:id — einen Endpunkt lesen, ändern (URL, Ereignisse, active) oder löschen
  • POST /webhooks/:id/rotate-secret — neues Secret; ?grace_hours= hält das alte in der Zwischenzeit gültig
  • POST /webhooks/:id/test — sofort ein signiertes Testereignis senden und die Antwort sehen
  • GET /webhooks/:id/deliveries — Zustellverlauf mit Status, Versuchen und letztem Fehler
  • POST /webhooks/:id/deliveries/:deliveryId/redeliver — eine abgeschlossene Zustellung erneut senden

Wichtiges Verhalten

  • Benachrichtigungen: Buchen, Verschieben und Stornieren senden die üblichen Patienten-E-Mails/SMS und aktualisieren Google Calendar. Kontaktiert Ihr System die Patienten bereits selbst, senden Sie notify: false (bzw. ?notify=false beim Stornieren). Batches benachrichtigen nie.
  • Statusregeln: scheduled → confirmed → completed sowie cancelled oder no_show. Abgeschlossene Termine bleiben abgeschlossen: eine Änderung liefert 409 INVALID_TRANSITION. Zeit- und Statusänderung werden in getrennten Anfragen gesendet.
  • Batches antworten mit 200 und einem Ergebnis je Element (created, updated oder error mit stabilem Code). Ein fehlerhaftes Element lässt die anderen nie scheitern, und das erneute Senden desselben Batches ist sicher.
  • Klinischer Zugriff wird protokolliert: jedes Lesen und Schreiben klinischer Datensätze erzeugt einen detaillierten Audit-Log-Eintrag (nur IDs, nie der Inhalt).

Beispiele für Anfragen und Antworten

Jedes Beispiel zeigt das exakte JSON, das Ihre Integration sendet und empfängt. Die Werte sind beispielhaft, und jede Anfrage trägt zusätzlich den oben gezeigten Authorization-Header. Öffnen Sie eine Gruppe, um ihre Aufrufe zu sehen.

Konto1
GET/

Anfrage

GET /api/v1

Antwort 200 OK

{
  "data": {
    "version": "v1",
    "organization": {
      "id": "6a1d3f58-92c4-4b7e-8d05-f3e27c9b1a40",
      "name": "Ruiz Physio",
      "slug": "ruiz-physio",
      "timezone": "America/Mexico_City"
    },
    "plan": "enterprise",
    "key": {
      "id": "9e05c7b2-14d8-4a36-b7f9-20c8e5a1d463",
      "name": "ERP sync",
      "expires_at": "2027-09-19T00:00:00.000000+00:00",
      "ip_restricted": true,
      "scopes": [
        "patients:read",
        "patients:write",
        "scheduling:read",
        "scheduling:write",
        "services:read",
        "services:write",
        "providers:read",
        "providers:write"
      ],
      "declared_scopes": [
        "patients:read",
        "patients:write",
        "scheduling:read",
        "scheduling:write",
        "services:read",
        "services:write",
        "providers:read",
        "providers:write"
      ]
    },
    "limits": {
      "requests_per_minute": {
        "read": 600,
        "write": 180,
        "organization": 3000
      },
      "page_size": {
        "default": 100,
        "max": 500
      },
      "max_body_bytes": 1048576
    }
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
Patienten7
GET/patients

Anfrage

GET /api/v1/patients?q=garcia&limit=2

Antwort 200 OK

{
  "data": [
    {
      "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
      "external_id": "ERP-P-1042",
      "medical_record_number": "MRN-20418",
      "full_name": "Ana García López",
      "email": "ana.garcia@example.com",
      "phone": "+14155550123",
      "date_of_birth": "1988-04-12",
      "sex": "female",
      "preferred_language": "es",
      "sms_opt_in": true,
      "archived_at": null,
      "created_at": "2026-09-01T15:04:05.123456+00:00",
      "updated_at": "2026-09-19T10:31:47.482913+00:00",
      "given_names": "Ana",
      "first_surname": "García",
      "second_surname": "López",
      "name_parts_confirmed_at": "2026-09-19T10:31:47.482913+00:00",
      "birth_country": "MX",
      "birth_state": "09"
    },
    {
      "id": "2b9e6d40-7c15-4a83-b0f6-e3a1d8c47952",
      "external_id": null,
      "medical_record_number": null,
      "full_name": "Marco García",
      "email": null,
      "phone": "+14155550188",
      "date_of_birth": null,
      "sex": null,
      "preferred_language": "en",
      "sms_opt_in": false,
      "created_at": "2026-09-01T15:04:05.123456+00:00",
      "updated_at": "2026-09-01T15:04:05.123456+00:00"
    }
  ],
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05",
    "next_cursor": "eyJ2IjoxLCJzIjoidXBkYXRlZF9hdCIsImQiOiJhc2MifQ.q8Zt1c",
    "has_more": true,
    "limit": 2
  }
}
GET/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23

Anfrage

GET /api/v1/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23?fields=id,full_name,email

Antwort 200 OK

{
  "data": {
    "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "full_name": "Ana García López",
    "email": "ana.garcia@example.com"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/patients

Anfrage· Pflichtfelder: full_name

POST /api/v1/patients
Idempotency-Key: erp-patient-1042-create
Content-Type: application/json

{
  "full_name": "Ana García López",
  "external_id": "ERP-P-1042",
  "email": "ana.garcia@example.com",
  "phone": "(415) 555-0123",
  "date_of_birth": "1988-04-12",
  "preferred_language": "es",
  "sms_opt_in": true
}

Antwort 201 Created

{
  "data": {
    "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "external_id": "ERP-P-1042",
    "medical_record_number": "MRN-20418",
    "full_name": "Ana García López",
    "email": "ana.garcia@example.com",
    "phone": "+14155550123",
    "date_of_birth": "1988-04-12",
    "sex": "female",
    "preferred_language": "es",
    "sms_opt_in": true,
    "archived_at": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00",
    "given_names": "Ana",
    "first_surname": "García",
    "second_surname": "López",
    "name_parts_confirmed_at": "2026-09-19T10:31:47.482913+00:00",
    "birth_country": "MX",
    "birth_state": "09"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05",
    "created": true
  }
}

Antwort 200 OK (same external_id sent again)

{
  "data": {
    "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "external_id": "ERP-P-1042",
    "medical_record_number": "MRN-20418",
    "full_name": "Ana García López",
    "email": "ana.garcia@example.com",
    "phone": "+14155550123",
    "date_of_birth": "1988-04-12",
    "sex": "female",
    "preferred_language": "es",
    "sms_opt_in": true,
    "archived_at": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00",
    "given_names": "Ana",
    "first_surname": "García",
    "second_surname": "López",
    "name_parts_confirmed_at": "2026-09-19T10:31:47.482913+00:00",
    "birth_country": "MX",
    "birth_state": "09"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05",
    "created": false
  }
}
PATCH/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23

Anfrage

PATCH /api/v1/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23
Content-Type: application/json

{
  "phone": "+14155550199",
  "email": null,
  "conditions": [
    {
      "name": "Asthma",
      "code": "J45.909",
      "system": "http://hl7.org/fhir/sid/icd-10-cm",
      "display": "Unspecified asthma, uncomplicated",
      "status": "active",
      "onset": "2019-04"
    }
  ]
}

Antwort 200 OK (conditions needs clinical:write; with clinical:read the clinical fields are returned too)

{
  "data": {
    "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "external_id": "ERP-P-1042",
    "medical_record_number": "MRN-20418",
    "full_name": "Ana García López",
    "email": null,
    "phone": "+14155550199",
    "date_of_birth": "1988-04-12",
    "sex": "female",
    "preferred_language": "es",
    "sms_opt_in": true,
    "archived_at": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00",
    "given_names": "Ana",
    "first_surname": "García",
    "second_surname": "López",
    "name_parts_confirmed_at": "2026-09-19T10:31:47.482913+00:00",
    "birth_country": "MX",
    "birth_state": "09"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/patients/upsert

Anfrage· Pflichtfelder: full_nameexternal_id

POST /api/v1/patients/upsert
Content-Type: application/json

{
  "external_id": "ERP-P-1042",
  "full_name": "Ana García López",
  "phone": "+14155550123"
}

Antwort 200 OK

{
  "data": {
    "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "external_id": "ERP-P-1042",
    "created": false
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Antwort 201 Created (new external_id)

{
  "data": {
    "id": "5d0c8e37-a1b4-4f92-86c3-7e1a09b2d548",
    "external_id": "ERP-P-1043",
    "created": true
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/patients/batch

Anfrage· Pflichtfelder: items

POST /api/v1/patients/batch
Content-Type: application/json

{
  "items": [
    {
      "external_id": "ERP-P-1042",
      "full_name": "Ana García López",
      "phone": "+14155550123"
    },
    {
      "external_id": "ERP-P-1043",
      "full_name": "Luis Herrera"
    },
    {
      "external_id": "ERP-P-1044",
      "full_name": "Sofía Vega",
      "email": "not-an-email"
    }
  ]
}

Antwort 200 OK

{
  "data": {
    "results": [
      {
        "index": 0,
        "status": "updated",
        "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23"
      },
      {
        "index": 1,
        "status": "created",
        "id": "5d0c8e37-a1b4-4f92-86c3-7e1a09b2d548"
      },
      {
        "index": 2,
        "status": "error",
        "id": null,
        "error": {
          "code": "VALIDATION_ERROR",
          "message": "Invalid email address",
          "field": "email"
        }
      }
    ],
    "summary": {
      "created": 1,
      "updated": 1,
      "failed": 1
    }
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
DELETE/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23

Anfrage

DELETE /api/v1/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23

Antwort 200 OK (patient with history: archived, record retained)

{
  "data": {
    "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "result": "archived",
    "deleted": false,
    "archived": true,
    "retain_until": "2036-10-06T15:02:11Z",
    "cancelled_appointments": 1
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Antwort 200 OK (patient with no history)

{
  "data": {
    "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "result": "deleted",
    "deleted": true,
    "archived": false,
    "retain_until": null,
    "cancelled_appointments": 0
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
Termine6
GET/appointments

Anfrage

GET /api/v1/appointments?from=2026-10-05T00:00:00Z&to=2026-10-06T00:00:00Z&status=scheduled&expand=patient,service&limit=1

Antwort 200 OK

{
  "data": [
    {
      "id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
      "external_id": "ERP-APPT-9001",
      "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
      "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
      "service_id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
      "starts_at": "2026-10-05T14:00:00+00:00",
      "ends_at": "2026-10-05T14:45:00+00:00",
      "status": "scheduled",
      "notes": "Follow-up on lab results",
      "created_at": "2026-09-01T15:04:05.123456+00:00",
      "updated_at": "2026-09-19T10:31:47.482913+00:00",
      "patient": {
        "id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
        "external_id": "ERP-P-1042",
        "medical_record_number": "MRN-20418",
        "full_name": "Ana García López",
        "email": "ana.garcia@example.com",
        "phone": "+14155550123"
      },
      "service": {
        "id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
        "external_id": "ERP-SVC-12",
        "name": "Follow-up visit",
        "duration_minutes": 45,
        "price_cents": 8500
      }
    }
  ],
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05",
    "next_cursor": "eyJ2IjoxLCJzIjoic3RhcnRzX2F0IiwiZCI6ImFzYyIsImx2IjoiMjAyNi0xMC0wNVQxNDowMDowMCswMDowMCIsImxpIjoiMGMxZTVhOWEifQ.Zk3vP9",
    "has_more": true,
    "limit": 1
  }
}
POST/appointments

Anfrage· Pflichtfelder: patient_idprovider_idstarts_atends_at

POST /api/v1/appointments
Idempotency-Key: erp-appt-9001-create
Content-Type: application/json

{
  "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
  "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
  "service_id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
  "starts_at": "2026-10-05T14:00:00Z",
  "ends_at": "2026-10-05T14:45:00Z",
  "notes": "Follow-up on lab results",
  "external_id": "ERP-APPT-9001",
  "notify": false
}

Antwort 201 Created

{
  "data": {
    "id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "external_id": "ERP-APPT-9001",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
    "service_id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
    "starts_at": "2026-10-05T14:00:00+00:00",
    "ends_at": "2026-10-05T14:45:00+00:00",
    "status": "scheduled",
    "notes": "Follow-up on lab results",
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05",
    "created": true
  }
}

Antwort 409 Conflict (slot already taken)

{
  "data": null,
  "error": {
    "code": "CONFLICT",
    "message": "The provider already has an appointment at this time"
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
PATCH/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18

Anfrage

PATCH /api/v1/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18
If-Match: 2026-09-19T10:31:47.482913+00:00
Content-Type: application/json

{
  "starts_at": "2026-10-06T15:00:00Z",
  "ends_at": "2026-10-06T15:45:00Z"
}

Antwort 200 OK (reschedule)

{
  "data": {
    "id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "external_id": "ERP-APPT-9001",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
    "service_id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
    "starts_at": "2026-10-06T15:00:00+00:00",
    "ends_at": "2026-10-06T15:45:00+00:00",
    "status": "scheduled",
    "notes": "Follow-up on lab results",
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T11:02:13.907245+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Antwort 412 Precondition Failed (changed since you read it)

{
  "data": null,
  "error": {
    "code": "PRECONDITION_FAILED",
    "message": "The appointment has changed since you read it; re-read it and retry",
    "details": {
      "current_updated_at": "2026-09-19T10:58:40.115602+00:00"
    }
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
PATCH/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18

Anfrage

PATCH /api/v1/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18
Content-Type: application/json

{
  "status": "completed"
}

Antwort 200 OK

{
  "data": {
    "id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "external_id": "ERP-APPT-9001",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
    "service_id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
    "starts_at": "2026-10-05T14:00:00+00:00",
    "ends_at": "2026-10-05T14:45:00+00:00",
    "status": "completed",
    "notes": "Follow-up on lab results",
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Antwort 409 Conflict (already finished)

{
  "data": null,
  "error": {
    "code": "INVALID_TRANSITION",
    "message": "Cannot change status from cancelled to completed",
    "details": {
      "from": "cancelled",
      "to": "completed"
    }
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/cancel

Anfrage

POST /api/v1/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/cancel?notify=false

Antwort 200 OK

{
  "data": {
    "id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "external_id": "ERP-APPT-9001",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
    "service_id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
    "starts_at": "2026-10-05T14:00:00+00:00",
    "ends_at": "2026-10-05T14:45:00+00:00",
    "status": "cancelled",
    "notes": "Follow-up on lab results",
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T11:20:09.331870+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/appointments/batch

Anfrage· Pflichtfelder: items

POST /api/v1/appointments/batch
Content-Type: application/json

{
  "items": [
    {
      "external_id": "ERP-APPT-9001",
      "status": "confirmed"
    },
    {
      "external_id": "ERP-APPT-9002",
      "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
      "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
      "starts_at": "2026-10-07T16:00:00Z",
      "ends_at": "2026-10-07T16:30:00Z"
    },
    {
      "external_id": "ERP-APPT-9003",
      "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
      "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
      "starts_at": "2026-10-07T16:15:00Z",
      "ends_at": "2026-10-07T16:45:00Z"
    }
  ]
}

Antwort 200 OK

{
  "data": {
    "results": [
      {
        "index": 0,
        "status": "updated",
        "id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18"
      },
      {
        "index": 1,
        "status": "created",
        "id": "7f3b2a10-c8d4-4e59-a1b6-04d9e5c73f82"
      },
      {
        "index": 2,
        "status": "error",
        "id": null,
        "error": {
          "code": "CONFLICT",
          "message": "The provider already has an appointment at this time"
        }
      }
    ],
    "summary": {
      "created": 1,
      "updated": 1,
      "failed": 1
    }
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
Leistungen3
POST/services

Anfrage· Pflichtfelder: name

POST /api/v1/services
Idempotency-Key: erp-svc-12-create
Content-Type: application/json

{
  "name": "Follow-up visit",
  "description": "Review of results and treatment plan",
  "duration_minutes": 45,
  "buffer_minutes": 10,
  "color": "#6366f1",
  "price_cents": 8500,
  "external_id": "ERP-SVC-12"
}

Antwort 201 Created

{
  "data": {
    "id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
    "external_id": "ERP-SVC-12",
    "name": "Follow-up visit",
    "description": "Review of results and treatment plan",
    "duration_minutes": 45,
    "buffer_minutes": 10,
    "color": "#6366f1",
    "price_cents": 8500,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05",
    "created": true
  }
}
PATCH/services/4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60

Anfrage

PATCH /api/v1/services/4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60
Content-Type: application/json

{
  "price_cents": 9000,
  "description": null
}

Antwort 200 OK

{
  "data": {
    "id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
    "external_id": "ERP-SVC-12",
    "name": "Follow-up visit",
    "description": null,
    "duration_minutes": 45,
    "buffer_minutes": 10,
    "color": "#6366f1",
    "price_cents": 9000,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
DELETE/services/4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60

Anfrage

DELETE /api/v1/services/4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60?force=true

Antwort 200 OK

{
  "data": {
    "id": "4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60",
    "deleted": true
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
Behandler3
GET/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74

Anfrage

GET /api/v1/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74

Antwort 200 OK

{
  "data": {
    "id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
    "external_id": "ERP-DR-7",
    "full_name": "Dr. Elena Ruiz",
    "specialty": "Physiotherapy",
    "bio": "Sports injuries and post-surgical rehabilitation.",
    "timezone": "America/Mexico_City",
    "availability": [
      {
        "day": 1,
        "start": "09:00",
        "end": "17:00"
      },
      {
        "day": 3,
        "start": "09:00",
        "end": "17:00"
      }
    ],
    "max_appointments_per_day": 12,
    "booking_window_days": 60,
    "portal_restricted_days": [
      0,
      6
    ],
    "cedula_profesional": "1234567",
    "curp": null,
    "birth_country": "MX",
    "staff_type": 2,
    "sis_service": null,
    "deactivated_at": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
PATCH/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74

Anfrage

PATCH /api/v1/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74
Content-Type: application/json

{
  "availability": [
    {
      "day": 1,
      "start": "09:00",
      "end": "13:00"
    },
    {
      "day": 1,
      "start": "14:00",
      "end": "18:00"
    }
  ],
  "availability_overrides": [
    {
      "date": "2026-12-24",
      "available": false
    }
  ],
  "max_appointments_per_day": 10,
  "booking_window_days": null,
  "external_id": "ERP-DR-7"
}

Antwort 200 OK

{
  "data": {
    "id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
    "external_id": "ERP-DR-7",
    "full_name": "Dr. Elena Ruiz",
    "specialty": "Physiotherapy",
    "bio": "Sports injuries and post-surgical rehabilitation.",
    "timezone": "America/Mexico_City",
    "availability": [
      {
        "day": 1,
        "start": "09:00",
        "end": "13:00"
      },
      {
        "day": 1,
        "start": "14:00",
        "end": "18:00"
      }
    ],
    "max_appointments_per_day": 10,
    "booking_window_days": null,
    "portal_restricted_days": [
      0,
      6
    ],
    "cedula_profesional": "1234567",
    "curp": null,
    "birth_country": "MX",
    "staff_type": 2,
    "sis_service": null,
    "deactivated_at": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-19T10:31:47.482913+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
GET/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74/availability

Anfrage

GET /api/v1/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74/availability?from=2026-10-05T00:00:00Z&to=2026-10-06T00:00:00Z&service_id=4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60

Antwort 200 OK

{
  "data": {
    "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
    "timezone": "America/Mexico_City",
    "duration_minutes": 45,
    "buffer_minutes": 10,
    "slots": [
      {
        "starts_at": "2026-10-05T15:00:00.000Z",
        "ends_at": "2026-10-05T15:45:00.000Z"
      },
      {
        "starts_at": "2026-10-05T15:55:00.000Z",
        "ends_at": "2026-10-05T16:40:00.000Z"
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
Klinische Unterlagen (Network)8
GET/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/record

Anfrage

GET /api/v1/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/record?limit=1

Antwort 200 OK

{
  "data": [
    {
      "appointment": {
        "id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
        "starts_at": "2026-10-05T14:00:00+00:00",
        "ends_at": "2026-10-05T14:45:00+00:00",
        "status": "completed",
        "notes": null
      },
      "clinical_notes": [
        {
          "id": "b3f81d64-8a27-4e05-9c3b-71d2f4a6e589",
          "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
          "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
          "author_name": "Dr. Elena Ruiz",
          "note_type": "soap",
          "is_draft": false,
          "status": "signed",
          "parent_note_id": null,
          "subjective": "Reports less pain when climbing stairs.",
          "objective": "Range of motion improved to 110°.",
          "assessment": "Recovering as expected.",
          "plan_text": "Continue exercises; review in two weeks.",
          "content": null,
          "vitals": {
            "bp_systolic": {
              "value": 124,
              "unit": "mm[Hg]",
              "code": "8480-6"
            },
            "bp_diastolic": {
              "value": 79,
              "unit": "mm[Hg]",
              "code": "8462-4"
            },
            "heart_rate": {
              "value": 68,
              "unit": "/min",
              "code": "8867-4"
            },
            "weight": {
              "value": 64.5,
              "unit": "kg",
              "code": "29463-7"
            },
            "height": {
              "value": 168,
              "unit": "cm",
              "code": "8302-2"
            },
            "bmi": {
              "value": 22.9,
              "unit": "kg/m2",
              "code": "39156-5"
            }
          },
          "template_key": null,
          "template_data": null,
          "signed_by_name": "Dr. Elena Ruiz",
          "signed_by_credential": "1234567",
          "signed_at": "2026-09-19T10:31:47.482913+00:00",
          "attestation": "I attest that this entry is accurate and complete and that I wrote it. Once signed it cannot be changed; any correction must be made with an addendum.",
          "legacy_signature": false,
          "voided_by_name": null,
          "voided_at": null,
          "void_reason": null,
          "created_at": "2026-09-01T15:04:05.123456+00:00",
          "updated_at": "2026-09-19T10:31:47.482913+00:00"
        }
      ],
      "intake": {
        "id": "c7a41e92-3d58-4b06-8f1a-9e2d60b5c3f7",
        "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
        "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
        "status": "submitted",
        "reason_for_visit": "Knee pain after running",
        "chief_complaint": "Pain on the inner side of the right knee",
        "symptom_onset": "3 weeks ago",
        "symptom_description": "Sharp when descending stairs",
        "pain_scale": 6,
        "recent_changes": "Started a half-marathon training plan",
        "current_medications": "Ibuprofen 400 mg as needed",
        "known_allergies": "Penicillin",
        "relevant_conditions": null,
        "address_confirmed": true,
        "emergency_contact_confirmed": true,
        "insurance_confirmed": false,
        "submitted_at": "2026-09-01T15:04:05.123456+00:00",
        "reviewed_at": null,
        "review_notes": null,
        "created_at": "2026-09-01T15:04:05.123456+00:00",
        "updated_at": "2026-09-01T15:04:05.123456+00:00"
      }
    }
  ],
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
GET/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/documents

Anfrage

GET /api/v1/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/documents

Antwort 200 OK

{
  "data": [
    {
      "id": "6a2d9f41-0b3c-4e78-a5d6-1f8e2b7c9d03",
      "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
      "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
      "category": "imaging",
      "title": "MRI right knee",
      "mime_type": "application/pdf",
      "size_bytes": 482113,
      "sha256": "9f2c4e81b7a05d36e1c8f40b2a97d6e53c0b18f7a4e2d95c6b3f0a8e71d4c2b9",
      "uploaded_by_name": "Dr. Elena Ruiz",
      "created_at": "2026-09-19T10:31:47.482913+00:00",
      "voided_at": null,
      "voided_by_name": null,
      "void_reason": null
    }
  ],
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
GET/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/documents/6a2d9f41-0b3c-4e78-a5d6-1f8e2b7c9d03

Anfrage

GET /api/v1/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/documents/6a2d9f41-0b3c-4e78-a5d6-1f8e2b7c9d03

Antwort 200 OK (the url expires after 60 seconds)

{
  "data": {
    "id": "6a2d9f41-0b3c-4e78-a5d6-1f8e2b7c9d03",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "category": "imaging",
    "title": "MRI right knee",
    "mime_type": "application/pdf",
    "size_bytes": 482113,
    "sha256": "9f2c4e81b7a05d36e1c8f40b2a97d6e53c0b18f7a4e2d95c6b3f0a8e71d4c2b9",
    "uploaded_by_name": "Dr. Elena Ruiz",
    "created_at": "2026-09-19T10:31:47.482913+00:00",
    "voided_at": null,
    "voided_by_name": null,
    "void_reason": null,
    "url": "https://…/storage/v1/object/sign/patient-documents/…?token=…",
    "url_expires_at": "2026-09-19T10:32:47.000Z"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes

Anfrage

POST /api/v1/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes
Idempotency-Key: erp-note-5521
Content-Type: application/json

{
  "note_type": "soap",
  "subjective": "Reports less pain when climbing stairs.",
  "objective": "Range of motion improved to 110°.",
  "assessment": "Recovering as expected.",
  "plan_text": "Continue exercises; review in two weeks.",
  "vitals": {
    "bp_systolic": 124,
    "bp_diastolic": 79,
    "heart_rate": 68,
    "weight": {
      "value": 64.5,
      "unit": "kg"
    },
    "height": 168
  }
}

Antwort 201 Created (a draft for the clinician to sign)

{
  "data": {
    "id": "b3f81d64-8a27-4e05-9c3b-71d2f4a6e589",
    "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "author_name": "Dr. Elena Ruiz",
    "note_type": "soap",
    "is_draft": true,
    "status": "draft",
    "parent_note_id": null,
    "subjective": "Reports less pain when climbing stairs.",
    "objective": "Range of motion improved to 110°.",
    "assessment": "Recovering as expected.",
    "plan_text": "Continue exercises; review in two weeks.",
    "content": null,
    "vitals": {
      "bp_systolic": {
        "value": 124,
        "unit": "mm[Hg]",
        "code": "8480-6"
      },
      "bp_diastolic": {
        "value": 79,
        "unit": "mm[Hg]",
        "code": "8462-4"
      },
      "heart_rate": {
        "value": 68,
        "unit": "/min",
        "code": "8867-4"
      },
      "weight": {
        "value": 64.5,
        "unit": "kg",
        "code": "29463-7"
      },
      "height": {
        "value": 168,
        "unit": "cm",
        "code": "8302-2"
      },
      "bmi": {
        "value": 22.9,
        "unit": "kg/m2",
        "code": "39156-5"
      }
    },
    "template_key": null,
    "template_data": null,
    "signed_by_name": null,
    "signed_by_credential": null,
    "signed_at": null,
    "attestation": null,
    "legacy_signature": false,
    "voided_by_name": null,
    "voided_at": null,
    "void_reason": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-01T15:04:05.123456+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Antwort 403 Forbidden (is_draft: false)

{
  "data": null,
  "error": {
    "code": "NOTE_SIGN_REQUIRES_CLINICIAN",
    "message": "API keys create drafts only; a clinician signs the note in the dashboard"
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
PATCH/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes/b3f81d64-8a27-4e05-9c3b-71d2f4a6e589

Anfrage

PATCH /api/v1/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes/b3f81d64-8a27-4e05-9c3b-71d2f4a6e589
Content-Type: application/json

{
  "plan_text": "Continue exercises; review in three weeks."
}

Antwort 200 OK (still a draft)

{
  "data": {
    "id": "b3f81d64-8a27-4e05-9c3b-71d2f4a6e589",
    "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "author_name": "Dr. Elena Ruiz",
    "note_type": "soap",
    "is_draft": true,
    "status": "draft",
    "parent_note_id": null,
    "subjective": "Reports less pain when climbing stairs.",
    "objective": "Range of motion improved to 110°.",
    "assessment": "Recovering as expected.",
    "plan_text": "Continue exercises; review in three weeks.",
    "content": null,
    "vitals": {
      "bp_systolic": {
        "value": 124,
        "unit": "mm[Hg]",
        "code": "8480-6"
      },
      "bp_diastolic": {
        "value": 79,
        "unit": "mm[Hg]",
        "code": "8462-4"
      },
      "heart_rate": {
        "value": 68,
        "unit": "/min",
        "code": "8867-4"
      },
      "weight": {
        "value": 64.5,
        "unit": "kg",
        "code": "29463-7"
      },
      "height": {
        "value": 168,
        "unit": "cm",
        "code": "8302-2"
      },
      "bmi": {
        "value": 22.9,
        "unit": "kg/m2",
        "code": "39156-5"
      }
    },
    "template_key": null,
    "template_data": null,
    "signed_by_name": null,
    "signed_by_credential": null,
    "signed_at": null,
    "attestation": null,
    "legacy_signature": false,
    "voided_by_name": null,
    "voided_at": null,
    "void_reason": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-01T15:04:05.123456+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Antwort 409 Conflict (already signed)

{
  "data": null,
  "error": {
    "code": "NOTE_LOCKED",
    "message": "This note is signed and cannot be changed or deleted; add an addendum instead"
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes

Anfrage

POST /api/v1/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes
Idempotency-Key: erp-note-5530
Content-Type: application/json

{
  "template_key": "mental-health.phq9@1",
  "template_data": {
    "phq9": {
      "answers": [
        1,
        2,
        1,
        1,
        2,
        1,
        1,
        1,
        0
      ],
      "difficulty": 1
    },
    "comments": "Sleep is the main complaint."
  }
}

Antwort 201 Created (a draft; total and band computed by Genkō)

{
  "data": {
    "id": "5c8e1a27-94d3-4b06-8f21-7e3a9d0c6b48",
    "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "author_name": "Dr. Elena Ruiz",
    "note_type": "progress",
    "is_draft": true,
    "status": "draft",
    "parent_note_id": null,
    "subjective": null,
    "objective": null,
    "assessment": null,
    "plan_text": null,
    "content": null,
    "vitals": null,
    "template_key": "mental-health.phq9@1",
    "template_data": {
      "phq9": {
        "answers": [
          1,
          2,
          1,
          1,
          2,
          1,
          1,
          1,
          0
        ],
        "difficulty": 1,
        "total": 10,
        "severity": "moderate"
      },
      "comments": "Sleep is the main complaint."
    },
    "signed_by_name": null,
    "signed_by_credential": null,
    "signed_at": null,
    "attestation": null,
    "legacy_signature": false,
    "voided_by_name": null,
    "voided_at": null,
    "void_reason": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-01T15:04:05.123456+00:00",
    "sis": null
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Antwort 400 Bad Request (a partial questionnaire)

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "mental-health.phq9@1: phq9.answers: PHQ-9 needs all 9 answers (0–3)",
    "details": {
      "field": "template_data.phq9.answers"
    }
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes/b3f81d64-8a27-4e05-9c3b-71d2f4a6e589/addenda

Anfrage· Pflichtfelder: content

POST /api/v1/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes/b3f81d64-8a27-4e05-9c3b-71d2f4a6e589/addenda
Idempotency-Key: erp-addendum-5522
Content-Type: application/json

{
  "content": "MRI report received: no meniscal tear."
}

Antwort 201 Created (a draft addendum)

{
  "data": {
    "id": "e3b9c2d4-7a15-4f68-9b0e-2c4d6f8a1b35",
    "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "author_name": "Dr. Elena Ruiz",
    "note_type": "addendum",
    "is_draft": true,
    "status": "draft",
    "parent_note_id": "b3f81d64-8a27-4e05-9c3b-71d2f4a6e589",
    "subjective": null,
    "objective": null,
    "assessment": null,
    "plan_text": null,
    "content": "MRI report received: no meniscal tear.",
    "vitals": {
      "bp_systolic": {
        "value": 124,
        "unit": "mm[Hg]",
        "code": "8480-6"
      },
      "bp_diastolic": {
        "value": 79,
        "unit": "mm[Hg]",
        "code": "8462-4"
      },
      "heart_rate": {
        "value": 68,
        "unit": "/min",
        "code": "8867-4"
      },
      "weight": {
        "value": 64.5,
        "unit": "kg",
        "code": "29463-7"
      },
      "height": {
        "value": 168,
        "unit": "cm",
        "code": "8302-2"
      },
      "bmi": {
        "value": 22.9,
        "unit": "kg/m2",
        "code": "39156-5"
      }
    },
    "template_key": null,
    "template_data": null,
    "signed_by_name": null,
    "signed_by_credential": null,
    "signed_at": null,
    "attestation": null,
    "legacy_signature": false,
    "voided_by_name": null,
    "voided_at": null,
    "void_reason": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-01T15:04:05.123456+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/intake/review

Anfrage· Pflichtfelder: status

POST /api/v1/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/intake/review
Content-Type: application/json

{
  "status": "approved",
  "review_notes": "Insurance to be confirmed at reception."
}

Antwort 200 OK

{
  "data": {
    "id": "c7a41e92-3d58-4b06-8f1a-9e2d60b5c3f7",
    "appointment_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
    "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
    "status": "approved",
    "reason_for_visit": "Knee pain after running",
    "chief_complaint": "Pain on the inner side of the right knee",
    "symptom_onset": "3 weeks ago",
    "symptom_description": "Sharp when descending stairs",
    "pain_scale": 6,
    "recent_changes": "Started a half-marathon training plan",
    "current_medications": "Ibuprofen 400 mg as needed",
    "known_allergies": "Penicillin",
    "relevant_conditions": null,
    "address_confirmed": true,
    "emergency_contact_confirmed": true,
    "insurance_confirmed": false,
    "submitted_at": "2026-09-01T15:04:05.123456+00:00",
    "reviewed_at": "2026-09-19T10:31:47.482913+00:00",
    "review_notes": "Insurance to be confirmed at reception.",
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-01T15:04:05.123456+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
Webhooks (Network)6
POST/webhooks

Anfrage· Pflichtfelder: urlevents

POST /api/v1/webhooks
Content-Type: application/json

{
  "url": "https://erp.example.com/genko-webhook",
  "description": "ERP sync",
  "events": [
    "appointment.created",
    "appointment.updated",
    "appointment.cancelled",
    "patient.updated"
  ]
}

Antwort 201 Created

{
  "data": {
    "id": "e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24",
    "url": "https://erp.example.com/genko-webhook",
    "description": "ERP sync",
    "events": [
      "appointment.created",
      "appointment.updated",
      "appointment.cancelled",
      "patient.updated"
    ],
    "active": true,
    "disabled_reason": null,
    "disabled_at": null,
    "consecutive_failures": 0,
    "previous_secret_expires_at": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-01T15:04:05.123456+00:00",
    "secret": "whsec_4f9c1e7a2b8d3065a1c7e94d0b2f8a61c3d5e7f9"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
PATCH/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24

Anfrage

PATCH /api/v1/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24
Content-Type: application/json

{
  "events": [
    "appointment.created",
    "appointment.cancelled"
  ],
  "active": true
}

Antwort 200 OK

{
  "data": {
    "id": "e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24",
    "url": "https://erp.example.com/genko-webhook",
    "description": "ERP sync",
    "events": [
      "appointment.created",
      "appointment.cancelled"
    ],
    "active": true,
    "disabled_reason": null,
    "disabled_at": null,
    "consecutive_failures": 0,
    "previous_secret_expires_at": null,
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-01T15:04:05.123456+00:00"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/rotate-secret

Anfrage

POST /api/v1/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/rotate-secret?grace_hours=48

Antwort 200 OK

{
  "data": {
    "id": "e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24",
    "url": "https://erp.example.com/genko-webhook",
    "description": "ERP sync",
    "events": [
      "appointment.created",
      "appointment.updated",
      "appointment.cancelled",
      "patient.updated"
    ],
    "active": true,
    "disabled_reason": null,
    "disabled_at": null,
    "consecutive_failures": 0,
    "previous_secret_expires_at": "2026-09-21T11:02:13.907245+00:00",
    "created_at": "2026-09-01T15:04:05.123456+00:00",
    "updated_at": "2026-09-01T15:04:05.123456+00:00",
    "secret": "whsec_b7d20e4f91a3c58e6d0f2b1a97c4e3850d6f1a28"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/test

Anfrage

POST /api/v1/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/test

Antwort 200 OK

{
  "data": {
    "event_id": "1e8a4c70-5b93-4d2f-a0c6-93f7b2d8e415",
    "delivered": true,
    "status_code": 200,
    "error": null,
    "duration_ms": 184
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Antwort 200 OK (receiver unreachable)

{
  "data": {
    "event_id": "1e8a4c70-5b93-4d2f-a0c6-93f7b2d8e415",
    "delivered": false,
    "status_code": null,
    "error": "timeout",
    "duration_ms": 10001
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
GET/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/deliveries

Anfrage

GET /api/v1/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/deliveries?status=failed&limit=1

Antwort 200 OK

{
  "data": [
    {
      "id": "5b0f7a3e-9c2d-4f6e-8a51-0d3c7e1b2a44",
      "endpoint_id": "e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24",
      "event_type": "appointment.updated",
      "resource_type": "appointment",
      "resource_id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
      "payload": {
        "id": "5b0f7a3e-9c2d-4f6e-8a51-0d3c7e1b2a44",
        "type": "appointment.updated",
        "created_at": "2026-09-19T11:02:13.907245Z",
        "data": {
          "id": "0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18",
          "external_id": "ERP-APPT-9001",
          "patient_id": "8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23",
          "provider_id": "17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74",
          "changed_fields": [
            "ends_at",
            "starts_at"
          ]
        }
      },
      "status": "failed",
      "attempts": 2,
      "next_attempt_at": "2026-09-19T11:37:14.000000+00:00",
      "last_attempt_at": "2026-09-19T11:07:14.000000+00:00",
      "last_status_code": 500,
      "last_error": "HTTP 500",
      "delivered_at": null,
      "created_at": "2026-09-19T11:02:13.907245+00:00"
    }
  ],
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05",
    "next_cursor": null,
    "has_more": false,
    "limit": 1
  }
}
POST/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/deliveries/5b0f7a3e-9c2d-4f6e-8a51-0d3c7e1b2a44/redeliver

Anfrage

POST /api/v1/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/deliveries/5b0f7a3e-9c2d-4f6e-8a51-0d3c7e1b2a44/redeliver

Antwort 200 OK

{
  "data": {
    "id": "5b0f7a3e-9c2d-4f6e-8a51-0d3c7e1b2a44",
    "status": "pending"
  },
  "error": null,
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
Fehler6
POST/patients

Anfrage

POST /api/v1/patients
Content-Type: application/json

{
  "full_name": "Ana García",
  "email": "ana.garcia",
  "nickname": "Ani"
}

Antwort 400 Bad Request

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid body",
    "details": {
      "issues": [
        {
          "path": "email",
          "message": "Invalid email address"
        },
        {
          "path": "",
          "message": "Unrecognized key: \"nickname\""
        }
      ]
    }
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
GET/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23

Anfrage

GET /api/v1/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23
Authorization: Bearer genko_mcp_… (an MCP key)

Antwort 401 Unauthorized

{
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "This is an MCP key, which only works on /api/mcp. Create a REST API key under Settings → Developers → REST API keys.",
    "details": {
      "key_kind": "mcp"
    }
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
POST/patients

Anfrage

POST /api/v1/patients
Authorization: Bearer genko_… (a read-only key)
Content-Type: application/json

{
  "full_name": "Ana García"
}

Antwort 403 Forbidden

{
  "data": null,
  "error": {
    "code": "FORBIDDEN",
    "message": "This API key does not have the required scope",
    "details": {
      "required_scope": "patients:write"
    }
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
GET/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/record

Anfrage

GET /api/v1/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/record
Authorization: Bearer genko_… (a Practice plan key)

Antwort 403 Forbidden

{
  "data": null,
  "error": {
    "code": "PLAN_LIMIT",
    "message": "This endpoint requires the enterprise plan or above",
    "details": {
      "required_plan": "enterprise"
    }
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
GET/patients/2b9e6d40-0000-4000-8000-000000000000

Anfrage

GET /api/v1/patients/2b9e6d40-0000-4000-8000-000000000000

Antwort 404 Not Found

{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Patient not found"
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}
GET/patients

Anfrage

GET /api/v1/patients?limit=500

Antwort 429 Too Many Requests

Retry-After: 23
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 23

{
  "data": null,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 600,
      "retry_after_seconds": 23
    }
  },
  "meta": {
    "request_id": "3f6c0b9e-1d24-4a7e-9b58-c2e41f7a6d05"
  }
}

Webhooks

Statt ständig abzufragen, kann Ihr System benachrichtigt werden, wenn sich etwas ändert. Legen Sie unter Settings → Developers → Webhooks einen Endpunkt an (oder mit POST /webhooks), und Genkō sendet ihm eine signierte HTTPS-Anfrage, sobald sich ein Termin oder ein Patient ändert, gleichgültig, wer die Änderung vorgenommen hat: Ihre eigenen API-Aufrufe, das Dashboard, das Patientenportal oder ein Import. Webhooks sind eine Network-Funktion mit bis zu 10 Endpunkten pro Organisation.

  • Ereignisse: appointment.created, appointment.updated, appointment.cancelled, appointment.completed, appointment.deleted, patient.created, patient.updated, patient.deleted, patient.archived, patient.restored. Jeder Endpunkt wählt, welche er erhält. Ein Wechsel zu cancelled oder completed sendet nur dieses Ereignis, nicht zusätzlich appointment.updated. note.signed und note.voided melden, dass eine Ärztin oder ein Arzt eine Notiz oder einen Nachtrag signiert hat bzw. dass eine signierte Notiz als irrtümlich markiert wurde: nur IDs, kein Inhalt; die Notiz lesen Sie mit clinical:read.
  • Keine Patientendaten unterwegs. Ein Ereignis enthält IDs und die Namen der geänderten Felder, niemals deren Werte. Lesen Sie den Datensatz mit GET /patients/:id oder GET /appointments/:id nach.
  • Unabhängig von notify. notify: false unterdrückt E-Mails, SMS und Kalendersynchronisierung, nicht aber Webhooks, denn sie beschreiben die Änderung selbst. Ihre eigenen API-Schreibzugriffe kommen deshalb ebenfalls als Ereignisse zurück: Erkennen Sie sie an external_id oder am Abgleich mit dem, was Sie gerade geschrieben haben.
  • Konsistent. Ereignisse werden in derselben Datenbanktransaktion wie die Änderung aufgezeichnet: Keines geht nach einem Commit verloren, und keines wird für eine zurückgerollte Änderung gesendet.

Was Ihr Server erhält (ein POST mit JSON-Body) und die mitgesendeten Header:

{
  "id": "5b0f7a3e-9c2d-4f6e-8a51-0d3c7e1b2a44",
  "type": "appointment.updated",
  "created_at": "2026-10-09T12:00:00.123456Z",
  "data": {
    "id": "0c1e5a9a-…",
    "external_id": "ERP-APPT-9001",
    "patient_id": "8d4f…",
    "provider_id": "17ab…",
    "changed_fields": ["ends_at", "starts_at"]
  }
}
POST /genko-webhook HTTP/1.1
Content-Type: application/json
User-Agent: Genko-Webhooks/1
Genko-Signature: t=1790000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Genko-Event-Id: 5b0f7a3e-9c2d-4f6e-8a51-0d3c7e1b2a44
Genko-Event-Type: appointment.updated
Genko-Delivery-Attempt: 1

Jede Anfrage verifizieren

Jede Anfrage trägt Genko-Signature: t=…,v1=…. Berechnen Sie einen HMAC-SHA256 über die Zeichenfolge t + "." + Roh-Body mit dem Secret Ihres Endpunkts (whsec_…, das beim Anlegen einmal angezeigt wird) und vergleichen Sie ihn in konstanter Zeit mit v1. Lehnen Sie die Anfrage ab, wenn t mehr als 5 Minuten von Ihrer Uhr abweicht; so lässt sich eine abgefangene Anfrage nicht erneut einspielen. Verifizieren Sie immer den rohen Body, vor jedem JSON-Parsing. Während ein Secret rotiert wird, enthält der Header zwei v1-Werte: Akzeptieren Sie einen davon.

Node.js (Express)

import crypto from 'node:crypto'
import express from 'express'

const SECRETS = [process.env.GENKO_WEBHOOK_SECRET] // add the old secret too while you are rotating

// The signature covers the RAW bytes: verify before you parse any JSON.
function verify(header, rawBody) {
  const items = header.split(',').map((p) => p.split('='))
  const t = Number(items.find(([k]) => k === 't')?.[1])
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false // replay window: 5 minutes
  const signatures = items.filter(([k]) => k === 'v1').map(([, v]) => v)
  return SECRETS.some((secret) => {
    const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex')
    return signatures.some((s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)))
  })
}

const app = express()
app.post('/genko-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8')
  if (!verify(req.get('Genko-Signature') ?? '', raw)) return res.sendStatus(400)
  const event = JSON.parse(raw)
  // Dedupe on event.id (also the Genko-Event-Id header): delivery is at-least-once.
  res.sendStatus(200) // acknowledge within 10 seconds, do the real work afterwards
})

Python (Flask)

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRETS = [os.environ["GENKO_WEBHOOK_SECRET"]]  # add the old secret too while you are rotating

def verify(header: str, raw_body: bytes) -> bool:
    items = [p.split("=", 1) for p in header.split(",") if "=" in p]
    t = next((v for k, v in items if k == "t"), "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:  # replay window: 5 minutes
        return False
    signatures = [v for k, v in items if k == "v1"]
    for secret in SECRETS:
        expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(s, expected) for s in signatures):
            return True
    return False

@app.post("/genko-webhook")
def genko_webhook():
    # The signature covers the RAW bytes: verify before you parse any JSON.
    if not verify(request.headers.get("Genko-Signature", ""), request.get_data()):
        abort(400)
    event = request.get_json()
    # Dedupe on event["id"] (also the Genko-Event-Id header): delivery is at-least-once.
    return "", 200  # acknowledge within 10 seconds, do the real work afterwards

Zustellung, Wiederholungen und Zustand

  • Mindestens einmal, ohne garantierte Reihenfolge. Entfernen Sie Duplikate anhand der Ereignis-id (auch als Genko-Event-Id gesendet; sie ändert sich bei Wiederholungen nie) und entscheiden Sie mit dem updated_at des Datensatzes, welche Version neuer ist.
  • Bestätigen Sie mit einem beliebigen 2xx innerhalb von 10 Sekunden und erledigen Sie die eigentliche Arbeit danach. Alles andere, auch eine Weiterleitung, ein Timeout oder ein Verbindungsfehler, gilt als Fehlschlag und wird nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und dann alle 24 Stunden wiederholt, höchstens 8 Versuche. Danach wird die Zustellung als aufgegeben markiert und bleibt 14 Tage lang zum erneuten Senden verfügbar.
  • Wiederholungen laufen, wenn sie fällig sind und die Warteschlange als Nächstes verarbeitet wird. Solange Ihre Integration die API nutzt, ist das etwa innerhalb einer Minute; sonst beim nächsten geplanten Durchlauf, spätestens nach einem Tag. Verlassen Sie sich nicht auf eine Wiederholung zu einem genauen Zeitpunkt: Das Abfragen mit updated_since bleibt das Sicherheitsnetz.
  • Zustand. Ein Endpunkt, der länger als 24 Stunden durchgehend fehlschlägt (20 oder mehr fehlgeschlagene Versuche in Folge), wird abgeschaltet, und der Organisationsinhaber erhält eine E-Mail. Ereignisse bleiben 14 Tage in der Warteschlange: Beheben Sie den Empfänger, aktivieren Sie den Endpunkt wieder und senden Sie Verpasstes erneut. Ein einziger Erfolg setzt den Zähler zurück.
  • Sicher konzipiert. Nur öffentliche https://-Adressen werden akzeptiert. Genkō löst den Host bei jeder Zustellung auf und lehnt private, Loopback- und Link-Local-Adressen ab, folgt nie Weiterleitungen und speichert die Antwort Ihres Servers nicht.

Das Secret rotieren

Nutzen Sie Secret rotieren im Dashboard oder POST /webhooks/:id/rotate-secret. Das neue Secret wird einmal angezeigt. Während der von Ihnen gewählten Übergangsfrist (standardmäßig 24 Stunden, bis zu 7 Tage oder keine) werden Zustellungen mit beiden Secrets signiert, sodass Sie das neue ausrollen können, ohne ein Ereignis zu verlieren; danach gilt das alte nicht mehr. Secret verloren? Rotieren Sie es. Test senden liefert ein signiertes webhook.test-Ereignis und zeigt die Antwort Ihres Servers.

Leitfaden zur ERP-Integration

Eine typische Integration besteht aus einem einmaligen Erstabgleich und danach nahezu Echtzeit-Updates mit einem Sicherheitsnetz. In dieser Reihenfolge:

  1. Einen Schlüssel erstellen. Ein REST-API-Schlüssel mit Lesen & Schreiben deckt die Synchronisierung von Terminen und Patienten ab; fügen Sie Admin nur hinzu, wenn Sie klinische Akten brauchen. Beschränken Sie ihn auf die IP-Adressen Ihres Servers und vergeben Sie ein Ablaufdatum, das Sie zum Rotieren nicht vergessen.
  2. Kennungen vereinbaren. Senden Sie Ihre eigene ID bei jedem Anlegen und Upsert als external_id. Danach können Sie Datensätze darüber suchen, ein Anlegen sicher wiederholen und Webhook-Ereignisse Ihren Zeilen zuordnen.
  3. Erstabgleich. Blättern Sie GET /patients?limit=500 und GET /appointments?limit=500 bis zum Ende durch und speichern Sie das höchste gesehene updated_at als Wasserzeichen.
  4. Änderungen senden. Nutzen Sie POST /patients/upsert und POST /appointments (oder die Batch-Endpunkte in Network) mit einem Idempotency-Key pro Änderung, damit eine Wiederholung sie nie verdoppelt, und notify: false, wenn Ihr System Patienten bereits selbst benachrichtigt.
  5. Änderungen empfangen. Abonnieren Sie die Webhook-Ereignisse für nahezu Echtzeit-Updates und rufen Sie den jeweils genannten Datensatz ab. Behalten Sie eine leichte Abfrage ?updated_since=<Wasserzeichen minus 60 s> als Sicherheitsnetz bei: Ein Webhook kann sich verspäten, geht aber nicht unbemerkt aus der Warteschlange verloren. Löschungen kommen als *.deleted-Ereignisse mit Ihrer external_id.
  6. Abgleichen. Blättern Sie einmal pro Woche ?fields=id&limit=500 durch und vergleichen Sie die IDs mit Ihrer Kopie, um Fehler auf einer der beiden Seiten zu finden.
  7. Fehler behandeln. Bei 429 warten Sie Retry-After ab. Bei 5xx und 503 wiederholen Sie mit exponentiellem Backoff und demselben Idempotency-Key. Wiederholen Sie 400, 403 und 404 nicht. Bieten Sie bei 409 CONFLICT beim Buchen einen anderen Slot aus GET /providers/:id/availability an.

Vor dem Go-live

  • Schlüssel werden als Secrets gespeichert und per IP beschränkt; nichts wird in einer URL gesendet.
  • Der Webhook-Empfänger verifiziert die Signatur über den rohen Body, lehnt alte Zeitstempel ab und entfernt Duplikate anhand der Ereignis-ID.
  • Die Synchronisierungsschleife überlappt ihr Wasserzeichen um 60 Sekunden und macht Upserts per id oder external_id.
  • Schreibzugriffe senden einen Idempotency-Key und weichen bei 429 und 5xx mit Backoff aus.
  • Sie haben Test senden und eine echte Änderung durchgängig ausprobiert und wissen, wo Zustellungen und Fehler sichtbar sind (Settings → Developers → Webhooks und das Audit-Log).
Maschinenlesbare Referenz: Der vollständige Katalog aus Endpunkten, Schemas und Fehlern liegt unter /api/v1/openapi.json (OpenAPI 3.1).

Kalender-Einbettungen

Überblick

Eine Kalender-Einbettung zeigt die Termine einer Praxis — Tag, Woche, Monat oder Agenda — in einem anderen Produkt: Ihrem CRM, einem Intranet, einem Partnerportal oder einer Website. Sie ist schreibgeschützt, und jede Ansicht braucht eine kurzlebige, signierte Sitzung, die Ihr Server ausstellt. Verfügbar im Network-Tarif und in dedizierten Enterprise-Installationen.

  • Für wen: Entwickler, die Genkō mit einem CRM oder einer Website verbinden, auf der Mitarbeiter oder Partner den Terminplan sehen sollen, ohne sich bei Genkō anzumelden.
  • Eine Einbettung pro Sicherheitsgrenze, nicht pro Ansicht. Jede Einbettung legt fest, wer sie anzeigen darf (eine exakte Liste von Origins) und wie viel sichtbar ist (nur belegt, Leistung oder volle Patientendetails). Bis zu 10 pro Organisation im Network-Tarif (50 in einer dedizierten Installation). Für einen Behandler oder eine Ansicht grenzen Sie zur Laufzeit ein, statt weitere Einbettungen anzulegen.
  • Klicks erreichen Ihre Seite. Ein Klick auf einen Termin kann ein schreibgeschütztes Detailfenster öffnen und sendet ein appointment:click-Ereignis mit Genkōs id und Ihrer external_id, damit Ihr CRM den eigenen Datensatz öffnen kann.
Nicht das Chat-Widget. Das Chat-Widget ist ein öffentlicher Assistent, der Patienten auf Ihrer Website bei der Buchung hilft. Eine Kalender-Einbettung ist eine signierte, schreibgeschützte Ansicht des Terminplans für Mitarbeiter und Partner: Sie bucht nie und hat keinen öffentlichen Modus.

So funktioniert es

Ihr Server tauscht einen API-Schlüssel gegen ein kurzlebiges Token; der Browser sieht nur das Token.

 Ihr Backend
 1. POST /api/v1/embeds/{id}/sessions ──▶  prüft Schlüssel, Scope, IP-Bereich und Tarif
    Authorization: Bearer genko_…     ◀──  201 { token, expires_at }   (standardmäßig 15 Min.)

 Ihre Seite (Browser)
 2. embed.js → getToken() → Ihr Backend → token
 3. <iframe src="…/embed/emb_…#t=token" referrerpolicy="origin">
                                      ──▶  prüft den Origin der Seite gegen die Freigabeliste
 4. iframe → GET /api/embed/emb_…/appointments   (Authorization: Bearer token)
                                      ──▶  prüft Einbettung, Schlüssel, Tarif und Origin bei JEDER Anfrage
                                      ◀──  Termine, gemäß Detailstufe
 5. iframe → Ihre Seite (Browser): ready, resize, appointment:click, token:expired, error  (postMessage)
  • Der API-Schlüssel bleibt auf Ihrem Server. Er steht nie in der Seite, im Script-Tag, in einem Data-Attribut oder in der Iframe-URL. Verwenden Sie einen Schlüssel nur mit dem Scope embeds:session und binden Sie ihn an den IP-Bereich Ihres Servers; ein solcher Schlüssel kann über die REST-API nichts lesen.
  • Tokens sind kurzlebig: standardmäßig 15 Minuten, höchstens 60, und nie länger als die Einbettung selbst. Jedes ist an eine Einbettung, eine Organisation, den ausstellenden Schlüssel und die erlaubten Origins gebunden. Tokens sind schreibgeschützt und werden nur vom Datenendpunkt der Einbettung akzeptiert — nie von /api/v1.
  • Die Origin-Freigabeliste wird dreimal durchgesetzt: beim Laden des Iframes (der Origin der Seite, dank referrerpolicy="origin" gesendet), im Messaging des Iframes (es spricht nur mit diesem Elternfenster) und bei jeder Datenanfrage (der Origin muss im Token stehen und noch auf der Einbettung erlaubt sein).
  • Notschalter greifen in Sekunden: Schlüssel widerrufen, Einbettung deaktivieren, löschen oder ablaufen lassen, einen Origin entfernen oder unter Network fallen beendet laufende Sitzungen bei der nächsten Anfrage.

Schnellstart in 5 Schritten

  1. Einbettung anlegen unter Einstellungen → Kalender-Einbettungen. Mit einer Vorlage beginnen, den exakten Origin jeder Seite eintragen, die sie anzeigt (z. B. https://crm.example.com), die Detailstufe wählen und Speichern. Die Live-Vorschau zeigt genau, was Partner sehen.
  2. API-Schlüssel anlegen unter Einstellungen → Integrationen → REST-API-Schlüssel nur mit dem Scope embeds:session und auf den IP-Bereich Ihres Servers beschränken. Als Server-Secret speichern (GENKO_API_KEY).
  3. Einen Backend-Endpunkt ergänzen, der Ihren Benutzer authentifiziert und POST /api/v1/embeds/{id}/sessions aufruft — ausgehend von einem der Beispiele unten.
  4. Das Snippet einfügen in CRM oder Seite: das Script embed.js plus Genko.embed.mount(...), wobei getToken Ihren Endpunkt aufruft. Der Editor zeigt es mit Ihrer Einbettungs-ID.
  5. Prüfen mit dem Origin-Test im Editor: die Adresse der Seite einfügen und auf Erlaubt achten. Dann die Seite öffnen: Der Kalender erscheint, und ein Klick auf einen Termin löst appointment:click aus.

Token-Endpunkt im Backend

Ihr Endpunkt ist der einzige Ort, an dem der API-Schlüssel verwendet wird. Er authentifiziert zuerst Ihren eigenen Benutzer, stellt dann ein Token für ihn aus und gibt es an den Browser zurück.

  • POST /api/v1/embeds/{id}/sessions mit Authorization: Bearer genko_… und JSON-Body: viewer (Pflicht, siehe unten), optional providers (bis 50 Behandler-IDs), optional view (day, week, month oder agenda) und optional ttl_seconds (60–3600, Standard 900).
  • Der Viewer ist Ihr Benutzer, kein Genkō-Konto. Die Personen in Ihrem CRM haben keinen Genkō-Login, also teilt Ihr Server mit, wer zusieht: id ist Ihre eigene, stabile Benutzer-ID (z. B. crm-user-42), label ein lesbarer Name oder eine E-Mail (z. B. Dana Smith); beide Pflicht, 1–128 Zeichen. Genkō prüft sie gegen nichts — es vertraut ihnen, weil Ihr Schlüssel das Token erzeugt hat. Sie werden ins Token signiert und mit der Schlüssel-ID ins Audit-Protokoll der Praxis geschrieben: beim Erzeugen des Tokens und bei jeder Datenanfrage mit Detailstufe full, die Patienten liefert, zusammen mit deren IDs. So kann die Praxis nachvollziehen, welcher Ihrer Benutzer welche Patienten gesehen hat. Verwenden Sie für eine Person immer dieselbe id. Der Viewer gewährt keinen Zugriff und wird im Kalender nicht angezeigt: Was sichtbar ist, bestimmen die Einbettung, der Schlüssel und die Eingrenzung über providers/view.
  • Eingrenzen verkleinert nur. providers muss innerhalb der Behandler der Einbettung liegen und view eine ihrer Ansichten sein; alles Weitere wird mit 400 VALIDATION_ERROR abgelehnt statt still ignoriert.
  • Erfolg ist 201 mit { token, expires_at, embed_id, viewer }. Der Aufruf ist nicht idempotent und wird nie aus dem Idempotenz-Cache wiederholt: Jeder Aufruf liefert ein neues Token.
  • Fehler behandeln: bei 401/403 Schlüssel, Scope, IP-Bereich und Tarif prüfen; bei 404 die Einbettungs-ID; bei 409 ist die Einbettung deaktiviert oder abgelaufen; bei 429 Retry-After abwarten. Geben Sie dem Browser einen allgemeinen Fehler zurück — der Loader löst ein error-Ereignis aus und versucht es beim nächsten Erneuern wieder.

Node.js

// token-server.mjs — Node 18+, no dependencies.
// Run: GENKO_API_KEY=genko_… node token-server.mjs
import http from 'node:http'

const GENKO = 'https://www.getgenko.com'
const EMBED_ID = 'emb_…'
// A REST key holding ONLY the embeds:session scope. It stays on this server.
const API_KEY = process.env.GENKO_API_KEY

async function mintEmbedToken({ viewer, providers, view }) {
  const res = await fetch(`${GENKO}/api/v1/embeds/${EMBED_ID}/sessions`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ viewer, providers, view, ttl_seconds: 900 }),
  })
  const body = await res.json().catch(() => ({}))
  if (!res.ok) throw new Error(`Genkō ${res.status} ${body.error?.code}: ${body.error?.message}`)
  return body.data // { token, expires_at, embed_id, viewer }
}

http.createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/genko/embed-token') { res.writeHead(404).end(); return }
  // 1. Authenticate YOUR user first (session cookie, SSO, …) and refuse anonymous callers.
  const user = { id: 'crm-user-42', name: 'Dana Smith' } // ← your signed-in user
  try {
    const session = await mintEmbedToken({
      // viewer = who is looking, in YOUR app (Genkō has no account for them). Both fields are
      // required, 1–128 chars, signed into the token and written to the practice's audit log.
      // They grant no access: what the calendar shows comes from the embed and the narrowing below.
      //   id:    your stable user id — keep it the same for a person, so audits can be traced back
      //   label: a readable name or email, so the practice can read the audit log without asking you
      viewer: { id: user.id, label: user.name },
      // Optional narrowing — it can only shrink what the embed allows:
      // providers: ['<provider uuid>'], view: 'week',
    })
    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' })
    res.end(JSON.stringify({ token: session.token, expires_at: session.expires_at }))
  } catch (err) {
    console.error(err.message)
    res.writeHead(502, { 'Content-Type': 'application/json' })
    res.end(JSON.stringify({ error: 'embed_token_unavailable' }))
  }
}).listen(3001, () => console.log('Token endpoint on http://localhost:3001/genko/embed-token'))

Python

# token_server.py — Python 3.9+, standard library only.
# Run: GENKO_API_KEY=genko_… python3 token_server.py
import json
import os
import urllib.error
import urllib.request
from http.server import BaseHTTPRequestHandler, HTTPServer

GENKO = "https://www.getgenko.com"
EMBED_ID = "emb_…"
# A REST key holding ONLY the embeds:session scope. It stays on this server.
API_KEY = os.environ["GENKO_API_KEY"]


def mint_embed_token(viewer, providers=None, view=None, ttl_seconds=900):
    body = {"viewer": viewer, "ttl_seconds": ttl_seconds}
    if providers:
        body["providers"] = providers  # narrowing: can only shrink what the embed allows
    if view:
        body["view"] = view
    req = urllib.request.Request(
        f"{GENKO}/api/v1/embeds/{EMBED_ID}/sessions",
        data=json.dumps(body).encode(),
        method="POST",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(req, timeout=10) as res:
            return json.load(res)["data"]  # {token, expires_at, embed_id, viewer}
    except urllib.error.HTTPError as e:
        err = (json.loads(e.read() or b"{}").get("error") or {})
        raise RuntimeError(f"Genkō {e.code} {err.get('code')}: {err.get('message')}") from None


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/genko/embed-token":
            self.send_error(404)
            return
        # 1. Authenticate YOUR user first and refuse anonymous callers.
        user = {"id": "crm-user-42", "name": "Dana Smith"}  # ← your signed-in user
        # viewer = who is looking, in YOUR app (Genkō has no account for them). Both fields are
        # required, 1–128 chars, signed into the token and written to the practice's audit log.
        # They grant no access: what the calendar shows comes from the embed and its narrowing.
        #   id:    your stable user id — keep it the same for a person, so audits can be traced back
        #   label: a readable name or email, so the practice can read the audit log without asking you
        viewer = {"id": user["id"], "label": user["name"]}
        try:
            session = mint_embed_token(viewer)
            # e.g. mint_embed_token(viewer, providers=["<provider uuid>"], view="week")
            status, payload = 200, {"token": session["token"], "expires_at": session["expires_at"]}
        except Exception as exc:
            self.log_error("%s", exc)
            status, payload = 502, {"error": "embed_token_unavailable"}
        data = json.dumps(payload).encode()
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Cache-Control", "no-store")
        self.send_header("Content-Length", str(len(data)))
        self.end_headers()
        self.wfile.write(data)


HTTPServer(("127.0.0.1", 3001), Handler).serve_forever()

PHP

<?php
// genko-embed-token.php — PHP 7.4+ with the curl extension. Route POST /genko/embed-token here.
// Set GENKO_API_KEY=genko_… in the environment: a REST key holding ONLY the embeds:session scope.
const GENKO = 'https://www.getgenko.com';
const EMBED_ID = 'emb_…';

function mint_embed_token(array $viewer, ?array $providers = null, ?string $view = null): array {
    $body = ['viewer' => $viewer, 'ttl_seconds' => 900];
    if ($providers) $body['providers'] = $providers; // narrowing: can only shrink what the embed allows
    if ($view) $body['view'] = $view;

    $ch = curl_init(GENKO . '/api/v1/embeds/' . EMBED_ID . '/sessions');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('GENKO_API_KEY'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $error = curl_error($ch);
    curl_close($ch);

    if ($raw === false) throw new RuntimeException("Genkō unreachable: $error");
    $json = json_decode($raw, true);
    if ($status !== 201) {
        throw new RuntimeException("Genkō $status " . ($json['error']['code'] ?? '') . ': ' . ($json['error']['message'] ?? ''));
    }
    return $json['data']; // token, expires_at, embed_id, viewer
}

// 1. Authenticate YOUR user first and refuse anonymous callers.
$user = ['id' => 'crm-user-42', 'name' => 'Dana Smith']; // ← your signed-in user

header('Content-Type: application/json');
header('Cache-Control: no-store');
// viewer = who is looking, in YOUR app (Genkō has no account for them). Both fields are
// required, 1–128 chars, signed into the token and written to the practice's audit log.
// They grant no access: what the calendar shows comes from the embed and its narrowing.
//   id:    your stable user id — keep it the same for a person, so audits can be traced back
//   label: a readable name or email, so the practice can read the audit log without asking you
$viewer = ['id' => $user['id'], 'label' => $user['name']];
try {
    $session = mint_embed_token($viewer);
    // e.g. mint_embed_token($viewer, ['<provider uuid>'], 'week');
    echo json_encode(['token' => $session['token'], 'expires_at' => $session['expires_at']]);
} catch (Throwable $e) {
    error_log($e->getMessage());
    http_response_code(502);
    echo json_encode(['error' => 'embed_token_unavailable']);
}

curl

# The key stays on your server: a REST key holding ONLY the embeds:session scope.
export GENKO_API_KEY=genko_…

# Mint a token for one viewer (15 minutes by default, at most 60).
# viewer = who is looking, in YOUR app: id = your stable user id, label = a readable name or
# email (both required, 1–128 chars). Signed into the token and written to the practice's
# audit log; they grant no access.
curl -sS -X POST "https://www.getgenko.com/api/v1/embeds/emb_…/sessions" \
  -H "Authorization: Bearer $GENKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"viewer":{"id":"crm-user-42","label":"Dana Smith"}}'

# Narrowed: only one provider, locked to the week view, 30 minutes:
curl -sS -X POST "https://www.getgenko.com/api/v1/embeds/emb_…/sessions" \
  -H "Authorization: Bearer $GENKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"viewer":{"id":"crm-user-42","label":"Dana Smith"},"providers":["<provider uuid>"],"view":"week","ttl_seconds":1800}'

# → 201 {"data":{"token":"eyJ…","expires_at":"…","embed_id":"emb_…","viewer":{…}},"error":null,"meta":{…}}
Rufen Sie diesen Endpunkt nie aus einem Browser auf und geben Sie den Schlüssel nie an einen Client weiter (auch nicht an mobile Apps). Gelangt ein Schlüssel nach außen, widerrufen Sie ihn: Alle damit ausgestellten Sitzungen enden in Sekunden.

Frontend-Integration

Der Loader (empfohlen)

Laden Sie embed.js von Genkō und binden Sie den Kalender in ein Element ein. getToken ist Ihre Funktion: Sie fragt Ihr Backend nach einem Token und gibt ein Promise mit dem Token zurück. Der Loader ruft sie beim Laden und etwa eine Minute vor jedem Ablauf erneut auf, damit der Kalender nie veraltet.

<div id="genko-calendar"></div>
<script src="https://www.getgenko.com/embed.js"></script>
<script>
  var calendar = Genko.embed.mount(document.getElementById('genko-calendar'), {
    embed: 'emb_…',
    // Called on load and again shortly before each token expires.
    // It must ask YOUR server for a token — never put an API key in the page.
    getToken: function () {
      return fetch('/genko/embed-token', { method: 'POST', credentials: 'same-origin' })
        .then(function (res) {
          if (!res.ok) throw new Error('Token request failed: ' + res.status)
          return res.json()
        })
        .then(function (data) { return data.token })
    },
    // Optional: view: 'week', providers: ['<provider uuid>']
    // Optional: theme: 'dark' — overrides the theme configured on the embed; omit it to use that one
  })

  calendar.on('appointment:click', function (appointment) {
    // appointment.id is Genkō's id; appointment.external_id is the id you set via the API (or null)
    console.log('Clicked', appointment.id, appointment.external_id)
  })
  calendar.on('error', function (err) { console.warn('Calendar embed error:', err.code) })
</script>
  • Der Loader erstellt das Iframe mit referrerpolicy="origin" und übergibt das Token im URL-Fragment (#t=…), das Browser nie an einen Server senden. Das Iframe entfernt es sofort aus seiner Adresse.
  • Das Iframe passt seine Höhe dem Inhalt an (außer Sie übergeben height oder die Einbettung hat eine feste Höhe).
  • Das Script einmal pro Seite einbinden; beliebig viele Kalender einbetten.

Einfaches <iframe> (für CRMs, die Scripts entfernen)

Wenn Ihr CRM nur ein Iframe akzeptiert, erzeugen Sie es serverseitig mit einem frisch ausgestellten Token.

<!-- For CRMs that strip <script>. Render this on YOUR server with a fresh token.
     It cannot refresh itself: after the token expires (15 min by default) the viewer must reload. -->
<iframe
  src="https://www.getgenko.com/embed/emb_…#t=YOUR_TOKEN"
  referrerpolicy="origin"
  title="Calendar"
  style="width:100%;height:720px;border:0">
</iframe>
  • Keine automatische Erneuerung: Läuft das Token ab (standardmäßig 15 Minuten, bis 60 mit ttl_seconds), zeigt der Kalender Sitzung abgelaufen, bis die Seite neu geladen wird. Stellen Sie das Token beim Rendern der Seite aus, nie im Voraus.
  • Ihre Seite erhält keine Ereignisse (kein Loader leitet sie weiter), und die Höhe ist fest.
  • Behalten Sie referrerpolicy="origin": Ohne diese Angabe senden manche Browser keinen Origin, und die Einbettung lädt nicht.

Eine eigenständige Testseite

Um eine Einbettung ohne CRM zu prüfen, speichern Sie diese Seite als test.html, liefern Sie sie von einem der erlaubten Origins aus und fügen Sie ein Token aus dem curl-Beispiel ein. In Produktion müssen Origins https sein: Nutzen Sie einen eigenen Host oder einen https-Tunnel.

<!doctype html>
<!-- Save as test.html and serve it from one of the embed's allowed origins (the page's origin
     must match exactly). Paste a token from the curl example; it is valid for 15 minutes. -->
<html>
<head><meta charset="utf-8"><title>Genkō calendar embed test</title></head>
<body style="font-family:system-ui;margin:24px">
  <h1>Calendar embed test</h1>
  <div id="genko-calendar"></div>
  <pre id="log"></pre>
  <script src="https://www.getgenko.com/embed.js"></script>
  <script>
    var TOKEN = 'YOUR_TOKEN' // from the curl example
    var log = function (m) { document.getElementById('log').textContent += m + '\n' }
    Genko.embed.mount(document.getElementById('genko-calendar'), {
      embed: 'emb_…',
      getToken: function () { return Promise.resolve(TOKEN) }
    })
      .on('ready', function () { log('ready') })
      .on('appointment:click', function (a) { log('click ' + a.id + ' ' + a.external_id) })
      .on('token:expired', function () { log('token expired — paste a new one and reload') })
      .on('error', function (e) { log('error ' + e.code) })
  </script>
</body>
</html>

Hinweise für CRMs und Websites

  • CRMs mit eigenem HTML oder Scripts: das Loader-Snippet verwenden. Den Token-Endpunkt hinter die Anmeldung Ihres CRMs legen (dessen Backend, eine Serverless-Funktion oder Ihr Integrationsserver).
  • CRMs, die nur ein Iframe oder ein URL-Widget erlauben: das einfache Iframe serverseitig mit frischem Token erzeugen oder das Widget auf eine kleine Seite Ihrer Domain zeigen lassen, die den Loader nutzt — deren Origin tragen Sie in der Einbettung ein.
  • Editoren, die Scripts entfernen (Rich-Text-Felder, manche CMS-Blöcke): wie bei nur Iframe. Werden auch Iframes entfernt, verlinken Sie stattdessen auf eine Seite Ihrer Domain.
  • Der Origin ist der der Seite, nicht des Anbieters. Erscheint der Kalender auf https://acme.examplecrm.com/…, tragen Sie https://acme.examplecrm.com ein. Tragen Sie jeden Host ein, auf dem er erscheinen kann (z. B. https://app.example.com und https://www.example.com).
  • Menüpfade einzelner Anbieter dokumentieren wir nicht — sie ändern sich oft. Suchen Sie in Ihrem CRM nach benutzerdefiniertem HTML, Iframe-Widget oder Web-Tab.

Hat die Seite eine eigene Content Security Policy, erlauben Sie Genkō als Frame-Quelle (und als Script-Quelle für den Loader). Das Iframe stellt seine Anfragen an Genkō selbst, connect-src braucht also nichts.

Content-Security-Policy: frame-src https://www.getgenko.com; script-src 'self' https://www.getgenko.com

Auf Genkō-Seite ist alles eingerichtet: Jede https-Seite darf /embed/* einbetten, und die Einbettung entscheidet selbst, ob sie für Ihren Origin angezeigt wird.

Konfigurationsreferenz

Sicherheitsrelevante Einstellungen sind eigene, von der Datenbank geprüfte Felder; die Darstellung liegt in einem versionierten config-Objekt. Beides wird im Editor bearbeitet.

Zugriff und Daten

EinstellungTypStandardGrenzenBeschreibung
namestring—1–80Interne Bezeichnung (in den Einstellungen sichtbar, nie für Partner).
activebooleantrueEinbettung abschalten, ohne sie zu löschen; laufende Sitzungen enden in Sekunden.
expires_attimestamp | nullnull> nowOptionales Enddatum. Sitzungen überdauern es nie.
allowed_originsstring[]—1–10Exakte Origins, die sie anzeigen dürfen: https://host[:port], klein geschrieben, ohne Pfad, ohne abschließenden Schrägstrich, ohne Platzhalter.
provider_idsuuid[][] = all≤ 100Nur Termine dieser Behandler. Tokens und providers des Loaders können weiter eingrenzen.
service_idsuuid[][] = all≤ 100Nur Termine dieser Leistungen.
statusesstring[]scheduled, confirmed, completed, pending_payment1–6Welche Terminstatus erscheinen (cancelled und no_show sind standardmäßig ausgeblendet).
window_days_backinteger70–90Wie weit in die Vergangenheit sie höchstens zeigt, egal welcher Zeitraum angefragt wird.
window_days_aheadinteger600–366Wie weit in die Zukunft sie zeigt.
detail_levelbusy | service | fullbusyDas Maximum, das eine Sitzung sehen darf — siehe Tabelle unten.

Darstellung (config)

EinstellungTypStandardGrenzenBeschreibung
viewsday week month agendaall four1–4Ansichten, zwischen denen gewechselt werden kann.
default_viewviewweek∈ viewsStartansicht (view des Loaders oder eines Tokens kann eine andere aktivierte Ansicht wählen).
week_startmonday | sundaymondayErster Wochentag in Wochen- und Monatsansicht.
hours{ start, end }{ 7, 20 }0 ≤ start < end ≤ 24Sichtbare Stunden im Tages- und Wochenraster.
weekendsbooleantrueSamstag und Sonntag in der Wochenansicht zeigen.
timezoneorg | provider | viewerorgorg: Zeitzone der Praxis; provider: die des Behandlers, wenn auf einen eingegrenzt; viewer: die des Geräts.
localeen | esenSprache der Oberfläche.
themelight | dark | autolightauto folgt dem Gerät. theme des Loaders überschreibt es.
primary_colorhex#4f46e5#RRGGBBAkzentfarbe. Nur Hex — es gibt kein eigenes CSS.
color_byprovider | service | statusproviderWonach Termine eingefärbt werden. Belegt-Einbettungen färben immer nach Behandler.
toolbar{ navigation, today, view_switcher, title }all trueZurück/Weiter, Heute, Ansichtswahl und Titel ein- oder ausblenden.
height{ mode: auto | fixed, px }auto, 720px 320–2000auto passt sich dem Inhalt an (der Loader skaliert das Iframe); fixed nutzt px und scrollt innen.
clickpanel | event | nonepanelpanel: schreibgeschütztes Detailfenster öffnen und appointment:click senden; event: nur das Ereignis senden; none: nichts.
actions{ confirm, reschedule, cancel }all falsefalseReserviert für Bestätigen, Verschieben und Absagen. Muss false sein; noch nicht verfügbar.

Was jede Detailstufe preisgibt

StufeFelderHinweise
busyid, external_id, starts_at, ends_at, provider { id, full_name }Nur, dass eine Zeit belegt ist und bei welchem Behandler. Keine Leistung, kein Status, kein Patient.
service+ service { id, name, color }, statusZusätzlich Name und Farbe der Leistung sowie der Terminstatus. Weiterhin kein Patient.
full+ patient { id, external_id, full_name, email, phone }Zusätzlich Name, E-Mail und Telefon des Patienten. Jede Datenanfrage auf dieser Stufe erzeugt einen detaillierten Audit-Eintrag mit dem Betrachter. Nur verwenden, wo die Betrachter Patientenidentitäten sehen dürfen.

JavaScript-API und Ereignisse

embed.js definiert genau ein globales Objekt, Genko.embed. Es ist reines ES5 und läuft daher auch in älteren CRM-Browsern.

var calendar = Genko.embed.mount(element, {
  embed: 'emb_…',           // required
  getToken: function (ctx) {          // required: returns a Promise of a token string
    // ctx = { embed, view, providers } — pass them to your backend to narrow the token
    return fetch('/genko/embed-token', { method: 'POST' }).then(function (r) { return r.json() })
      .then(function (d) { return d.token })
  },
  view: 'week',                       // optional: start in this view (one of the embed's views)
  providers: ['<provider uuid>'],     // optional: show fewer providers (never more than the token allows)
  theme: 'dark',                      // optional: light | dark | auto — OVERRIDES the embed's configured theme; omit to use it
  height: 640,                        // optional: fixed pixel height (omit to auto-resize)
  title: 'Team calendar'              // optional: the iframe's accessible title
})

calendar.on('ready', function (e) { /* { embed, view } */ })
calendar.on('appointment:click', function (a) { /* { id, external_id, starts_at, ends_at } */ })
calendar.on('token:expired', function (e) { /* { reason } — the loader is already fetching a new token */ })
calendar.on('resize', function (e) { /* { height } */ })
calendar.on('error', function (e) { /* { code, message? } */ })

calendar.update({ view: 'day', providers: ['<provider uuid>'], theme: 'dark' })
calendar.off('appointment:click')     // remove all handlers for an event (or pass the handler)
calendar.destroy()                    // remove the iframe and every listener
  • mount(element, options) gibt eine Instanz zurück. Fehlt das Element, ist die ID ungültig oder fehlt getToken, wird sofort ein Fehler geworfen.
  • on(event, handler) / off(event, handler?) abonnieren und kündigen; unbekannte Ereignisnamen werfen einen Fehler. Eine Ausnahme in einem Handler stoppt die anderen nie.
  • update({ view, providers, theme }) ändert den Kalender zur Laufzeit. Eine Änderung von view oder providers ruft getToken mit den neuen Werten erneut auf, damit Ihr Backend ein enger gefasstes Token ausstellen kann.
  • destroy() entfernt das Iframe und alle Listener.
  • Ereignisse: ready (erste Daten sichtbar), appointment:click (mit id und external_id — die ID, die Sie dem Termin über die API gegeben haben, oder null), token:expired (der Loader holt bereits ein neues Token), resize und error (Codes unten).

Das Nachrichtenprotokoll genko:v1

Loader und Iframe kommunizieren über postMessage; jede Nachricht trägt ns: "genko:v1". Der Loader akzeptiert Nachrichten nur von seinem eigenen Iframe am Origin von Genkō; das Iframe nur vom serverseitig geprüften Eltern-Origin und verweigert die Anzeige, wenn eine genko:v1-Nachricht von anderswo kommt. Das brauchen Sie nur für einen eigenen Loader.

// iframe → your page (checked: event.origin === embed origin && event.source === the iframe)
{ ns: 'genko:v1', type: 'init' }                      // asks the loader for its options
{ ns: 'genko:v1', type: 'ready', view: 'week' }
{ ns: 'genko:v1', type: 'resize', height: 812 }
{ ns: 'genko:v1', type: 'appointment:click', appointment: { id, external_id, starts_at, ends_at } }
{ ns: 'genko:v1', type: 'token:expired', reason: 'token_expired' }
{ ns: 'genko:v1', type: 'error', code: 'origin_not_allowed' }

// your page → iframe (accepted only from the parent origin the server verified)
{ ns: 'genko:v1', type: 'options', view, providers, theme }
{ ns: 'genko:v1', type: 'token', token: 'eyJ…' }

Fehler und Fehlerbehebung

Jede Antwort hat die Form { data, error: { code, message, details? }, meta: { request_id } }. Verzweigen Sie nach error.code (stabil) und beim Datenendpunkt nach error.details.reason — nie nach dem Text. Nennen Sie dem Support meta.request_id.

POST /api/v1/embeds/{id}/sessions

CodeHTTPWann
UNAUTHORIZED401Fehlender, fehlerhafter, unbekannter, widerrufener oder abgelaufener Schlüssel; ein MCP-Schlüssel (genko_mcp_…); oder ein Einbettungs-Token als Schlüssel.
FORBIDDEN403Dem Schlüssel fehlt embeds:session (details.required_scope), oder die Anfrage kam von einer IP außerhalb seiner Freigabeliste.
PLAN_LIMIT403Die Organisation ist nicht im Network-Tarif (details.required_plan: "enterprise", die stabile Kennung des Network-Tarifs).
NOT_FOUND404Keine solche Einbettung in der Organisation des Schlüssels.
CONFLICT409Die Einbettung ist deaktiviert (details.reason: "embed_inactive") oder abgelaufen ("embed_expired").
VALIDATION_ERROR400Ungültiger Body (fehlendes viewer, unbekanntes Feld, ttl_seconds außerhalb des Bereichs) oder Eingrenzung weiter als die Einbettung (details.not_in_embed, details.enabled_views).
INVALID_JSON400Der Body ist kein gültiges JSON.
UNSUPPORTED_MEDIA_TYPE415Content-Type: application/json fehlt.
PAYLOAD_TOO_LARGE413Body über 1 MB.
RATE_LIMITED429Schreiblimit des Schlüssels überschritten; Retry-After Sekunden warten.
INTERNAL500Unser Fehler; mit Backoff erneut versuchen.

GET /api/embed/{id}/appointments (vom Iframe aufgerufen)

CodeHTTPWann
UNAUTHORIZED401details.reason: missing_token, invalid_token, token_expired (der Loader holt ein neues) oder session_revoked (Schlüssel widerrufen oder embeds:session entzogen).
FORBIDDEN403origin_not_allowed (Origin nicht im Token oder nicht mehr auf der Einbettung) oder embed_inactive (deaktiviert oder abgelaufen).
PLAN_LIMIT403Die Organisation ist unter Network gefallen.
VALIDATION_ERROR400Zeitraum über 31 Tage, from nicht vor to, ein unbekannter Parameter oder ein Credential in der URL.
RATE_LIMITED429Mehr als 120 Anfragen pro Minute für diese Einbettung von einer IP.
INTERNAL500Unser Fehler; der Kalender bietet Erneut versuchen an.

Codes des error-Ereignisses im Loader

codeBedeutung
origin_not_allowedDer Origin der Seite steht nicht auf der Liste der Einbettung (oder der Browser hat keinen gesendet).
embed_inactiveDie Einbettung ist deaktiviert oder abgelaufen.
plan_requiredDie Organisation ist nicht im Network-Tarif.
not_foundDie Einbettungs-ID existiert nicht.
token_fetch_failedBeim ersten Laden ist Ihr getToken fehlgeschlagen oder hat kein Token geliefert.
token_refresh_failedDasselbe beim Erneuern; der Kalender funktioniert weiter, bis das alte Token abläuft.
network_errorDas Iframe konnte Genkō nicht erreichen.

Häufige Probleme

Im Rahmen steht Dieser Kalender kann hier nicht angezeigt werden
Der Origin der Seite steht nicht auf der Liste. Genau vergleichen — Schema, Host und Port: https://www.example.com und https://example.com sind verschiedene Origins, ebenso http und https. Nutzen Sie den Origin-Test im Editor mit der vollständigen Adresse der Seite.
… hat die Verbindung abgelehnt (die eigene Fehlerseite des Browsers im Rahmen)
Das Iframe zeigt auf eine Seite, die nicht eingebettet werden darf — meist eine Dashboard-URL statt /embed/emb_… — oder die Content Security Policy Ihrer Seite blockiert Genkō in frame-src (die Browserkonsole nennt den Grund).
Sitzung abgelaufen
Das Token ist abgelaufen. Mit dem Loader dauert das nur, bis getToken ein neues liefert; bleibt es, schlägt Ihr Token-Endpunkt fehl (achten Sie auf token_refresh_failed). Beim einfachen Iframe die Seite neu laden.
Der Sitzungstausch liefert 403 FORBIDDEN mit required_scope
Der Schlüssel hat kein embeds:session. Legen Sie einen Schlüssel mit diesem Scope an (Schlüssel lassen sich nicht bearbeiten).
403 PLAN_LIMIT
Kalender-Einbettungen erfordern den Network-Tarif (oder eine dedizierte Enterprise-Installation). Der Tarif wird bei jeder Anfrage geprüft; ein Downgrade stoppt Einbettungen sofort.
Speichern scheitert mit Each origin must be exact
Pfade, abschließende Schrägstriche und Platzhalter entfernen: https://crm.example.com, nicht https://crm.example.com/ oder https://*.example.com.
Nichts erscheint, und es gibt keinen Fehler
Prüfen Sie die Filter (Behandler, Leistungen, Status) und das Zeitfenster (Tage zurück und voraus): Ein Zeitraum außerhalb des Fensters liefert keine Termine statt eines Fehlers.

Limits und Sicherheit

  • Tokens: standardmäßig 15 Minuten, mit ttl_seconds 60 Sekunden bis 60 Minuten, nie über den Ablauf der Einbettung hinaus.
  • Daten: höchstens 31 Tage pro Anfrage (das Iframe teilt ein Monatsraster in zwei Anfragen) und 999 Termine pro Anfrage (darüber hinaus weist der Kalender darauf hin, dass er die ersten zeigt). Das Fenster der Einbettung — bis 90 Tage zurück und 366 voraus — begrenzt alles.
  • Ratenlimits: Der Datenendpunkt erlaubt 120 Anfragen pro Minute je Einbettung und IP; der Sitzungstausch zählt gegen das REST-Schreiblimit des Schlüssels (Network: 180 pro Minute und Schlüssel).
  • Einbettungen: 10 pro Organisation im Network-Tarif (50 in einer dedizierten Installation), je bis zu 10 Origins.
  • Patientendaten je Stufe: busy keine; service keine; full Name, E-Mail und Telefon — bei jeder Anfrage mit der ID des Betrachters protokolliert.
Klinische Daten sind nie enthalten, auf keiner Stufe: keine klinischen oder Terminnotizen, Anamneseantworten, Allergien, Medikamente, Erkrankungen, Versicherung, Geburtsdatum oder Adresse. Der Datenendpunkt fragt diese Spalten gar nicht erst ab.

Ausblick

  • Aktionen — Bestätigen, Verschieben und Absagen direkt in der Einbettung — sind geplant und noch nicht verfügbar. Die Konfiguration reserviert sie bereits (config.actions); zum Einschalten ist später keine neue Einbettung nötig.
  • Ebenfalls geplant: eine Einbettung an bestimmte API-Schlüssel binden und im Editor einen eigenen Schlüssel erzeugen.
  • Derzeit nicht geplant: ein öffentlicher (anonymer) Modus und eigenes CSS.

API & KI (MCP)

Was ist die MCP-API?

Genkō stellt einen Model Context Protocol (MCP)-Server bereit, der es externen KI-Agenten und Tools ermöglicht, Ihre Praxisdaten in einem strukturierten Tool-Call-Format zu lesen und zu schreiben. Dies ist die gleiche zugrunde liegende Registry, die vom Dashboard-KI-Assistenten verwendet wird – sodass jeder Agent, den Sie verbinden, Zugriff auf die gleichen Fähigkeiten erhält.

Der MCP-Endpunkt ist ein zustandsloser HTTP-Server, der mit jedem Client kompatibel ist, der den MCP Streamable HTTP-Transport spricht (z. B. Claude Desktop, OpenAI Agents SDK oder jeder benutzerdefinierte Agent, der mit @modelcontextprotocol/sdk erstellt wurde).

Plananforderungen: MCP-Zugriff ist ab dem Group-Plan verfügbar. Group erhält schreibgeschützten Zugriff (1 Schlüssel). Practice+ erhält Lese- + Schreibzugriff (3 Schlüssel). Network erhält alle Bereiche und unbegrenzte Schlüssel. MCP-Schlüssel und REST-API-Schlüssel werden getrennt begrenzt.
Getrennt von der REST-API: MCP-Schlüssel funktionieren nur unter /api/mcp, Schlüssel der REST-API nur unter /api/v1. Jede Art hat ein eigenes Panel unter Settings → Developers und ein eigenes Schlüssellimit, beide folgen aber denselben Bereichen und Planregeln, ein Tool und der passende Endpunkt verhalten sich also immer gleich.

Schnellstart

1. Gehen Sie zu Settings → Developers und scrollen Sie zum MCP keys-Panel.
2. Klicken Sie auf Add MCP key, geben Sie dem Schlüssel einen Namen (z. B. "Claude Desktop") und wählen Sie einen Bereich.
3. Kopieren Sie den angezeigten Rohschlüssel sofort – er wird nur einmal angezeigt.
4. Stellen Sie in Ihrem MCP-Client die Server-URL und den Authorization-Header ein:

# Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "genko": {
      "url": "https://www.getgenko.com/api/mcp",
      "headers": {
        "Authorization": "Bearer genko_mcp_YOUR_KEY_HERE"
      }
    }
  }
}
Org-Auswahl: Genkō löst die Organisation automatisch aus Ihrem API-Schlüssel auf – kein Org-Slug in der URL erforderlich.

Authentifizierung

Alle Anfragen an /api/mcp müssen einen gültigen API-Schlüssel als Bearer-Token enthalten:

Authorization: Bearer genko_mcp_...

MCP-Schlüssel werden in Settings → Developers → MCP keys erstellt. Jeder Schlüssel hat einen Bereich:

  • Read — kann nur List-/Get-Tools aufrufen (Group-Plan)
  • Read + Write — kann auch Datensätze erstellen und aktualisieren (Practice+-Plan)
  • Admin — alles oben Genannte plus klinische Datensätze und das Löschen von Patienten (Network)

Schlüssel können jederzeit widerrufen werden. Der Widerruf ist sofort – laufende Anfragen werden nicht unterbrochen, aber nachfolgende Anfragen mit dem widerrufenen Schlüssel geben 401 Unauthorized zurück.

Verfügbare Tools

Die verfügbar gemachten Tools hängen vom Bereich Ihres API-Schlüssels ab. Alle Tools arbeiten nur mit Daten, die auf Ihre Organisation beschränkt sind.

Read-Tools (verfügbar bei allen Bereichen):

  • list_appointments — listet Termine, gefiltert nach Patient, Provider, Leistung, Status, externer ID, einem date, einem relativen range (today, this_week, next_7_days, next_30_days) oder einem from/to-Fenster
  • get_appointment — ruft einen einzelnen Termin nach ID mit vollständigen Details ab
  • list_patients — durchsucht Patienten nach Name, E-Mail oder Telefon (mind. 3 Zeichen) oder findet einen per mrn oder external_id; paginiert mit meta.next_cursor
  • get_patient — ruft einen Patienten nach ID ab (klinische Felder wie Notizen und Allergien nur mit klinischem Zugriff)
  • list_providers — listet alle Provider mit ihren Fachrichtungen auf
  • get_provider — ruft das Profil eines Providers und dessen wöchentlichen Verfügbarkeitsplan ab
  • list_services — listet alle Termintypen (Dienstleistungen) mit Dauer und Preis auf
  • check_availability — gibt offene Zeitfenster für einen Provider an einem bestimmten Datum zurück
  • search_icd10cm_codes — durchsucht ICD-10-CM, um eine Diagnose zu kodieren (die Suche läuft in Genkō; nichts wird an Dritte gesendet)
  • get_org_info — ID, Name, Slug und Zeitzone der Organisation (für jeden Schlüssel verfügbar)
  • hubspot_get_status — zeigt, ob HubSpot mit der Organisation verbunden ist, und liefert dann Portal-ID und Verbindungsdatum (für jeden Schlüssel verfügbar; { connected: false }, wenn nicht verbunden)
Listen-Tools liefern { data, meta: { next_cursor, has_more, limit } } und akzeptieren cursor; übergeben Sie meta.next_cursor für die nächste Seite. Standardwerte, Antwortformen, Zeitzonenregeln und die Benennung Leistung / Termintyp stehen in der Tool-Referenz unten.

Write-Tools (Lese- + Schreib- oder Admin-Bereich, Practice+ erforderlich):

  • book_appointment — bucht einen neuen Termin (konfliktgeprüft)
  • update_appointment — ändert Zeit, Status oder Notizen eines vorhandenen Termins (konfliktgeprüft)
  • cancel_appointment — setzt einen Termin auf stornierten Status
  • update_patient — aktualisiert Name, E-Mail, Telefon, Geburtsdatum oder Notizen eines Patienten (mit null lässt sich ein Feld leeren); mit klinischem Schreibrecht auch die kodierten Listen zu Allergien, Diagnosen und Medikamenten
  • find_or_create_patient — sucht nach Telefon, E-Mail oder Name und legt den Datensatz auf Wunsch an, wenn er fehlt
  • hubspot_sync_patient — legt einen Patienten als HubSpot-Kontakt an oder aktualisiert ihn (Abgleich per E-Mail) und liefert die Kontakt-ID; erfordert eine HubSpot-Verbindung und eine Patienten-E-Mail
  • hubspot_log_appointment_note — protokolliert ein Terminereignis als Notiz am HubSpot-Kontakt des Patienten und synchronisiert den Kontakt bei Bedarf zuvor; erfordert eine HubSpot-Verbindung und eine Patienten-E-Mail
HubSpot-Tools: Die HubSpot-Synchronisierung ist eine Integration ab Starter und wird unter Settings → Integrations verbunden. Die beiden schreibenden Tools brauchen einen Read-+-Write-Schlüssel (Practice+) und schlagen mit einem Fehler fehl, wenn HubSpot nicht verbunden ist; hubspot_get_status schlägt aus diesem Grund nie fehl.
Konflikterkennung: book_appointment und update_appointment führen serverseitige Konfliktprüfungen durch. Wenn der Slot bereits belegt ist, gibt das Tool einen CONFLICT-Fehler zurück, anstatt doppelt zu buchen.
Statusregeln: Termine mit dem Status completed, cancelled und no_show sind final – update_appointment und cancel_appointment geben einen INVALID_TRANSITION-Fehler zurück, statt sie wieder zu öffnen. Das Stornieren eines bereits stornierten Termins gelingt, ohne den Patienten erneut zu benachrichtigen. Tool-Fehler enthalten einen stabilen code (z. B. NOT_FOUND, CONFLICT, INVALID_TRANSITION, VALIDATION_ERROR), auf den Sie in Ihrer Logik reagieren können.

Klinische Datensatz-Tools (Admin-Schlüssel, Network erforderlich — dieselbe Regel wie bei den klinischen REST-Endpunkten):

  • get_patient_record — ruft das vollständige longitudinale Patientenprotokoll ab: alle Besuche mit klinischen Notizen und Intake-Formularen in chronologischer Reihenfolge
  • list_appointment_notes — listet alle klinischen Notizen zu einem Termin auf (SOAP, Verlauf, Intake-Überprüfung, Entlassung)
  • get_clinical_note — ruft eine einzelne klinische Notiz nach ID mit allen SOAP-Feldern oder Freitext ab
  • get_appointment_intake — ruft das vom Patienten ausgefüllte Vorbesuchsformular für einen Termin ab
  • create_clinical_note — erstellt eine SOAP- oder Verlaufsnotiz als Entwurf für einen Termin; eine Fachkraft signiert sie im Dashboard (is_draft=false wird mit NOTE_SIGN_REQUIRES_CLINICIAN abgelehnt); sie kann eine Fachvorlage enthalten (template_key + template_data)
  • update_clinical_note — bearbeitet einen Notizentwurf (mit appointment_id); eine signierte Notiz liefert NOTE_LOCKED und wird nie verändert
  • add_clinical_addendum — fügt einer signierten Notiz einen Nachtrag als Entwurf hinzu (Korrektur oder spätere Ergänzung); die ursprüngliche Notiz ändert sich nie

Admin-Tools (Admin-Bereich, Network+ erforderlich):

  • review_intake — genehmigt oder lehnt ein Intake-Formular ab; abgelehnte Formulare fordern den Patienten zur Überarbeitung auf

Tool-Referenz

Jedes Tool mit Parametern, Standardwerten und Ergebnis. Diese Tabelle wird bei jedem Build gegen den Server geprüft und kann daher nicht von dem abweichen, was tools/list liefert. Ein Schlüssel sieht nur die Tools, die sein Scope und Ihr Tarif erlauben.

ToolVoraussetzungParameterRückgabe
get_org_infojeder Schlüsselkeine{ id, name, slug, timezone }
list_servicesservices:read
Group+
  • cursor string · optional
  • limit integer · 1–100 · Standard 100 · optional
  • external_id string · optional
{ data, meta }
list_providersproviders:read
Group+
  • cursor string · optional
  • limit integer · 1–100 · Standard 100 · optional
  • external_id string · optional
{ data, meta }
check_availabilityscheduling:read
Group+
  • provider_id uuid · Pflicht
  • date date · YYYY-MM-DD · Pflicht
  • duration_minutes integer · 5–480 · Standard 30 · optional
  • appointment_type_id uuid · optional
[{ start, end, starts_at, ends_at, timezone }]
list_appointmentsscheduling:read
Group+
  • patient_id uuid · optional
  • provider_id uuid · optional
  • service_id uuid · optional
  • external_id string · optional
  • range enum · today | this_week | next_7_days | next_30_days · optional
  • date date · YYYY-MM-DD · optional
  • from datetime · optional
  • to datetime · optional
  • status enum · scheduled | confirmed | cancelled | completed | no_show · optional
  • limit integer · 1–100 · Standard 50 · optional
  • cursor string · optional
{ data, meta }
get_appointmentscheduling:read
Group+
  • appointment_id uuid · Pflicht
appointment
list_patientspatients:read
Group+
  • query string · optional
  • email string · optional
  • phone string · optional
  • mrn string · optional
  • external_id string · optional
  • include_total boolean · optional
  • limit integer · 1–50 · Standard 20 · optional
  • cursor string · optional
{ data, meta }
get_patientpatients:read
Group+
  • patient_id uuid · Pflicht
patient
get_providerproviders:read
Group+
  • provider_id uuid · Pflicht
provider
search_icd10cm_codespatients:read
Group+
  • query string · Pflicht
  • system enum · diagnosis | icd10cm | cie10 · Standard diagnosis · optional
  • limit integer · 1–50 · Standard 10 · optional
{ release, system, results }
hubspot_get_statusjeder Schlüsselkeine{ connected, portal_id?, connected_at? }
find_or_create_patientpatients:write
Practice+
  • phone string · E.164 · optional
  • email string · optional
  • full_name string · optional
  • auto_create boolean · Standard false · optional
{ found, patient | patients, created? }
book_appointmentscheduling:write
Practice+
  • patient_id uuid · Pflicht
  • provider_id uuid · Pflicht
  • starts_at datetime · UTC, Z · Pflicht
  • ends_at datetime · UTC, Z · Pflicht
  • appointment_type_id uuid · optional
  • notes string · optional
{ booked: true, appointment }
cancel_appointmentscheduling:write
Practice+
  • appointment_id uuid · Pflicht
{ cancelled: true, already_cancelled?, appointment }
update_appointmentscheduling:write
Practice+
  • appointment_id uuid · Pflicht
  • starts_at datetime · UTC, Z · optional
  • ends_at datetime · UTC, Z · optional
  • status enum · scheduled | confirmed | completed | no_show · optional
  • notes string · optional
{ updated: true, appointment }
update_patientpatients:write
Practice+
  • patient_id uuid · Pflicht
  • full_name string · optional
  • email string · null löscht · optional
  • phone string · null löscht · optional
  • date_of_birth date · YYYY-MM-DD · null löscht · optional
  • notes string · null löscht · optional
  • given_names string · null löscht · optional
  • first_surname string · null löscht · optional
  • second_surname string · null löscht · optional
  • birth_country string · null löscht · optional
  • birth_state string · null löscht · optional
  • allergies array · optional
  • conditions array · optional
  • medications array · optional
{ updated: true, patient, updated_fields }
hubspot_sync_patientpatients:write
Practice+
  • patient_id uuid · Pflicht
{ synced: true, contact_id }
hubspot_log_appointment_notescheduling:write
Practice+
  • appointment_id uuid · Pflicht
{ logged: true, contact_id }
get_patient_recordclinical:read
Network
  • patient_id uuid · Pflicht
  • limit integer · 1–200 · Standard 100 · optional
[visit]
list_appointment_notesclinical:read
Network
  • appointment_id uuid · Pflicht
[note]
get_clinical_noteclinical:read
Network
  • note_id uuid · Pflicht
note
get_appointment_intakeclinical:read
Network
  • appointment_id uuid · Pflicht
intake | { status: "not_submitted" }
create_clinical_noteclinical:write
Network
  • appointment_id uuid · Pflicht
  • patient_id uuid · Pflicht
  • note_type enum · soap | progress | intake_review | discharge · Standard progress · optional
  • is_draft boolean · Standard true · optional
  • subjective string · optional
  • objective string · optional
  • assessment string · optional
  • plan_text string · optional
  • content string · optional
  • vitals object · optional
  • sis object · optional
  • template_key string · null löscht · optional
  • template_data object · optional
{ created: true, note }
update_clinical_noteclinical:write
Network
  • appointment_id uuid · Pflicht
  • note_id uuid · Pflicht
  • note_type enum · soap | progress | intake_review | discharge · optional
  • is_draft boolean · optional
  • subjective string · null löscht · optional
  • objective string · null löscht · optional
  • assessment string · null löscht · optional
  • plan_text string · null löscht · optional
  • content string · null löscht · optional
  • vitals object · optional
  • sis object · optional
  • template_key string · null löscht · optional
  • template_data object · optional
{ updated: true, note }
add_clinical_addendumclinical:write
Network
  • appointment_id uuid · Pflicht
  • note_id uuid · Pflicht
  • content string · Pflicht
{ created: true, addendum }
review_intakeclinical:write
Network
  • appointment_id uuid · Pflicht
  • status enum · approved | rejected · Pflicht
  • review_notes string · optional
{ reviewed: true, intake }

Konventionen für alle Tools

  • Antwortformen. Listen-Tools liefern { data, meta: { next_cursor, has_more, limit } }. check_availability liefert ein reines JSON-Array von Zeitfenstern ohne Hülle. Schreibende Tools liefern ein Objekt, das benennt, was geschehen ist: book_appointment { booked: true, appointment }, update_appointment { updated: true, appointment }, cancel_appointment { cancelled: true, appointment }. Einzel-Lesezugriffe (get_appointment, get_patient, get_provider) liefern den Datensatz selbst. Ein fehlgeschlagener Aufruf liefert isError: true mit { error, code, details? }; verzweigen Sie nach code.
  • Seitengröße. Alle Listen-Tools akzeptieren limit und cursor. Standard und Maximum: list_patients 20 (max. 50), list_appointments 50 (max. 100), list_services und list_providers 100 (max. 100). Übergeben Sie meta.next_cursor als cursor, um fortzufahren.
  • Leistungen sind Termintypen. Eine Leistung wird als Termintyp gespeichert, und die Tools verwenden beide Namen für dieselbe UUID: book_appointment und check_availability erwarten appointment_type_id, list_appointments filtert mit service_id, und jeder zurückgegebene Termin enthält service_id. Verwenden Sie für alle drei die ID aus list_services.
  • Zeitzonen: erst prüfen, dann buchen. check_availability liest date (YYYY-MM-DD) als Kalendertag in der Zeitzone des Behandlers, oder in der der Organisation, wenn der Behandler keine hat; die Antwort nennt die verwendete Zone in timezone. Jedes Zeitfenster hat lokale start/end und UTC-Werte starts_at/ends_at. book_appointment und update_appointment verlangen UTC-ISO-8601-Zeitstempel mit Z am Ende: Übernehmen Sie starts_at und ends_at unverändert aus dem Zeitfenster. Ein Zeitstempel ohne Offset wird in der Zone des Behandlers gelesen (Ersatz: die der Organisation), verlassen Sie sich aber nicht darauf. list_appointments liest date, from und to in der Zeitzone der Organisation.
  • Unbekannte Argumente werden abgelehnt. Wie die REST-API lehnt der MCP-Server einen Aufruf ab, der ein Argument enthält, das das Tool nicht definiert. Der Aufruf scheitert mit einem JSON-RPC-Fehler <code>InvalidParams</code> (-32602), der das Argument nennt, statt ohne es zu laufen; ein falsch geschriebener Filter erweitert das Ergebnis also nie unbemerkt. (Der Dashboard-Assistent ist nachsichtiger: Er verwirft unbekannte Argumente und behandelt leere oder null-Werte als nicht angegeben.)
Urheberschaft bei per API erstellten Notizen: per API erstellte klinische Notizen werden dem Benutzer zugeordnet, der den API-Schlüssel erstellt hat (oder dem Inhaber der Organisation, falls dieser Benutzer nicht mehr existiert). Jedes klinische Lesen und Schreiben wird im Audit-Log festgehalten.

Ratenlimits

MCP-API-Anfragen sind pro Schlüssel ratenlimitiert unter Verwendung eines festen 60-Sekunden-Fensters. Das Standardlimit beträgt 100 Anfragen pro Minute. Wenn Sie das Limit überschreiten, antwortet der Server mit:

HTTP 429 Too Many Requests
Retry-After: 60

Die Nutzung für jeden Schlüssel (Aufrufe der letzten 7 Tage) ist im Settings → Developers → MCP keys-Panel neben jedem Schlüsselnamen sichtbar.

Network-Pläne können ein höheres Ratenlimit anfordern. Kontaktieren Sie uns unter hello@getgenko.com.

Dashboard-KI-Assistent

Group+-Organisationen können einen integrierten KI-Assistenten direkt im Dashboard aktivieren. Wenn aktiviert, erscheint ein schwebendes Chat-Widget in der unteren rechten Ecke jeder Dashboard-Seite für alle Teammitglieder; was es kann, hängt von der Rolle ab.

Für Owners und Admins hat der Assistent vollen Admin-Bereich-Tool-Zugriff, einschließlich Buchen, Ändern und Stornieren von Terminen, und kann Fragen beantworten wie:

  • “Who is my next patient today?”
  • “Find all appointments for Maria Santos this month”
  • “What slots are available for Dr. Reyes on Friday?”
  • “Update appointment #abc123 to 3pm”

Zum Aktivieren: Gehen Sie zu Settings → Integrations und schalten Sie Dashboard AI Assistant ein. Der Schalter ist nur ab dem Group-Plan sichtbar. Kein API-Schlüssel erforderlich – der Assistent verwendet Ihre Sitzung automatisch.

Rollen und Limits: Provider und Personal erhalten einen schreibgeschützten Assistenten (Provider sehen standardmäßig ihren eigenen Kalender): Er kann nachschlagen, ändert aber nie einen Datensatz. Nachrichten werden pro Organisation und Kalendermonat gezählt: Group 500, Practice 2.000, Network unbegrenzt. Die aktuelle Nutzung sehen Sie unter Settings → Billing.

Der Dashboard-Assistent spricht mit Ihrem Team, nie mit Patienten. Patienten haben im Patientenportal ihren eigenen Assistenten (Practice+); WhatsApp übernimmt heute Erinnerungen und einfache Antworten – bestätigen, verschieben, absagen (siehe Patienten-Selbstbuchung), und ein patientenseitiger KI-Assistent über WhatsApp ist auf der Roadmap.

Einbettbares Chat-Widget

Practice+-Organisationen können außerdem ein öffentliches KI-Chat-Widget in ihre eigene Website einbetten. Besucher können Fragen zu Leistungen, Providern und Verfügbarkeit stellen, ohne Ihre Website zu verlassen. Das Widget kann keine Patientendaten sehen oder schreiben – es hat nur Zugriff auf einen öffentlich sicheren Tool-Bereich (z. B. Leistungen und freie Termine auflisten).

Zum Aktivieren:

  1. Gehen Sie zu Settings → Integrations und suchen Sie das Panel Website Chat Widget.
  2. Schalten Sie es ein.
  3. Fügen Sie unter Allowed origins die Domains hinzu, auf denen Sie das Widget einbetten (z. B. https://ihrepraxis.de), eine pro Zeile. Verwenden Sie *, um jeden Ursprung zuzulassen.
  4. Kopieren Sie den Einbettungs-Code und fügen Sie ihn vor dem schließenden </body>-Tag Ihrer Website ein:
<script src="https://www.getgenko.com/widget.js" data-org="your-slug" defer></script>
Bereich & Ratenlimits: Das Widget ist pro Besuchersitzung und pro Organisation ratenbegrenzt, um Missbrauch zu verhindern, und hat nie Schreibzugriff. Es ist eine separate Oberfläche gegenüber dem oben beschriebenen Dashboard-KI-Assistenten, der nur für Mitarbeiter gedacht ist und vollen Admin-Bereich-Zugriff nutzt.

Bereit loszulegen?

Registrieren Sie sich kostenlos — keine Kreditkarte erforderlich.