API da LiderHub - LiderHub

Visao geral

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.

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.

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

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:

{
  "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:

{
  "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:

Acesse a plataforma

Entre em chat.liderhub.ai com a conta do workspace que vai usar a API.

Abra a aba Credenciais API

No menu lateral, vá em Configurações → Credenciais API.

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.

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.

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.

A mesma chave é compartilhada entre a API REST e o MCP Server da LiderHub — você pode reaproveitar credenciais existentes.

MCP Server

Conecte agentes de IA (Claude, Cursor, Windsurf) diretamente ao seu workspace.

Exemplo: enviar lead para N8N

Passo a passo completo de uma Custom Tool que envia dados do lead para o N8N via webhook.

Deixe uma sugestao

Feedback de Melhorias sobre API da LiderHub

Agradecemos muito pelo seu tempo! Se voce precisa de suporte, acesse Obtenha suporte.

​Visao geral

​Rate Limit

​Códigos de erro

​400 Bad Request

​401 Unauthorized

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​503 Service Unavailable

​Formato da resposta de erro

​Como obter a chave de API

MCP Server

Exemplo: enviar lead para N8N

​Deixe uma sugestao

Visao geral

Rate Limit

Códigos de erro

400 Bad Request

401 Unauthorized

404 Not Found

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

Formato da resposta de erro

Como obter a chave de API

Deixe uma sugestao