GET
/api/v1/bookingsBuchung anlegen
Legt eine Buchung im Namen eines Fahrgasts an (Gast-Buchung). Der Idempotency-Key-Header ist Pflicht — Wiederholungen mit demselben Key liefern dieselbe Buchung (200 statt 201) und buchen nie doppelt.
Wofür
Der Schreibkanal für eigene Buchungsoberflächen und Plugins: Halte über /stops auflösen, Abfahrt über /trips finden, dann hier buchen. Der Fahrgast erhält die Bestätigung samt Verwaltungslink an die übermittelte Telefonnummer.
Anfrage
Erfordert das Recht
write:bookings.curl -sS \
-H "Authorization: Bearer rb_live_…" \
"https://rufbusle.de/api/v1/bookings"Antwort
{
"id": "bkg_5Rt8wY",
"tripId": "trp_9Vc4mQ",
"rideDate": "2026-08-12",
"boardingStopId": "stp_7Kq2vX",
"alightingStopId": "stp_1Ax9bN",
"seats": 2,
"wheelchairUsers": 0,
"status": "SCHEDULED",
"canceled": false,
"transportMode": "BUS",
"source": "WEB",
"sourcePluginSlug": "phone-agent",
"pickupWindowStart": "08:15",
"pickupWindowEnd": "08:15",
"createdAt": "2026-08-10T14:32:05.000Z",
"phone": "+4915112345678"
}Beispielwerte, keine echten Daten. Unbekannte Felder bitte ignorieren — es können jederzeit welche hinzukommen.
Felder
| Feld | Typ | Beschreibung |
|---|---|---|
id | string | Interne ID der Buchung. |
tripId | string | Fahrt, auf die gebucht wurde. |
rideDate | string | null | Servicedatum der Fahrt (YYYY-MM-DD). |
boardingStopId | string | Einstieg — Verweis auf einen Halt. |
alightingStopId | string | Ausstieg — Verweis auf einen Halt. |
seats | integer | Gebuchte Sitzplätze. |
wheelchairUsers | integer | Davon Rollstuhlplätze. |
status | string | Stand der Durchführung: SCHEDULED | PICKED_UP | COMPLETED | NOSHOW. |
canceled | boolean | Storniert. Stornos verschwinden nicht, sie werden markiert. |
transportMode | string | Durchführung als BUS oder TAXI. |
source | string | Herkunft der Buchung: WEB | RECURRING | PLUGIN | API. |
sourcePluginSlug | string | null | Slug des erzeugenden Plugins (bei source PLUGIN oder plugin-gebundenen API-Schlüsseln); sonst null. Erlaubt Integrationen, eigene Buchungen zu erkennen. |
pickupWindowStart | string | null | Beginn des zugesagten Abholfensters; sonst null. |
pickupWindowEnd | string | null | Ende des zugesagten Abholfensters; sonst null. |
createdAt | string | Zeitpunkt der Buchung, ISO 8601 (UTC). |
phoneoptional | string | null | Nur mit Scope read:bookings:pii; sonst nicht enthalten. |
Worauf zu achten ist
Die Punkte, an denen Integrationen erfahrungsgemäß hängen bleiben.
- Der
Idempotency-Keyist Pflicht. Maschinen wiederholen Requests — ohne Key wäre der erste Timeout eine Doppelbuchung. - Die Buchung entsteht als Gast-Buchung:
phoneist Pflicht (E.164) und empfängt die Bestätigungs-SMS. Zurücklesen lässt sich die Nummer nur mitread:bookings:pii. - Antwort 201 = neu angelegt, 200 = Idempotenz-Replay.
409 CONFLICTheißt: keine freie Kapazität auf diesem Abschnitt. - In
booking.created-Webhooks erkennen Sie eigene Buchungen ansource/sourcePluginSlug. - Zusätzliche Limits: enger Schreib-Bucket pro Schlüssel, Limit pro Zielrufnummer und ein Tages-Deckel pro Stadt.