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

# API da LiderHub

> Conheca a API da LiderHub e veja como gerar a sua chave de autenticacao.

## Visao geral

<Info>
  A API da LiderHub está em fase **beta**, mas já está disponível para uso em qualquer workspace. Para começar, basta gerar uma chave de API em **Configurações → Credenciais API** dentro da plataforma.
</Info>

Nesta secao, voce encontra a referencia da API da LiderHub para integrar seu workspace com sistemas externos.

Com a API, voce pode:

* consultar conversas e contatos;
* listar conexoes e configuracoes do workspace;
* gerenciar grupos do WhatsApp;
* enviar mensagens;
* integrar automações com seus sistemas internos.

## Rate Limit

A API possui um limite de **3 requisições por segundo** por workspace. Requisições que excederem esse limite receberão o status HTTP `429 Too Many Requests`.

<Tip>
  Para evitar erros de rate limit, implemente um mecanismo de retry com backoff exponencial nas suas integrações.
</Tip>

## Códigos de erro

A API retorna erros padronizados em formato JSON. Abaixo estão os principais códigos de status e suas causas.

### 400 Bad Request

Erro de validação ou parâmetros inválidos.

| Causa            | Descrição                                                  |
| ---------------- | ---------------------------------------------------------- |
| Validação falhou | Parâmetros não passaram na validação (formato, tipo, etc.) |
| UUID inválido    | ID informado não está no formato UUID válido               |
| Conexão inválida | Contato não possui conexão WhatsApp vinculada              |
| Conexão fechada  | WhatsApp está desconectado                                 |
| Janela expirada  | Janela de 24 horas do WhatsApp expirou                     |

### 401 Unauthorized

Erro de autenticação com a chave de API.

| Causa              | Descrição                                            |
| ------------------ | ---------------------------------------------------- |
| Header ausente     | O header `x-company-key` não foi enviado             |
| Chave inválida     | A chave de API não existe ou está incorreta          |
| Sem permissão      | A chave não tem permissão para acessar este endpoint |
| Chave expirada     | A chave de API expirou                               |
| Chave desabilitada | A chave de API foi desabilitada                      |

### 404 Not Found

Recurso não encontrado no workspace.

| Causa                     | Descrição                                         |
| ------------------------- | ------------------------------------------------- |
| Contato não encontrado    | O ID do contato informado não existe              |
| Mensagem não encontrada   | O ID da mensagem informado não existe             |
| Conexão não encontrada    | O ID da conexão informado não existe              |
| Contato fora do workspace | O contato não existe ou não pertence ao workspace |

### 429 Too Many Requests

Limite de requisições excedido.

| Causa               | Descrição                                          |
| ------------------- | -------------------------------------------------- |
| Rate limit excedido | Limite de requisições por segundo foi ultrapassado |

### 500 Internal Server Error

Erro interno do servidor.

| Causa           | Descrição                    |
| --------------- | ---------------------------- |
| Erro inesperado | Erro não tratado no servidor |

### 503 Service Unavailable

Serviço temporariamente indisponível.

| Causa                | Descrição                                                |
| -------------------- | -------------------------------------------------------- |
| Serviço indisponível | Sistema de autenticação ou outro serviço está fora do ar |

### Formato da resposta de erro

Todas as respostas de erro seguem o formato:

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "timestamp": "2026-03-25T17:30:00.000Z",
  "path": "/v1/contacts"
}
```

Para erros de validação, o campo `errors` detalha cada problema:

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "timestamp": "2026-03-25T17:30:00.000Z",
  "path": "/v1/contacts",
  "errors": [
    {
      "field": "createdAfter",
      "message": "createdAfter must be a valid ISO 8601 date string"
    }
  ]
}
```

## Como obter a chave de API

A autenticação é feita pelo header `x-company-key`. Cada workspace gera a própria chave dentro da plataforma:

<Steps>
  <Step title="Acesse a plataforma">
    Entre em [chat.liderhub.ai](https://chat.liderhub.ai) com a conta do workspace que vai usar a API.
  </Step>

  <Step title="Abra a aba Credenciais API">
    No menu lateral, vá em **Configurações → Credenciais API**.
  </Step>

  <Step title="Gere uma nova chave">
    Clique em **Gerar nova chave**, dê um nome para identificar o uso (por exemplo, `N8N`, `Backend interno`, `Cursor`) e copie o valor exibido.
  </Step>

  <Step title="Guarde com segurança">
    A chave só é exibida uma vez. Guarde em um gerenciador de senhas — se perder, gere outra e atualize as integrações que a utilizam.
  </Step>
</Steps>

<Warning>
  Nunca exponha sua chave em código público, repositórios ou mensagens. Se suspeitar que vazou, desabilite a chave em **Configurações → Credenciais API** e gere uma nova.
</Warning>

<Tip>
  A mesma chave é compartilhada entre a API REST e o [MCP Server](/api/mcp) da LiderHub — você pode reaproveitar credenciais existentes.
</Tip>

<CardGroup cols={2}>
  <Card title="MCP Server" icon="plug" href="/api/mcp">
    Conecte agentes de IA (Claude, Cursor, Windsurf) diretamente ao seu workspace.
  </Card>

  <Card title="Exemplo: enviar lead para N8N" icon="flask" href="/integracoes/exemplo-custom-tool">
    Passo a passo completo de uma Custom Tool que envia dados do lead para o N8N via webhook.
  </Card>
</CardGroup>

## Deixe uma sugestao

<Accordion title="Feedback de Melhorias sobre API da LiderHub">
  Agradecemos muito pelo seu tempo! Se voce precisa de suporte, acesse [Obtenha suporte](/suporte/obtenha-suporte).

  <iframe src="https://tally.so/embed/682q2k?feature=API%20da%20LiderHub&alignLeft=1&hideTitle=1&transparentBackground=1" width="100%" height="350" frameBorder="0" title="Enviar feedback de melhorias" />
</Accordion>