Dokumentation

Das Kieu Buchungstool ist ein einbettbares Online-Buchungs-Widget mit eigener Oberfläche. Im Hintergrund nutzt es die Timify Booker Services API für Standorte, Leistungen, Verfügbarkeiten und Buchungen.

Produktiv läuft das Widget auf Netlify (z. B. kieu-buchungstool.netlify.app). Auf kieu.de (Shopify) wird es per embed.js in einem Modal geöffnet — Nutzer bleiben auf der Website.

Der Stepper oben zeigt 3 Schritte: Behandlung → Tag & Uhrzeit → Kontaktdaten. Standort, Zusatzleistungen und SMS sind Teil des Flows, aber nicht als eigene Stepper-Nummer sichtbar.

Reservierung kurz erklärt

1. Nutzer wählt Termin und füllt Kontaktdaten aus
2. Timify reserviert den Slot (~5 Min.) via POST /reservations
3. Sinch sendet SMS-Code (wenn OTP aktiv)
4. Nach erfolgreicher Prüfung: POST /appointments/confirm

Drei Dateien in public/ können nach dem Deploy direkt auf dem Server ersetzt werden — ohne Neu-Build. Ein Hard-Reload im Browser reicht meist aus.

Alternative Pfade per URL-Parameter: ?ui=…&content=…&settings=…

Nur per Code-Deploy: neue UI-Keys, Design, Schriftarten, Stepper-Labels in widgetDefaults.js.

Alle sichtbaren Texte im Widget (Überschriften, Untertitel, Formular-Labels, Buttons, Fehlermeldungen) werden aus ui-strings.json geladen. Es reicht, nur die Keys einzutragen, die ihr ändern wollt — fehlende Keys nutzen den Standard aus dem Code.

Beispiel

{
  "selectLocationTitle": "Wähle deinen Standort",
  "selectServiceTitle": "Wähle deine Behandlung",
  "contactFormTitle": "Fülle deine Kontaktdaten aus",
  "suggestedSlotsTitle": "Für dich vorgeschlagen",
  "continueBooking": "Buchung fortsetzen",
  "preferredDoctorLabel": "Behandler:in",
  "confirmAddToCalendar": "Zum Kalender hinzufügen",
  "confirmCalendarApple": "Apple Kalender",
  "confirmCalendarGoogle": "Google Kalender",
  "confirmCalendarOutlook": "Microsoft Outlook"
}

Wichtige Key-Gruppen

Einzelne Keys können auch in booking-settings.json unter "ui": { … } überschrieben werden — das hat Vorrang vor ui-strings.json.

Neuer Text-Key, der im Code noch nicht existiert? Dann muss der Key in src/content/uiStrings.js ergänzt und ein Code-Deploy gemacht werden.

Nach der Buchung zeigt das Widget einen Erfolgstext. Welcher Text erscheint, steuert ihr über booking-settings.json — global oder pro Leistung.

Beispiel-Konfiguration

{
  "confirm": {
    "variant": null,
    "serviceVariants": {
      "TIMIFY_SERVICE_ID": "followUp"
    }
  },
  "confirmVariants": {
    "visit": {
      "subtitle": "Vielen Dank für dein Vertrauen. Wir freuen uns auf deinen baldigen Besuch!"
    },
    "followUp": {
      "subtitle": "Bzgl. Leistungsumfang und Kosten werden wir dich in den nächsten Tagen telefonisch kontaktieren."
    }
  }
}

Leistungs-ID finden

• Timify → Leistung öffnen → ID aus der URL kopieren
• Oder: Externe ID verwenden, wenn in Timify gesetzt

Der Bereich wählt automatisch freie Timify-Slots. Ihr legt Regeln fest — keine festen Termine in der JSON-Datei.

{
  "appointmentSuggestionsDefaults": {
    "defaultPeriod": "next",
    "dayCount": 2,
    "timesPerDay": 2,
    "minDayGap": 3
  },
  "appointmentSuggestions": {
    "ERSTBERATUNG": {
      "defaultPeriod": "2w",
      "minDayGap": 7,
      "preferTimes": ["09:00", "10:00"]
    }
  }
}

Ablauf im Widget

Nach der Auswahl einer Hauptbehandlung prüft das Widget, ob Zusatzleistungen (Upsells) hinterlegt sind. Nur dann erscheint der Screen „Zusatzleistung buchen?“ — er ist nicht als eigener Schritt im Stepper sichtbar (intern Schritt 1b).

Wann erscheint der Upsell-Screen?

Was kommt woher?

Wichtig: In content.json tragt ihr nur die Verknüpfung (IDs) ein — keine Texte oder Preise. Empfehlung: in Timify bei allen Leistungen eine Externe ID setzen (z. B. BOTOX-HAUPT), damit die JSON-Einträge lesbar und stabil bleiben.

addonsConfig — Datenquelle wählen

Steuert, woher das Widget die Upsell-Zuordnung liest:

{
  "addonsConfig": {
    "source": "content",
    "fallbackToContent": false
  },
  "addons": { … }
}

Beispiel addons

