Buchen, Stornieren, Umbuchen & Rückruf

Buchen, Stornieren, Umbuchen & Rückruf

Vier Endpunkte für den vollständigen Terminlebenszyklus.

Jede der folgenden Anfragen erfordert calendarId als Feld im JSON-Body. Du findest sie vorausgefüllt unter Dashboard → Kalender → API → Integrations-Anleitung. Falls deine Plattform den Body in einen Umschlag einpackt (z.B. Retells args-Objekt), übergib sie stattdessen als URL-Query-Parameter — ?calendarId=YOUR_CALENDAR_ID — denn die API liest calendarId nur aus dem Top-Level-Body, der Query-Zeichenkette oder den Routen-Parametern, niemals aus einem verschachtelten args-Objekt.

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": "+491761234567",
  "reason": "Erstberatung"
}

Erfolgsantwort:

{
  "action": "booked",
  "success": true,
  "humanReadable": "Ihr Termin am Montag, 3. März um 10:00 Uhr wurde gebucht.",
  "day": "Montag",
  "date": "2026-03-03",
  "time": "10:00",
  "appointmentId": "550e8400-e29b-41d4-a716-446655440000"
}

Zeit belegt: Die Antwort ist action: "suggest" mit Alternativvorschlägen (time1–time3) — wie bei der Verfügbarkeitsprüfung.

Terminfreigabe aktiv: Wenn der Kalender Terminanfragen erst genehmigen verwendet, kommt statt booked die Antwort action: "pending_approval" zurück — der Termin ist als Anfrage eingetragen und wird erst nach Genehmigung durch den Kalenderinhaber verbindlich.

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": "+491761234567",
  "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": "Ihr Termin am Montag, 3. März um 10:00 Uhr wurde storniert."
}

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

{
  "action": "verification_required",
  "success": false,
  "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": "+491761234567",
  "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": "Ihr Termin wurde auf Dienstag, 4. März um 14:00 Uhr verschoben.",
  "day": "Dienstag",
  "date": "2026-03-04",
  "time": "14:00",
  "previousDay": "Montag",
  "previousDate": "2026-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": "+491761234567",
  "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"
}

Der Geschäftsinhaber erhält eine E-Mail mit den Kontaktdaten des Anrufers. Rückrufanfragen sind aus Schutz vor Missbrauch mengenbegrenzt (5 pro Unternehmen und Stunde, 2 pro Anrufer und Stunde).