API de bike-sharing: o que podes integrar com o Fleet OS (PMS, app do edifício e sistemas internos)

Resposta direta: a API do Fleet OS, o software com que a Cityflow opera a sua própria frota, tem 46 endpoints REST com autenticação Bearer e sandbox de testes. O PMS de um hotel, a app de um edifício ou o teu ERP podem criar reservas, registar a entrega e a devolução da bicicleta, consultar a frota e ler métricas.

Este artigo é para operadores com frota própria. Se tens um hotel e só queres bicicletas para os teus hóspedes, não há nada para integrar: nos hotéis que a Cityflow opera, o hóspede abre a bicicleta com a chave NFC do quarto. Tens isso em bicicletas elétricas para hotéis.

O que há exatamente na API do Fleet OS?

Há 46 endpoints em seis grupos. Todos vão por POST, com o corpo em JSON e a chave no cabeçalho «Authorization: Bearer». Os parâmetros e os exemplos estão na referência da API.

Os 27 das tabelas funcionam da mesma forma: envias o record_id e só os campos que mudam.

Como se faz a autenticação e como se testa sem risco?

Com uma chave de API que a Cityflow entrega ao contratares o Fleet OS; sem ela, a plataforma não devolve dados. Desde o primeiro dia tens um sandbox com dados de teste para validar a integração sem mexer em bicicletas reais.

As respostas do sandbox indicam-no no campo meta e, se faltar um parâmetro obrigatório, o erro diz qual.

Como se liga o PMS de um hotel?

Chamando os endpoints de reservas a partir do PMS ou de um pequeno desenvolvimento intermédio. Um fluxo possível:

1. O hóspede junta a bicicleta à sua estadia: /create_advance_booking, com o e-mail, a propriedade, as datas e as bicicletas.
2. Se cancelar a estadia: /cancel_booking.
3. À chegada: /rental_checkin, que devolve o código de desbloqueio para lho mostrar.
4. No fim: /rental_checkout, que fecha o aluguer com a respetiva liquidação.
5. A qualquer momento, /get_booking dá o estado da reserva.

O Fleet OS não escreve no PMS: para lançar o valor na conta do quarto, o teu desenvolvimento leva a liquidação ao PMS com a API do próprio PMS, ou a Cityflow constrói-o como integração à parte.

E a app de um edifício ou de uma empresa?

Com os mesmos endpoints. A app de um edifício a que prestas serviço mostra as bicicletas livres com /get_vehicles_status e, com /create_advance_booking e /rental_checkin, o residente reserva e recebe o código sem sair dela.

Para a frota de uma empresa, a intranet pode:

• registar cada colaborador com /register_corporate_user, que valida o domínio do e-mail;
• atribuir permissões por departamento ou perfil com /set_employee_permissions;
• reservar no campus com /create_campus_reservation.

O que pode ler e escrever um ERP ou um sistema interno?

Pode ler métricas e escrever o estado da frota. /get_master_overview dá a vista de toda a tua rede num período e /get_franchise_metrics separa-a por franchisado ou por propriedade. Mais em como gerir várias frotas a partir de um único painel.

O teu sistema de oficina pode passar uma bicicleta para manutenção, e de volta a disponível, com /update_bike_status. As bicicletas novas entram com /create_bike, com o modelo, a propriedade e o tipo de cadeado. O Fleet OS é compatível com cadeados Linka, AXA IN e Omni e com o IoT da Acton e da Okai: tens isso no guia de cadeados inteligentes e IoT.

As tabelas cobrem reservas, pagamentos, manutenções, incidências e utilizadores, entre outras.

O que não está na API?

Faltam três coisas que convém saber antes de desenhar a integração:

• Avisos automáticos (webhooks). A API não avisa quando um aluguer começa ou termina: o teu sistema pergunta com /get_booking ou /get_vehicles_status.
• Conectores prontos para um PMS concreto. Constrói-os a tua equipa ou a Cityflow.
• Escrever nos teus sistemas. O Fleet OS responde às tuas chamadas; não escreve por iniciativa própria no teu PMS nem no teu ERP.

Qualquer uma delas se orça como integração: 750 € a standard; as não standard, com proposta.

Quanto custa usar a API?

Nada à parte: o acesso está incluído na mensalidade do Fleet OS, que é de 300 € por mês mais de 8 € a 3 € por veículo, conforme o escalão, com 1.000 € de ativação e sem fidelização. Só se pagam à parte as integrações com hardware ou sistemas que o Fleet OS não traz de origem, 750 € a standard. O detalhe está nos preços do Fleet OS.

Como se começa?

1. Lê a referência da API e assinala os endpoints do teu caso.
2. Pede uma demo e diz à Cityflow que sistemas queres ligar.
3. Ao contratar recebes a chave e o sandbox, e a tua equipa valida a integração.

O Fleet OS é o software com que a Cityflow opera a sua frota em 9 províncias, e há operadores do setor que já trabalham com ele. Tens mais na página do Fleet OS, onde também podes pedir uma demo.

Perguntas frequentes

Quantos endpoints tem a API do Fleet OS?

46 endpoints REST com autenticação Bearer e um sandbox com dados de teste, repartidos por seis grupos; 27 deles servem para alterar as tabelas campo a campo. A referência completa está publicada em cityflow.app/software/api.

É possível ligar o Fleet OS ao PMS de um hotel?

Sim: o PMS, ou um desenvolvimento intermédio, chama os endpoints de reservas para criar a reserva, registar a entrega com o respetivo código de desbloqueio, fechar o aluguer com a sua liquidação ou cancelá-lo. O Fleet OS não traz um conector pronto para um PMS concreto: se for a Cityflow a construí-lo, é uma integração à parte, 750 € a standard.

A API do Fleet OS avisa o meu sistema quando um aluguer começa ou termina?

Não: a referência não inclui avisos automáticos (webhooks). O teu sistema consulta o estado com /get_booking ou /get_vehicles_status; se precisares que o Fleet OS avise, orça-se como integração.

Quanto custa o acesso à API do Fleet OS?

Está incluído na mensalidade do Fleet OS: 300 € por mês mais de 8 € a 3 € por veículo, conforme o escalão, e 1.000 € de ativação, sem fidelização. As integrações com hardware ou sistemas que o Fleet OS não traz de origem custam 750 € a standard.

Posso testar a integração sem mexer na minha frota real?

Sim. Desde o primeiro dia tens um sandbox com dados de teste, e as respostas indicam-no no campo meta. A tua equipa valida cada passo antes de o ligar às bicicletas reais.