Boas práticas de uso da API v1

Este guia reúne as melhores práticas, padrões de integração e recomendações de segurança para uso da API v1 do CPF.CNPJ. Está organizado por nível de maturidade da integração: desde uma chamada simples no front-end até arquiteturas robustas com back-end, cache e retry.

Antes de prosseguir, é fundamental que você conheça a estrutura geral da API. Acesse a documentação completa para detalhes de pacotes, endpoints e schemas de resposta.

Sumário

1. Requisições diretas (front-end)
2. Requisições internas (back-end)
3. Modalidade Batch (lotes)
4. Token de testes (mocks)
5. Validação no client antes de chamar a API
6. Como escolher o pacote certo
7. Rate limit e limites de uso
8. Timeouts e pacotes de longa duração
9. Cache do lado do servidor (e do cliente)
10. Retry, backoff e idempotência
11. Tratamento de códigos de erro
12. Segurança e rotação de tokens
13. Auditoria, logs e suporte
14. Exemplos de integração (cURL, Node.js, PHP, Python)
15. Checklist final de produção

1. Requisições diretas (front-end)

Você realiza consultas diretamente no endpoint da API a partir do navegador, sem back-end intermediário. Indicado para protótipos, ferramentas internas ou formulários simples em que o token está confinado a um IP fixo.

Regras de segurança absolutas:

• Nunca use o token * (qualquer IP) em ambiente público — gere um token específico para o IP da sua aplicação.
• Crie uma rota proxy no seu domínio (/api/cpf/{cpf}) para que o token jamais apareça no HTML/JS do navegador. Se o token vazar, qualquer pessoa pode consumir seus créditos.
• Habilite captcha (hCaptcha, reCaptcha v3, Cloudflare Turnstile) antes da chamada para inibir crawlers.
• Restrinja o domínio de origem via cabeçalho Origin e configuração CORS.

Vantagens:

• Integração rápida — apenas fetch() ou XMLHttpRequest.
• Sem necessidade de manter servidor próprio.

Desvantagens:

• Difícil rastrear consumo por usuário.
• Token visível no DevTools do navegador (mesmo restringido por IP).
• Sem possibilidade de cache compartilhado entre usuários.

2. Requisições internas (back-end)

Modalidade recomendada para a maioria dos cenários produtivos. Sua aplicação back-end intermedia todas as chamadas à API, pode autenticar usuários, aplicar regras de negócio e cachear respostas.

Você pode usar o token * (qualquer IP) com segurança, ideal para infraestrutura com IPs dinâmicos como Google Cloud Run, AWS Lambda, Heroku, DigitalOcean App Platform, Vercel.

Vantagens:

• Controle granular de quotas por usuário, plano ou tenant.
• Cache compartilhado de respostas (reduz custo).
• Possibilidade de criar APIs internas customizadas (agregando dados de múltiplos pacotes).
• Token oculto do cliente final.
• Logs centralizados para auditoria e cobrança interna.

Desvantagens:

• Maior tempo de integração inicial.
• Requer infraestrutura back-end (banco para cache, fila para retry).

3. Modalidade Batch (lotes)

Para volumes grandes (milhares a milhões de consultas), use o cabeçalho X-Batch-Token com seu token de batch. Permite consultas assíncronas sem competir pelo rate limit padrão. Indicado para enriquecimento de bases existentes, KYC em lote, due diligence.

• Não conta no rate limit por segundo.
• Resultados podem ser entregues por callback (webhook) ou consultados sob demanda.
• Solicite seu token de batch pelo painel ou pelo suporte.

4. Token de testes (mocks)

Use o token público 5ae973d7a997af13f0aaf2bf60e65803 em ambiente de desenvolvimento e CI. Ele retorna respostas mockadas com a mesma estrutura da produção, sem consumir créditos.

curl "https://api.cpfcnpj.com.br/5ae973d7a997af13f0aaf2bf60e65803/1/00000000000"

Cobre todos os 27 pacotes ativos (CPF, CNPJ, BNMP, Interpol, CAC/SINIC, PPE, Programas Sociais, CNS, etc).

5. Validação no client antes de chamar a API

CPF/CNPJ inválidos retornam erro cobrado como tentativa em alguns planos. Sempre valide o dígito verificador no client antes de enviar:

• CPF: 11 dígitos, validação por módulo 11.
• CNPJ: 14 dígitos, validação por módulo 11.
• Remova máscaras (pontos, traços, barras) antes de enviar.
• Bibliotecas: cpf-cnpj-validator (JS), brutils (Node), validate-docbr (Python).

Isso elimina ~30% das requisições inválidas em formulários típicos.

6. Como escolher o pacote certo

Cada pacote tem custo e tempo de resposta diferentes. Use o menor pacote que atende sua necessidade real:

7. Rate limit e limites de uso

• Padrão: 20 requisições por segundo por token. Clientes premium têm limites customizados (ver lg_api_limit no painel).
• HTTP 429 indica rate limit excedido — implemente backoff exponencial.
• Camadas de proteção: Cloudflare WAF, DigitalOcean App Platform autoscaler, e rate limit interno por Lua atômico no Redis.
• Para chamadas paralelas, mantenha no máximo floor(rate_limit / 2) requisições simultâneas para deixar margem a picos.

8. Timeouts e pacotes de longa duração

Configure o timeout do seu HTTP client de acordo com o pacote:

• Pacotes 17, 18, 26, 12, 13: timeout ≥ 5 segundos.
• Pacotes 1-3, 7-9, 10-11, 14, 15, 19, 21, 22, 24, 25: timeout ≥ 15 segundos.
• Pacote 6 (CNPJ + RF), 16 (CNPJ + IE), 20 (BNMP): timeout ≥ 30 segundos.
• Pacotes 23 (Antecedentes) e 27 (CAC/SINIC): timeout ≥ 45 segundos. Esses pacotes consultam a Polícia Federal em tempo real e podem levar ~20s. Implemente UI de "consultando..." e considere processar de forma assíncrona.

