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.
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
Use Listar eventos, Criar evento e Apagar evento.
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
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
Dentro de
data vem uma lista de { id, name, primary, canWrite, timeZone }, com até 100 calendários.
Listar eventos
recurringEventId aponta a série) e os cancelados ficam de fora.
Janela e datas
- A janela traz os eventos que terminam depois de
timeMine começam antes detimeMax. - Formatos aceitos em
timeMinetimeMax:AAAA-MM-DD;AAAA-MM-DDTHH:mm:ss(espaço no lugar doT; segundos e milissegundos opcionais), com fuso opcionalZ,±HH:MMou±HHmm; eDD/MM/AAAAcom hora opcionalHH:mmouHH:mm:ss. Com barra é sempre dia/mês/ano. - Sem fuso, a hora vale no
timeZone. timeMinsó com a data = 00:00 do dia;timeMaxsó com a data inclui o dia inteiro.- Na URL, mande o fuso positivo como
%2B(ex.:%2B03:00) ou useZ, e o#docalendarIdcomo%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 }, comattendees=[{ email, responseStatus, optional }].pagination:{ limit, nextPageToken, hasMore, timeMin, timeMax, timeZone }, com os valores de fato usados.
Paginação
ComhasMore: 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
Texto vazio vale como campo ausente.
Datas de start e end
- Formatos:
AAAA-MM-DD;AAAA-MM-DDTHH:mm:ss(espaço no lugar doT; segundos e milissegundos opcionais), com fuso opcionalZ,±HH:MMou±HHmm; eDD/MM/AAAAcom hora opcionalHH:mmouHH: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. Oendtem de ser depois dostart. - Só a data nos dois = evento de dia inteiro, e o
endé o último dia do evento, inclusivo:startigual aend= evento de 1 dia (2026-11-03a2026-11-05= 3 dias). - Misturar data com e sem hora responde 400
ERR_INVALID_FIELDcomfieldend.
Convidados e Meet
- Com
sendUpdates: none, convidado de fora do Google pode não receber o evento no calendário dele. createMeetLink: truedevolvemeetLinkna resposta.meetStatuspending= o link ainda está sendo gerado;failure= o Google não criou a sala, e o evento fica criado semmeetLink.
Proteção contra duplicar (requestId)
- Repetir o mesmo pedido (mesmo
summary,starteend) com o mesmorequestIddevolve o evento já criado comreplayed: true, sem criar outro. - O mesmo
requestIdcom outro conteúdo responde 409ERR_GOOGLE_EVENT_REQUEST_ID_USED. Use umrequestIdnovo para cada evento (ex.: o id do pedido no seu sistema). - Enquanto um pedido com esse
requestIdestá em andamento, outro igual responde 409ERR_GOOGLE_EVENT_REQUEST_IN_PROGRESS. Depois de um 424ERR_GOOGLE_EVENT_CREATE_UNCONFIRMED, espere 1 minuto e repita o mesmo pedido. - Use sempre o mesmo
calendarIdcom o mesmorequestId:primarye o id do calendário principal contam como calendários diferentes. - Se o evento criado com esse
requestIdfoi apagado, a rota responde 409ERR_GOOGLE_EVENT_REQUEST_ID_USEDaté o Google expurgar o evento apagado. Depois disso, orequestIdvolta a ser aceito e cria um evento novo.
Resposta
Dentro dedata, o evento, com os mesmos campos de Listar eventos, mais replayed e meetStatus (null sem Meet).
Erros
Apagar evento
Regras:
- Evento já apagado responde 200 com
alreadyDeleted: trueenquanto o Google guarda o registro do apagado. Depois que o Google o expurga, a resposta é 404ERR_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.
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).

