Documentação da API LeadCNPJ

Cookbook

Exemplos práticos

Receitas prontas pra os casos de uso mais comuns. Substitua leadcnpj_live_... pela sua chave criada em Configurações → API.

1. Consulta unitária básica

Dados públicos RFB + cache de enriquecimento (se houver). Custo: 1 consulta — 0,5 crédito nos planos com API.

curl -H "Authorization: Bearer leadcnpj_live_..." \
     https://leadcnpj.com.br/api/v1/empresa/12345678000190

Retorna razão social, CNAE traduzido, QSA com sócios + qualificação, regime tributário, endereço, contato, faixa etária dos sócios, datas em ISO. Quando há cache de enriquecimento, o campo enriquecimento traz dados cruzados na web (localização, site, contatos, decisores) — sem cobrança extra.

2. Consulta com enriquecimento ativo

Força refresh do enriquecimento (dados cruzados na web). Custo: 2 créditos (1 base + 1 enriquecimento).

curl -H "Authorization: Bearer leadcnpj_live_..." \
     "https://leadcnpj.com.br/api/v1/empresa/12345678000190?enriquecer=true"

Use quando: (a) o CNPJ ainda não tem cache; (b) cache existente está stale; (c) você precisa de dados garantidamente frescos pra uma proposta comercial.

3. Busca: agências de publicidade em RS com WhatsApp e e-mail corporativo

Busca com 5 filtros (UF + CNAE + 3 booleanos de qualidade de contato). Passa folgado do mínimo de 3 filtros exigido pela API:

curl -X POST https://leadcnpj.com.br/api/v1/empresas/buscar \
  -H "Authorization: Bearer leadcnpj_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "uf": "RS",
    "cnae": ["7311400"],
    "email_corporativo": true,
    "whatsapp": true,
    "ignorar_contabilidade": true,
    "per_page": 25
  }'

Notas:

• situacao_ativa=true é aplicado por padrão pela API — não precisa enviar.
• Filtros que você não quer aplicar (natureza_juridica, capital_social_de, idade_minima, etc.) simplesmente não vão no JSON — não envie como string vazia ou null.
• Custo: 1 consulta por CNPJ retornado na página (não pelo total). Com per_page: 25, página cheia custa 25 consultas — 12,5 créditos nos planos com API.

4. Paginar todos os resultados

Loop simples em bash pra varrer todas as páginas. Use total_pages do meta da primeira resposta.

BODY='{"uf":"RS","cnae":["7311400"],"email_corporativo":true,
       "whatsapp":true,"ignorar_contabilidade":true,"per_page":100}'

# Primeira pagina + descobre total_pages
RESP=$(curl -s -X POST https://leadcnpj.com.br/api/v1/empresas/buscar \
  -H "Authorization: Bearer leadcnpj_live_..." \
  -H "Content-Type: application/json" \
  -d "$BODY")
TOTAL=$(echo "$RESP" | jq -r '.meta.total_pages')

# Salva pagina 1 e continua a partir da 2
echo "$RESP" > pagina_1.json
for p in $(seq 2 $TOTAL); do
  curl -s -X POST https://leadcnpj.com.br/api/v1/empresas/buscar \
    -H "Authorization: Bearer leadcnpj_live_..." \
    -H "Content-Type: application/json" \
    -d "$(echo "$BODY" | jq ".page=$p")" \
    > pagina_$p.json
  sleep 1  # respeita rate limit (Growth = 30/min, Scale = 60/min)
done

5. Enriquecer lista de CNPJs em lote (até 100, síncrono)

Pra listas pequenas (CSV de até 100 linhas), use modo síncrono — resposta vem em uma chamada só.

curl -X POST https://leadcnpj.com.br/api/v1/enriquecer \
  -H "Authorization: Bearer leadcnpj_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "cnpjs": [
      "12345678000190",
      "98765432000110",
      "12345678000190"
    ]
  }'

Custo: 1 consulta por CNPJ encontrado (0,5 crédito nos planos com API). CNPJs não-existentes têm refund automático.

6. Enriquecer lote grande (101 a 1.000 CNPJs, async)

Acima de 100 CNPJs a API cria um job assíncrono e devolve 202 com job_id. Faça polling pra pegar o resultado.

# 1. Cria job
JOB=$(curl -s -X POST https://leadcnpj.com.br/api/v1/enriquecer \
  -H "Authorization: Bearer leadcnpj_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"cnpjs\":[$(cat lista.json | jq -c '.[]' | paste -sd, -)]}")
JOB_ID=$(echo "$JOB" | jq -r '.data.job_id')

# 2. Polling a cada 10s ate completar
while true; do
  STATUS=$(curl -s -H "Authorization: Bearer leadcnpj_live_..." \
    https://leadcnpj.com.br/api/v1/enriquecer/$JOB_ID | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done

# 3. Pega resultado final
curl -s -H "Authorization: Bearer leadcnpj_live_..." \
  https://leadcnpj.com.br/api/v1/enriquecer/$JOB_ID > resultado.json

7. Python — busca + enriquecimento individual

import requests, os

TOKEN = os.environ['LEADCNPJ_TOKEN']
BASE = 'https://leadcnpj.com.br/api/v1'
HEADERS = {'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'}

# 1. Busca empresas
resp = requests.post(f'{BASE}/empresas/buscar', json={
    'uf': 'RS',
    'cnae': ['7311400'],
    'email_corporativo': True,
    'whatsapp': True,
    'ignorar_contabilidade': True,
    'per_page': 50,
}, headers=HEADERS)
resp.raise_for_status()
empresas = resp.json()['data']

# 2. Pra cada empresa, busca enriquecimento completo
for emp in empresas:
    detalhe = requests.get(
        f"{BASE}/empresa/{emp['cnpj']}?enriquecer=true",
        headers=HEADERS,
    ).json()
    print(detalhe['data']['razao_social'],
          detalhe['data']['enriquecimento']['google']['rating']
            if detalhe['data'].get('enriquecimento', {}).get('google') else None)

8. Tratamento de erros

Toda resposta de erro segue o mesmo shape (veja Erros e Códigos):

{
  "error": {
    "code": "validation_error",
    "message": "Busca exige no mínimo 3 filtros ativos pra evitar consultas muito amplas. Você enviou 2. Combine pelo menos UF + CNAE + outro filtro (porte, idade, capital, email, etc.).",
    "details": {
      "filtros_ativos": 2,
      "minimo": 3,
      "filtros_validos": ["uf","municipio","cnae","porte", ...]
    },
    "request_id": "01KRBNZ4R3E8TKB8J3RQR8JS7A"
  }
}

Sempre logue request_id no seu lado — facilita debug quando precisar abrir ticket de suporte.

9. Respeitar rate limit (429)

Cada resposta inclui headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Quando excede, vem 429 com Retry-After em segundos:

import time, requests

def call_with_retry(url, **kwargs):
    for tentativa in range(5):
        r = requests.get(url, **kwargs)
        if r.status_code == 429:
            wait = int(r.headers.get('Retry-After', 1))
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError('Excedeu retries de rate limit')