Como testar uma API de CPF em ambiente sandbox antes de ir para produção

Introdução

Testar uma integração de API antes de colocá-la em produção é uma prática fundamental de engenharia de software. No caso de APIs de consulta de CPF, essa etapa é ainda mais importante: erros na integração podem resultar em cadastros mal processados, fraudes não detectadas ou experiências ruins para o usuário final.

Muitos desenvolvedores enfrentam um dilema ao testar APIs de CPF: como validar a integração com dados reais sem gastar dinheiro com planos pagos ou consumir um volume significativo de consultas? A resposta está em usar o plano gratuito como ambiente de testes. A CPFHub.io oferece exatamente isso: o plano gratuito usa o mesmo endpoint de produção e retorna dados reais, permitindo validar toda a integração antes de fazer upgrade.

O que é um ambiente sandbox e por que ele importa

Definição

Um ambiente sandbox é um espaço isolado onde você pode testar integrações sem afetar dados de produção, sem custos significativos e sem riscos de impacto para usuários reais.

Por que testar antes da produção

• Validar o formato da requisição -- Garantir que headers, endpoint e parâmetros estão corretos.

• Tratar erros corretamente -- Verificar como a aplicação reage a erros 400, 401, 429 e 500.

• Medir performance -- Avaliar o tempo de resposta e ajustar timeouts.

• Validar o parsing da resposta -- Confirmar que todos os campos do JSON são processados corretamente.

• Testar fluxos completos -- Simular o fluxo real do usuário, do cadastro ao resultado.

Usando o plano gratuito da CPFHub.io como sandbox

A CPFHub.io não possui um endpoint de sandbox separado. Em vez disso, o plano gratuito funciona como ambiente de testes, com as mesmas características da API de produção:

• Mesmo endpoint -- GET https://api.cpfhub.io/cpf/{CPF_NUMBER}
• Mesmos headers -- x-api-key e Accept: application/json
• Mesmo formato de resposta -- JSON com os mesmos campos
• Dados reais -- As consultas retornam dados reais, não dados fictícios

Limitações do plano gratuito (para testes)

• 50 consultas por mês
• Rate limit de 1 requisição a cada 2 segundos
• SLA de 80%

Essas limitações são adequadas para testes e desenvolvimento, mas insuficientes para produção.

Configurando o ambiente de testes

Passo 1: Criar conta de teste

Crie uma conta gratuita em cpfhub.io

Passo 2: Configurar variáveis de ambiente

# .env.development
CPFHUB_API_KEY=sua_chave_de_teste
CPFHUB_API_URL=https://api.cpfhub.io

# .env.production
CPFHUB_API_KEY=sua_chave_de_producao
CPFHUB_API_URL=https://api.cpfhub.io

A URL é a mesma em ambos os ambientes. A diferenciação é feita pela chave de API, que permite rastrear o consumo de cada ambiente separadamente no dashboard.

Passo 3: Criar um módulo de consulta configurável

// cpfhub-client.js
class CPFHubClient {
    constructor(apiKey, baseUrl = 'https://api.cpfhub.io') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
    }

    async consultarCPF(cpf) {
    const cpfLimpo = cpf.replace(/\D/g, '');
    const response = await fetch(
    `${this.baseUrl}/cpf/${cpfLimpo}`,
    {
    method: 'GET',
    headers: {
    'x-api-key': this.apiKey,
    'Accept': 'application/json'
    },
    signal: AbortSignal.timeout(10000)
    }
    );

    if (!response.ok) {
    throw new Error(`Erro HTTP ${response.status}`);
    }

    return response.json();
    }
}

// Instanciar com base no ambiente
const client = new CPFHubClient(process.env.CPFHUB_API_KEY);
module.exports = client;

Testes que você deve realizar

Teste 1: Requisição bem-sucedida

Verifique se a API retorna status 200 e todos os campos esperados:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json"

Resposta esperada:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Verifique:

• O campo success é true.
• O objeto data contém todos os campos esperados: cpf, name, nameUpper, gender, birthDate, day, month, year.
• Os tipos de dados estão corretos (strings para textos, números para dia/mês/ano).

Teste 2: CPF com formato inválido

