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

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:
- 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.
- 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.
- 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.
- 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.
- 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).

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

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.
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.
| Funktion | Plan |
|---|---|
| Klinische Notizen, Signatur, Nachträge, „Irrtümlich erfasst“, Druckansicht | Starter+ |
| Problemliste mit ICD-10-CM-Suche, Allergien, Medikamente, Vitalwerte | Starter+ |
| Longitudinale Akte mit Suche und Vitalwertverlauf | Starter+ |
| Aktendownload und Besuchszusammenfassungen | Starter+ |
| Archivierung und Aktenaufbewahrung | Alle Pläne |
| Fachspezifische Notizvorlagen | Group+ |
| 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 |
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
- Eine neue Notiz ist ein Entwurf. Die verfassende Person kann ihn bearbeiten oder verwerfen; Owner und Admins können ihn ebenfalls verwerfen.
- 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.
- 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.
- 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.
- 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.
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.
| Vorlage | Was sie erfasst |
|---|---|
| Zahnschema | Bleibende und Milchzähne in FDI- oder Universal-Nummerierung; Befunde je Fläche; geplante oder erledigte Behandlungen. |
| Psychopathologischer Befund | Jeder Befundbereich, Risikoeinschätzung und klinischer Eindruck, optional mit PHQ-9 und GAD-7. |
| PHQ-9 · GAD-7 | Die Fragebögen einzeln, für Folgetermine. |
| Physiotherapeutischer Befund | Körperregionen, Bewegungsausmaß je Gelenk und Bewegung (Seite, aktiv und passiv, in Grad), Outcome-Messungen, Befund und Plan. |
| Augenuntersuchung | Sehschärfe je Auge in Snellen (Meter oder Fuß), dezimal oder logMAR, mit berechnetem logMAR; Augeninnendruck mit Messmethode; objektive und subjektive Refraktion. |
| Tierärztliche Untersuchung | Tierart, Rasse, Geschlecht und Kastrationsstatus, Body Condition Score (9-Punkte-Skala), Befund und Plan. Das Gewicht des Besuchs wird gegen die Tierart geprüft. |
| Ästhetische Behandlung | Behandlungsarten, Einwilligung, je behandelter Zone eine Zeile mit Produkt, Charge, Verfallsdatum und Menge (Einheiten oder mL), Technik und Nachsorge. |
| Allgemeine Notizen | Strukturierte SOAP-Konsultation (Systemanamnese und Untersuchung nach Systemen), Eingriffsnotiz, Konsil/Überweisung und Entlassbericht — für jede Praxis. |
| Therapienotizen | Verlaufsnotiz (Interventionen, Reaktion, Fortschritt bei den Zielen, Risiko), biopsychosoziale Erstaufnahme, Behandlungsplan mit messbaren Zielen und eine klinisch eingeschätzte Risikobewertung (keine validierte Skala). |
| Mehr je Fachgebiet | Zahnä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 & Ergotherapie | Ernä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. |
| Wundversorgung | Wundassessment (Ä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. |
| Mexiko | Anamnese (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 mitactive: falseexportiert. - 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.

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

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

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)


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.
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).
| Plan | Monatlich | Jährlich | Patienten | Personal | Organisationen |
|---|---|---|---|---|---|
| Free | $0 | — | 100 | 3 | 1 |
| Solo | $49 | $490 | 250 | 4 | 1 |
| Starter | $79 | $790 | 750 | 8 | 1 |
| Group | $139 | $1.390 | 2.000 | 15 | 5 |
| Practice | $279 | $2.790 | 7.500 | 40 | 10 |
| Network | $549 | $5.490 | 10.000 | Unbegrenzt | 25 |
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
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.
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:
- Gehen Sie zu Settings → Portal
- Schalten Sie Enable Patient Portal ein
- Ihre Praxis erhält eine eindeutige öffentliche Buchungs-URL:
https://www.getgenko.com/portal/your-slug - Teilen Sie diesen Link mit Patienten per E-Mail, Website, Terminbestätigungen oder anderswo

