Buchungen für Entwickler

Jeder Kanal bucht über denselben Weg wie die Buchungsseite: Ridian prüft die freien Zeiten erneut, schreibt den Kalendereintrag und schickt der buchenden Person die Bestätigung mit Verwaltungslink.

Alvin

Alvin listet deine Terminarten, findet freie Zeiten und zeigt Buchungen, in der App und in WhatsApp. Zum Buchen, Verschieben oder Absagen zeigt Alvin einen Vorschlag, den du bestätigst, solange Alvins Ausführungsmodus auf Vor Änderungen fragen steht, dem Standard. Mit Automatisch ausführen führt Alvin es direkt aus. Ist die Zeit nicht mehr frei oder ein Kalender nicht lesbar, ändert sich nichts.

Abwesenheiten trägt Alvin auf Zuruf ein („Ich bin nächste Woche im Urlaub“) und übergibt danach Buchungen an eine Vertretung, ebenfalls als Vorschlag zum Bestätigen.

MCP

Mit den Scopes bookings:read und bookings:write nutzen MCP-Clients diese Werkzeuge: list_appointment_types, find_booking_slots (bis 31 Tage), list_bookings (bis 92 Tage), get_booking, book_appointment, reschedule_booking, cancel_booking und anonymize_booking, für Abwesenheiten dazu list_absences, create_absence, delete_absence und reassign_booking. Schick bei book_appointment eine feste request_id mit; dieselbe request_id liefert dieselbe Buchung statt einer zweiten. Ein- und Ausgaben stehen in der MCP-Referenz.

REST-API

In Team-Workspaces liest und bucht ein Developer-Projekt mit App-Token über https://api.getridian.com/v1. Den Zugang schaltest du unter Developer > API-Projekte, Tab Zugriff, ein; Termine > Buchungen > API zeigt den Stand und führt dorthin. Das Projekt handelt für den ganzen Workspace.

Methode und Pfad	Scope	Zweck
GET /appointment-types	bookings:read	Terminarten, mit reminder_minutes_before
GET /appointment-types/{id}/slots?from=&to=	bookings:read	Freie Zeiten, bis 31 Tage
GET /bookings?from=&to=	bookings:read	Buchungen, bis 92 Tage, bis 100 je Seite; status=cancelled für Absagen
GET /bookings/{id}	bookings:read	Eine Buchung
POST /bookings	bookings:write	Buchen: appointment_type_id, start, booker (name, email), time_zone, language, request_id
POST /bookings/{id}/reschedule	bookings:write	Verschieben: start
POST /bookings/{id}/cancel	bookings:write	Absagen: optional reason
POST /bookings/{id}/anonymize	bookings:write	Personendaten der Buchung entfernen, ohne Body; auch für abgesagte Buchungen. Liefert die Buchung mit anonymized: true

Buchungen enthalten series_id und series_index (ab 0) für Termine einer Serie, sonst null; jeder Termin ist eine eigene Buchung und wird einzeln verschoben oder abgesagt. waitlist_length ist die Zahl der Wartenden für eine Gruppenzeit oder einen Kurs, sonst null. Alvin und MCP liefern dieselben Felder.

Zeiten sind ISO-Zeitpunkte mit Offset, etwa 2026-11-03T08:30:00+01:00. Eine Zeit, die nicht mehr frei ist, ergibt 409; frag die freien Zeiten neu ab. Bezahlte Terminarten ergeben 402 und werden auf ihrer Buchungsseite gebucht.

curl https://api.getridian.com/v1/bookings \
  -H "Authorization: Bearer $RIDIAN_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appointment_type_id":"…","start":"2026-11-03T08:30:00+01:00","booker":{"name":"Lea Beispiel","email":"lea@example.org"},"time_zone":"Europe/Berlin","request_id":"crm-4711"}'

Webhooks

In Team-Workspaces meldet Ridian Buchungen an deinen Endpunkt, eingerichtet unter Developer > Webhooks:

• booking.created: Eine Buchung ist bestätigt. Serien melden je Termin ein Ereignis mit series_id und series_index.
• booking.rescheduled: Eine Buchung hat eine neue Zeit; previous enthält die alte.
• booking.cancelled: Eine bestätigte Buchung wurde abgesagt, mit cancelled_by und cancellation_reason.
• booking.reassigned: Eine Buchung ging an eine andere Person; host_user_id ist die neue, previous_host_user_id die vorige.
• waitlist.joined: Jemand steht auf einer Warteliste: bestätigt bei Gruppe und Kurs, sofort bei einem ausgebuchten Tag. kind ist seat oder day, dazu start bzw. day, position (nur seat), person und lead_id.
• waitlist.promoted: Jemand ist nachgerückt bzw. hat den Zahlungslink bekommen; booking_id ist die neue Buchung. Bestätigte Nachrücker melden zusätzlich booking.created.

Jede Zustellung trägt x-ridian-event, x-ridian-delivery, x-ridian-timestamp und x-ridian-signature: v1=<hex HMAC-SHA256> über x-ridian-timestamp + "." + raw_body. Schlüssel ist das Signing-Secret (ridian_whsec_…), das beim Anlegen des Webhooks einmal angezeigt wird. Entdoppele über x-ridian-delivery, bevor du mit 2xx antwortest. Unter Developer > Webhooks siehst du alle Webhooks des Workspace mit Zustellprotokoll: Ereignis, Zeit, HTTP-Status oder Fehlergrund und nächster Versuch. Zustellungen löschen wir 30 Tage nach der Zustellung bzw. nach dem letzten Versuch.