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
-
Crie ou selecione um projeto.
-
APIs e serviços → Biblioteca: ative a Google Calendar API.
-
Tela de permissão OAuth: configure o app e adicione os escopos
.../auth/calendar.eventse.../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. -
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.phpO 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
agendadado 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
| Arquivo | Papel |
|---|---|
backend/config/google_calendar.php | Client ID/secret, redirect, escopos, fuso |
backend/src/integrations/google-calendar/GoogleCalendarService.php | Cliente OAuth + CRUD de eventos (não toca no banco) |
backend/src/services/comercial/google_calendar_service.php | Schema, tokens, regras de sincronização |
backend/api/comercial/google-calendar.php | API JSON (status e ações) |
backend/api/comercial/google-calendar-callback.php | Callback OAuth (responde com redirect) |
database/migrations/20260919_google_calendar_oauth.php | Migração |
6. Erros comuns
| Sintoma | Causa provável |
|---|---|
redirect_uri_mismatch | O 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 |