Google Agenda — Agenda de Visitas
Integração OAuth 2.0 por colaborador: cada utilizador liga a sua própria conta Google
e as visitas agendadas em dashboard/comercial/agenda-visitas.php passam a ser criadas
como eventos no calendário dele. Os eventos do Google também aparecem no painel do dia.
1. Configuração no Google Cloud Console
-
Criar/abrir um projeto e ativar a Google Calendar API.
-
Em APIs e serviços → Ecrã de consentimento OAuth, configurar o ecrã (tipo Interno se todos os colaboradores usam contas do mesmo Workspace, caso contrário Externo) e adicionar os scopes:
https://www.googleapis.com/auth/calendar.eventshttps://www.googleapis.com/auth/userinfo.emailopenid
-
Em Credenciais → Criar credenciais → ID de cliente OAuth, tipo Aplicação Web.
-
Em URIs de redirecionamento autorizados, registar exatamente:
<APP_URL>/backend/api/comercial/google-agenda-callback.phpExemplos:
http://localhost:8080/backend/api/comercial/google-agenda-callback.php,https://app.exemplo.com/backend/api/comercial/google-agenda-callback.php.
2. Variáveis de ambiente (.env)
GOOGLE_CALENDAR_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_CALENDAR_CLIENT_SECRET=GOCSPX-xxxxx
# Opcionais
# GOOGLE_CALENDAR_REDIRECT_URI= # default: APP_URL + caminho do callback
# GOOGLE_CALENDAR_ID=primary # calendário destino
# GOOGLE_CALENDAR_TIMEZONE=America/Sao_Paulo
# GOOGLE_CALENDAR_EVENT_MINUTES=60 # duração do evento da visita
Sem GOOGLE_CALENDAR_CLIENT_ID/GOOGLE_CALENDAR_CLIENT_SECRET a página continua a
funcionar normalmente e a barra da integração informa que está indisponível.
3. Uso
Na Agenda de Visitas, a barra Google Agenda oferece:
| Ação | Efeito |
|---|---|
| Conectar Google Agenda | Inicia o consentimento OAuth e guarda o token do colaborador |
| Sincronizar novas visitas | Liga/desliga o envio automático de cada visita agendada |
| Mostrar eventos do Google | Sobrepõe os eventos do calendário no mês e no painel do dia |
| Sincronizar agora | Envia para o Google as visitas passadas que ainda não têm evento |
| Desconectar | Revoga o token no Google e apaga a ligação local |
4. Peças de código
| Ficheiro | Papel |
|---|---|
backend/config/google_calendar.php | Leitura das variáveis de ambiente |
backend/src/integrations/google-calendar/GoogleCalendarService.php | OAuth + CRUD de eventos |
backend/src/integrations/google-calendar/calendar_storage.php | Schema, tokens e sincronização das visitas |
backend/api/comercial/google-agenda.php | API JSON (status, connect, events, sync, toggle, disconnect) |
backend/api/comercial/google-agenda-callback.php | Redirect URI do OAuth |
assets/js/pages/comercial/agenda-visitas.js | UI da barra e sobreposição dos eventos |
5. Base de dados
Criado automaticamente no primeiro pedido (backend_google_calendar_ensure_schema):
- Tabela
user_google_calendar_accounts— token OAuth, e-mail, calendário,sync_enabled,last_sync_atelast_errorporuser_id(único). - Colunas novas em
lead_visits—google_event_id,google_calendar_id,google_event_link,google_synced_at.
6. Notas
- A criação do evento é best-effort: uma falha no Google nunca impede o agendamento da
visita; o erro fica em
user_google_calendar_accounts.last_errore noapi_log. - O
refresh_tokensó é devolvido pelo Google no primeiro consentimento — por isso o fluxo usaprompt=consente o token antigo é preservado nas renovações. - Tokens nunca são escritos nos logs (filtro em
calendar_log.php). - A permissão exigida é a mesma da página:
leads.visits.manage.