API de bike-sharing: què pots integrar amb Fleet OS (PMS, app de l'edifici i sistemes interns)

Resposta directa: l'API de Fleet OS, el software amb el qual Cityflow opera la seva pròpia flota, té 46 endpoints REST amb autenticació Bearer i sandbox de proves. El PMS d'un hotel, l'app d'un edifici o el teu ERP poden crear reserves, registrar l'entrega i la devolució de la bici, consultar la flota i llegir mètriques.

Aquest article és per a operadors amb flota pròpia. Si tens un hotel i només vols bicis per als teus hostes, no hi ha res a integrar: als hotels que opera Cityflow, l'hoste obre la bici amb la clau NFC de la seva habitació. Ho tens a bicis elèctriques per a hotels.

Què hi ha exactament a l'API de Fleet OS?

Hi ha 46 endpoints en sis grups. Tots van per POST, amb el cos en JSON i la clau a la capçalera «Authorization: Bearer». Els paràmetres i els exemples són a la referència de l'API.

Els 27 de taules funcionen igual: envies el record_id i només els camps que canvien.

Com s'autentica i com es prova sense risc?

Amb una clau d'API que Cityflow lliura en contractar Fleet OS; sense ella, la plataforma no retorna dades. Des del primer dia tens un sandbox amb dades de prova per validar la integració sense tocar bicis reals.

Les respostes del sandbox ho indiquen al seu camp meta, i si falta un paràmetre obligatori, l'error diu quin.

Com es connecta el PMS d'un hotel?

Cridant els endpoints de reserves des del PMS o des d'un petit desenvolupament intermedi. Un flux possible:

1. L'hoste afegeix la bici a la seva estada: /create_advance_booking, amb el seu correu, la propietat, les dates i les bicis.
2. Si cancel·la l'estada: /cancel_booking.
3. En arribar: /rental_checkin, que retorna el codi de desbloqueig per ensenyar-l'hi.
4. En acabar: /rental_checkout, que tanca el lloguer amb la seva liquidació.
5. En qualsevol moment, /get_booking dona l'estat de la reserva.

Fleet OS no escriu al PMS: per carregar l'import al compte de l'habitació, el teu desenvolupament porta la liquidació al PMS amb l'API del mateix PMS, o Cityflow el construeix com a integració a part.

I l'app d'un edifici o d'una empresa?

Amb els mateixos endpoints. L'app d'un edifici al qual dones servei ensenya les bicis lliures amb /get_vehicles_status i, amb /create_advance_booking i /rental_checkin, el resident reserva i rep el seu codi sense sortir-ne.

Per a la flota d'una empresa, la seva intranet pot:

• donar d'alta cada empleat amb /register_corporate_user, que valida el domini del correu;
• assignar permisos per departament o perfil amb /set_employee_permissions;
• reservar al campus amb /create_campus_reservation.

Què pot llegir i escriure un ERP o un sistema intern?

Pot llegir mètriques i escriure l'estat de la flota. /get_master_overview dona la vista de tota la teva xarxa en un període i /get_franchise_metrics la separa per franquícia o per propietat. Més a com gestionar diverses flotes des d'un únic panell.

El teu sistema de taller pot passar una bici a manteniment, i de tornada a disponible, amb /update_bike_status. Les bicis noves entren amb /create_bike, amb el seu model, la seva propietat i el seu tipus de cadenat. Fleet OS és compatible amb cadenats Linka, AXA IN i Omni i amb l'IoT d'Acton i Okai: ho tens a la guia de cadenats intel·ligents i IoT.

Les taules cobreixen reserves, pagaments, manteniments, incidències i usuaris, entre altres.

Què no està a l'API?

Falten tres coses que convé saber abans de dissenyar la integració:

• Avisos automàtics (webhooks). L'API no avisa quan comença o acaba un lloguer: el teu sistema pregunta amb /get_booking o /get_vehicles_status.
• Connectors fets amb un PMS concret. El construeix el teu equip o Cityflow.
• Escriure als teus sistemes. Fleet OS respon a les teves crides; no escriu pel seu compte al teu PMS ni al teu ERP.

Qualsevol d'elles es pressuposta com a integració: 750 € l'estàndard; les no estàndard, amb proposta.

Quant costa fer servir l'API?

Res a part: l'accés va inclòs a la quota de Fleet OS, que són 300 € al mes més de 8 € a 3 € per vehicle segons el tram, amb 1.000 € d'activació i sense permanència. Només es paguen a part les integracions amb maquinari o sistemes que Fleet OS no porta de sèrie, 750 € l'estàndard. El detall és a les tarifes de Fleet OS.

Com es comença?

1. Llegeix la referència de l'API i marca els endpoints del teu cas.
2. Demana una demo i explica a Cityflow quins sistemes vols connectar.
3. En contractar reps la clau i el sandbox, i el teu equip valida la integració.

Fleet OS és el software amb el qual Cityflow opera la seva flota en 9 províncies, i hi ha operadors del sector que ja hi roden. Tens més a la pàgina de Fleet OS, on també pots demanar una demo.

Preguntes freqüents

Quants endpoints té l'API de Fleet OS?

46 endpoints REST amb autenticació Bearer i un sandbox amb dades de prova, repartits en sis grups; 27 d'ells serveixen per canviar les taules camp a camp. La referència completa està publicada a cityflow.app/software/api.

Es pot connectar Fleet OS amb el PMS d'un hotel?

Sí: el PMS, o un desenvolupament intermedi, crida els endpoints de reserves per crear la reserva, registrar l'entrega amb el seu codi de desbloqueig, tancar el lloguer amb la seva liquidació o cancel·lar-lo. Fleet OS no porta un connector fet per a un PMS concret: si el construeix Cityflow, és una integració a part, 750 € l'estàndard.

L'API de Fleet OS avisa el meu sistema quan comença o acaba un lloguer?

No: la referència no inclou avisos automàtics (webhooks). El teu sistema consulta l'estat amb /get_booking o /get_vehicles_status; si necessites que Fleet OS avisi, es pressuposta com a integració.

Quant costa l'accés a l'API de Fleet OS?

Està inclòs a la quota de Fleet OS: 300 € al mes més de 8 € a 3 € per vehicle segons el tram, i 1.000 € d'activació, sense permanència. Només es paguen a part les integracions amb maquinari o sistemes que Fleet OS no porta de sèrie, 750 € l'estàndard.

Puc provar la integració sense tocar la meva flota real?

Sí. Des del primer dia tens un sandbox amb dades de prova, i les seves respostes ho indiquen al camp meta. El teu equip valida cada pas abans de connectar-lo a les bicis reals.