Pular para o conteúdo principal

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​

  1. Criar/abrir um projeto e ativar a Google Calendar API.

  2. 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.events
    • https://www.googleapis.com/auth/userinfo.email
    • openid
  3. Em Credenciais → Criar credenciais → ID de cliente OAuth, tipo Aplicação Web.

  4. Em URIs de redirecionamento autorizados, registar exatamente:

    <APP_URL>/backend/api/comercial/google-agenda-callback.php

    Exemplos: 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çãoEfeito
Conectar Google AgendaInicia o consentimento OAuth e guarda o token do colaborador
Sincronizar novas visitasLiga/desliga o envio automático de cada visita agendada
Mostrar eventos do GoogleSobrepõe os eventos do calendário no mês e no painel do dia
Sincronizar agoraEnvia para o Google as visitas passadas que ainda não têm evento
DesconectarRevoga o token no Google e apaga a ligação local

4. Peças de código​

FicheiroPapel
backend/config/google_calendar.phpLeitura das variáveis de ambiente
backend/src/integrations/google-calendar/GoogleCalendarService.phpOAuth + CRUD de eventos
backend/src/integrations/google-calendar/calendar_storage.phpSchema, tokens e sincronização das visitas
backend/api/comercial/google-agenda.phpAPI JSON (status, connect, events, sync, toggle, disconnect)
backend/api/comercial/google-agenda-callback.phpRedirect URI do OAuth
assets/js/pages/comercial/agenda-visitas.jsUI 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_at e last_error por user_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_error e no api_log.
  • O refresh_token só é devolvido pelo Google no primeiro consentimento — por isso o fluxo usa prompt=consent e 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.