Agenda não sincroniza com Google Calendar

A integração Google Calendar ↔ Kontato sincroniza nos 2 sentidos: agendamentos da Kontato viram eventos no Google e eventos do Google viram agendamentos na Kontato (com origem google_import, inertes). Quando algo trava, há 4 camadas pra diagnosticar.

Sintomas comuns

Sintoma	Camada provável
"Conectei mas não vejo nada do Google aqui"	Toggle por agenda OFF ou primeira sincronização ainda não rodou
"Eventos da Kontato não aparecem no Google"	Hook de criação não disparou (ver logs `google_sync_log`)
"Sincronizou ontem, hoje parou"	`sync_token` invalidado pelo Google ou webhook expirou
"Reconectei mas não voltou"	Re-mapeamento por agenda necessário
"Vejo eventos errados / duplicados"	Anti-loop falhou, contatar suporte

Diagnóstico em 4 níveis

Nível 1 — Conexão OAuth global

Acesse: Menu lateral → Configurações → Integrações.

Verifique:

Status: ✓ Conectado + email Google visível
Conectado em: data correta

Se aparece ❌ Não conectado: OAuth nunca foi feito ou foi desconectado. Click "Conectar Google Calendar" e autorize.

Nível 2 — Toggle por agenda

Cada agenda Kontato tem toggle individual de sync. OAuth global ativado não basta — precisa habilitar por agenda também.

Acesse: Configurações → Agenda → [selecione agenda].

Seção "Google Calendar":

Toggle "Sincronizar com Google Calendar" = ✅ ON
Calendário mapeado (ex: "Cadeira 1" ou "Kontato — Cadeira 1")
Última sincronização: data recente (não vazia)

Se toggle está OFF: ative. Sistema vai disparar sync inicial (puxa eventos existentes do Google pra Kontato).

Nível 3 — Sync token e webhook

Por baixo, cada agenda guarda 2 estados de sincronização:

google_sync_token — token incremental do Google, identifica último delta consumido
google_webhook_* — channel registrado pra receber push notifications

Quando dão problema:

sync_token invalidado (Google retorna 410): pode acontecer após dias sem sync. Sistema detecta e reseta automaticamente — próximo sync vira full sync (puxa tudo de novo)
Webhook expirou (Google channels duram 7 dias): cron /api/cron/google-renovar-webhooks roda 1x/dia pra renovar. Se a renovação falhar, fallback é o cron polling a cada 10min

Em prática, mesmo se webhook morrer, o cron de polling cobre. Você raramente precisa intervir.

Nível 4 — Forçar sync manual

Se nada apareceu mesmo depois de minutos:

Configurações → Integrações → [Agenda específica] → click "Forçar sincronização agora".

Isso chama POST /api/google/agendas/[id]/sync que executa processarMudancasGoogle(agendaId) imediatamente, sem esperar cron.

Reconexão completa (último recurso)

Quando NADA acima resolveu:

Desconectar global: Configurações → Integrações → Desconectar Google Calendar
- Apaga tokens OAuth + zera google_sync_ativo em todas as agendas
- NÃO apaga dados (eventos no Google + agendamentos na Kontato permanecem)
Reconectar: Conectar Google Calendar → autorizar
Re-mapear cada agenda que estava ativa: toggle ON + escolher calendário Google
Esperar ~10 minutos pra cron processar primeiro sync de cada uma

Logs auditáveis (`google_sync_log`)

Cada operação de sync deixa um registro:

direcao: kontato_to_google ou google_to_kontato
acao: create / update / delete / skip / error
entidade_id, google_event_id
detalhe (motivo do skip ou erro)

Acesso: tabela google_sync_log no Supabase (admin / suporte). Útil pra entender:

"Webhook chegou às 14:32 e processou X eventos"
"Sync skipped porque agenda X com toggle OFF"
"Erro: token OAuth expirado e refresh falhou"

Se você é dono e quer ver logs sem acessar Supabase, ainda não há painel UI público. Abra ticket no suporte da Kira solicitando análise dos logs do seu negócio.

Edge cases reais

Token OAuth expirou

Tokens Google expiram em ~1h. Sistema renova automaticamente via refresh_token. Se o refresh falhar (ex: você revogou acesso direto na sua conta Google):

Sync para
Status mostra "Token inválido" / "Reconectar necessário"
Solução: reconectar OAuth do zero (passo da seção anterior)

Eventos do Google não aparecem na Kontato

Cenário: você cria evento direto no Google Calendar mapeado e ele não aparece em /agenda da Kontato.

Causas comuns:

Sync ainda não rodou (cron a cada 10min, webhook pode ter ~30s de delay)
Evento criado em calendário diferente do que está mapeado pra agenda Kontato
Toggle de sync da agenda está OFF
Evento all-day: aparece como bloqueio dia inteiro (00:00–23:59)
Evento recorrente: importa instâncias dos próximos 60 dias

Forçar sync manual resolve.

Eventos da Kontato não vão pro Google

Cenário inverso: você cria agendamento na Kontato e ele não aparece no Google Calendar.

Causas comuns:

Toggle de sync da agenda OFF (não vai pra Google)
Calendário Google mapeado foi deletado direto no Google → re-mapear
Hook de sync falhou (ver google_sync_log filtrando acao=error)
Anti-loop: agendamento origem='google_import' na criação NÃO sobe pro Google (já é evento do Google originalmente)

Eventos do Google ficam "inertes" na Kontato

Por design (RN futura): eventos importados do Google viram agendamentos com origem='google_import' que não disparam automações da Kontato:

Sem notificação D-1
Sem cobrança automática
Sem confirmação WhatsApp
Sem entrada no funil de fidelidade
Botões "Compareceu/Faltou" ocultos
Cliente_id NULL (não vincula ao CRM)

Card aparece cinza neutro na grade /agenda com badge "G" (ícone Google).

Comportamento esperado, não é bug.

Conflito de horário

Se você tem agendamento Kontato 14:00–15:00 e cria evento Google no mesmo slot:

Sistema permite overlap (não bloqueia)
UI marca visualmente "⚠ Conflito de horário"
Resolva manualmente (mover um dos 2)

Editar evento que veio do Google

Mudar data/hora na Kontato: sincroniza de volta pro Google ✅
Mudar título/descrição na Kontato: NÃO sobe (decisão de design — edite no Google)
Excluir na Kontato: deleta evento no Google ✅
Mudar no Google: sincroniza de volta pro Kontato ✅ (mantém origem google_import)

Ainda travado?

Se passou pelos 4 níveis + reconectou e ainda não funciona:

Anote o ID da agenda afetada (URL /configuracoes/agenda/[id])
Anote o sintoma exato e quando começou
Abre ticket pelo botão "?" (Kira) com essas infos
Suporte consulta google_sync_log direto e encontra o erro

Próximos artigos

Visão geral do troubleshooting — outros sintomas
Bot não agenda — agenda Kontato com problema (não Google)
Cobrança não confirma — outro caso de webhook