Envie um CPF com menos de 11 dígitos ou com caracteres inválidos e verifique se a API retorna status 400:

curl -X GET https://api.cpfhub.io/cpf/123 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json"

Verifique se sua aplicação trata o erro 400 adequadamente, exibindo mensagem amigável ao usuário.

Teste 3: Chave de API inválida

Teste com uma chave errada para confirmar que o erro 401 é tratado:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: CHAVE_INVALIDA" \
    -H "Accept: application/json"

Teste 4: Rate limit

Se possível, faça múltiplas requisições em sequência rápida para testar o comportamento quando o rate limit (429) é atingido. Verifique se o retry com backoff exponencial está funcionando.

Teste 5: Timeout

Configure um timeout baixo (ex: 100ms) temporariamente para verificar se a aplicação trata timeouts corretamente.

Escrevendo testes automatizados

Teste de integração com Jest (Node.js)

const CPFHubClient = require('./cpfhub-client');

describe('CPFHub API Integration', () => {
    const client = new CPFHubClient(process.env.CPFHUB_API_KEY);

    test('deve retornar dados para CPF válido', async () => {
    const resultado = await client.consultarCPF('12345678900');
    expect(resultado.success).toBe(true);
    expect(resultado.data).toHaveProperty('cpf');
    expect(resultado.data).toHaveProperty('name');
    expect(resultado.data).toHaveProperty('gender');
    expect(resultado.data).toHaveProperty('birthDate');
    expect(resultado.data).toHaveProperty('day');
    expect(resultado.data).toHaveProperty('month');
    expect(resultado.data).toHaveProperty('year');
    });

    test('deve lançar erro para CPF inválido', async () => {
    await expect(
    client.consultarCPF('000')
    ).rejects.toThrow('Erro HTTP 400');
    });

    test('deve remover caracteres não numéricos', async () => {
    // O cliente deve limpar o CPF antes de enviar
    const resultado = await client.consultarCPF('123.456.789-00');
    expect(resultado.data.cpf).toBe('12345678900');
    });
});

Usando mocks para testes unitários

Para testes unitários que não devem consumir a API real, use mocks:

jest.mock('./cpfhub-client', () => ({
    consultarCPF: jest.fn().mockResolvedValue({
    success: true,
    data: {
    cpf: '12345678900',
    name: 'João da Silva',
    nameUpper: 'JOAO DA SILVA',
    gender: 'M',
    birthDate: '15/06/1990',
    day: 15,
    month: 6,
    year: 1990
    }
    })
}));

Checklist de migração para produção

Antes de ir para produção, verifique cada item:

• Chave de API de produção -- Substituir a chave de teste pela de produção via variáveis de ambiente.

• Plano adequado ao volume -- Se você espera mais de 50 consultas/mês, faça upgrade para o Plano Pro (R$ 149/mês, 1.000 consultas).

• Tratamento de todos os erros HTTP -- 400, 401, 404, 429, 500 e 503.

• Timeout configurado -- Recomendado: 10 segundos.

• Retry com backoff exponencial -- Para erros 429 e 500.

• Cache implementado -- Evitar consultas duplicadas para o mesmo CPF.

• Logs de consultas -- Registrar data, CPF consultado e resultado para auditoria.

• Chave protegida -- Chave de API apenas no backend, nunca no frontend.

• Monitoramento -- Alertas para falhas de integração em produção.

Monitorando a API em produção

Após a migração, monitore continuamente:

• Taxa de sucesso -- Percentual de consultas com status 200. Deve ser superior a 99%.

• Tempo de resposta -- Acompanhe se o tempo médio se mantém em torno de 900ms.

• Consumo mensal -- O dashboard da CPFHub.io mostra o total de consultas realizadas.

• Erros recorrentes -- Monitore padrões de erro que possam indicar problemas na integração.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

Testar uma API de CPF antes de ir para produção é uma prática que previne problemas, reduz custos e garante uma experiência confiável para o usuário final. O plano gratuito da CPFHub.io serve como ambiente de testes completo — mesmo endpoint, mesmos dados reais, sem custo. Com os testes estruturados, erros tratados e a checklist de migração completa, a transição para produção se torna segura e previsível. Comece agora em cpfhub.io.