Integrações: Google, BulkGate, Cloudflare e CSV

O FIRO suporta autenticação Google em quatro contextos distintos, cada um com o seu controlador dedicado:

• User (gestor de tenant) — login no backoffice via GoogleUserAuthController.
• Staff (profissional) — login no painel de staff via fluxo OAuth com selecção de tenant.
• Customer (cliente final) — login no portal /minha-conta via GoogleCustomerAuthController.
• Platform Admin — fluxo restrito para administradores da plataforma.

Em todos os casos, o login Google é alternativo ao magic link — o utilizador escolhe o que prefere. Não há password em nenhum fluxo.

Cada profissional pode ligar a sua conta Google Calendar. O sync funciona nos dois sentidos:

FIRO → Google

Cada marcação criada/alterada gera ou actualiza um evento no Calendar. O profissional vê tudo numa só agenda.

Google → FIRO

Eventos criados manualmente no Calendar bloqueiam disponibilidade nos slots públicos do FIRO. Tentativa de criar marcação a partir de eventos relevantes.

Detalhe técnico

• Tokens OAuth (refresh_token, access_token) cifrados na base via protected $casts = ['... ' => 'encrypted'].
• Conector em GoogleCalendarOAuthController; despachante de sync em GoogleCalendarSyncDispatcher.
• Eventos rastreados via BookingItemGoogleCalendarEvent.
• Feature controlada por plano: external_calendar_sync (Pro+).

A localização do tenant aparece em mapa interactivo na página pública usando Google Maps. A API key é gerida centralmente pela administração da plataforma e os tenants beneficiam dela sem terem de pedir conta Google própria.

• Latitude/longitude guardadas no tenant.
• Marcador na localização exacta.
• Link directo para abrir no Google Maps do telemóvel.

O canal SMS usa BulkGate, provedor europeu profissional. O FIRO abstrai a integração — o tenant só configura template e antecedência.

• Credenciais centralizadas (gestão pela administração da plataforma).
• Endpoint de envio via BulkGateSmsService.
• Faturação mensal por tenant ligada ao limite mensal definido.
• Test send disponível para validação antes de produção.

Confirmações de entrega são tratadas quando suportadas pela API e ficam em NotificationLog.

Domínios personalizados são gerenciados via Cloudflare SaaS. O fluxo é:

1. Tenant aponta CNAME do seu domínio para o destino do FIRO.
2. O FIRO chama a API Cloudflare para registar o hostname.
3. Cloudflare emite o certificado SSL automaticamente.
4. Estado é trackeado em cloudflare_hostname_id e cloudflare_ssl_status.

Renovação do SSL é automática para sempre. O tenant não precisa de ferramentas como Let's Encrypt nem de tocar em servidores.

Para tenants que migram de outras ferramentas:

Importação

• CsvImportService + UI dedicada (ContactImportController).
• Mapeamento de colunas configurável no upload.
• Cada lote regista origem em CsvSource.

Exportação

• CsvExportService para clientes, marcações, transações.
• Útil para análise externa ou migração de saída (sem lock-in).

O envio de emails usa Gmail SMTP através de GmailMailer. As credenciais são geridas centralmente. O tenant não tem de configurar SMTP próprio nem manter servidor de email.

• Compatível com HTML rico.
• Templates renderizados por EmailTemplateRenderer.
• Logs em NotificationLog.

Custom SMTP por tenant (envio com domínio próprio) está no roadmap.

API pública aberta a integradores externos está prevista no plano Business e está no roadmap de implementação. Hoje, integrações fora do scope listado acima exigem desenvolvimento à medida via contacto comercial.

Webhooks para eventos (marcação criada, confirmada, cancelada) também estão no roadmap. Casos de uso típico: integração com Zapier, ferramentas de marketing, ERPs.