Kort antwoord: de API van Fleet OS, de software waarmee Cityflow zijn eigen vloot beheert, heeft 46 REST-endpoints met Bearer-authenticatie en een sandbox om te testen. Het PMS van een hotel, de app van een gebouw of je ERP kunnen boekingen aanmaken, de uitgifte en inname van de fiets registreren, de vloot opvragen en statistieken lezen.
Dit artikel is voor operators met een eigen vloot. Heb je een hotel en wil je alleen fietsen voor je gasten, dan valt er niets te integreren: in de hotels die Cityflow beheert, opent de gast de fiets met de NFC-sleutel van zijn kamer. Dat lees je bij e-bikes voor hotels.
Wat zit er precies in de API van Fleet OS?
Er zijn 46 endpoints in zes groepen. Ze werken allemaal met POST, met de body in JSON en de sleutel in de header “Authorization: Bearer”. De parameters en de voorbeelden staan in de API-referentie.
| Groep | Endpoints | Waarvoor |
|---|---|---|
| Boekingen en toerisme (7) | /create_advance_booking, /get_booking, /cancel_booking, /rental_checkin, /rental_checkout, /purchase_tourist_pass, /validate_tourist_pass | Boeken, uitgeven met ontgrendelcode, innemen met afrekening, passen |
| Stedelijke micromobiliteit (3) | /get_vehicles_status, /get_operating_zones, /calculate_trip_fare | Status van de vloot, zones van een stad, tarief van een rit |
| Bedrijfsvloten (3) | /register_corporate_user, /set_employee_permissions, /create_campus_reservation | Registratie op basis van het e-maildomein, rechten, reserveringen op een campus |
| Meerdere steden en franchises (2) | /get_master_overview, /get_franchise_metrics | Overzicht van het netwerk, statistieken per franchise of per locatie |
| Intern beheer (4) | /create_hotel, /set_hotel_prices, /create_bike, /update_bike_status | Aanmaken, prijzen per hotel, status van elke fiets |
| Tabellen (27) | /update_booking, /update_payment, /update_maintenance en nog 24 | Een record veld voor veld wijzigen |
De 27 tabelendpoints werken allemaal hetzelfde: je stuurt de record_id en alleen de velden die veranderen.
Hoe werkt de authenticatie en hoe test je zonder risico?
Met een API-sleutel die Cityflow levert als je Fleet OS afneemt; zonder die sleutel geeft het platform geen gegevens terug. Vanaf de eerste dag heb je een sandbox met testgegevens om de integratie te valideren zonder aan echte fietsen te komen.
De antwoorden van de sandbox geven dat aan in hun veld meta, en ontbreekt er een verplichte parameter, dan zegt de foutmelding welke.
Hoe koppel je het PMS van een hotel?
Door de boekingsendpoints aan te roepen vanuit het PMS of vanuit een kleine tussenliggende ontwikkeling. Een mogelijke flow:
- De gast voegt de fiets toe aan zijn verblijf: /create_advance_booking, met zijn e-mailadres, de locatie, de data en de fietsen.
- Annuleert hij het verblijf: /cancel_booking.
- Bij aankomst: /rental_checkin, dat de ontgrendelcode teruggeeft om die aan de gast te tonen.
- Aan het eind: /rental_checkout, dat de huur met de afrekening afsluit.
- Op elk moment geeft /get_booking de status van de boeking.
Fleet OS schrijft niet in het PMS: om het bedrag op de kamerrekening te zetten, brengt je ontwikkeling de afrekening naar het PMS met de API van dat PMS, of bouwt Cityflow het als aparte integratie.
En de app van een gebouw of een bedrijf?
Met dezelfde endpoints. De app van een gebouw waarvoor je de dienst levert, toont de beschikbare fietsen met /get_vehicles_status, en met /create_advance_booking en /rental_checkin boekt de bewoner en krijgt hij zijn code zonder de app te verlaten.
Voor de vloot van een bedrijf kan het intranet:
- elke medewerker registreren met /register_corporate_user, dat het e-maildomein controleert;
- rechten per afdeling of profiel toekennen met /set_employee_permissions;
- op de campus reserveren met /create_campus_reservation.
Wat kan een ERP of een intern systeem lezen en schrijven?
Het kan statistieken lezen en de status van de vloot schrijven. /get_master_overview geeft het overzicht van je hele netwerk over een periode en /get_franchise_metrics splitst dat per franchise of per locatie. Meer daarover in meerdere vloten beheren vanuit één dashboard.
Je werkplaatssysteem kan een fiets op onderhoud zetten, en weer op beschikbaar, met /update_bike_status. Nieuwe fietsen komen erbij met /create_bike, met hun model, hun locatie en hun type slot. Fleet OS is compatibel met sloten van Linka, AXA IN en Omni en met de IoT van Acton en Okai: dat lees je in de gids over slimme sloten en IoT.
De tabellen omvatten onder meer boekingen, betalingen, onderhoud, incidenten en gebruikers.
Wat zit er niet in de API?
Er ontbreken drie dingen die je beter weet voordat je de integratie ontwerpt:
- Automatische meldingen (webhooks). De API meldt niet wanneer een huur begint of eindigt: je systeem vraagt het op met /get_booking of /get_vehicles_status.
- Kant-en-klare connectoren voor een specifiek PMS. Die bouwt je eigen team of Cityflow.
- Schrijven in je systemen. Fleet OS antwoordt op je aanroepen; het schrijft niet uit zichzelf in je PMS of je ERP.
Elk daarvan wordt als integratie begroot: € 750 voor een standaardintegratie; niet-standaardintegraties met een voorstel.
Wat kost het om de API te gebruiken?
Niets extra: de toegang is inbegrepen in het abonnement van Fleet OS, dat € 300 per maand kost plus € 8 tot € 3 per voertuig afhankelijk van de staffel, met € 1.000 activering en zonder minimale looptijd. Alleen integraties met hardware of systemen die Fleet OS niet standaard ondersteunt, betaal je apart, € 750 voor een standaardintegratie. De details staan bij de tarieven van Fleet OS.
Hoe begin je?
- Lees de API-referentie en markeer de endpoints voor jouw situatie.
- Vraag een demo aan en vertel Cityflow welke systemen je wilt koppelen.
- Bij het afsluiten krijg je de sleutel en de sandbox, en valideert je team de integratie.
Fleet OS is de software waarmee Cityflow zijn vloot in 9 provincies beheert, en er rijden al operators uit de sector mee. Meer vind je op de pagina van Fleet OS, waar je ook een demo kunt aanvragen.
Veelgestelde vragen
Hoeveel endpoints heeft de API van Fleet OS?
46 REST-endpoints met Bearer-authenticatie en een sandbox met testgegevens, verdeeld over zes groepen; 27 ervan dienen om de tabellen veld voor veld te wijzigen. De volledige referentie staat op cityflow.app/software/api.
Kun je Fleet OS koppelen aan het PMS van een hotel?
Ja: het PMS, of een tussenliggende ontwikkeling, roept de boekingsendpoints aan om de boeking aan te maken, de uitgifte met de ontgrendelcode te registreren, de huur met de afrekening af te sluiten of hem te annuleren. Fleet OS heeft geen kant-en-klare connector voor een specifiek PMS: bouwt Cityflow die, dan is het een aparte integratie, € 750 voor een standaardintegratie.
Laat de API van Fleet OS mijn systeem weten wanneer een huur begint of eindigt?
Nee: de referentie bevat geen automatische meldingen (webhooks). Je systeem vraagt de status op met /get_booking of /get_vehicles_status; wil je dat Fleet OS meldingen stuurt, dan wordt dat als integratie begroot.
Wat kost toegang tot de API van Fleet OS?
Die is inbegrepen in het abonnement van Fleet OS: € 300 per maand plus € 8 tot € 3 per voertuig afhankelijk van de staffel, en € 1.000 activering, zonder minimale looptijd. Integraties met hardware of systemen die Fleet OS niet standaard ondersteunt, kosten € 750 voor een standaardintegratie.
Kan ik de integratie testen zonder aan mijn echte vloot te komen?
Ja. Vanaf de eerste dag heb je een sandbox met testgegevens, en de antwoorden geven dat aan in het veld meta. Je team valideert elke stap voordat het die aan de echte fietsen koppelt.
VOLGENDE STAP
Wil je een voorstel op maat voor jouw operatie?
Vertel ons wat je nodig hebt en we reageren binnen 24 uur met een plan afgestemd op jouw business.
Praat met sales
