Pular para o conteúdo principal

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​

  1. Habilite a Google Calendar API no projeto.

  2. Em APIs e serviços → Credenciais, crie um ID do cliente OAuth do tipo Aplicativo da Web.

  3. Em URIs de redirecionamento autorizados, registre exatamente:

    {APP_URL}/backend/api/comercial/google-agenda-callback.php

    Ex.: https://portal.gevtech.com.br/backend/api/comercial/google-agenda-callback.php.

  4. Na Tela de consentimento OAuth, declare os escopos:

    • https://www.googleapis.com/auth/calendar.events
    • https://www.googleapis.com/auth/calendar.readonly
  5. 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ávelObrigatóriaPapel
GOOGLE_CALENDAR_CLIENT_IDsimID do cliente OAuth
GOOGLE_CALENDAR_CLIENT_SECRETsimSegredo do cliente OAuth
GOOGLE_CALENDAR_REDIRECT_URInãoForça o URI de retorno (proxy/subpasta). Por padrão é derivado da URL da requisição, com fallback em APP_URL
GOOGLE_CALENDAR_TOKEN_KEYnãoChave dedicada para cifrar os tokens no banco. Sem ela a chave é derivada do client secret
APP_TIMEZONEnãoFuso dos eventos criados. Default America/Sao_Paulo

Estrutura​

ArquivoPapel
backend/src/integrations/google-calendar/GoogleCalendarService.phpClient OAuth + Calendar v3 (auth URL, troca/refresh de token, upsert/delete/list de eventos)
backend/src/integrations/google-calendar/google_calendar.phpHelpers procedurais: schema, guarda de tokens cifrados, status, push de visita
backend/api/comercial/google-agenda.phpstatus, auth_url, events, calendars (GET); disconnect, sync, toggle, calendar (POST)
backend/api/comercial/google-agenda-callback.phpRetorno do consentimento; avisa a janela mãe via postMessage e fecha o popup
backend/src/services/comercial/leads_service.phpbackend_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 coluna last_error da 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.