9. Cache do lado do servidor (e do cliente)

Nossa API já cacheia internamente respostas por TTL variável (CPF/CNPJ ~2h). Você pode (e deve) cachear do seu lado também para reduzir custo:

• Cache positivo (status=1): TTL de 1 a 24h é seguro para dados cadastrais (RF atualiza diariamente).
• Cache negativo (status=0, erros transitórios): TTL curto, 1-5 minutos.
• Não cacheie respostas com erroCodigo 1004 (pacote indisponível) ou 1000 (token inválido) — corrija o problema na origem.
• Use o campo consultaID como chave estável para deduplicação.
• Para o pacote 6 (Cartão CNPJ PDF), nossa API mantém cache de 1 minuto para timeouts — refazer a consulta dentro deste prazo retorna o resultado completo sem cobrança adicional.

10. Retry, backoff e idempotência

Toda consulta GET é idempotente — você pode repetir sem efeitos colaterais. Implemente retry para erros transitórios:

Pseudocódigo de backoff exponencial com jitter:

delay = min(base * 2 ** attempt + random(0, 0.5), max_delay)

11. Tratamento de códigos de erro

Todos os erros vêm com erroCodigo numérico estável. Mapeie no client:

12. Segurança e rotação de tokens

• Use HTTPS sempre — a API rejeita HTTP plain.
• Armazene tokens em variáveis de ambiente / secret manager (AWS Secrets, GCP Secret Manager, HashiCorp Vault), nunca em código-fonte.
• Crie tokens distintos por ambiente (dev, staging, prod) e por aplicação.
• Rotacione o token a cada 90-180 dias ou imediatamente em caso de suspeita de vazamento.
• Restrinja por IP sempre que possível. Use * apenas para back-ends com IP dinâmico.
• Quando atrás de um proxy interno, repasse o IP real no cabeçalho X-Forwarded-For.
• Ative alertas de uso anormal no painel para detectar consumo suspeito.

13. Auditoria, logs e suporte

• Persista o campo consultaID de cada resposta — ele é o identificador único usado pelo nosso suporte para investigar discrepâncias.
• Logue: timestamp, pacote, CPF/CNPJ consultado (mascarado se LGPD), consultaID, delay, status HTTP.
• Não armazene PII em logs sem necessidade legal — siga LGPD (Lei 13.709/2018).
• Mantenha logs por pelo menos 6 meses para reconciliação de cobrança.

14. Exemplos de integração

cURL

curl --max-time 30 \
  "https://api.cpfcnpj.com.br/${TOKEN}/1/${CPF}"

Node.js (fetch nativo, Node 18+)

async function consultarCpf(cpf, pacote = 1) {
  const url = `https://api.cpfcnpj.com.br/${process.env.CPFCNPJ_TOKEN}/${pacote}/${cpf}`;
  const ctrl = new AbortController();
  const timer = setTimeout(() => ctrl.abort(), 30_000);
  try {
    const res = await fetch(url, { signal: ctrl.signal });
    const data = await res.json();
    if (data.status !== 1) throw new Error(`erro ${data.erroCodigo}: ${data.erro}`);
    return data;
  } finally {
    clearTimeout(timer);
  }
}

PHP (cURL)

function consultarCpf(string $cpf, int $pacote = 1): array {
    $token = getenv('CPFCNPJ_TOKEN');
    $url = "https://api.cpfcnpj.com.br/{$token}/{$pacote}/{$cpf}";
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_CONNECTTIMEOUT => 5,
    ]);
    $body = curl_exec($ch);
    if ($body === false) throw new RuntimeException(curl_error($ch));
    curl_close($ch);
    return json_decode($body, true);
}

Python (requests + retry)

import os, requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(total=5, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504])
session.mount('https://', HTTPAdapter(max_retries=retry))

def consultar_cpf(cpf: str, pacote: int = 1) -> dict:
    token = os.environ['CPFCNPJ_TOKEN']
    r = session.get(f"https://api.cpfcnpj.com.br/{token}/{pacote}/{cpf}", timeout=30)
    r.raise_for_status()
    return r.json()

15. Checklist final de produção

• ☐ Token armazenado em variável de ambiente / secret manager
• ☐ Token restringido por IP (ou * apenas se back-end com IP dinâmico)
• ☐ HTTPS obrigatório, certificado válido
• ☐ Validação de CPF/CNPJ no client antes da chamada
• ☐ Pacote escolhido é o mínimo necessário
• ☐ Timeout configurado de acordo com o pacote
• ☐ Retry com backoff exponencial em 429/5xx
• ☐ Cache local com TTL apropriado
• ☐ Tratamento de todos os erroCodigo conhecidos
• ☐ consultaID persistido para auditoria
• ☐ Captcha implementado se chamada vem do front-end
• ☐ Alertas de uso anormal ativados no painel
• ☐ Documentação interna do mapeamento pacote → caso de uso
• ☐ Plano de rotação de token (90-180 dias)

Recomendação geral

Para fluxos com interação direta do usuário final (ex.: formulário de cadastro), recomendamos uma camada de validação prévia por e-mail ou SMS. Os dados só são consultados após o pré-cadastro e validação por reCaptcha, evitando consultas externas não autorizadas. Para aprimorar ainda mais, inclua um throttle de 3-5 segundos entre consultas do mesmo usuário se ele digitou um CPF/CNPJ válido e tentou alterá-lo logo em seguida.

Em caso de dúvida ou comportamento inesperado, abra um chamado no portal de suporte informando o consultaID da requisição em questão.