Respuesta directa: la API de Fleet OS, el software con el que Cityflow opera su propia flota, tiene 46 endpoints REST con autenticación Bearer y sandbox de pruebas. El PMS de un hotel, la app de un edificio o tu ERP pueden crear reservas, registrar la entrega y la devolución de la bici, consultar la flota y leer métricas.
Este artículo es para operadores con flota propia. Si tienes un hotel y solo quieres bicis para tus huéspedes, no hay nada que integrar: en los hoteles que opera Cityflow, el huésped abre la bici con la llave NFC de su habitación. Lo tienes en bicis eléctricas para hoteles.
¿Qué hay exactamente en la API de Fleet OS?
Hay 46 endpoints en seis grupos. Todos van por POST, con el cuerpo en JSON y la clave en la cabecera «Authorization: Bearer». Los parámetros y los ejemplos están en la referencia de la API.
| Grupo | Endpoints | Para qué |
|---|---|---|
| Reservas y turismo (7) | /create_advance_booking, /get_booking, /cancel_booking, /rental_checkin, /rental_checkout, /purchase_tourist_pass, /validate_tourist_pass | Reservar, entregar con código de desbloqueo, devolver con liquidación, pases |
| Micromovilidad urbana (3) | /get_vehicles_status, /get_operating_zones, /calculate_trip_fare | Estado de la flota, zonas de una ciudad, tarifa de un trayecto |
| Flotas corporativas (3) | /register_corporate_user, /set_employee_permissions, /create_campus_reservation | Alta por dominio del correo, permisos, reservas en un campus |
| Multiciudad y franquicias (2) | /get_master_overview, /get_franchise_metrics | Vista de la red, métricas por franquicia o propiedad |
| Gestión interna (4) | /create_hotel, /set_hotel_prices, /create_bike, /update_bike_status | Altas, precios por hotel, estado de cada bici |
| Tablas (27) | /update_booking, /update_payment, /update_maintenance y 24 más | Cambiar un registro campo a campo |
Los 27 de tablas funcionan igual: mandas el record_id y solo los campos que cambian.
¿Cómo se autentica y cómo se prueba sin riesgo?
Con una clave de API que Cityflow entrega al contratar Fleet OS; sin ella, la plataforma no devuelve datos. Desde el primer día tienes un sandbox con datos de prueba para validar la integración sin tocar bicis reales.
Las respuestas del sandbox lo indican en su campo meta, y si falta un parámetro obligatorio, el error dice cuál.
¿Cómo se conecta el PMS de un hotel?
Llamando a los endpoints de reservas desde el PMS o desde un pequeño desarrollo intermedio. Un flujo posible:
- El huésped añade la bici a su estancia: /create_advance_booking, con su correo, la propiedad, las fechas y las bicis.
- Si cancela la estancia: /cancel_booking.
- Al llegar: /rental_checkin, que devuelve el código de desbloqueo para enseñárselo.
- Al acabar: /rental_checkout, que cierra el alquiler con su liquidación.
- En cualquier momento, /get_booking da el estado de la reserva.
Fleet OS no escribe en el PMS: para cargar el importe en la cuenta de la habitación, tu desarrollo lleva la liquidación al PMS con la API del propio PMS, o Cityflow lo construye como integración aparte.
¿Y la app de un edificio o de una empresa?
Con los mismos endpoints. La app de un edificio al que das servicio enseña las bicis libres con /get_vehicles_status y, con /create_advance_booking y /rental_checkin, el residente reserva y recibe su código sin salir de ella.
Para la flota de una empresa, su intranet puede:
- dar de alta a cada empleado con /register_corporate_user, que valida el dominio del correo;
- asignar permisos por departamento o perfil con /set_employee_permissions;
- reservar en el campus con /create_campus_reservation.
¿Qué puede leer y escribir un ERP o un sistema interno?
Puede leer métricas y escribir el estado de la flota. /get_master_overview da la vista de toda tu red en un periodo y /get_franchise_metrics la separa por franquicia o por propiedad. Más en cómo gestionar varias flotas desde un único panel.
Tu sistema de taller puede pasar una bici a mantenimiento, y de vuelta a disponible, con /update_bike_status. Las bicis nuevas entran con /create_bike, con su modelo, su propiedad y su tipo de candado. Fleet OS es compatible con candados Linka, AXA IN y Omni y con el IoT de Acton y Okai: lo tienes en la guía de candados inteligentes e IoT.
Las tablas cubren reservas, pagos, mantenimientos, incidencias y usuarios, entre otras.
¿Qué no está en la API?
Faltan tres cosas que conviene saber antes de diseñar la integración:
- Avisos automáticos (webhooks). La API no avisa cuando empieza o termina un alquiler: tu sistema pregunta con /get_booking o /get_vehicles_status.
- Conectores hechos con un PMS concreto. Lo construye tu equipo o Cityflow.
- Escribir en tus sistemas. Fleet OS responde a tus llamadas; no escribe por su cuenta en tu PMS ni en tu ERP.
Cualquiera de ellas se presupuesta como integración: 750 € la estándar; las no estándar, con propuesta.
¿Cuánto cuesta usar la API?
Nada aparte: el acceso va incluido en la cuota de Fleet OS, que son 300 € al mes más de 8 € a 3 € por vehículo según el tramo, con 1.000 € de activación y sin permanencia. Solo se pagan aparte las integraciones con hardware o sistemas que Fleet OS no trae de serie, 750 € la estándar. El detalle está en las tarifas de Fleet OS.
¿Cómo se empieza?
- Lee la referencia de la API y marca los endpoints de tu caso.
- Pide una demo y cuéntale a Cityflow qué sistemas quieres conectar.
- Al contratar recibes la clave y el sandbox, y tu equipo valida la integración.
Fleet OS es el software con el que Cityflow opera su flota en 9 provincias, y hay operadores del sector que ya ruedan con él. Tienes más en la página de Fleet OS, donde también puedes pedir una demo.
Preguntas frecuentes
¿Cuántos endpoints tiene la API de Fleet OS?
46 endpoints REST con autenticación Bearer y un sandbox con datos de prueba, repartidos en seis grupos; 27 de ellos sirven para cambiar las tablas campo a campo. La referencia completa está publicada en cityflow.app/software/api.
¿Se puede conectar Fleet OS con el PMS de un hotel?
Sí: el PMS, o un desarrollo intermedio, llama a los endpoints de reservas para crear la reserva, registrar la entrega con su código de desbloqueo, cerrar el alquiler con su liquidación o cancelarlo. Fleet OS no trae un conector hecho para un PMS concreto: si lo construye Cityflow, es una integración aparte, 750 € la estándar.
¿La API de Fleet OS avisa a mi sistema cuando empieza o termina un alquiler?
No: la referencia no incluye avisos automáticos (webhooks). Tu sistema consulta el estado con /get_booking o /get_vehicles_status; si necesitas que Fleet OS avise, se presupuesta como integración.
¿Cuánto cuesta el acceso a la API de Fleet OS?
Está incluido en la cuota de Fleet OS: 300 € al mes más de 8 € a 3 € por vehículo según el tramo, y 1.000 € de activación, sin permanencia. Las integraciones con hardware o sistemas que Fleet OS no trae de serie cuestan 750 € la estándar.
¿Puedo probar la integración sin tocar mi flota real?
Sí. Desde el primer día tienes un sandbox con datos de prueba, y sus respuestas lo indican en el campo meta. Tu equipo valida cada paso antes de conectarlo a las bicis reales.
SIGUIENTE PASO
¿Quieres una propuesta a medida para tu operación?
Cuéntanos qué necesitas y te respondemos en menos de 24 horas con un plan adaptado a tu negocio.
Hablar con comercial
