Google Calendar

Quando você cria um evento na Agenda do Syncro (/agenda), pode espelhar automaticamente no seu Google Calendar — e vice-versa: eventos criados no Google aparecem no Syncro. Sincronização bidirecional, ativa por tenant via toggle. Esse artigo cobre setup OAuth, como funciona o sync e troubleshooting.

Pré-requisitos

• Permissão admin.
• Conta Google (Gmail, Google Workspace).
• Calendário principal ou secundário que você queira sincronizar.

Setup — conectar conta Google

1. Vá em Configurações → Integrações.
2. Card Google Calendar com badge Desconectado.
3. Clique em Conectar Google.
4. Modal abre.
5. Clique em Autorizar com Google.
6. Você é redirecionado pro Google OAuth:

• Login (se não logado).
• Tela de consentimento.
• Escopos solicitados:
• openid, email, profile (perfil básico).
• https://www.googleapis.com/auth/calendar (acesso ao calendário).

7. Clique em Permitir.
8. Google redireciona de volta pro Syncro.
9. Sistema:

• Troca o code por access_token (curta duração) + refresh_token (permanente).
• Cria OAuthConnection no banco com platform='google', status 'active'.
• Salva tokens encriptados.

10. Card vira Conectado com seu e-mail Google ao lado.

Ativar sincronização

Após conectar, sync ainda não ativa automaticamente. Você precisa ligar o toggle:

1. Vá em /agenda.
2. Sidebar → card Google Calendar.
3. Toggle Sincronizar eventos (apenas admin/manager pode mexer).
4. Sistema atualiza tenants.settings_json.calendar_google_sync_enabled = true.
5. Sincronização inicia.

Como funciona o sync

Outbound (Syncro → Google)

Quando você cria/atualiza/cancela evento no Syncro:

1. CalendarOrchestrator::createEvent cria evento local.
2. Verifica GoogleCalendarSyncer::shouldSync:

• Tenant tem sync ativa?
• OAuthConnection ativa?
• Evento source='syncro' (não é espelho)?

3. Se sim, dispara job SyncCalendarEventToGoogle:

• tries=3 com backoff [10s, 30s, 120s].
• Idempotente: se evento já existe no Google (google_event_id), faz UPDATE.
• Caso erro persistente, salva em event.google_sync_error.

4. Evento aparece no Google Calendar do dono em ~10s.

Inbound (Google → Syncro)

Cron calendar:pull-google roda a cada 15 minutos:

1. Pra cada tenant com sync ativa:

• Busca eventos do Google dos próximos 60 dias.
• Pra cada evento:
• Existe local com google_event_id igual? → UPDATE (mas só se source='google' — não sobrescreve eventos source='syncro').
• Não existe? → INSERT com source='google'.
• Eventos que sumiram do Google mas existem local (com source='google'): marca status='canceled'.

⚠️ Atenção: sistema não mexe em eventos source='syncro' durante pull (evita loop infinito). Só cuida de eventos importados do Google.

Token de longa duração

OAuth Google usa refresh_token permanente:

• access_token: dura ~1h. Usado pra cada chamada API.
• refresh_token: permanente. Usado pra renovar access_token.

Sistema renova automaticamente quando access_token expira. Cliente não precisa reautorizar a cada hora.

Quando refresh falha

• Cliente revogou acesso em myaccount.google.com.
• Cliente mudou senha Google + 2FA agressivo.
• Conta Google suspensa.

Nesses casos:

1. Sistema marca OAuthConnection.status='revoked'.
2. Card volta pra Reconectar.
3. Cliente clica → reautoriza.
4. Tudo volta a funcionar.

Múltiplos calendários

Conexão é por tenant, não por usuário. O calendário usado é o principal da conta Google conectada.

Pra ter calendários separados (ex: Comercial, Suporte), conecte contas Google diferentes em tenants diferentes.

💡 Dica: o tenant inteiro compartilha 1 calendário Google. Pra dividir por usuário, cada user cria evento assigned_to: si próprio — visualmente filtra na sidebar do Syncro.

Mapeamento de campos

Evento Google → Evento Syncro:

Localização do evento

Sistema preenche location_type:

• none — sem localização.
• physical — endereço físico.
• zoom, google_meet, phone — detectado automaticamente se URL bater (auto-detection).
• custom — qualquer outro link.

Quem vê os eventos sincronizados

• Eventos source='syncro' espelhados no Google: só aparecem no Google do dono (admin que conectou).
• Eventos source='google' puxados pra Syncro: visíveis pra todos do tenant (com filtros normais de visibilidade).

Limitações conhecidas

• Não suporta calendários compartilhados Google (somente o calendário principal).
• Sem suporte a recurring events complexos (séries de eventos podem não espelhar perfeitamente).
• Lembretes (notificações Google) não vêm — Syncro tem próprio sistema de EventReminder.
• Anexos Google Drive: só link textual, sem download.

Privacidade e escopo

Com escopo auth/calendar, Syncro pode:

• ✅ Ler eventos.
• ✅ Criar eventos.
• ✅ Atualizar eventos.
• ✅ Deletar eventos que ele criou (não toca em eventos manuais do user).

Syncro não pode:

• ❌ Acessar Gmail, Drive, Docs, outros serviços Google.
• ❌ Compartilhar dados com terceiros.

Cliente pode revogar a qualquer momento em myaccount.google.com → Apps com acesso à sua conta.

Erros comuns

"Conectei mas eventos não aparecem no Google"

• Verificar toggle de sync ativo em /agenda.
• Verificar tenants.settings_json.calendar_google_sync_enabled=true.
• Aguardar até 15 min pro próximo pull.
• Verificar logs (storage/logs/laravel.log) por erros de sync.

"Status virou Reconectar"

Token expirou ou foi revogado. Clique em Reconectar e reautorize.

"Eventos do Google demoram pra aparecer"

Cron roda a cada 15 min — máximo 14:59 de delay esperado.

"Cancelei evento no Google mas no Syncro continua"

• Esperado se source='syncro' (sistema não cancela espelho de eventos próprios).
• Esperado se cron ainda não rodou.

"Conectei conta errada"

Vá em Desconectar → conecte novamente com a conta certa.

Setup técnico (super_admin)

Variáveis no portainer-stack.yml:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=https://app.syncro.chat/configuracoes/integracoes/google/callback

App Google criado em console.cloud.google.com → APIs & Services → OAuth Consent Screen + Credentials.

Próximos passos

• Pra usar calendário no dia a dia, veja Sincronizar Google Calendar.
• Pra criar eventos via IA, veja Tools do agente.

Artigos relacionados

• Sincronizar Google Calendar
• Agenda interna
• Lembretes de eventos
• Desconectar integração