Pular para o conteúdo principal
Estas rotas usam as contas do Google Agenda que a sua empresa já conectou no painel do PanÐá Zap, em Configurações → Integrações → Google Calendar. Com elas, um sistema externo consulta os calendários, lista os eventos de um período e cria ou apaga eventos (com convidados e link do Google Meet), sem lidar com o acesso ao Google. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}. Os endereços seguem a URL base da API: https://{BaseUrl}/v2/api/external/{ApiID}/googleCalendar/....
Sem token do Google: nenhuma rota do Google Agenda recebe token do Google. O servidor usa a conta já conectada no painel, e as respostas nunca trazem token nem chave do Google. Por isso, a conta precisa estar conectada no painel antes do uso: nas rotas que consultam o Google, conta que não concluiu a autorização (409) ou com o acesso revogado ou vencido (424) é recusada até ser conectada de novo no painel.
Limite de chamadas: 120 chamadas por minuto por empresa, somando as 5 rotas do Google Agenda. Acima disso, a rota responde 429 ERR_RATE_LIMITED. A resposta traz retryAfterSeconds e o cabeçalho Retry-After, com os segundos de espera.

Antes de começar

1

Conecte a conta no painel

Em Configurações → Integrações → Google Calendar, conecte a conta Google da empresa. O passo a passo está em Integrações externas.
2

Pegue o accountId

Listar contas devolve o id de cada conta conectada: é o accountId de todas as outras rotas.
3

Escolha o calendário

Listar calendários devolve o id de cada calendário da conta: é o calendarId das rotas de eventos. Sem calendarId, vale primary, o calendário principal da conta.
4

Trabalhe com os eventos

Rotas

Erros comuns a todas as rotas

Erros das rotas que consultam o Google

Valem para Listar calendários, Listar eventos, Criar evento e Apagar evento:

Listar contas

Lista as contas do Google Agenda conectadas no painel da empresa. O id de cada conta é o accountId das outras rotas. Esta rota lê só os dados do PanÐá Zap, sem consultar o Google. Dentro de data vem uma lista de { id, name, isActive, isDefault, connected, authExpired }, com a conta padrão primeiro. Conta inativa também aparece e pode ser usada. Esta rota só tem os erros comuns.

Listar calendários

Lista os calendários de uma conta do Google Agenda conectada no painel. Consulta o Google na hora. Dentro de data vem uma lista de { id, name, primary, canWrite, timeZone }, com até 100 calendários.

Listar eventos

Lista os eventos de um calendário numa janela de tempo, em ordem de início. Eventos recorrentes vêm abertos em ocorrências (recurringEventId aponta a série) e os cancelados ficam de fora.

Janela e datas

  • A janela traz os eventos que terminam depois de timeMin e começam antes de timeMax.
  • Formatos aceitos em timeMin e timeMax: AAAA-MM-DD; AAAA-MM-DDTHH:mm:ss (espaço no lugar do T; segundos e milissegundos opcionais), com fuso opcional Z, ±HH:MM ou ±HHmm; e DD/MM/AAAA com hora opcional HH:mm ou HH:mm:ss. Com barra é sempre dia/mês/ano.
  • Sem fuso, a hora vale no timeZone.
  • timeMin só com a data = 00:00 do dia; timeMax só com a data inclui o dia inteiro.
  • Na URL, mande o fuso positivo como %2B (ex.: %2B03:00) ou use Z, e o # do calendarId como %23 (ex.: calendários de feriados).

Resposta

  • data: lista de eventos { id, calendarId, summary, description, location, allDay, start, end, timeZone, status, eventType, transparency, htmlLink, meetLink, attendees, recurringEventId, created, updated }, com attendees = [{ email, responseStatus, optional }].
  • pagination: { limit, nextPageToken, hasMore, timeMin, timeMax, timeZone }, com os valores de fato usados.

Paginação

Com hasMore: true, chame de novo com pageToken = nextPageToken e os mesmos timeMin, timeMax e timeZone devolvidos em pagination. Sem eles, o padrão “agora” mudaria a janela entre as páginas.

Erros


Criar evento

Cria um evento num calendário de uma conta do Google Agenda conectada no painel. O evento usa os lembretes padrão do calendário e não cria registro em Agendamentos do PanÐá Zap. Texto vazio vale como campo ausente.

Datas de start e end

  • Formatos: AAAA-MM-DD; AAAA-MM-DDTHH:mm:ss (espaço no lugar do T; segundos e milissegundos opcionais), com fuso opcional Z, ±HH:MM ou ±HHmm; e DD/MM/AAAA com hora opcional HH:mm ou HH:mm:ss. Com barra é sempre dia/mês/ano.
  • Com hora nos dois = evento com horário. Sem fuso, a hora vale no timeZone; com fuso, vale como veio. O end tem de ser depois do start.
  • Só a data nos dois = evento de dia inteiro, e o end é o último dia do evento, inclusivo: start igual a end = evento de 1 dia (2026-11-03 a 2026-11-05 = 3 dias).
  • Misturar data com e sem hora responde 400 ERR_INVALID_FIELD com field end.

Convidados e Meet

  • Com sendUpdates: none, convidado de fora do Google pode não receber o evento no calendário dele.
  • createMeetLink: true devolve meetLink na resposta. meetStatus pending = o link ainda está sendo gerado; failure = o Google não criou a sala, e o evento fica criado sem meetLink.

Proteção contra duplicar (requestId)

  • Repetir o mesmo pedido (mesmo summary, start e end) com o mesmo requestId devolve o evento já criado com replayed: true, sem criar outro.
  • O mesmo requestId com outro conteúdo responde 409 ERR_GOOGLE_EVENT_REQUEST_ID_USED. Use um requestId novo para cada evento (ex.: o id do pedido no seu sistema).
  • Enquanto um pedido com esse requestId está em andamento, outro igual responde 409 ERR_GOOGLE_EVENT_REQUEST_IN_PROGRESS. Depois de um 424 ERR_GOOGLE_EVENT_CREATE_UNCONFIRMED, espere 1 minuto e repita o mesmo pedido.
  • Use sempre o mesmo calendarId com o mesmo requestId: primary e o id do calendário principal contam como calendários diferentes.
  • Se o evento criado com esse requestId foi apagado, a rota responde 409 ERR_GOOGLE_EVENT_REQUEST_ID_USED até o Google expurgar o evento apagado. Depois disso, o requestId volta a ser aceito e cria um evento novo.
Sem requestId, a falha de comunicação responde 424 ERR_GOOGLE_EVENT_CREATE_UNCONFIRMED e o evento pode ter sido criado: confira em Listar eventos antes de repetir.

Resposta

Dentro de data, o evento, com os mesmos campos de Listar eventos, mais replayed e meetStatus (null sem Meet).

Erros


Apagar evento

Apaga um evento de um calendário do Google Agenda. Regras:
  • Evento já apagado responde 200 com alreadyDeleted: true enquanto o Google guarda o registro do apagado. Depois que o Google o expurga, a resposta é 404 ERR_GOOGLE_CALENDAR_EVENT_NOT_FOUND.
  • Se o evento era de um agendamento do sistema (ex.: reserva da página de agendamento), o agendamento continua e só perde o vínculo com o Google Agenda.
Dentro de data vem { eventId, calendarId, alreadyDeleted, appointmentsUnlinked }. O appointmentsUnlinked diz quantos agendamentos foram desvinculados (null = não deu para conferir; o evento foi apagado mesmo assim).
Para conectar contas Google e ver os eventos pela tela, veja Integrações externas e Eventos do Google Calendar.