> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://ajuda.elephan.ai/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Como utilizar a API da Elephan ?

A **API da Elephan** permite que sistemas externos consultem os dados da sua conta de forma automatizada e segura.  
​

Com ela, você pode levar informações geradas pela Elephan para o seu **CRM, ferramenta de BI, planilhas ou sistemas internos**, sem precisar exportar relatórios manualmente.  
​

## O que é a API da Elephan?

A API da Elephan é uma **API REST** que devolve os dados da sua conta em formato JSON.

Ela funciona com dois princípios importantes:

* **Autenticação por chave de API:** toda requisição precisa ser identificada por uma chave (`elk_...`) gerada dentro da plataforma.
* **Somente leitura:** a API apenas consulta informações. Nada pode ser criado, alterado ou removido através dela.

O endereço base da API em produção é:

[https://api.elephan.dev](https://api.elephan.dev)

A documentação técnica completa, com exemplos de requisição e resposta para cada endpoint, está disponível em:

[https://elephan-api.readme.io](https://elephan-api.readme.io)

## Tipos de chave de API

A Elephan oferece dois tipos de chave. A diferença entre elas está em **quem pode gerar** e em **quais dados cada uma alcança**.

|  | API do Time | API Individual |
| --- | --- | --- |
| Quem pode gerar | Apenas Super Admins | Qualquer usuário da plataforma |
| Quantidade | Uma chave ativa por time | Uma chave ativa por usuário |
| Dados acessados | Todos os dados do time | Os dados que aquele usuário já vê na plataforma |
| Uso recomendado | Integrações do time: CRM, BI, data warehouse | Automações e análises pessoais |

## Como escolher

Use a **API do Time** quando a integração pertence à empresa e precisa enxergar o time inteiro, por exemplo, um painel de BI com o desempenho de todos os vendedores.

Use a **API Individual** quando a integração é de uma pessoa e deve respeitar exatamente o que ela já pode ver na plataforma, por exemplo, um vendedor que quer acompanhar as próprias reuniões em uma ferramenta pessoal.

Importante: a chave individual **herda as permissões do usuário**. Se o usuário só tem acesso às próprias reuniões na plataforma, a chave dele também retornará apenas as próprias reuniões.

## 1. Acesse a área de Integrações

No menu lateral esquerdo, acesse:

**Integrações → API / Webhooks**

Localize o card **API** e clique no ícone de engrenagem para abrir as configurações da integração.

[![](https://storage.crisp.chat/users/helpdesk/website/-/c/f/b/2/cfb2a33331452800/b394ddd6-5949-47da-8708-afb1d6_tmk6th.png)](https://downloads.intercomcdn.com/i/o/y556j3ga/2674725626/a7d1fa27447c3bd5ccab390855d1/image.png?expires=1791376200&signature=b8f62f352c256da47454b0310bd5cec8082e8e587df0af9d1a4cc8f7ac5083d9&req=diYgEs58mIddX%2FMW1HO4zb9MUm9eBn7IUQCaFCne3DVHz8mVA8SNa%2FGczwrm%0AwAABDs4zmCO8me%2FNQvI%3D%0A)

## 2. Gere sua chave de API do Time

No painel lateral que se abre, você verá a seção **Chave de API do time**.

1. Clique em **Gerar nova chave**.
2. A chave será exibida no formato `elk_prod_...`.
3. Clique no ícone de **copiar** e guarde a chave em um local seguro.

[![](https://storage.crisp.chat/users/helpdesk/website/-/7/9/3/4/7934e84dd19a540/17b5e41a-3a55-40bb-a1a3-46ec04_5fgycd.png)](https://downloads.intercomcdn.com/i/o/y556j3ga/2674686882/77ef9b736989490d3e9d0e49d706/image.png?expires=1791376200&signature=51b758620a9434ff2322a1a1a0992fca90bc98c643564272a3e90ba9d504263c&req=diYgEs92m4lXW%2FMW1HO4zUh%2F9JUR3oCY6oWg7NqsFZ4CYpIUNmB9XBmrE8%2BC%0AznqxhrAYf%2Bua%2BeCQApo%3D%0A)

**Importante**: A chave completa é exibida **apenas uma vez**, no momento em que é gerada. Depois de fechar ou recarregar a tela, você verá somente os primeiros caracteres dela. Se perder a chave, será necessário gerar uma nova. Apenas usuários com permissão de **Super Admin** podem gerar, revogar ou desativar a chave de API do time.

## Substituindo a chave do time

Cada time utiliza **uma única chave de API ativa**.

Para substituir a chave atual, use o botão **Revogar e gerar nova chave**.

A chave anterior deixa de funcionar imediatamente, e todas as integrações que a utilizam precisarão ser atualizadas com a nova chave.

## 3. Gere sua chave de API Individual

A chave individual fica disponível na mesma tela de **Integrações → API / Webhooks**, na área da sua chave pessoal.

1. Clique na opção para gerar sua chave individual.
2. Copie a chave exibida (`elk_prod_...`) e guarde em local seguro.

[![](https://storage.crisp.chat/users/helpdesk/website/-/f/0/a/5/f0a5bcbd0284d000/75560e02-ea84-4d35-99c0-d98a78_nk6u46.png)](https://downloads.intercomcdn.com/i/o/y556j3ga/2674691684/a1aa88e9cbb7dd31fe7c805da889/image.png?expires=1791376200&signature=ff928ff7e2417409a4bf9ebd2b69c047874357177cb5fff5c832683f2db8f63c&req=diYgEs93nIdXXfMW1HO4zUt2boWWIGy1BWnwBIwSZ8KwnzjDJimBRS7NrnZS%0AoppHofjapQQmBgfz8YQ%3D%0A)

Cada usuário pode ter **uma chave individual ativa por vez**. Para substituí-la, revogue a atual e gere uma nova.

**Importante**: se o usuário dono da chave for desativado ou removido do time, a chave individual deixa de funcionar automaticamente.

## 4. Autentique sua primeira chamada

A chave de API deve ser enviada no cabeçalho `Authorization`, no formato **Bearer**:

```
Authorization: Bearer elk_prod_xxxxxxxxxx
```

## Testando a conexão

O endpoint de verificação de status não exige autenticação e serve para confirmar que a API está disponível:

```
curl https://api.elephan.dev/health
```

## Primeira consulta autenticada

Para listar as reuniões transcritas do seu time:

```
curl -H "Authorization: Bearer elk_prod_xxxxxxxxxx" \   "https://api.elephan.dev/v1/transcribes?limit=10"
```

Se a chave estiver correta, a resposta virá em JSON com a lista de reuniões e as informações de paginação.

## 5. Conexão realizada

A partir daqui, sua ferramenta já pode consultar os dados disponíveis na Elephan.

Nenhuma configuração adicional é necessária na plataforma.

## O que a integração permite?

## 1. Consultar reuniões e transcrições

| Método | Endpoint | O que retorna |
| --- | --- | --- |
| GET | /v1/transcribes | Lista de reuniões transcritas |

São retornadas apenas as reuniões com transcrição **já concluída**.

Cada reunião traz informações como título, data, duração, participantes, respostas do scorecard, palavras-chave, concorrentes citados, pontos importantes e análise de sentimento. A consulta por ID inclui ainda a **transcrição completa**, o **resumo gerado pela IA** e o link da gravação.

Filtros disponíveis em `/v1/transcribes`:

* `email` — filtra pelo e-mail do usuário
* `startDate` e `endDate` — período, no formato ISO 8601
* `page` e `limit` — paginação (padrão: 20 registros por página, máximo de 100)

Exemplo:

```
curl -H "Authorization: Bearer elk_prod_xxxxxxxxxx" \   "https://api.elephan.dev/v1/transcribes?startDate=2026-01-01T00:00:00Z&endDate=2026-01-31T23:59:59Z"
```

## 2. Consultar usuários da equipe

| Método | Endpoint | O que retorna |
| --- | --- | --- |
| GET | /v1/users | Lista de usuários do time |

Cada usuário retorna informações como nome, e-mail, status, perfil de permissão, data de cadastro e último acesso.

Filtros disponíveis: `page` e `limit` (padrão: 100 registros por página).

## 3. Consultar tipos de reunião

| Método | Endpoint | O que retorna |
| --- | --- | --- |
| GET | /v1/prompts | Tipos de reunião configurados no time |

Os tipos de reunião são úteis para filtrar reuniões e scorecards por modelo de análise. O `id` retornado aqui é o valor que você usa no filtro `promptId` dos outros endpoints.

Filtros disponíveis: `page` e `limit` (padrão: 100 registros por página).

## 4. Consultar scorecards

| Método | Endpoint | O que retorna |
| --- | --- | --- |
| GET | /v1/scorecard/by-seller | Desempenho agregado por vendedor |
| GET | /v1/scorecard/by-question | Desempenho agregado por pergunta |

Em `/v1/scorecard/by-seller` e `/v1/scorecard/by-question`, os parâmetros `startDate` e `endDate` são **obrigatórios** — sem eles a API responde com erro `400`. Também é possível filtrar por `promptId` e `userId`, e paginar com `page` e `limit` (padrão: 20, máximo de 100).

O agrupamento **por vendedor** retorna a quantidade de reuniões avaliadas, a média geral e a média por pergunta. O agrupamento **por pergunta** retorna a média, o total de respostas e a distribuição das notas.

Exemplo:

```
curl -H "Authorization: Bearer elk_prod_xxxxxxxxxx" \   "https://api.elephan.dev/v1/scorecard/by-seller?startDate=2026-01-01T00:00:00Z&endDate=2026-01-31T23:59:59Z"
```

## 5. Consultar conversas de WhatsApp

Disponível quando a integração de WhatsApp está configurada na sua conta.

| Método | Endpoint | O que retorna |
| --- | --- | --- |
| GET | /v1/conversations | Lista de conversas com contadores e médias |

A listagem traz o nome do contato, o telefone, o responsável pela conversa, a quantidade de mensagens, a data da última mensagem e a média do scorecard.

Importante: por privacidade, o endpoint de mensagens retorna apenas os **dados de cada mensagem**, data, direção (enviada ou recebida) e tipo. **O conteúdo das mensagens não é exposto pela API.**

Filtros disponíveis em `/v1/conversations`, `startDate`, `endDate`, `page` e `limit` (padrão: 20 registros por página, máximo de 100).

Filtros disponíveis em `/v1/conversations/{id}/messages`: `startDate`, `endDate`, `page` e `limit`.

## 6. Consultar insights

| Método | Endpoint | O que retorna |
| --- | --- | --- |
| GET | /v1/insights | Insights extraídos das reuniões e conversas |
| GET | /v1/insights/clusters | Insights agrupados por tema |

Filtros disponíveis: `source` (`product`, `sale` ou `cs`), `type` (um ou mais tipos separados por vírgula), `startDate`, `endDate`, `page` e `limit` (padrão: 20, máximo de 100).

Em `/v1/insights` também é possível filtrar por `dealId`, para trazer os insights de uma negociação específica do CRM.

Em `/v1/insights/clusters`, cada grupo retorna o tema identificado, a quantidade de insights, os tipos que o compõem, o período coberto e alguns exemplos.

Importante: os insights são dados consolidados do time. Por isso, as chaves individuais só acessam esses endpoints quando o usuário já possui visibilidade de todo o time na plataforma.

## 7. Consultar o consumo da própria chave

| Método | Endpoint | O que retorna |
| --- | --- | --- |
| GET | /v1/stats/usage | Volume de chamadas, tempo de resposta e erros |

O parâmetro `days` define o período consultado (padrão: 7 dias, máximo de 30).

Com a chave do time, o retorno mostra o consumo consolidado. Com a chave individual, mostra o consumo da sua própria chave.

O consumo também pode ser acompanhado visualmente no gráfico **Uso Diário da API**, dentro do card **API** na tela de Integrações.

# Paginação e filtros

Todos os endpoints de listagem seguem o mesmo padrão de paginação, controlado pelos parâmetros `page` e `limit`.

A resposta traz os registros em `data` e as informações de navegação em `pagination`:

```
{   "data": [ ... ],   "pagination": {     "page": 1,     "limit": 20,     "total": 250,     "totalPages": 13,     "hasNext": true,     "hasPrev": false   } }
```

Use `hasNext` para saber se ainda existem páginas a serem consultadas e incremente `page` até que ele seja `false`.

O valor máximo de `limit` é **100** na maioria dos endpoints. Valores acima disso são ajustados automaticamente para o limite permitido.

Datas devem sempre ser informadas no formato **ISO 8601**, por exemplo: `2026-01-15T00:00:00Z`.

# Limites de uso

Cada chave de API possui um limite de **1.000 requisições por hora**.

Toda resposta da API inclui cabeçalhos que mostram a sua situação atual:

| Cabeçalho | Significado |
| --- | --- |
| X-RateLimit-Limit | Total de requisições permitidas na janela |
| X-RateLimit-Remaining | Quantas requisições ainda restam |
| X-RateLimit-Reset | Quando o limite será renovado |

Ao exceder o limite, a API responde com o código **429** e o cabeçalho `Retry-After`, indicando quantos segundos aguardar antes de tentar novamente.

Se você precisar de um volume maior, fale com o nosso time de suporte.

# Erros comuns

| Código | Significado | O que fazer |
| --- | --- | --- |
| 400 | Parâmetro ausente ou em formato inválido | Confira as datas em ISO 8601 e os parâmetros obrigatórios do endpoint |
| 401 | Chave ausente, inválida, desativada ou revogada | Confirme o cabeçalho Authorization: Bearer e gere uma nova chave, se necessário |
| 403 | A chave não tem permissão para esse recurso | Utilize a chave de API do time para dados consolidados |
| 404 | Registro não encontrado ou fora do seu escopo de acesso | Verifique o identificador informado |
| 429 | Limite de requisições excedido | Aguarde o tempo indicado em Retry-After |

## Segurança e permissões

### Acesso restrito ao seu time

Cada chave de API possui acesso apenas aos dados da equipe à qual ela pertence.

A ferramenta conectada não consegue visualizar informações de outros times.

### Acesso somente leitura

A API permite apenas consultas.

Nenhuma informação pode ser criada, alterada ou removida através dela.

### Armazenamento da chave

A chave é armazenada de forma criptografada na Elephan e exibida em texto apenas no momento da geração.

Por isso, guarde-a em um gerenciador de senhas ou em um cofre de credenciais da sua empresa.

### Importante

* A chave de API deve ser enviada no cabeçalho `Authorization: Bearer`.
* A chave completa é exibida apenas uma vez, no momento da geração.
* Cada time possui uma chave de API ativa, e cada usuário pode ter uma chave individual ativa.
* Gerar uma nova chave revoga a anterior, e as integrações precisarão ser atualizadas.
* A chave não expira automaticamente: ela permanece válida até ser revogada.
* Apenas Super Admins podem gerenciar a chave de API do time.
* A chave individual respeita as mesmas permissões que o usuário já possui na plataforma.
* O acesso é somente leitura: a API não altera informações dentro da Elephan.
* O endereço do servidor pode variar entre ambientes de produção e homologação.
* Nunca compartilhe sua chave por e-mail, chat ou repositórios de código.

Se surgir qualquer dúvida, não hesite em nos contatar pela plataforma ou através do e-mail [ajuda@elephan.ai](vscode-webview://0jtublri8jao7uisf1rdcv4u7uogg11di6kis67429ree5nq9rpd/index.html?id=e4daa29d-3460-42a7-ac06-6cc6fcb77766&parentId=4&origin=f3fa3477-350c-4cb0-b63f-6ff24406dead&swVersion=5&extensionId=Anthropic.claude-code&platform=electron&vscode-resource-base-authority=vscode-resource.vscode-cdn.net&parentOrigin=vscode-file%3A%2F%2Fvscode-app&session=27712cb0-2108-41bc-9eaa-795fb7efeb79)