> ## 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 de CRM: Funis, Oportunidades e Agendamentos

> Gerencie todo o seu fluxo de vendas no PanÐá Zap — crie funis, acompanhe oportunidades, agende compromissos e automatize lembretes via API.

A API de CRM do PanÐá Zap permite construir e gerenciar todo o seu fluxo de vendas de forma programática — desde a criação de estruturas de pipeline e o acompanhamento de oportunidades até o agendamento de compromissos e a automação de lembretes.

Todas as requisições exigem o cabeçalho `Authorization: Bearer {BearerToken}`.

***

## Pipelines

Um pipeline é um funil de vendas nomeado que contém etapas ordenadas. Crie quantos pipelines forem necessários para representar diferentes produtos, equipes ou processos de vendas.

### Criar pipeline

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

```json theme={null}
{ "name": "Sales Pipeline", "description": "Main sales funnel" }
```

### Listar pipelines

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/pipeline/list?page=1&limit=20
```

### Exibir pipeline

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/pipeline/show/{id}
```

### Atualizar pipeline

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/pipeline/update/{id}
```

```json theme={null}
{ "name": "Updated Pipeline Name" }
```

### Excluir pipeline

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/pipeline/delete/{id}
```

***

## Etapas

As etapas são as colunas ordenadas dentro de um pipeline — por exemplo, "Lead", "Proposta Enviada", "Negociação", "Fechado".

### Criar etapa

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

```json theme={null}
{
  "name": "Proposal Sent",
  "pipelineId": 5,
  "order": 3,
  "color": "#3B82F6"
}
```

| Campo        | Tipo    | Obrigatório | Descrição                                                     |
| ------------ | ------- | ----------- | ------------------------------------------------------------- |
| `name`       | string  | Sim         | Rótulo da etapa exibido na visualização do pipeline.          |
| `pipelineId` | integer | Sim         | Pipeline ao qual esta etapa pertence.                         |
| `order`      | integer | Não         | Posição da etapa dentro do pipeline (indexado a partir de 1). |
| `color`      | string  | Não         | Código de cor hexadecimal para o card da etapa.               |

### Listar etapas por pipeline

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/stage/list?page=1&limit=20&pipelineId=5
```

### Exibir etapa

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/stage/show/{id}
```

### Atualizar etapa

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/stage/update/{id}
```

```json theme={null}
{ "name": "Contract Signed" }
```

### Excluir etapa

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/stage/delete/{id}
```

***

## Oportunidades

Uma oportunidade representa um negócio em andamento, vinculado a um contato e a uma etapa dentro de um pipeline.

### Criar oportunidade

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

```json theme={null}
{
  "name": "Enterprise License - Acme Corp",
  "number": "5511999999999",
  "contactName": "Maria Silva",
  "email": "maria@acme.com",
  "value": 15000.00,
  "status": "open",
  "pipelineId": 5,
  "stageId": 12,
  "responsibleId": 3,
  "closingForecast": "2026-12-31",
  "description": "Annual enterprise license renewal",
  "validateNumber": true
}
```

| Campo             | Tipo    | Obrigatório | Descrição                                                      |
| ----------------- | ------- | ----------- | -------------------------------------------------------------- |
| `name`            | string  | Sim         | Título da oportunidade.                                        |
| `number`          | string  | Sim         | Número de telefone do contato ao qual vincular a oportunidade. |
| `contactName`     | string  | Não         | Nome de exibição do contato.                                   |
| `email`           | string  | Não         | E-mail do contato.                                             |
| `value`           | number  | Não         | Valor estimado do negócio.                                     |
| `status`          | string  | Não         | `open`, `win` ou `lose`.                                       |
| `pipelineId`      | integer | Não         | Pipeline no qual colocar a oportunidade.                       |
| `stageId`         | integer | Não         | Etapa dentro do pipeline.                                      |
| `responsibleId`   | integer | Não         | Agente responsável por esta oportunidade.                      |
| `closingForecast` | string  | Não         | Data prevista de fechamento (`YYYY-MM-DD`).                    |
| `description`     | string  | Não         | Notas de texto livre sobre a oportunidade.                     |
| `validateNumber`  | boolean | Não         | Valida o número de telefone no WhatsApp.                       |

### Atualizar oportunidade

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

Aceita os mesmos campos da criação, com `opportunityId` como um campo obrigatório adicional identificando o registro a ser atualizado.

```json theme={null}
{
  "opportunityId": 30,
  "status": "win",
  "stageId": 15
}
```

### Listar oportunidades

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/listOpportunities?page=1&limit=40&status=open&pipelineId=5
```

| Query param  | Descrição                             |
| ------------ | ------------------------------------- |
| `page`       | Número da página (padrão: `1`).       |
| `limit`      | Resultados por página (padrão: `40`). |
| `status`     | Filtra por `open`, `win` ou `lose`.   |
| `pipelineId` | Filtra por pipeline.                  |

### Excluir oportunidade

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

```json theme={null}
{ "opportunityId": 30 }
```

***

## Agendamentos

Os agendamentos são eventos programados vinculados a um contato e, opcionalmente, a um canal do WhatsApp.

### Criar agendamento

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

```json theme={null}
{
  "title": "Sales Meeting",
  "description": "Discuss commercial proposal",
  "contactId": 45,
  "contactName": "Maria Silva",
  "contactPhone": "5511999999999",
  "whatsappId": 12,
  "startAt": "2026-07-15T14:00:00.000Z",
  "endAt": "2026-07-15T15:00:00.000Z",
  "status": "pending",
  "notes": "Bring printed proposal"
}
```

| Campo          | Tipo    | Obrigatório | Descrição                                                         |
| -------------- | ------- | ----------- | ----------------------------------------------------------------- |
| `title`        | string  | Sim         | Título do agendamento.                                            |
| `contactId`    | integer | Não         | ID de um contato existente.                                       |
| `contactName`  | string  | Não         | Nome do contato (usado ao criar um novo contato automaticamente). |
| `contactPhone` | string  | Não         | Número de telefone do contato.                                    |
| `whatsappId`   | integer | Não         | Canal a ser usado para mensagens de lembrete.                     |
| `startAt`      | string  | Sim         | Horário de início no formato ISO 8601.                            |
| `endAt`        | string  | Não         | Horário de término no formato ISO 8601.                           |
| `status`       | string  | Não         | `pending`, `confirmed`, `cancelled` ou `completed`.               |
| `description`  | string  | Não         | Pauta ou contexto do agendamento.                                 |
| `notes`        | string  | Não         | Notas internas visíveis apenas para os agentes.                   |

### Listar agendamentos

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/appointment/list?page=1&limit=20&status=pending
```