Patienten-Selbstbuchung
Wenn Patienten Ihren Portallink besuchen, folgen sie einem einfachen Ablauf:
- Angebote durchsuchen: Verfügbare Dienstleistungen mit Beschreibungen und Provider mit Fachrichtungen/Biografien ansehen
- Dienstleistung & Provider auswählen: Wählen Sie, welche Dienstleistung sie möchten und wen sie bevorzugen (oder automatisch zuweisen)
- 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
- Kontaktinformationen eingeben: Vorname, Nachname, E-Mail, Telefon. Kontoerstellung ist nicht erforderlich.
- 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.
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>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):
| Nachricht | Wann sie gesendet wird |
|---|---|
| Buchungsbestätigung | Direkt nach der Buchung eines Termins |
| Erinnerung am Vortag | Am Morgen vor dem Termin |
| Erinnerung am Termintag | Einige Stunden vor dem Termin |
| Hinweis zur Verschiebung | Wenn ein Termin verschoben wird |
| Hinweis zur Absage | Wenn 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.
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.
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:
- Klicken Sie auf Export oben rechts
- Wählen Sie Format: CSV (öffnet in Tabellenkalkulationen wie Excel) oder Excel (erstellt eine herunterladbare .xlsx-Datei)
- Die Datei enthält alle KPIs und Aufschlüsselungsdaten für den ausgewählten Zeitraum
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):
- Gehen Sie zu Settings → Integrations
- Klicken Sie auf Meinen Kalender verbinden und melden Sie sich mit dem Google-Konto an, mit dem Sie synchronisieren möchten
- 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.
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.

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.
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"
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:readundclinical: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.
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:
fromist inklusive,toexklusive, 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:
enterpriseist der stabile Bezeichner des Network-Tarifs (er stammt aus der Zeit vor der Umbenennung). Das steht indetails.required_planeinesPLAN_LIMIT-Fehlers und im FeldplanvonGET /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 mitIdempotent-Replayed: true), ohne die Arbeit zu wiederholen; derselbe Schlüssel mit anderer Anfrage ergibt422 IDEMPOTENCY_KEY_REUSED; ein Duplikat, das eintrifft, solange die erste Anfrage läuft, ergibt409 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 mit503, statt ein doppeltes Schreiben zu riskieren: versuchen Sie es kurz danach erneut. Das Anlegen eines Datensatzes mit bereits vorhandenerexternal_idliefert 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-RemainingundRateLimit-Reset; bei Überschreitung folgt429mitRetry-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=500undGET /appointments?limit=500bis zum Ende durch. - Inkrementeller Abgleich: merken Sie sich das höchste gesehene
updated_atund 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 peridoderexternal_iddurch: eine Transaktion, die vor Ihrem letzten Lesen begann, kann danach committen. - Löschungen erscheinen nicht in
updated_since. Abonnieren Sie die Webhookspatient.deletedundappointment.deletedund gleichen Sie gelegentlich ab, indem Sie?fields=id&limit=500durchblättern und mit Ihrer Kopie vergleichen. Archivierungen erscheinen dagegen (archived_atwird gesetzt,updated_atändert sich), archivierte Patienten fehlen aber in Listen, außer mitinclude_archived=true;patient.archivedundpatient.restoredmelden sie. external_idist 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, mitq(mind. 3 Zeichen),email,phone,mrn,external_id,updated_since,sort,fieldsGET /patients/:id— ein PatientPOST /patients— anlegen; eine vorhandeneexternal_idliefert diesen PatientenPATCH /patients/:id— ändert nur, was Sie senden;nullleert ein FeldPOST /patients/upsert— anlegen oder aktualisieren perexternal_idPOST /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 bisretain_untilaufbewahrt); ein Patient ohne Vorgeschichte wird gelöscht. Die Antwort nennt das Ergebnis (result).cascadeist veraltet und wird ignoriert (Verhaltensänderung, Oktober 2026). Network,patients:delete
Termine
GET /appointments— Liste, mitprovider_id,patient_id,service_id,status,from,to,updated_since,external_id,expandGET /appointments/:id— ein TerminPOST /appointments— buchen (konfliktgeprüft);notify,external_idundstatuszum Import von VerlaufsdatenPATCH /appointments/:id— Status ändern oder verschieben, optional abgesichert mitIf-Match: <updated_at>(412, wenn er sich geändert hat)POST /appointments/:id/cancel— stornieren; Wiederholen ist harmlosPOST /appointments/batch— bis zu 500 Termine pro Aufruf, Upsert perexternal_id(Network)
Leistungen und Provider
GET|POST /services— Leistungstypen auflisten und anlegenGET|PATCH|DELETE /services/:id— lesen, ändern, löschen; eine von Terminen genutzte Leistung zu löschen erfordert?force=trueGET /providers, GET /providers/:id— Name, Fachrichtung, Zeitzone, Wochenzeiten und Buchungsregeln (nie Benutzer-IDs oder E-Mails)PATCH /providers/:id— Zeiten, Buchungsregeln undexternal_idaktualisieren (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-FormularenGET /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 UploadGET /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 kannvitalsenthalten (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örigentemplate_data, die gegen das Schema der Vorlage geprüft werden (NoteTemplateDataim OpenAPI-Dokument); Genkō berechnet die PHQ-9- und GAD-7-Summen und Schweregrade sowie den logMAR jeder Sehschärfe, prüftvitals.weighteinervet.exam@1-Notiz gegen die Tierart, und die Vorlage ist nach der Signatur mit der Notiz gesperrtGET|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 DashboardGET /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öschenPOST /webhooks/:id/rotate-secret— neues Secret;?grace_hours=hält das alte in der Zwischenzeit gültigPOST /webhooks/:id/test— sofort ein signiertes Testereignis senden und die Antwort sehenGET /webhooks/:id/deliveries— Zustellverlauf mit Status, Versuchen und letztem FehlerPOST /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=falsebeim Stornieren). Batches benachrichtigen nie. - Statusregeln:
scheduled → confirmed → completedsowiecancelledoderno_show. Abgeschlossene Termine bleiben abgeschlossen: eine Änderung liefert409 INVALID_TRANSITION. Zeit- und Statusänderung werden in getrennten Anfragen gesendet. - Batches antworten mit
200und einem Ergebnis je Element (created,updatedodererrormit 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
/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
/patientsAnfrage
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
}
}/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23Anfrage
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"
}
}/patientsAnfrage· 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
}
}/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23Anfrage
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"
}
}/patients/upsertAnfrage· 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"
}
}/patients/batchAnfrage· 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"
}
}/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23Anfrage
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
/appointmentsAnfrage
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
}
}/appointmentsAnfrage· 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"
}
}/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18Anfrage
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"
}
}/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18Anfrage
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"
}
}/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/cancelAnfrage
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"
}
}/appointments/batchAnfrage· 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
/servicesAnfrage· 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
}
}/services/4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60Anfrage
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"
}
}/services/4e2a7b19-0d63-4c58-b8f4-9a1e3d5c7f60Anfrage
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
/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74Anfrage
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"
}
}/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74Anfrage
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"
}
}/providers/17ab90de-5c42-4e8f-a3d1-2b6f8c0e9d74/availabilityAnfrage
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
/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/recordAnfrage
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"
}
}/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/documentsAnfrage
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"
}
}/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/documents/6a2d9f41-0b3c-4e78-a5d6-1f8e2b7c9d03Anfrage
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"
}
}/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notesAnfrage
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"
}
}/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes/b3f81d64-8a27-4e05-9c3b-71d2f4a6e589Anfrage
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"
}
}/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notesAnfrage
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"
}
}/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/notes/b3f81d64-8a27-4e05-9c3b-71d2f4a6e589/addendaAnfrage· 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"
}
}/appointments/0c1e5a9a-72b4-4d3f-8e61-a5f90b2c4d18/intake/reviewAnfrage· 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
/webhooksAnfrage· 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"
}
}/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24Anfrage
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"
}
}/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/rotate-secretAnfrage
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"
}
}/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/testAnfrage
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"
}
}/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/deliveriesAnfrage
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
}
}/webhooks/e91c3a5d-40b7-4f82-a6d3-58c1b9e07f24/deliveries/5b0f7a3e-9c2d-4f6e-8a51-0d3c7e1b2a44/redeliverAnfrage
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
/patientsAnfrage
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"
}
}/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23Anfrage
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"
}
}/patientsAnfrage
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"
}
}/patients/8d4f2c1a-3b7e-4a90-9f12-6c5d0e7a1b23/recordAnfrage
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"
}
}/patients/2b9e6d40-0000-4000-8000-000000000000Anfrage
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"
}
}/patientsAnfrage
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 zucancelledodercompletedsendet nur dieses Ereignis, nicht zusätzlichappointment.updated.note.signedundnote.voidedmelden, 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 mitclinical: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/:idoderGET /appointments/:idnach. - Unabhängig von
notify.notify: falseunterdrü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 anexternal_idoder 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 afterwardsZustellung, Wiederholungen und Zustand
- Mindestens einmal, ohne garantierte Reihenfolge. Entfernen Sie Duplikate anhand der Ereignis-
id(auch alsGenko-Event-Idgesendet; sie ändert sich bei Wiederholungen nie) und entscheiden Sie mit demupdated_atdes 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_sincebleibt 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:
- 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.
- 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. - Erstabgleich. Blättern Sie
GET /patients?limit=500undGET /appointments?limit=500bis zum Ende durch und speichern Sie das höchste geseheneupdated_atals Wasserzeichen. - Änderungen senden. Nutzen Sie
POST /patients/upsertundPOST /appointments(oder die Batch-Endpunkte in Network) mit einemIdempotency-Keypro Änderung, damit eine Wiederholung sie nie verdoppelt, undnotify: false, wenn Ihr System Patienten bereits selbst benachrichtigt. - Ä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 Ihrerexternal_id. - Abgleichen. Blättern Sie einmal pro Woche
?fields=id&limit=500durch und vergleichen Sie die IDs mit Ihrer Kopie, um Fehler auf einer der beiden Seiten zu finden. - Fehler behandeln. Bei
429warten SieRetry-Afterab. Bei5xxund503wiederholen Sie mit exponentiellem Backoff und demselbenIdempotency-Key. Wiederholen Sie400,403und404nicht. Bieten Sie bei409 CONFLICTbeim Buchen einen anderen Slot ausGET /providers/:id/availabilityan.
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
idoderexternal_id. - Schreibzugriffe senden einen
Idempotency-Keyund weichen bei429und5xxmit 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).
/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ōsidund Ihrerexternal_id, damit Ihr CRM den eigenen Datensatz öffnen kann.
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:sessionund 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
- 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. - API-Schlüssel anlegen unter Einstellungen → Integrationen → REST-API-Schlüssel nur mit dem Scope
embeds:sessionund auf den IP-Bereich Ihres Servers beschränken. Als Server-Secret speichern (GENKO_API_KEY). - Einen Backend-Endpunkt ergänzen, der Ihren Benutzer authentifiziert und
POST /api/v1/embeds/{id}/sessionsaufruft — ausgehend von einem der Beispiele unten. - Das Snippet einfügen in CRM oder Seite: das Script
embed.jsplusGenko.embed.mount(...), wobeigetTokenIhren Endpunkt aufruft. Der Editor zeigt es mit Ihrer Einbettungs-ID. - 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:clickaus.
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}/sessionsmitAuthorization: Bearer genko_…und JSON-Body:viewer(Pflicht, siehe unten), optionalproviders(bis 50 Behandler-IDs), optionalview(day,week,monthoderagenda) und optionalttl_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:
idist Ihre eigene, stabile Benutzer-ID (z. B.crm-user-42),labelein 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 Detailstufefull, 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 dieselbeid. Der Viewer gewährt keinen Zugriff und wird im Kalender nicht angezeigt: Was sichtbar ist, bestimmen die Einbettung, der Schlüssel und die Eingrenzung überproviders/view. - Eingrenzen verkleinert nur.
providersmuss innerhalb der Behandler der Einbettung liegen undvieweine ihrer Ansichten sein; alles Weitere wird mit400 VALIDATION_ERRORabgelehnt statt still ignoriert. - Erfolg ist
201mit{ 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/403Schlüssel, Scope, IP-Bereich und Tarif prüfen; bei404die Einbettungs-ID; bei409ist die Einbettung deaktiviert oder abgelaufen; bei429Retry-Afterabwarten. Geben Sie dem Browser einen allgemeinen Fehler zurück — der Loader löst einerror-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":{…}}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
heightoder 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 Siehttps://acme.examplecrm.comein. Tragen Sie jeden Host ein, auf dem er erscheinen kann (z. B.https://app.example.comundhttps://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.comAuf 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
| Einstellung | Typ | Standard | Grenzen | Beschreibung |
|---|---|---|---|---|
name | string | — | 1–80 | Interne Bezeichnung (in den Einstellungen sichtbar, nie für Partner). |
active | boolean | true | Einbettung abschalten, ohne sie zu löschen; laufende Sitzungen enden in Sekunden. | |
expires_at | timestamp | null | null | > now | Optionales Enddatum. Sitzungen überdauern es nie. |
allowed_origins | string[] | — | 1–10 | Exakte Origins, die sie anzeigen dürfen: https://host[:port], klein geschrieben, ohne Pfad, ohne abschließenden Schrägstrich, ohne Platzhalter. |
provider_ids | uuid[] | [] = all | ≤ 100 | Nur Termine dieser Behandler. Tokens und providers des Loaders können weiter eingrenzen. |
service_ids | uuid[] | [] = all | ≤ 100 | Nur Termine dieser Leistungen. |
statuses | string[] | scheduled, confirmed, completed, pending_payment | 1–6 | Welche Terminstatus erscheinen (cancelled und no_show sind standardmäßig ausgeblendet). |
window_days_back | integer | 7 | 0–90 | Wie weit in die Vergangenheit sie höchstens zeigt, egal welcher Zeitraum angefragt wird. |
window_days_ahead | integer | 60 | 0–366 | Wie weit in die Zukunft sie zeigt. |
detail_level | busy | service | full | busy | Das Maximum, das eine Sitzung sehen darf — siehe Tabelle unten. |
Darstellung (config)
| Einstellung | Typ | Standard | Grenzen | Beschreibung |
|---|---|---|---|---|
views | day week month agenda | all four | 1–4 | Ansichten, zwischen denen gewechselt werden kann. |
default_view | view | week | ∈ views | Startansicht (view des Loaders oder eines Tokens kann eine andere aktivierte Ansicht wählen). |
week_start | monday | sunday | monday | Erster Wochentag in Wochen- und Monatsansicht. | |
hours | { start, end } | { 7, 20 } | 0 ≤ start < end ≤ 24 | Sichtbare Stunden im Tages- und Wochenraster. |
weekends | boolean | true | Samstag und Sonntag in der Wochenansicht zeigen. | |
timezone | org | provider | viewer | org | org: Zeitzone der Praxis; provider: die des Behandlers, wenn auf einen eingegrenzt; viewer: die des Geräts. | |
locale | en | es | en | Sprache der Oberfläche. | |
theme | light | dark | auto | light | auto folgt dem Gerät. theme des Loaders überschreibt es. | |
primary_color | hex | #4f46e5 | #RRGGBB | Akzentfarbe. Nur Hex — es gibt kein eigenes CSS. |
color_by | provider | service | status | provider | Wonach Termine eingefärbt werden. Belegt-Einbettungen färben immer nach Behandler. | |
toolbar | { navigation, today, view_switcher, title } | all true | Zurück/Weiter, Heute, Ansichtswahl und Titel ein- oder ausblenden. | |
height | { mode: auto | fixed, px } | auto, 720 | px 320–2000 | auto passt sich dem Inhalt an (der Loader skaliert das Iframe); fixed nutzt px und scrollt innen. |
click | panel | event | none | panel | panel: schreibgeschütztes Detailfenster öffnen und appointment:click senden; event: nur das Ereignis senden; none: nichts. | |
actions | { confirm, reschedule, cancel } | all false | false | Reserviert für Bestätigen, Verschieben und Absagen. Muss false sein; noch nicht verfügbar. |
Was jede Detailstufe preisgibt
| Stufe | Felder | Hinweise |
|---|---|---|
busy | id, 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 }, status | Zusä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 listenermount(element, options)gibt eine Instanz zurück. Fehlt das Element, ist die ID ungültig oder fehltgetToken, 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 vonviewoderprovidersruftgetTokenmit 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(mitidundexternal_id— die ID, die Sie dem Termin über die API gegeben haben, odernull),token:expired(der Loader holt bereits ein neues Token),resizeunderror(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
| Code | HTTP | Wann |
|---|---|---|
UNAUTHORIZED | 401 | Fehlender, fehlerhafter, unbekannter, widerrufener oder abgelaufener Schlüssel; ein MCP-Schlüssel (genko_mcp_…); oder ein Einbettungs-Token als Schlüssel. |
FORBIDDEN | 403 | Dem Schlüssel fehlt embeds:session (details.required_scope), oder die Anfrage kam von einer IP außerhalb seiner Freigabeliste. |
PLAN_LIMIT | 403 | Die Organisation ist nicht im Network-Tarif (details.required_plan: "enterprise", die stabile Kennung des Network-Tarifs). |
NOT_FOUND | 404 | Keine solche Einbettung in der Organisation des Schlüssels. |
CONFLICT | 409 | Die Einbettung ist deaktiviert (details.reason: "embed_inactive") oder abgelaufen ("embed_expired"). |
VALIDATION_ERROR | 400 | Ungü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_JSON | 400 | Der Body ist kein gültiges JSON. |
UNSUPPORTED_MEDIA_TYPE | 415 | Content-Type: application/json fehlt. |
PAYLOAD_TOO_LARGE | 413 | Body über 1 MB. |
RATE_LIMITED | 429 | Schreiblimit des Schlüssels überschritten; Retry-After Sekunden warten. |
INTERNAL | 500 | Unser Fehler; mit Backoff erneut versuchen. |
GET /api/embed/{id}/appointments (vom Iframe aufgerufen)
| Code | HTTP | Wann |
|---|---|---|
UNAUTHORIZED | 401 | details.reason: missing_token, invalid_token, token_expired (der Loader holt ein neues) oder session_revoked (Schlüssel widerrufen oder embeds:session entzogen). |
FORBIDDEN | 403 | origin_not_allowed (Origin nicht im Token oder nicht mehr auf der Einbettung) oder embed_inactive (deaktiviert oder abgelaufen). |
PLAN_LIMIT | 403 | Die Organisation ist unter Network gefallen. |
VALIDATION_ERROR | 400 | Zeitraum über 31 Tage, from nicht vor to, ein unbekannter Parameter oder ein Credential in der URL. |
RATE_LIMITED | 429 | Mehr als 120 Anfragen pro Minute für diese Einbettung von einer IP. |
INTERNAL | 500 | Unser Fehler; der Kalender bietet Erneut versuchen an. |
Codes des error-Ereignisses im Loader
| code | Bedeutung |
|---|---|
origin_not_allowed | Der Origin der Seite steht nicht auf der Liste der Einbettung (oder der Browser hat keinen gesendet). |
embed_inactive | Die Einbettung ist deaktiviert oder abgelaufen. |
plan_required | Die Organisation ist nicht im Network-Tarif. |
not_found | Die Einbettungs-ID existiert nicht. |
token_fetch_failed | Beim ersten Laden ist Ihr getToken fehlgeschlagen oder hat kein Token geliefert. |
token_refresh_failed | Dasselbe beim Erneuern; der Kalender funktioniert weiter, bis das alte Token abläuft. |
network_error | Das 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.comundhttps://example.comsind verschiedene Origins, ebensohttpundhttps. 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ō inframe-src(die Browserkonsole nennt den Grund). - Sitzung abgelaufen
- Das Token ist abgelaufen. Mit dem Loader dauert das nur, bis
getTokenein neues liefert; bleibt es, schlägt Ihr Token-Endpunkt fehl (achten Sie auftoken_refresh_failed). Beim einfachen Iframe die Seite neu laden. - Der Sitzungstausch liefert
403 FORBIDDENmitrequired_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, nichthttps://crm.example.com/oderhttps://*.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_seconds60 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:
busykeine;servicekeine;fullName, E-Mail und Telefon — bei jeder Anfrage mit der ID des Betrachters protokolliert.
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).
/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"
}
}
}
}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, einemdate, einem relativenrange(today,this_week,next_7_days,next_30_days) oder einemfrom/to-Fensterget_appointment— ruft einen einzelnen Termin nach ID mit vollständigen Details ablist_patients— durchsucht Patienten nach Name, E-Mail oder Telefon (mind. 3 Zeichen) oder findet einen permrnoderexternal_id; paginiert mitmeta.next_cursorget_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 aufget_provider— ruft das Profil eines Providers und dessen wöchentlichen Verfügbarkeitsplan ablist_services— listet alle Termintypen (Dienstleistungen) mit Dauer und Preis aufcheck_availability— gibt offene Zeitfenster für einen Provider an einem bestimmten Datum zurücksearch_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)
{ 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 Statusupdate_patient— aktualisiert Name, E-Mail, Telefon, Geburtsdatum oder Notizen eines Patienten (mitnulllässt sich ein Feld leeren); mit klinischem Schreibrecht auch die kodierten Listen zu Allergien, Diagnosen und Medikamentenfind_or_create_patient— sucht nach Telefon, E-Mail oder Name und legt den Datensatz auf Wunsch an, wenn er fehlthubspot_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-Mailhubspot_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_get_status schlägt aus diesem Grund nie fehl.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.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 Reihenfolgelist_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 abget_appointment_intake— ruft das vom Patienten ausgefüllte Vorbesuchsformular für einen Termin abcreate_clinical_note— erstellt eine SOAP- oder Verlaufsnotiz als Entwurf für einen Termin; eine Fachkraft signiert sie im Dashboard (is_draft=falsewird mitNOTE_SIGN_REQUIRES_CLINICIANabgelehnt); sie kann eine Fachvorlage enthalten (template_key+template_data)update_clinical_note— bearbeitet einen Notizentwurf (mitappointment_id); eine signierte Notiz liefertNOTE_LOCKEDund wird nie verändertadd_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.
| Tool | Voraussetzung | Parameter | Rückgabe |
|---|---|---|---|
get_org_info | jeder Schlüssel | keine | { id, name, slug, timezone } |
list_services | services:readGroup+ |
| { data, meta } |
list_providers | providers:readGroup+ |
| { data, meta } |
check_availability | scheduling:readGroup+ |
| [{ start, end, starts_at, ends_at, timezone }] |
list_appointments | scheduling:readGroup+ |
| { data, meta } |
get_appointment | scheduling:readGroup+ |
| appointment |
list_patients | patients:readGroup+ |
| { data, meta } |
get_patient | patients:readGroup+ |
| patient |
get_provider | providers:readGroup+ |
| provider |
search_icd10cm_codes | patients:readGroup+ |
| { release, system, results } |
hubspot_get_status | jeder Schlüssel | keine | { connected, portal_id?, connected_at? } |
find_or_create_patient | patients:writePractice+ |
| { found, patient | patients, created? } |
book_appointment | scheduling:writePractice+ |
| { booked: true, appointment } |
cancel_appointment | scheduling:writePractice+ |
| { cancelled: true, already_cancelled?, appointment } |
update_appointment | scheduling:writePractice+ |
| { updated: true, appointment } |
update_patient | patients:writePractice+ |
| { updated: true, patient, updated_fields } |
hubspot_sync_patient | patients:writePractice+ |
| { synced: true, contact_id } |
hubspot_log_appointment_note | scheduling:writePractice+ |
| { logged: true, contact_id } |
get_patient_record | clinical:readNetwork |
| [visit] |
list_appointment_notes | clinical:readNetwork |
| [note] |
get_clinical_note | clinical:readNetwork |
| note |
get_appointment_intake | clinical:readNetwork |
| intake | { status: "not_submitted" } |
create_clinical_note | clinical:writeNetwork |
| { created: true, note } |
update_clinical_note | clinical:writeNetwork |
| { updated: true, note } |
add_clinical_addendum | clinical:writeNetwork |
| { created: true, addendum } |
review_intake | clinical:writeNetwork |
| { 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.)
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.
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.
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:
- Gehen Sie zu Settings → Integrations und suchen Sie das Panel Website Chat Widget.
- Schalten Sie es ein.
- 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. - 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>
Bereit loszulegen?
Registrieren Sie sich kostenlos — keine Kreditkarte erforderlich.