# Como testar uma API de CPF em ambiente sandbox antes de ir para produção > Aprenda a testar uma API de consulta de CPF em ambiente sandbox, validar a integração e migrar para produção com segurança usando a CPFHub.io. **Publicado:** 08/04/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-testar-api-cpf-ambiente-sandbox-producao --- ## 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**](https://www.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](https://www.cpfhub.io/) ### Passo 2: Configurar variáveis de ambiente ```bash # .env.development CPFHUB_API_KEY=sua_chave_de_teste CPFHUB_API_URL=https://api.cpfhub.io ``` ```bash # .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 ```javascript // 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: ```bash curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" ``` Resposta esperada: ```json { "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: ```bash 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: ```bash 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) ```javascript 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: ```javascript 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](https://www.gov.br/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. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## 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**](https://www.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](https://www.cpfhub.io/).