Buchen, Stornieren, Umbuchen & Rückruf

API-Referenz für das Buchen, Stornieren, Umbuchen von Terminen und Rückrufanfragen über FlowCaptain.

Buchen, Stornieren, Umbuchen & Rückruf

Vier Endpunkte für den vollständigen Terminlebenszyklus.

Termin buchen

Erstellt einen neuen Termin im verbundenen Google Kalender. FlowCaptain prüft vor der Buchung automatisch, ob das gewünschte Zeitfenster tatsächlich verfügbar ist.

POST /api/v1/book-appointment

Anfrage-Body:

{
  "query": "Montag, 3. März um 10 Uhr",
  "callerName": "Max Mustermann",
  "callerPhone": "+491761234567",
  "callerIdNumber": "+491761234567",
  "description": "Erstberatung"
}

Feld	Typ	Erforderlich	Beschreibung
query	string	Ja	Natürlichsprachliches Datum/Uhrzeit für den Termin
callerName	string	Ja	Name der buchenden Person
callerPhone	string	Nein	Telefonnummer (für Benachrichtigungen)
callerIdNumber	string	Nein	Anrufer-ID aus der Telefonie (für Terminsuche)
description	string	Nein	Terminbeschreibung

Erfolgsantwort:

{
  "message": "Ihr Termin am Montag, 3. März um 10:00 wurde gebucht.",
  "status": "booked",
  "appointment": {
    "date": "2026-03-03",
    "time": "10:00",
    "day": "Montag",
    "callerName": "Max Mustermann"
  }
}

Termin stornieren

Storniert einen bestehenden Termin. Der Termin wird im Google Kalender als storniert markiert, aber nicht gelöscht — so bleibt er für Ihre Unterlagen sichtbar.

POST /api/v1/cancel-appointment

Anfrage-Body:

{
  "query": "meinen Termin am Montag",
  "callerName": "Max Mustermann",
  "callerIdNumber": "+491761234567"
}

Feld	Typ	Erforderlich	Beschreibung
query	string	Ja	Natürlichsprachliche Beschreibung, welcher Termin storniert werden soll
callerName	string	Nein	Hilft bei der Identifikation des Termins
callerIdNumber	string	Nein	Anrufer-ID für die Suche

FlowCaptain verwendet mehrere Merkmale, um den richtigen Termin zu identifizieren. Je mehr Informationen übergeben werden (Anrufer-ID, Name, Datum), desto zuverlässiger die Zuordnung.

Erfolgsantwort:

{
  "message": "Ihr Termin am Montag, 3. März um 10:00 wurde storniert.",
  "status": "cancelled"
}

Termin umbuchen

Verschiebt einen bestehenden Termin auf eine neue Zeit. FlowCaptain prüft die Verfügbarkeit zur neuen Zeit vor der Umbuchung.

POST /api/v1/reschedule-appointment

Anfrage-Body:

{
  "query": "meinen Montags-Termin auf Dienstag 14 Uhr verschieben",
  "callerName": "Max Mustermann",
  "callerIdNumber": "+491761234567"
}

Feld	Typ	Erforderlich	Beschreibung
query	string	Ja	Natürlichsprachliche Anfrage mit gewünschter neuer Zeit
callerName	string	Nein	Hilft bei der Identifikation des Termins
callerIdNumber	string	Nein	Anrufer-ID für die Suche

Erfolgsantwort:

{
  "message": "Ihr Termin wurde auf Dienstag, 4. März um 14:00 verschoben.",
  "status": "rescheduled",
  "appointment": {
    "date": "2026-03-04",
    "time": "14:00",
    "day": "Dienstag"
  }
}

Rückruf anfordern

Fordert einen Rückruf vom Geschäftsinhaber an, wenn der Voice Bot das Anliegen des Anrufers nicht lösen kann.

POST /api/v1/request-callback

Anfrage-Body:

{
  "callerName": "Max Mustermann",
  "callerPhone": "+491761234567",
  "issueDescription": "Möchte Rückruf",
  "language": "de"
}

Feld	Typ	Erforderlich	Beschreibung
callerName	string	Nein*	Name des Anrufers
callerPhone	string	Nein*	Telefonnummer des Anrufers
callerIdNumber	string	Nein*	Anrufer-ID aus der Telefonie
issueDescription	string	Nein	Kurzbeschreibung des Anliegens
language	string	Nein	"de" oder "en" (Standard: "de")

*Mindestens eines von callerName, callerPhone oder callerIdNumber ist erforderlich.

Erfolgsantwort:

{
  "action": "callback_requested",
  "success": true,
  "humanReadable": "Rückrufanfrage übermittelt"
}

Der Geschäftsinhaber erhält eine E-Mail mit den Kontaktdaten des Anrufers. Rückrufanfragen sind aus Schutz vor Missbrauch mengenbegrenzt.

Häufige Fehlerantworten

Termin nicht gefunden:

{
  "message": "Kein Termin gefunden, der Ihrer Anfrage entspricht.",
  "status": "not_found"
}

Neue Zeit nicht verfügbar (Umbuchung):

{
  "message": "Dienstag um 14 Uhr ist nicht verfügbar. Alternativen: Dienstag um 15 Uhr, Mittwoch um 10 Uhr.",
  "status": "unavailable"
}