| Query param | Descrição                                                            |
| ----------- | -------------------------------------------------------------------- |
| `page`      | Número da página (padrão: `1`).                                      |
| `limit`     | Resultados por página (padrão: `20`).                                |
| `status`    | Filtra por `pending`, `confirmed`, `cancelled` ou `completed`.       |
| `startFrom` | Retorna agendamentos com início nesta data ISO 8601 ou depois.       |
| `startTo`   | Retorna agendamentos com início nesta data ISO 8601 ou antes.        |
| `search`    | Busca por texto livre no título do agendamento e no nome do contato. |

### Exibir agendamento

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/appointment/show/{id}
```

### Atualizar agendamento

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/appointment/update/{id}
```

Aceita os mesmos campos de [Criar agendamento](#criar-agendamento).

### Excluir agendamento

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/appointment/delete/{id}
```

***

## Lembretes Agendados

Os lembretes agendados são regras reutilizáveis que enviam automaticamente uma mensagem do WhatsApp a um contato um determinado número de horas antes do seu compromisso. Cada regra de lembrete se aplica a todos os agendamentos no canal configurado.

### Criar lembrete agendado

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

```json theme={null}
{
  "name": "24h Reminder",
  "hoursBeforeEvent": 24,
  "messageType": "message",
  "messageContent": "Hi {{nome}}, reminder of your meeting tomorrow at {{hora}}!",
  "whatsappId": 12,
  "active": true
}
```

| Campo              | Tipo    | Obrigatório | Descrição                                                                                             |
| ------------------ | ------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| `name`             | string  | Sim         | Nome interno para esta regra de lembrete.                                                             |
| `hoursBeforeEvent` | integer | Sim         | Quantas horas antes do agendamento a mensagem deve ser enviada.                                       |
| `messageType`      | string  | Sim         | `message` para uma mensagem de texto livre, ou `waba_template` para um modelo WABA.                   |
| `messageContent`   | string  | Sim\*       | Texto da mensagem. Suporta variáveis de personalização. Obrigatório quando `messageType` é `message`. |
| `whatsappId`       | integer | Sim         | Canal do qual enviar o lembrete.                                                                      |
| `active`           | boolean | Não         | Se a regra fica ativa imediatamente após a criação.                                                   |

**Variáveis de personalização:**

| Variável           | Substituída por                |
| ------------------ | ------------------------------ |
| `{{nome}}`         | Nome completo do contato.      |
| `{{primeiroNome}}` | Primeiro nome do contato.      |
| `{{telefone}}`     | Número de telefone do contato. |
| `{{data}}`         | Data do agendamento.           |
| `{{hora}}`         | Horário do agendamento.        |
| `{{titulo}}`       | Título do agendamento.         |

### Listar lembretes agendados

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

### Alternar estado ativo do lembrete agendado

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/scheduleReminder/toggle/{id}
```

Inverte a flag `active`. Nenhum corpo de requisição é necessário.

### Atualizar lembrete agendado

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/scheduleReminder/update/{id}
```

Aceita os mesmos campos de [Criar lembrete agendado](#criar-lembrete-agendado).

### Excluir lembrete agendado

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/scheduleReminder/delete/{id}
```

***

## Métricas do Dashboard

Obtenha análises de volume de tickets e tempo de resposta para um determinado intervalo de datas. Use isso para construir relatórios personalizados, monitorar o desempenho de SLA, ou enviar KPIs para uma ferramenta de BI externa.

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/dash/ticketsAndTimes?startDate=2026-03-01&endDate=2026-03-31
```

| Query param | Tipo   | Obrigatório | Descrição                                               |
| ----------- | ------ | ----------- | ------------------------------------------------------- |
| `startDate` | string | Sim         | Início do período do relatório no formato `YYYY-MM-DD`. |
| `endDate`   | string | Sim         | Fim do período do relatório no formato `YYYY-MM-DD`.    |

**Exemplo de resposta:**

```json theme={null}
{
  "success": true,
  "data": {
    "totalAttendances": 1240,
    "activeDemand": 312,
    "receptiveDemand": 928,
    "newContacts": 184,
    "aht": 420,
    "awt": 95
  }
}
```

| Campo              | Descrição                                     |
| ------------------ | --------------------------------------------- |
| `totalAttendances` | Total de tickets atendidos no período.        |
| `activeDemand`     | Tickets iniciados pela sua equipe (outbound). |
| `receptiveDemand`  | Tickets iniciados pelos contatos (inbound).   |
| `newContacts`      | Novos contatos criados durante o período.     |
| `aht`              | Tempo médio de atendimento em segundos.       |
| `awt`              | Tempo médio de espera em segundos.            |