Bike-Sharing-API: was du mit Fleet OS integrieren kannst (PMS, Gebäude-App und interne Systeme)

Direkte Antwort: Die API von Fleet OS, der Software, mit der Cityflow seine eigene Flotte betreibt, hat 46 REST-Endpunkte mit Bearer-Authentifizierung und eine Sandbox zum Testen. Das PMS eines Hotels, die App eines Gebäudes oder dein ERP können Buchungen anlegen, Übergabe und Rückgabe des Rads erfassen, die Flotte abfragen und Kennzahlen lesen.

Dieser Artikel richtet sich an Betreiber mit eigener Flotte. Hast du ein Hotel und willst nur Räder für deine Gäste, gibt es nichts zu integrieren: In den Hotels, die Cityflow betreibt, öffnet der Gast das Rad mit dem NFC-Schlüssel seines Zimmers. Mehr dazu unter E-Bikes für Hotels.

Was genau steckt in der API von Fleet OS?

46 Endpunkte in sechs Gruppen. Alle laufen über POST, mit dem Body in JSON und dem Schlüssel im Header „Authorization: Bearer“. Parameter und Beispiele stehen in der API-Referenz.

Die 27 Tabellen-Endpunkte funktionieren alle gleich: Du schickst die record_id und nur die Felder, die sich ändern.

Wie authentifiziert man sich, und wie testet man ohne Risiko?

Mit einem API-Schlüssel, den Cityflow beim Abschluss von Fleet OS übergibt; ohne ihn liefert die Plattform keine Daten. Vom ersten Tag an hast du eine Sandbox mit Testdaten, um die Integration zu prüfen, ohne echte Räder anzufassen.

Die Antworten der Sandbox weisen das in ihrem Feld meta aus, und fehlt ein Pflichtparameter, sagt der Fehler, welcher.

Wie wird das PMS eines Hotels angebunden?

Indem die Buchungs-Endpunkte aufgerufen werden, direkt aus dem PMS oder über eine kleine Zwischenentwicklung. Ein möglicher Ablauf:

1. Der Gast fügt das Rad seinem Aufenthalt hinzu: /create_advance_booking, mit seiner E-Mail, dem Objekt, dem Zeitraum und den Rädern.
2. Storniert er den Aufenthalt: /cancel_booking.
3. Bei der Ankunft: /rental_checkin, das den Entsperrcode zurückgibt, damit du ihn dem Gast anzeigst.
4. Am Ende: /rental_checkout, das die Miete mit ihrer Abrechnung abschließt.
5. Jederzeit liefert /get_booking den Status der Buchung.

Fleet OS schreibt nicht ins PMS: Um den Betrag auf die Zimmerrechnung zu buchen, überträgt deine Entwicklung die Abrechnung über die API des PMS selbst ins PMS, oder Cityflow baut das als separate Integration.

Und die App eines Gebäudes oder eines Unternehmens?

Mit denselben Endpunkten. Die App eines Gebäudes, das du mit Rädern versorgst, zeigt mit /get_vehicles_status die freien Räder, und mit /create_advance_booking und /rental_checkin bucht der Bewohner und bekommt seinen Code, ohne die App zu verlassen.

Für die Flotte eines Unternehmens kann dessen Intranet:

• jeden Mitarbeiter mit /register_corporate_user registrieren, das die Domain der E-Mail prüft;
• mit /set_employee_permissions Berechtigungen nach Abteilung oder Profil vergeben;
• mit /create_campus_reservation auf dem Campus buchen.

Was kann ein ERP oder ein internes System lesen und schreiben?

Es kann Kennzahlen lesen und den Status der Flotte schreiben. /get_master_overview liefert den Überblick über dein ganzes Netz in einem Zeitraum, und /get_franchise_metrics schlüsselt ihn nach Franchise oder Objekt auf. Mehr dazu unter wie du mehrere Flotten von einem einzigen Panel aus verwaltest.

Dein Werkstattsystem kann ein Rad mit /update_bike_status in die Wartung setzen und wieder auf verfügbar. Neue Räder kommen mit /create_bike dazu, mit Modell, Objekt und Schlosstyp. Fleet OS ist kompatibel mit Schlössern von Linka, AXA IN und Omni sowie mit dem IoT von Acton und Okai: Das steht im Leitfaden zu Smart Locks und IoT.

