Buchen, Stornieren & Umbuchen

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

Buchen, Stornieren & Umbuchen

Drei Endpunkte für den vollständigen Terminlebenszyklus.

Termin buchen

Erstellt einen neuen Termin im verbundenen Google Kalender.

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.

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 (zuverlässigste Methode)

Suchreihenfolge: Die API findet den Termin in dieser Reihenfolge: callerIdNumber, dann callerPhone, dann callerName, dann Datum. Wenn eine Methode fehlschlägt (z.B. anderes Telefon), wird die nächste stillschweigend versucht.

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. Die API 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"
  }
}

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"
}