Pular para o conteúdo principal

Integração Google Agenda (Agenda de Visitas)

Cada colaborador conecta a própria conta Google via OAuth 2.0. As visitas agendadas em /dashboard/comercial/agenda-visitas.php viram eventos no Google Agenda do responsável pela visita (lead_visits.user_id).

A sincronização é de sentido único: CRM → Google. Alterações feitas diretamente no Google Agenda não voltam para o CRM.

1. Google Cloud Console​

  1. Crie ou selecione um projeto.

  2. APIs e serviços → Biblioteca: ative a Google Calendar API.

  3. Tela de permissão OAuth: configure o app e adicione os escopos .../auth/calendar.events e .../auth/userinfo.email. Enquanto o app estiver em Testing, só as contas listadas em "Usuários de teste" conseguem conectar, e o refresh token expira em 7 dias — publique o app antes de usar em produção.

  4. Credenciais → Criar credenciais → ID do cliente OAuth → Aplicativo da Web. Em URIs de redirecionamento autorizados, registre exatamente:

    https://SEU-DOMINIO/backend/api/comercial/google-calendar-callback.php

    O valor precisa bater caractere a caractere com GOOGLE_CALENDAR_REDIRECT_URI. A barra de status na página mostra o redirect em uso quando a integração não está configurada.

2. Variáveis de ambiente​

GOOGLE_CALENDAR_CLIENT_ID=
GOOGLE_CALENDAR_CLIENT_SECRET=
GOOGLE_CALENDAR_REDIRECT_URI=https://SEU-DOMINIO/backend/api/comercial/google-calendar-callback.php
GOOGLE_CALENDAR_TIMEZONE=America/Sao_Paulo
GOOGLE_CALENDAR_TOKEN_KEY=

GOOGLE_CALENDAR_TOKEN_KEY é opcional: quando preenchida, os tokens OAuth são cifrados no banco com AES-256-GCM. Trocar ou perder essa chave invalida os tokens já gravados — todos os usuários precisarão reconectar.

Sem GOOGLE_CALENDAR_REDIRECT_URI, o valor é derivado do host da requisição (útil só em ambiente local).

3. Migração​

php database/migrations/20260919_google_calendar_oauth.php

Cria google_calendar_accounts (uma linha por tenant + usuário) e acrescenta a lead_visits as colunas google_event_id, google_calendar_id, google_html_link, google_synced_at e google_sync_error.

O schema também é criado sob demanda ao abrir a Agenda de Visitas (backend_gcal_ensure_schema), como no resto do módulo Comercial.

4. Uso​

Na Agenda de Visitas, a barra "Google Agenda" mostra o estado da conexão:

  • Conectar Google Agenda → consentimento no Google → volta para a página com ?gcal=conectado.
  • Sincronizar novas visitas → liga/desliga o envio automático sem perder a autorização.
  • Sincronizar pendentes → envia as visitas agendada do operador que ainda não têm evento.
  • Enviar ao Google Agenda (por visita) → envio manual de uma visita.
  • Desconectar → revoga o token no Google e apaga a conta local. Os eventos já criados permanecem no calendário do usuário.

Ao salvar uma visita nova, o envio é automático e não bloqueia o agendamento: se o Google falhar, a visita é gravada e o motivo aparece no toast, no selo do card e em lead_visits.google_sync_error.

Visitas com status = 'cancelada' têm o evento removido do Google na próxima sincronização.

5. Arquivos​

ArquivoPapel
backend/config/google_calendar.phpClient ID/secret, redirect, escopos, fuso
backend/src/integrations/google-calendar/GoogleCalendarService.phpCliente OAuth + CRUD de eventos (não toca no banco)
backend/src/services/comercial/google_calendar_service.phpSchema, tokens, regras de sincronização
backend/api/comercial/google-calendar.phpAPI JSON (status e ações)
backend/api/comercial/google-calendar-callback.phpCallback OAuth (responde com redirect)
database/migrations/20260919_google_calendar_oauth.phpMigração

6. Erros comuns​

SintomaCausa provável
redirect_uri_mismatchO URI registrado no Google difere de GOOGLE_CALENDAR_REDIRECT_URI
"O Google não devolveu refresh_token"Autorização anterior ainda ativa: remova o app em myaccount.google.com/permissions e conecte de novo
"Autorização do Google expirada"Refresh token revogado ou expirado (app em Testing por mais de 7 dias)
"O responsável pela visita ainda não conectou o Google Agenda"A visita é de outro usuário, que precisa conectar a própria conta