Buchen, Stornieren, Umbuchen & Rückruf

Vier Endpunkte für den vollständigen Terminlebenszyklus.

Der Verifizierungscode für Stornierung und Umbuchung ist eine Einstellung des Kalenders (unter Benachrichtigungen) und wirkt auf allen Wegen — Telefon, API und MCP. Davon zu unterscheiden ist der Verifizierungsmodus des Assistenten (unter Termine & Kalender): Er legt fest, wie die Identität geprüft wird, bevor der Assistent einem Anrufer bestehende Termine überhaupt nennt.

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:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "dateTime": "2026-03-03T10:00:00+01:00",
  "callerName": "Max Mustermann",
  "callerIdNumber": "+4917604069001",
  "reason": "Erstberatung"
}

Erfolgsantwort:

{
  "action": "booked",
  "success": true,
  "humanReadable": "Termin erfolgreich gebucht: Dienstag, 03.03 um 10:00 Uhr",
  "result": "Termin erfolgreich gebucht",
  "day": "Dienstag",
  "date": "03.03",
  "time": "10:00",
  "appointmentId": "550e8400-e29b-41d4-a716-446655440000"
}

Abgabe-Kalender: Bei einem Abgabe-Kalender zählt nur der Tag. Die Antwort enthält dann kein Feld time, dafür serviceType: "drop_off" — mit genannter Leistung z.B. "humanReadable": "Auftrag eingeplant: Inspektion am Dienstag, 03.03" und serviceName.

Zeit belegt: Die Antwort ist action: "suggest" mit Alternativvorschlägen (time1–time3) — wie bei der Verfügbarkeitsprüfung. Ist der Tag komplett ausgebucht, kommt action: "reject".

Leistung nicht gefunden: Passt serviceName zu keiner Leistung dieses Kalenders, antwortet die API mit action: "suggest_service" (passende Vorschläge in suggestedServices) oder mit action: "clarify"; beide Antworten enthalten die Liste services der buchbaren Leistungen. Leistungen vom Typ Ohne Termin sind nie buchbar.

Terminfreigabe aktiv: Wenn der Kalender Terminanfragen erst genehmigen verwendet, kommt statt booked die Antwort action: "pending_approval" zurück (z.B. "humanReadable": "Ihre Terminanfrage für Dienstag, 03.03 um 10:00 Uhr wurde übermittelt und wird geprüft.") — der Termin ist als Anfrage eingetragen und wird erst verbindlich, wenn der Kalenderinhaber sie genehmigt. Bei Abgabe-Kalendern fehlt auch hier die Uhrzeit.

Termin stornieren

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

POST /api/v1/cancel-appointment

Anfrage-Body:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "callerIdNumber": "+4917604069001",
  "callerName": "Max Mustermann",
  "appointmentDate": "2026-03-03"
}

*FlowCaptain verwendet mehrere Merkmale, um den richtigen Termin zu identifizieren. Je mehr Informationen übergeben werden (Anrufer-ID, Name, Datum), desto zuverlässiger die Zuordnung. Bei mehreren passenden Terminen antwortet die API mit action: "clarify" und einer Liste appointments[] zur Rückfrage.

Erfolgsantwort:

{
  "action": "cancelled",
  "success": true,
  "humanReadable": "Termin erfolgreich storniert: Dienstag, 03.03 um 10:00 Uhr",
  "result": "Termin erfolgreich storniert",
  "day": "Dienstag",
  "date": "03.03",
  "time": "10:00"
}

SMS-Verifizierung: Wenn im Kalender der Verifizierungscode aktiviert ist, verlangt die API vor der Stornierung einen Code:

{
  "action": "verification_required",
  "success": false,
  "humanReadable": "Zur Sicherheit haben wir einen Code an ***4567 gesendet. Bitte nennen Sie den 4-stelligen Code.",
  "verificationPhone": "***4567"
}

Der Code wird per SMS an die hinterlegte Nummer gesendet. Wiederhole die Anfrage mit dem Feld verificationCode. Ein falscher Code ergibt action: "verification_failed".

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:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "callerIdNumber": "+4917604069001",
  "callerName": "Max Mustermann",
  "newDateTime": "2026-03-04T14:00:00+01:00"
}

*Terminsuche und SMS-Verifizierung funktionieren wie beim Stornieren.

Erfolgsantwort:

{
  "action": "rescheduled",
  "success": true,
  "humanReadable": "Termin erfolgreich verschoben: von Dienstag, 03.03 um 10:00 Uhr auf Mittwoch, 04.03 um 14:00 Uhr",
  "result": "Termin erfolgreich verschoben",
  "day": "Mittwoch",
  "date": "04.03",
  "time": "14:00",
  "previousDay": "Dienstag",
  "previousDate": "03.03",
  "previousTime": "10:00"
}

Neue Zeit belegt: Die Antwort ist action: "suggest" mit Alternativvorschlägen.

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:

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

*Übergib mindestens eines von callerName, callerPhone oder callerIdNumber, damit das Unternehmen zurückrufen kann.

Erfolgsantwort:

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

Der Geschäftsinhaber erhält eine E-Mail mit den Kontaktdaten des Anrufers — an die Benachrichtigungs-E-Mail des Kalenders (unter Benachrichtigungen). Ist dort keine E-Mail hinterlegt, sagt die Antwort keinen Rückruf zu. Rückrufanfragen sind zum Schutz vor Missbrauch mengenbegrenzt.