API di bike sharing: cosa puoi integrare con Fleet OS (PMS, app dell'edificio e sistemi interni)

Risposta diretta: l'API di Fleet OS, il software con cui Cityflow gestisce la propria flotta, ha 46 endpoint REST con autenticazione Bearer e una sandbox di prova. Il PMS di un hotel, l'app di un edificio o il tuo ERP possono creare prenotazioni, registrare la consegna e la riconsegna della bici, consultare la flotta e leggere metriche.

Questo articolo è per operatori con flotta propria. Se hai un hotel e vuoi solo bici per i tuoi ospiti, non c'è niente da integrare: negli hotel gestiti da Cityflow, l'ospite apre la bici con la chiave NFC della sua camera. Trovi tutto in bici elettriche per hotel.

Cosa c'è esattamente nell'API di Fleet OS?

Ci sono 46 endpoint in sei gruppi. Usano tutti POST, con il corpo in JSON e la chiave nell'intestazione «Authorization: Bearer». I parametri e gli esempi sono nella documentazione dell'API.

I 27 delle tabelle funzionano allo stesso modo: invii il record_id e solo i campi che cambiano.

Come ci si autentica e come si prova senza rischi?

Con una chiave API che Cityflow consegna quando sottoscrivi Fleet OS; senza, la piattaforma non restituisce dati. Dal primo giorno hai una sandbox con dati di prova per convalidare l'integrazione senza toccare bici reali.

Le risposte della sandbox lo indicano nel campo meta, e se manca un parametro obbligatorio, l'errore dice quale.

Come si collega il PMS di un hotel?

Chiamando gli endpoint delle prenotazioni dal PMS o da un piccolo sviluppo intermedio. Un flusso possibile:

1. L'ospite aggiunge la bici al suo soggiorno: /create_advance_booking, con la sua email, la struttura, le date e le bici.
2. Se annulla il soggiorno: /cancel_booking.
3. All'arrivo: /rental_checkin, che restituisce il codice di sblocco da mostrargli.
4. Alla fine: /rental_checkout, che chiude il noleggio con il saldo finale.
5. In qualsiasi momento, /get_booking dà lo stato della prenotazione.

Fleet OS non scrive nel PMS: per addebitare l'importo sul conto della camera, il tuo sviluppo porta il saldo nel PMS con l'API del PMS stesso, oppure Cityflow lo costruisce come integrazione a parte.

E l'app di un edificio o di un'azienda?

Con gli stessi endpoint. L'app di un edificio a cui dai servizio mostra le bici libere con /get_vehicles_status e, con /create_advance_booking e /rental_checkin, il residente prenota e riceve il suo codice senza uscire dall'app.

Per la flotta di un'azienda, la sua intranet può:

• registrare ogni dipendente con /register_corporate_user, che convalida il dominio dell'email;
• assegnare permessi per reparto o profilo con /set_employee_permissions;
• prenotare nel campus con /create_campus_reservation.

Cosa può leggere e scrivere un ERP o un sistema interno?

Può leggere metriche e scrivere lo stato della flotta. /get_master_overview dà la vista di tutta la tua rete in un periodo e /get_franchise_metrics la suddivide per franchising o per proprietà. Approfondisci in come gestire più flotte da un unico pannello.

Il tuo sistema di officina può mettere una bici in manutenzione, e rimetterla disponibile, con /update_bike_status. Le bici nuove entrano con /create_bike, con il loro modello, la loro proprietà e il loro tipo di lucchetto. Fleet OS è compatibile con i lucchetti Linka, AXA IN e Omni e con l'IoT di Acton e Okai: lo trovi nella guida ai lucchetti intelligenti e all'IoT.

Le tabelle coprono prenotazioni, pagamenti, manutenzioni, segnalazioni e utenti, tra le altre.

Cosa non c'è nell'API?

Mancano tre cose che conviene sapere prima di progettare l'integrazione:

• Avvisi automatici (webhook). L'API non avvisa quando un noleggio inizia o finisce: il tuo sistema chiede con /get_booking o /get_vehicles_status.
• Connettori pronti con un PMS specifico. Li costruisce il tuo team o Cityflow.
• Scrivere nei tuoi sistemi. Fleet OS risponde alle tue chiamate; non scrive di sua iniziativa nel tuo PMS né nel tuo ERP.

Ognuna di queste si preventiva come integrazione: 750 € quella standard; quelle non standard, con una proposta.

Quanto costa usare l'API?

Niente in più: l'accesso è incluso nel canone di Fleet OS, che è di 300 € al mese più da 8 € a 3 € per veicolo secondo la fascia, con 1.000 € di attivazione e senza vincolo di durata. Si pagano a parte solo le integrazioni con hardware o sistemi che Fleet OS non include di serie, 750 € quella standard. Il dettaglio è nelle tariffe di Fleet OS.

Come si comincia?

1. Leggi la documentazione dell'API e segna gli endpoint del tuo caso.
2. Chiedi una demo e racconta a Cityflow quali sistemi vuoi collegare.
3. Alla sottoscrizione ricevi la chiave e la sandbox, e il tuo team convalida l'integrazione.

Fleet OS è il software con cui Cityflow gestisce la sua flotta in 9 province, e ci sono operatori del settore che lo usano già. Trovi di più nella pagina di Fleet OS, dove puoi anche chiedere una demo.

Domande frequenti

Quanti endpoint ha l'API di Fleet OS?

46 endpoint REST con autenticazione Bearer e una sandbox con dati di prova, divisi in sei gruppi; 27 di questi servono a modificare le tabelle campo per campo. La documentazione completa è pubblicata su cityflow.app/software/api.

Si può collegare Fleet OS al PMS di un hotel?

Sì: il PMS, o uno sviluppo intermedio, chiama gli endpoint delle prenotazioni per creare la prenotazione, registrare la consegna con il suo codice di sblocco, chiudere il noleggio con il saldo finale o annullarlo. Fleet OS non ha un connettore pronto per un PMS specifico: se lo costruisce Cityflow, è un'integrazione a parte, 750 € quella standard.

L'API di Fleet OS avvisa il mio sistema quando un noleggio inizia o finisce?

No: la documentazione non include avvisi automatici (webhook). Il tuo sistema consulta lo stato con /get_booking o /get_vehicles_status; se ti serve che Fleet OS avvisi, si preventiva come integrazione.

Quanto costa l'accesso all'API di Fleet OS?

È incluso nel canone di Fleet OS: 300 € al mese più da 8 € a 3 € per veicolo secondo la fascia, e 1.000 € di attivazione, senza vincolo di durata. Le integrazioni con hardware o sistemi che Fleet OS non include di serie costano 750 € quella standard.

Posso provare l'integrazione senza toccare la mia flotta reale?

Sì. Dal primo giorno hai una sandbox con dati di prova, e le sue risposte lo indicano nel campo meta. Il tuo team convalida ogni passaggio prima di collegarlo alle bici reali.