RufBusle/Entwickler
Dokumentation

Plugins

Ein Plugin ist ein zusätzlicher Buchungskanal oder eine Erweiterung, die eine Stadt aus dem Katalog installiert — mit expliziter Zustimmung zu genau den Berechtigungen, die Ihr System braucht.

Das Modell: Katalog, Zustimmung, Schlüssel

Wer was darf, entscheidet die Stadt — einmal, ausdrücklich, nachvollziehbar.

Externe Plugins sind eigenständige Systeme, die über die REST-API und Webhooks mit RufBusle sprechen. Der Weg in den Betrieb: RufBusle nimmt Ihr Plugin mit Name, Beschreibung und angeforderten Berechtigungen in den Katalog auf; eine Stadt installiert es und stimmt dabei den Berechtigungen zu; bei der Installation entsteht ein API-Schlüssel, dessen Rechte exakt der Zustimmung entsprechen — plus optional ein signierter Webhook auf Ihre Basis-URL.

Die Zustimmung wird eingefroren: erweitert Ihr Plugin später seine Berechtigungen, gilt das nie automatisch für bestehende Installationen. Ihr System muss also damit umgehen, dass einzelne Städte nur die älteren Rechte gewährt haben (die Antwort von GET /v1/me nennt die tatsächlichen Scopes).

Berechtigungen

Genau das anfordern, was das Plugin braucht — die Stadt sieht jede Zeile im Zustimmungsdialog.
Fahrplan lesen
Haltestellen, Linien, Fahrten und Bedienzeiten der Stadt.
Buchungen lesen (pseudonymisiert)
Buchungen ohne personenbezogene Angaben, also ohne Namen und Telefonnummern.
Buchungen inkl. Kontaktdaten lesen
Zusätzlich Telefonnummern der Fahrgäste. Nur gewähren, wenn ein Auftragsverarbeitungsvertrag mit dem Anbieter besteht. (Gibt personenbezogene Daten frei — wird der Stadt eigens hervorgehoben.)
Fahrzeuge lesen
Fahrzeug-Stammdaten inkl. Kennzeichen und Fremdsystem-ID.
Buchungen anlegen und stornieren
Das Plugin kann im Namen von Fahrgästen Fahrten buchen und stornieren, z. B. als zusätzlicher Buchungskanal.

Für den Datenzugriff gelten dieselben Konventionen wie überall in der API: Anfragen mit dem Schlüssel als Authorization: Bearer rb_live_…, die Stadt ergibt sich aus dem Schlüssel, und ohne read:bookings:pii fehlen Telefonnummern vollständig.

Buchen als Kanal

Der Kern eines Buchungs-Plugins: Halte auflösen, Abfahrt finden, buchen.

Mit write:bookings legt Ihr System Buchungen im Namen von Fahrgästen an: Halte über GET /v1/stops, Abfahrten über GET /v1/trips, dann POST /v1/bookings. Der Fahrgast bekommt Bestätigung und Verwaltungslink per SMS an die übermittelte Nummer — Ihr Kanal muss keine eigenen Bestätigungen bauen.

Shell
curl -X POST https://rufbusle.de/api/v1/bookings \
  -H "Authorization: Bearer rb_live_…" \
  -H "Idempotency-Key: mein-system-4711" \
  -H "Content-Type: application/json" \
  -d '{
    "boardingStopId": "stp_7Kq2vX",
    "alightingStopId": "stp_1Ax9bN",
    "date": "2026-08-14",
    "time": "08:15",
    "seats": 2,
    "phone": "+4915112345678"
  }'

Storniert wird per POST /v1/bookings/{id}/cancel. Details und Feldtabellen stehen in der API-Referenz.

Eigene Buchungen erkennen

Der Rückkanal: Ereignisse tragen die Herkunft jeder Buchung.

Abonniert Ihr Plugin Ereignisse, erhält es sie als signierte Webhooks (Header X-Rufbusle-Signature, Prüfung wie in der Webhook-Doku). Jede Buchung trägt source und sourcePluginSlug — daran erkennt Ihr System in booking.created, ob die Buchung aus dem eigenen Kanal stammt oder von woanders (Web, Serie, andere Plugins).

Lauffähiges Beispiel

Ein komplettes Demo-Plugin ohne Abhängigkeiten.

Im Repository liegt unter examples/plugins/demo-webhook-booker ein Ein-Datei-Node-Server, der den kompletten Kreislauf zeigt: Webhook-Signatur prüfen, eigene Buchungen erkennen, buchen und stornieren — als Vorlage für den eigenen Einstieg.

Grenzen & Fairness

Damit ein Kanal nie zur Last für die Stadt wird.
Schreib-Limit
Eigener, engerer Bucket pro Schlüssel für Buchungen (zusätzlich zum Lese-Limit).
Limit pro Rufnummer
Mehrfachbuchungen an dieselbe Nummer sind pro Stunde begrenzt — Gast-Buchungen lösen SMS aus.
Tages-Deckel pro Stadt
Ein gemeinsames Tagesbudget aller API-Buchungen einer Stadt fängt entlaufene Systeme ab.
Aussetzen & Widerruf
Die Stadt kann jederzeit deinstallieren oder den Schlüssel rotieren; die Plattform kann Installationen aussetzen. Ihr System sollte 403-Antworten sauber behandeln.