Die Tabellen decken unter anderem Buchungen, Zahlungen, Wartungen, Vorfälle und Nutzer ab.

Was ist nicht in der API?

Drei Dinge fehlen, die du kennen solltest, bevor du die Integration entwirfst:

• Automatische Benachrichtigungen (Webhooks). Die API meldet sich nicht, wenn eine Miete beginnt oder endet: Dein System fragt mit /get_booking oder /get_vehicles_status nach.
• Fertige Konnektoren für ein bestimmtes PMS. Die baut dein Team oder Cityflow.
• In deine Systeme schreiben. Fleet OS antwortet auf deine Aufrufe; es schreibt nicht von sich aus in dein PMS oder dein ERP.

Jedes davon wird als Integration kalkuliert: 750 € als Standard-Integration; Nicht-Standard-Integrationen nach Angebot.

Was kostet die Nutzung der API?

Nichts extra: Der Zugang ist in der Gebühr von Fleet OS enthalten, also 300 € im Monat plus 8 € bis 3 € pro Fahrzeug je nach Staffel, mit 1.000 € Aktivierung und ohne Mindestlaufzeit. Extra bezahlt werden nur Integrationen mit Hardware oder Systemen, die Fleet OS nicht standardmäßig mitbringt, 750 € als Standard-Integration. Die Details stehen in den Tarifen von Fleet OS.

Wie fängt man an?

1. Lies die API-Referenz und markiere die Endpunkte für deinen Fall.
2. Fordere eine Demo an und erzähl Cityflow, welche Systeme du anbinden willst.
3. Mit dem Vertrag bekommst du den Schlüssel und die Sandbox, und dein Team prüft die Integration.

Fleet OS ist die Software, mit der Cityflow seine Flotte in 9 Provinzen betreibt, und es gibt Betreiber aus der Branche, die schon damit fahren. Mehr findest du auf der Seite von Fleet OS, wo du auch eine Demo anfordern kannst.

Häufig gestellte Fragen

Wie viele Endpunkte hat die API von Fleet OS?

46 REST-Endpunkte mit Bearer-Authentifizierung und eine Sandbox mit Testdaten, verteilt auf sechs Gruppen; 27 davon dienen dazu, die Tabellen Feld für Feld zu ändern. Die vollständige Referenz ist unter cityflow.app/software/api veröffentlicht.

Lässt sich Fleet OS mit dem PMS eines Hotels verbinden?

Ja: Das PMS oder eine Zwischenentwicklung ruft die Buchungs-Endpunkte auf, um die Buchung anzulegen, die Übergabe mit ihrem Entsperrcode zu erfassen, die Miete mit ihrer Abrechnung abzuschließen oder sie zu stornieren. Fleet OS bringt keinen fertigen Konnektor für ein bestimmtes PMS mit: Baut Cityflow ihn, ist das eine separate Integration, 750 € als Standard-Integration.

Benachrichtigt die API von Fleet OS mein System, wenn eine Miete beginnt oder endet?

Nein: Die Referenz enthält keine automatischen Benachrichtigungen (Webhooks). Dein System fragt den Status mit /get_booking oder /get_vehicles_status ab; brauchst du Benachrichtigungen von Fleet OS, wird das als Integration kalkuliert.

Was kostet der Zugang zur API von Fleet OS?

Er ist in der Gebühr von Fleet OS enthalten: 300 € im Monat plus 8 € bis 3 € pro Fahrzeug je nach Staffel und 1.000 € Aktivierung, ohne Mindestlaufzeit. Integrationen mit Hardware oder Systemen, die Fleet OS nicht standardmäßig mitbringt, kosten 750 € als Standard-Integration.

Kann ich die Integration testen, ohne meine echte Flotte anzufassen?

Ja. Vom ersten Tag an hast du eine Sandbox mit Testdaten, und ihre Antworten weisen das im Feld meta aus. Dein Team prüft jeden Schritt, bevor es ihn mit den echten Rädern verbindet.