API de Consulta de Dados Empresariais#
Consulte dados cadastrais de empresas brasileiras (CNPJ), informações de CPF e perfis profissionais do LinkedIn de forma rápida, confiável e econômica.
Índice#
Autenticação#
Todas as requisições à API requerem autenticação via API Key.Como Autenticar#
Envie sua API Key no header X-API-Key em todas as requisições:Gerenciamento de API Keys#
Criar: Acesse o dashboard → API Keys → Nova Chave
Revogar: Dashboard → API Keys → Ações → Revogar
Múltiplas Keys: Crie diferentes keys para ambientes (dev, prod) ou serviços
Segurança#
Nunca exponha sua API Key em código cliente (frontend)
Use variáveis de ambiente: process.env.API_KEY
Revogue imediatamente keys comprometidas
Rotacione keys periodicamente
Endpoints#
Base URL#
A API oferece os seguintes endpoints principais:Empresas (CNPJ)#
Consulta de dados cadastrais da Receita Federal.GET /companies/v1/search - Consulta empresa por CNPJ ou domínio
POST /companies/v1/search - Busca avançada com filtros complexos
Empresas (LinkedIn)#
Consulta de dados de empresas no LinkedIn (R$ 0,49 por consulta).GET /social/v1/companies/search - Busca empresa por ID público do LinkedIn
Pessoas (LinkedIn)#
Consulta de perfis profissionais no LinkedIn (R$ 0,49 por consulta/pessoa).GET /social/v1/people/search - Busca pessoa por profile public ID
POST /social/v1/people/search - Busca avançada de pessoas com filtros
CPF#
Consulta de informações de CPF.GET /cpf/v1/search - Consulta dados de CPF
Pricing & Datasets#
Sistema de Cobrança#
A API utiliza um sistema de cobrança por dataset, permitindo que você pague apenas pelos dados que precisa.Como Funciona#
Para Endpoints CNPJ#
1.
Seleção: Escolha os datasets necessários via query parameter datasets
2.
Cobrança: O valor é calculado automaticamente e debitado do saldo
3.
Resposta: A API retorna os campos solicitados + informações de custo
{
"success": true,
"data": {
},
"datasets": ["complete", "address"],
"cost": 0.32,
"costFormatted": "R$ 0,32"
}
Gestão de Créditos#
Compra: Adquira créditos via dashboard com pagamento por Stripe
Saldo: Visualize seu saldo atual em tempo real
Histórico: Acompanhe todas as transações e consultas
Alertas: Receba notificações quando o saldo estiver baixo
Rate Limits#
Para garantir disponibilidade e performance para todos os usuários, a API implementa rate limiting por API Key.Limites por API Key#
| Janela | Limite | Descrição |
|---|
| Por segundo | 5 requisições | Limite de burst |
| Por minuto | 100 requisições | Limite médio |
| Por hora | 1.000 requisições | Limite de volume |
Resposta de Rate Limit Excedido#
Quando você excede o limite, a API retorna 429 Too Many Requests:{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Limite de requisições excedido. Tente novamente em alguns segundos.",
"limit": 5,
"ttl": 1000
}
}
Boas Práticas#
O que fazer ao receber erro 429:1.
Aguarde o tempo indicado no campo ttl da resposta
2.
Implemente um sistema de retry com intervalo crescente
3.
Distribua suas requisições ao longo do tempo
4.
Use cache para dados consultados com frequência
5.
Evite loops rápidos sem delay entre requisições
Erros Comuns#
Códigos de Erro#
| Código HTTP | Código Interno | Descrição | Solução |
|---|
| 401 | API_KEY_MISSING | API Key não foi enviada | Adicione o header X-API-Key |
| 401 | API_KEY_INVALID | API Key inválida ou desativada | Verifique sua key no dashboard |
| 429 | RATE_LIMIT_EXCEEDED | Limite de requisições excedido | Aguarde e implemente retry com backoff |
| 400 | INVALID_CNPJ | CNPJ inválido (formato ou dígito verificador) | Valide o CNPJ antes de enviar |
| 400 | INVALID_CPF | CPF inválido (formato ou dígito verificador) | Valide o CPF antes de enviar |
| 400 | MISSING_PARAMETER | Parâmetro obrigatório não foi enviado | Verifique os parâmetros requeridos |
| 400 | INVALID_DATASETS | Datasets solicitados são inválidos | Use apenas datasets válidos |
| 404 | COMPANY_NOT_FOUND | Empresa não encontrada na base de dados | Verifique o CNPJ |
| 404 | PERSON_NOT_FOUND | Pessoa não encontrada no LinkedIn | Verifique o profile_public_id |
| 402 | INSUFFICIENT_CREDITS | Saldo insuficiente no workspace | Adicione créditos via dashboard |
| 408 | REQUEST_TIMEOUT | Tempo limite excedido na consulta | Tente novamente |
| 500 | INTERNAL_ERROR | Erro interno do servidor | Tente novamente ou entre em contato |
| 503 | SERVICE_UNAVAILABLE | Serviço temporiamente indisponível | Tente novamente em alguns minutos |
{
"success": false,
"error": {
"code": "API_KEY_INVALID",
"message": "API Key inválida ou desativada",
"details": {}
}
}
Como Tratar os Erros#
Sempre verifique o código de erro retornado e trate adequadamente:401: Verifique sua API Key no dashboard
429: Aguarde o tempo indicado antes de nova tentativa
402: Adicione créditos ao seu workspace
400/404: Verifique os dados enviados na requisição
500: Tente novamente ou entre em contato com o suporte
Suporte#
Contato#
Boas Práticas#
1.
Cache: Armazene dados que não mudam frequentemente
2.
Batch: Use buscas com filtros ao invés de múltiplas consultas individuais
3.
Datasets: Solicite apenas os dados necessários
4.
Compressão: Habilite gzip nas requisições
Segurança#
1.
API Keys: Nunca exponha em código cliente ou repositórios públicos
2.
Rotação: Rotacione keys periodicamente
3.
Múnimas Keys: Crie keys específicas por ambiente ou serviço
4.
Monitoramento: Acompanhe uso anormal no dashboard
Confiabilidade#
1.
Retry Logic: Implemente retry automático com backoff exponencial
2.
Timeout: Configure timeouts adequados (recomendado: 30s)
3.
Circuit Breaker: Implemente para evitar cascata de falhas
4.
Logging: Registre requests e responses para debug
Modificado em 2026-04-14 16:50:01