Integração Google Agenda — Agenda de Visitas
Conecta o Google Agenda de cada vendedor à página Comercial → Agenda de Visitas
(/dashboard/comercial/agenda-visitas.php).
Diferente do Google Drive — que usa conta de serviço (ver integracao-google-drive.md) — a agenda é
pessoal: cada colaborador autoriza a própria conta por OAuth 2.0 e o portal guarda
o refresh token dele.
O que a integração faz
- Conectar / desconectar a conta Google do usuário logado (popup de consentimento).
- Escolher o calendário de destino entre os calendários graváveis da conta.
- Enviar toda visita nova para o calendário do responsável pela visita, com assunto, contato, empresa, telefone, endereço do lead e lembrete de 30 minutos.
- Sincronizar em lote as visitas futuras (até 180 dias) que ainda não têm evento.
- Mostrar no calendário do portal os demais compromissos do Google no mês visível, para o vendedor ver conflitos antes de agendar.
- Pausar a sincronização sem desconectar a conta.
Sem GOOGLE_CALENDAR_CLIENT_ID/GOOGLE_CALENDAR_CLIENT_SECRET no servidor a barra
da integração não aparece e a página continua funcionando como antes.
Configuração no Google Cloud Console
-
Habilite a Google Calendar API no projeto.
-
Em APIs e serviços → Credenciais, crie um ID do cliente OAuth do tipo Aplicativo da Web.
-
Em URIs de redirecionamento autorizados, registre exatamente:
{APP_URL}/backend/api/comercial/google-agenda-callback.phpEx.:
https://portal.gevtech.com.br/backend/api/comercial/google-agenda-callback.php. -
Na Tela de consentimento OAuth, declare os escopos:
https://www.googleapis.com/auth/calendar.eventshttps://www.googleapis.com/auth/calendar.readonly
-
Enquanto o app estiver em Teste, adicione os e-mails dos vendedores em Usuários de teste — caso contrário o Google recusa o consentimento.
Variáveis de ambiente
| Variável | Obrigatória | Papel |
|---|---|---|
GOOGLE_CALENDAR_CLIENT_ID | sim | ID do cliente OAuth |
GOOGLE_CALENDAR_CLIENT_SECRET | sim | Segredo do cliente OAuth |
GOOGLE_CALENDAR_REDIRECT_URI | não | Força o URI de retorno (proxy/subpasta). Por padrão é derivado da URL da requisição, com fallback em APP_URL |
GOOGLE_CALENDAR_TOKEN_KEY | não | Chave dedicada para cifrar os tokens no banco. Sem ela a chave é derivada do client secret |
APP_TIMEZONE | não | Fuso dos eventos criados. Default America/Sao_Paulo |
Estrutura
| Arquivo | Papel |
|---|---|
backend/src/integrations/google-calendar/GoogleCalendarService.php | Client OAuth + Calendar v3 (auth URL, troca/refresh de token, upsert/delete/list de eventos) |
backend/src/integrations/google-calendar/google_calendar.php | Helpers procedurais: schema, guarda de tokens cifrados, status, push de visita |
backend/api/comercial/google-agenda.php | status, auth_url, events, calendars (GET); disconnect, sync, toggle, calendar (POST) |
backend/api/comercial/google-agenda-callback.php | Retorno do consentimento; avisa a janela mãe via postMessage e fecha o popup |
backend/src/services/comercial/leads_service.php | backend_leads_visit_google_sync() e backend_leads_visits_google_sync_all() |
Banco
backend_gcal_ensure_schema() cria google_calendar_accounts (uma linha por usuário:
e-mail, calendário escolhido, tokens cifrados em AES-256-GCM, validade, flag de
sincronização, último erro).
backend_leads_ensure_schema() adiciona a lead_visits: google_event_id,
google_calendar_id, google_event_link e google_synced_at.
Comportamento e limites
- A permissão exigida é a mesma da página:
leads.visits.manage. - O evento vai para o calendário do responsável pela visita (
user_id), não do operador que agendou. Se esse responsável não conectou a conta, a visita é salva normalmente e nada é enviado. - Falha no Google nunca derruba o agendamento: a visita é gravada, o erro fica no
log (
gcalendar), na colunalast_errorda conta e o front avisa em toast. - O refresh token só chega no primeiro consentimento; ao reconectar, o token anterior é preservado se o Google não mandar um novo.
- Editar ou cancelar uma visita ainda não propaga para o Google — a página atual não
tem esses fluxos.
backend_gcal_delete_visit_event()já existe para quando tiver. - Os eventos do Google exibidos no painel são somente leitura; os que já são espelho de uma visita do portal não aparecem duplicados.