{
  "addonsConfig": { "source": "content" },
  "addons": {
    "BOTOX-HAUPT": ["BLUTANALYSE-ZUSATZ"],
    "ERSTBERATUNG": [
      "AUFKLAERUNGSBOGEN",
      { "externalId": "DNA-TEST", "sameSlot": true, "hint": "Optional vor dem Termin" }
    ],
    "69f361562c7b933ec4960f7c": [
      { "serviceId": "andere_timify_id", "sameSlot": false }
    ]
  }
}

Felder pro Zusatz-Eintrag

UI-Texte anpassen (ui-strings.json)

IDs finden

Fehlersuche

• Upsell-Screen fehlt trotz JSON: Hauptleistungs-ID stimmt nicht (Externe ID vs. Service-ID prüfen).
• Screen leer / keine Karten: Zusatz-IDs in Timify nicht gefunden oder Leistung nicht online buchbar.
• Browser-Konsole (F12): Warnung addons: … konnte nicht aufgelöst werden → falsche ID im Array.
• Mit VITE_DEBUG_CONSOLE=true im Build: zusätzliche Logs zu Timify-Upsell-Feldern.

Technischer Hinweis: Die Timify Reservation-API nimmt pro Buchung aktuell eine service_id (die Hauptbehandlung). Zusatzleistungen sind in der UI und Zusammenfassung sichtbar; ob Timify sie als kombinierte Buchung speichert, bitte mit der Praxis in Timify klären.

Behandler werden aus Timify geladen (Ressourcen-Kategorie „Ärzteteam“ bzw. Name enthält „Arzt“). Es gibt aktuell keine JSON-Liste im Buchungstool. Die gezielte Behandlerauswahl ist nur verfügbar, wenn Timify für die Leistung Ärzte in availabilities.resources liefert. Maßgeblich für die tatsächliche Zuweisung ist immer Timify (Confirm-Response).

Kieu nutzt Timify Enterprise (Branch Manager): eine Enterprise-ID, mehrere Filialen. Das Widget lädt alle Standorte und nutzt danach die company_id der gewählten Filiale.

Build-Umgebung (.env / Netlify)

VITE_TIMIFY_ENTERPRISE_ID=deine-enterprise-id
VITE_TIMIFY_LOCALE=de-de
VITE_BASE_PATH=/
VITE_OTP_ENABLED=true
SINCH_APPLICATION_KEY=…
SINCH_APPLICATION_SECRET=…

Standort-Namen, Adressen und Leistungspreise kommen aus Timify — nicht aus den JSON-Dateien.

OTP läuft über Sinch Verification API — nicht über Timify SMS. Die Endpunkte /api/otp/send und /api/otp/verify sind Netlify Functions.

Manuell vom Rechner

npm run netlify:login
npm run netlify:init
npm run netlify:env
npm run netlify:deploy

JSON-Dateien ohne Neu-Build

• public/ui-strings.json
• public/content.json
• public/booking-settings.json

Das Monitoring führt regelmäßig eine vollständige Testbuchung durch und storniert den Termin danach automatisch. Bei Fehler wird eine Alert-E-Mail versendet. Das Skript läuft als GitHub Actions Workflow — kein eigener Server nötig.

OTP-Bypass (Monitoring-Modus)

Das Widget versendet OTP-Codes über Sinch. Im Monitoring-Modus wird Sinch nicht aufgerufen — stattdessen gibt das Netlify-Backend bei Erkennung des geheimen Headers einen festen Code zurück. Echte Buchungen von Nutzern sind davon nicht betroffen.

GitHub Actions Workflow

Der Workflow liegt unter .github/workflows/monitoring.yml und wird stündlich ausgeführt. Er kann auch manuell über Actions → Run workflow gestartet werden.

# Datei: .github/workflows/monitoring.yml (liegt im Repo)
# Läuft täglich um 09:00 und 18:00 Berliner Zeit (Sommerzeit).
# Kann auch manuell unter Actions → Run workflow gestartet werden.

# Wichtig: Playwright-Browser werden in jedem Lauf neu installiert
# (npx playwright install chromium --with-deps).
# Das ist nötig, weil node_modules/ im .gitignore ist und
# Playwright-Binaries nicht im Repo liegen.

Lokales Testen

cd monitoring/
npm install
npx playwright install chromium
cp config.example.js config.js
# config.js ausfüllen
npm run check:visible    # sichtbarer Browser
npm run check            # headless

Fehlersuche

<button type="button" data-kieu-booking-open>Termin buchen</button>
<script
  src="https://kieu-buchungstool.netlify.app/embed.js"
  data-widget-url="https://kieu-buchungstool.netlify.app/widget.html"
  data-enterprise-id="DEINE_ENTERPRISE_ID"
  data-button-label="Termin buchen"
></script>

• embed.js leitet Tracking-Events per postMessage an die Elternseite weiter
• UTM-Parameter der Elternseiten-URL werden ans Widget übergeben
• Mehrere Buttons: alle mit data-kieu-booking-open, ein Script reicht

Container auf kieu.de: GTM-MJFXB3VX. Das Widget feuert Custom Events in den dataLayer; embed.js leitet sie an die Elternseite weiter.

Debug in der Browser-Konsole auf kieu.de:

dataLayer.filter((e) => String(e.event || '').startsWith('kieu_'))

Ausführliche GTM-Anleitung im Repo: docs/gtm-setup-dr-kieu.md und Import-Datei docs/gtm-kieu-booking-funnel-import.json.