# Como Criar um Ambiente Seguro para Testes de APIs de CPF > Aprenda a criar um ambiente de testes seguro para APIs de CPF, com dados fictícios, isolamento de ambientes e práticas de segurança. **Publicado:** 10/05/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/ambiente-seguro-testes-apis-cpf --- Para criar um ambiente seguro de testes para APIs de CPF, use CPFs gerados algoritmicamente (nunca dados reais), mantenha chaves de API diferentes para cada ambiente (desenvolvimento, staging e produção), implemente mocks nas chamadas à API em testes automatizados e execute rotinas de limpeza após cada execução. Essa combinação garante cobertura completa de testes sem expor dados pessoais de titulares reais. ## Introdução Testar integrações com APIs de CPF é uma etapa essencial do desenvolvimento, mas usar dados reais de CPF em ambientes de teste representa um risco significativo à privacidade. Ambientes de staging e desenvolvimento frequentemente possuem controles de segurança menos rigorosos que produção, e o uso de dados pessoais reais nesses contextos pode violar a LGPD. Este guia cobre as principais práticas para criar um ambiente de testes seguro para APIs de CPF sem comprometer dados pessoais de titulares reais. --- ## Princípios de um ambiente de testes seguro Um ambiente de testes para APIs de CPF deve seguir princípios claros: | Princípio | Descrição | Implementação | |-----------|-----------|---------------| | Isolamento | Testes não afetam produção | Ambientes completamente separados | | Dados fictícios | Nenhum CPF real em testes | Geradores de CPF válidos algoritmicamente | | Credenciais separadas | Chaves de API distintas por ambiente | API keys diferentes para dev/staging/prod | | Paridade | Ambiente de teste replica produção | Mesma stack, configurações similares | | Limpeza automática | Dados de teste não acumulam | Scripts de cleanup pós-execução | | Rastreabilidade | Testes são auditáveis | Logs de execução com identificação | --- ## Geração de CPFs fictícios para testes Nunca use CPFs reais em testes. Gere CPFs algoritmicamente válidos que não pertencem a ninguém: ```python import random def gerar_cpf_ficticio() -> str: """Gera um CPF válido algoritmicamente para uso em testes.""" digitos = [random.randint(0, 9) for _ in range(9)] # Primeiro dígito verificador soma = sum(d * (10 - i) for i, d in enumerate(digitos)) resto = soma % 11 digitos.append(0 if resto < 2 else 11 - resto) # Segundo dígito verificador soma = sum(d * (11 - i) for i, d in enumerate(digitos)) resto = soma % 11 digitos.append(0 if resto < 2 else 11 - resto) cpf = "".join(map(str, digitos)) return f"{cpf[:3]}.{cpf[3:6]}.{cpf[6:9]}-{cpf[9:]}" def gerar_lote_cpfs(quantidade: int) -> list: """Gera um lote de CPFs fictícios únicos.""" cpfs = set() while len(cpfs) < quantidade: cpfs.add(gerar_cpf_ficticio()) return list(cpfs) # Gerar 10 CPFs para testes cpfs_teste = gerar_lote_cpfs(10) for cpf in cpfs_teste: print(cpf) ``` Esses CPFs passam na validação algorítmica, mas por serem gerados aleatoriamente não correspondem a pessoas reais no cadastro da [Receita Federal](https://www.gov.br/receitafederal). --- ## Estrutura de ambientes isolados Mantenha ambientes completamente separados para cada fase do ciclo de desenvolvimento: - **Desenvolvimento local** -- cada desenvolvedor executa testes contra mocks locais, sem chamadas externas - **Integração (CI)** -- pipeline automatizado que executa testes contra um stub da API com respostas pré-definidas - **Staging** -- réplica do ambiente de produção com chaves de API de teste e dados fictícios - **Produção** -- único ambiente com acesso a dados reais, protegido com todos os controles de segurança ```javascript // Configuração de ambientes com variáveis de ambiente const config = { development: { apiUrl: "http://localhost:3001/mock/cpf", apiKey: "dev_key_nao_funciona_em_prod", logLevel: "debug", useMock: true }, staging: { apiUrl: "https://api.cpfhub.io/cpf", apiKey: process.env.CPFHUB_STAGING_KEY, logLevel: "info", useMock: false }, production: { apiUrl: "https://api.cpfhub.io/cpf", apiKey: process.env.CPFHUB_PROD_KEY, logLevel: "warn", useMock: false } }; const env = process.env.NODE_ENV || "development"; const currentConfig = config[env]; async function consultarCPF(cpf) { if (currentConfig.useMock) { return { success: true, data: { cpf: cpf, name: "Pessoa Fictícia de Teste", nameUpper: "PESSOA FICTICIA DE TESTE", gender: "M", birthDate: "1990-01-01", day: "01", month: "01", year: "1990" } }; } const response = await fetch( `${currentConfig.apiUrl}/${cpf}`, { headers: { "x-api-key": currentConfig.apiKey } } ); return response.json(); } ``` --- ## Testes automatizados com mock Escreva testes automatizados que não dependam de chamadas reais à API. Use mocks para simular respostas: - **Teste de resposta válida** -- verifique que seu código processa corretamente uma resposta de sucesso com todos os campos - **Teste de CPF inválido** -- simule uma resposta de erro e verifique que seu código trata adequadamente - **Teste de timeout** -- simule latência alta para validar que timeouts são tratados sem expor dados - **Teste de erro de rede** -- simule falha de conexão para verificar resiliência e fallback - **Teste de resposta malformada** -- simule JSON inválido para garantir que parsing errors são capturados Ferramentas como Jest (JavaScript), pytest com pytest-mock (Python) e WireMock (Java) facilitam a criação desses cenários sem chamadas reais. --- ## Limpeza e ciclo de vida dos dados de teste Mesmo dados fictícios devem ser gerenciados com disciplina: - **Cleanup pós-teste** -- scripts automatizados que limpam o banco de dados de teste após cada execução - **Dados efêmeros** -- utilize bancos de dados in-memory (SQLite, H2) para testes que não precisam de persistência - **TTL em caches de teste** -- configure expiração de 5 minutos em caches usados durante testes - **Rotação de ambientes** -- destrua e recrie ambientes de staging periodicamente para evitar acúmulo de dados - **Identificação clara** -- prefixe dados de teste com marcadores como "TEST_" para facilitar identificação e exclusão ```bash # Script de limpeza pós-teste #!/bin/bash echo "Limpando dados de teste..." # Limpar banco de testes psql -U test_user -d test_db \ -c "DELETE FROM consultas_cpf WHERE ambiente = 'test';" # Limpar cache Redis de teste redis-cli -n 1 FLUSHDB # Remover logs de teste rm -f /var/log/app/test_*.log echo "Limpeza concluída." ``` --- ## Perguntas frequentes ### CPFs gerados algoritmicamente para testes passam na validação da API da CPFHub.io? Não. CPFs gerados algoritmicamente são matematicamente válidos, mas não correspondem a registros reais na base da Receita Federal. A API retornará `success: false` para esses CPFs — o comportamento correto para testar o fluxo de CPF não encontrado. Para testar o fluxo positivo, use o plano gratuito com um CPF real em ambiente de staging isolado. ### É possível usar o próprio CPF do desenvolvedor para testes de integração? Tecnicamente sim, mas não é recomendado. Dados pessoais reais em logs de desenvolvimento, repositórios e bancos de teste violam a LGPD e princípios de privacy by design. Use CPFs gerados algoritmicamente para testes negativos e, para testes positivos, um CPF real apenas em staging com controles adequados — nunca em desenvolvimento local. ### Como simular erros de rate limit e timeout da API em testes automatizados? Use mocks que retornam status HTTP específicos: 429 para rate limit, 504 para timeout e 503 para indisponibilidade. Ferramentas como WireMock (Java), nock (Node.js) e pytest-responses (Python) permitem configurar essas respostas sem depender da API real. Teste também o comportamento pós-erro — retry com backoff, fallback gracioso e logging adequado. ### Chaves de API de teste e de produção devem ser rotacionadas com frequência? Sim. Rotacione as chaves de staging a cada ciclo de desenvolvimento e as de produção ao menos a cada 90 dias ou sempre que houver mudança de equipe. Nunca use a mesma chave em múltiplos ambientes — além do risco de exposição, dificulta a auditoria de uso. O painel da CPFHub.io permite gerar e revogar chaves de API a qualquer momento. ### Leia também - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) --- ## Conclusão Um ambiente de testes seguro para APIs de CPF protege dados pessoais reais enquanto permite validação completa da integração. A combinação de CPFs fictícios gerados algoritmicamente, ambientes isolados, mocks automatizados e rotinas de limpeza garante que o ciclo de desenvolvimento não comprometa a privacidade dos titulares. A API do [cpfhub.io](https://www.cpfhub.io/) já está disponível no plano gratuito — comece hoje com 50 consultas mensais sem cartão de crédito e monte seu ambiente de testes em minutos.