# Buchungen für Entwickler

Buchen mit Alvin, MCP-Clients, der REST-API und Webhooks.

Source: https://docs.getridian.com/de/scheduling/developers/
Language: de
Reviewed: 2026-11-03

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](https://docs.getridian.com/de/scheduling/absences/) 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](https://docs.getridian.com/de/developers/mcp/).

## 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.

```sh
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.