> ## Documentation Index
> Fetch the complete documentation index at: https://ajuda.pandazap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API do Google Agenda: consulte calendários e crie eventos

> Liste as contas e os calendários do Google Agenda conectados no painel, consulte eventos por período e crie ou apague eventos pela API do PanÐá Zap.

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](https://ajuda.pandazap.com/api/overview.md#url-base) da API: `https://{BaseUrl}/v2/api/external/{ApiID}/googleCalendar/...`.

> [!NOTE]
>
> **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.

> [!WARNING]
>
> **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](https://ajuda.pandazap.com/platform/integracoes-externas.md).

**2. Pegue o accountId**

[Listar contas](#listar-contas) devolve o `id` de cada conta conectada: é o `accountId` de todas as outras rotas.

**3. Escolha o calendário**

[Listar calendários](#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](#listar-eventos), [Criar evento](#criar-evento) e [Apagar evento](#apagar-evento).

## Rotas

| Ação | Método e caminho |
| - | - |
| [Listar contas](#listar-contas) | `GET /googleCalendar/account/list` |
| [Listar calendários](#listar-calendários) | `GET /googleCalendar/calendar/list` |
| [Listar eventos](#listar-eventos) | `GET /googleCalendar/event/list` |
| [Criar evento](#criar-evento) | `POST /googleCalendar/event/create` |
| [Apagar evento](#apagar-evento) | `POST /googleCalendar/event/delete/{eventId}` |

## Erros comuns a todas as rotas

| Código | Quando acontece |
| - | - |
| `402` `ERR_FEATURE_NOT_IN_PLAN` | O plano da empresa não tem Google Agenda. |
| `402` `ERR_TENANT_PAYMENT_BLOCKED` | Empresa bloqueada por pagamento. |
| `403` `ERR_SESSION_NOT_AUTH_TOKEN` | O token é de outra sessão da API. |
| `404` `ERR_API_CONFIG_NOT_FOUND` | O `ApiID` da URL não existe nesta empresa. |
| `429` `ERR_RATE_LIMITED` | Passou do limite por minuto. A resposta traz `retryAfterSeconds` e o cabeçalho `Retry-After`. |
| `500` `ERR_GOOGLE_CALENDAR_API` | Falha inesperada no servidor. |

### Erros das rotas que consultam o Google

Valem para [Listar calendários](#listar-calendários), [Listar eventos](#listar-eventos), [Criar evento](#criar-evento) e [Apagar evento](#apagar-evento):

| Código | Quando acontece |
| - | - |
| `400` `ERR_GOOGLE_CALENDAR_INVALID_REQUEST` | O Google recusou o pedido. |
| `404` `ERR_GOOGLE_CALENDAR_CONFIG_NOT_FOUND` | `accountId` inexistente nesta empresa. |
| `409` `ERR_GOOGLE_CALENDAR_NOT_CONNECTED` | A conta não concluiu a autorização do Google: conecte-a no painel. |
| `424` `ERR_GOOGLE_AUTH_REVOKED` e `ERR_GOOGLE_AUTH_EXPIRED` | Acesso ao Google revogado ou vencido: reconecte a conta no painel. |
| `424` `ERR_NO_GOOGLE_APP_CONFIGURED` e `ERR_PLATFORM_GOOGLE_APP_DISABLED` | Aplicativo do Google não configurado ou desativado no servidor. |
| `424` `ERR_GOOGLE_CALENDAR_RATE_LIMITED` | Cota do Google esgotada no momento. |

***

## Listar contas

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/googleCalendar/account/list
```

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.

| Campo | Significado |
| - | - |
| `connected` | `false` = a autorização do Google não foi concluída: conecte a conta no painel antes de usar. |
| `authExpired` | `true` = o acesso foi revogado ou venceu: reconecte no painel. |

Conta inativa também aparece e pode ser usada. Esta rota só tem os [erros comuns](#erros-comuns-a-todas-as-rotas).

***

## Listar calendários

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/googleCalendar/calendar/list?accountId=1
```

Lista os calendários de uma conta do Google Agenda conectada no painel. Consulta o Google na hora.

| Query param | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `accountId` | number | Sim | ID da conta (veja [Listar contas](#listar-contas)). |

Dentro de `data` vem uma lista de `{ id, name, primary, canWrite, timeZone }`, com até 100 calendários.

| Campo | Significado |
| - | - |
| `id` | É o `calendarId` das rotas de eventos. O calendário principal da conta também atende por `primary`. |
| `canWrite` | `true` = a conta pode criar e apagar eventos nele (dono ou editor). |
| `timeZone` | Fuso do calendário. |

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` | Com `fields`: sem `accountId`. |
| `404` `ERR_GOOGLE_CALENDAR_NOT_FOUND` | Também pode aparecer nesta rota. |
| `422` `ERR_GOOGLE_CALENDAR_PERMISSION` | O Google negou o acesso a essa conta. |
| `424` `ERR_GOOGLE_CALENDAR_UNAVAILABLE` | O Google não respondeu, falhou ou passou de 15 s. Pode tentar de novo. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas) e os [das rotas que consultam o Google](#erros-das-rotas-que-consultam-o-google). |

***

## Listar eventos

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/googleCalendar/event/list?accountId=1&calendarId=primary&timeMin=2026-11-03&timeMax=2026-11-05
```

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.

| Query param | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `accountId` | number | Sim | ID da conta (veja [Listar contas](#listar-contas)). |
| `calendarId` | string | Não | ID do calendário (veja [Listar calendários](#listar-calendários)). Padrão `primary` = calendário principal da conta. |
| `timeMin` | string | Não | Início da janela (ex.: `2026-11-03`, `2026-11-03T08:00:00` ou `03/11/2026 08:00`). Padrão = agora. |
| `timeMax` | string | Não | Fim da janela, nos mesmos formatos. Padrão = `timeMin` + 30 dias. Janela de até 366 dias. |
| `timeZone` | string | Não | Fuso IANA das datas sem fuso. Padrão `America/Sao_Paulo`. |
| `limit` | number | Não | Eventos por página, de 1 a 250. Padrão 50. |
| `pageToken` | string | Não | `nextPageToken` da página anterior (veja **Paginação**, abaixo). |

### 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.

| Situação | Como vem |
| - | - |
| Evento com horário | `start` e `end` como o Google devolve, com fuso (ex.: `2026-11-03T14:00:00-03:00`). |
| Evento de dia inteiro (`allDay: true`) | `start` e `end` em `AAAA-MM-DD`; `end` é o último dia do evento, inclusivo (evento de 1 dia tem `start` igual a `end`). |
| Campo sem valor | `summary`, `description`, `location`, `timeZone`, `meetLink` e `recurringEventId` vêm `null`. |
| `transparency` | `opaque` = ocupa o horário; `transparent` = livre. |

### 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

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` | Com `fields`: sem `accountId`. |
| `400` `ERR_INVALID_FIELD` | Com `field`: `calendarId`, `timeMin`, `timeMax`, `limit` ou `pageToken` fora do formato. |
| `400` `ERR_INVALID_TIMEZONE` | `timeZone` que não é um fuso IANA. |
| `400` `ERR_INVALID_TIME_RANGE` | `timeMax` não posterior a `timeMin`, ou janela maior que 366 dias. |
| `400` `ERR_GOOGLE_CALENDAR_INVALID_REQUEST` | O Google recusou o pedido (ex.: `pageToken` inválido). |
| `404` `ERR_GOOGLE_CALENDAR_NOT_FOUND` | `calendarId` inexistente ou sem acesso para a conta. |
| `422` `ERR_GOOGLE_CALENDAR_PERMISSION` | O Google negou o acesso ao calendário. |
| `424` `ERR_GOOGLE_CALENDAR_UNAVAILABLE` | O Google não respondeu, falhou ou passou de 15 s. Pode tentar de novo. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas) e os [das rotas que consultam o Google](#erros-das-rotas-que-consultam-o-google). |

***

## Criar evento

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/googleCalendar/event/create
```

```json theme={null}
{
  "accountId": 1,
  "calendarId": "primary",
  "summary": "Consulta com Maria Souza",
  "description": "Primeira consulta",
  "location": "Av. Paulista, 1000 - São Paulo",
  "start": "2026-11-03T14:00:00",
  "end": "2026-11-03T15:00:00",
  "timeZone": "America/Sao_Paulo",
  "attendees": ["cliente@exemplo.com"],
  "sendUpdates": "none",
  "createMeetLink": true,
  "requestId": "troque-por-um-id-unico-por-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.

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `accountId` | number | Sim | ID da conta (veja [Listar contas](#listar-contas)). |
| `calendarId` | string | Não | ID do calendário (veja [Listar calendários](#listar-calendários)). Padrão `primary`. |
| `summary` | string | Sim | Título, até 1024 caracteres. |
| `description` | string | Não | Até 8192 caracteres. |
| `location` | string | Não | Até 1024 caracteres. |
| `start` | string | Sim | Início (formatos abaixo). |
| `end` | string | Sim | Fim (formatos abaixo). |
| `timeZone` | string | Não | Fuso IANA. Padrão `America/Sao_Paulo`. |
| `attendees` | lista | Não | Lista de até 100 e-mails. |
| `sendUpdates` | string | Não | `none` (padrão: o Google não avisa os convidados), `all` (avisa todos por e-mail) ou `externalOnly` (avisa só quem não usa Google Agenda). |
| `createMeetLink` | boolean | Não | `true` cria um link do Google Meet. |
| `requestId` | string | Não | De 1 a 200 caracteres. Protege contra duplicar (regras abaixo). |

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.

> [!WARNING]
>
> **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](#listar-eventos) antes de repetir.

### Resposta

Dentro de `data`, o evento, com os mesmos campos de [Listar eventos](#listar-eventos), mais `replayed` e `meetStatus` (`null` sem Meet).

### Erros

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` | Com `fields`. |
| `400` `ERR_INVALID_FIELD` | Com `field`: data fora dos formatos, mistura de data com e sem hora, texto acima do limite, `attendees` fora do formato, `sendUpdates` fora da lista, `createMeetLink` que não é `true` nem `false`, `requestId` acima de 200 caracteres ou `calendarId` inválido. |
| `400` `ERR_INVALID_TIMEZONE` | `timeZone` que não é um fuso IANA. |
| `400` `ERR_END_BEFORE_START` | `end` não é depois de `start` (no dia inteiro, `end` anterior a `start`). |
| `404` `ERR_GOOGLE_CALENDAR_NOT_FOUND` | `calendarId` inexistente ou sem acesso para a conta. |
| `409` `ERR_GOOGLE_EVENT_REQUEST_ID_USED` | `requestId` de evento apagado ou reaproveitado com outro conteúdo. |
| `409` `ERR_GOOGLE_EVENT_REQUEST_IN_PROGRESS` | Outro pedido com o mesmo `requestId` em andamento; até 1 minuto depois de um 424 sem confirmação. |
| `422` `ERR_GOOGLE_CALENDAR_PERMISSION` | Sem permissão para criar nesse calendário (ex.: calendário só de leitura). |
| `424` `ERR_GOOGLE_EVENT_CREATE_UNCONFIRMED` | O Google não respondeu, falhou ou passou de 15 s e não deu para confirmar a criação. |
| `424` `ERR_GOOGLE_CALENDAR_UNAVAILABLE` | O Google falhou ao conferir o evento de um `requestId` repetido. Pode tentar de novo. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas) e os [das rotas que consultam o Google](#erros-das-rotas-que-consultam-o-google). |

***

## Apagar evento

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/googleCalendar/event/delete/{eventId}
```

```json theme={null}
{
  "accountId": 1,
  "calendarId": "primary",
  "sendUpdates": "none"
}
```

Apaga um evento de um calendário do Google Agenda.

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `eventId` (caminho) | string | Sim | ID do evento devolvido por [Listar eventos](#listar-eventos) ou por [Criar evento](#criar-evento). |
| `accountId` (body) | number | Sim | ID da conta (veja [Listar contas](#listar-contas)). |
| `calendarId` (body) | string | Não | Padrão `primary`. Tem de ser o calendário em que o evento está. |
| `sendUpdates` (body) | string | Não | Quem o Google avisa do cancelamento: `none` (padrão), `all` ou `externalOnly`. Com `none`, convidado de fora do Google pode continuar com o evento no calendário dele. |

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).

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` | Com `fields`: sem `accountId`. |
| `400` `ERR_INVALID_FIELD` | Com `field`: `calendarId` ou `sendUpdates` fora do formato. |
| `404` `ERR_GOOGLE_CALENDAR_EVENT_NOT_FOUND` | Evento inexistente nesse calendário, `calendarId` errado ou `eventId` fora do formato. |
| `422` `ERR_GOOGLE_CALENDAR_PERMISSION` | Sem permissão para apagar nesse calendário. |
| `424` `ERR_GOOGLE_CALENDAR_UNAVAILABLE` | O Google não respondeu, falhou ou passou de 15 s. Pode tentar de novo. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas) e os [das rotas que consultam o Google](#erros-das-rotas-que-consultam-o-google). |

> [!TIP]
>
> Para conectar contas Google e ver os eventos pela tela, veja [Integrações externas](https://ajuda.pandazap.com/platform/integracoes-externas.md) e [Eventos do Google Calendar](https://ajuda.pandazap.com/platform/comunicacao-marketing.md#eventos-do-google-calendar).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.