# Como Implementar Verificação de Identidade (CPF) Segura em APIs > Aprenda a implementar verificação de identidade baseada em CPF de forma segura em APIs, com validações em camadas e proteção contra fraudes. **Publicado:** 04/05/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/verificacao-identidade-cpf-segura-apis --- Para implementar verificação de identidade por CPF de forma segura em APIs, estruture o processo em cinco camadas: validação algorítmica local, consulta à API de CPF com cruzamento de nome e data de nascimento, análise comportamental por IP e dispositivo, e confirmação por canal externo. Cada camada adiciona confiança ao resultado sem comprometer a velocidade do onboarding. ## Introdução A verificação de identidade baseada em CPF é uma etapa crítica em processos de onboarding, concessão de crédito e abertura de contas digitais. Uma implementação insegura pode permitir fraudes de identidade, enquanto uma abordagem excessivamente restritiva prejudica a experiência do usuário legítimo. O desafio é encontrar o equilíbrio entre segurança e usabilidade, validando a identidade do titular sem expor dados sensíveis a riscos desnecessários. --- ## Fluxo de verificação em camadas Uma verificação robusta não depende de uma única etapa. Combine múltiplas camadas para aumentar a confiança na identidade declarada: | Camada | Verificação | Objetivo | |--------|------------|----------| | 1 - Formato | Validação algorítmica do CPF | Rejeitar entradas inválidas antes da chamada à API | | 2 - Existência | Consulta à API do CPFHub | Confirmar que o CPF existe e obter dados cadastrais | | 3 - Consistência | Comparação de nome e data de nascimento | Verificar se os dados informados batem com os retornados | | 4 - Comportamento | Análise de padrões de uso | Detectar tentativas automatizadas ou padrões suspeitos | | 5 - Confirmação | Verificação por canal externo (SMS, e-mail) | Validar posse do titular sobre canais cadastrados | --- ## Camada 1: validação algorítmica local Antes de consumir a API, valide o formato do CPF localmente para evitar chamadas desnecessárias: ```python def validar_cpf_local(cpf: str) -> bool: """Validação algorítmica do CPF sem chamada externa.""" cpf = cpf.replace(".", "").replace("-", "").strip() if len(cpf) != 11 or not cpf.isdigit(): return False if cpf == cpf[0] * 11: return False # Cálculo do primeiro dígito verificador soma = sum(int(cpf[i]) * (10 - i) for i in range(9)) resto = soma % 11 digito1 = 0 if resto < 2 else 11 - resto if int(cpf[9]) != digito1: return False # Cálculo do segundo dígito verificador soma = sum(int(cpf[i]) * (11 - i) for i in range(10)) resto = soma % 11 digito2 = 0 if resto < 2 else 11 - resto return int(cpf[10]) == digito2 ``` Essa validação elimina CPFs com formato inválido e sequências repetidas sem gerar tráfego de rede. --- ## Camadas 2 e 3: consulta e consistência Após a validação local, consulte a API para confirmar a existência do CPF e compare os dados retornados com os informados pelo usuário: ```python import requests from difflib import SequenceMatcher def verificar_identidade(cpf: str, nome_informado: str, nascimento_informado: str) -> dict: """Verifica identidade cruzando dados informados com a API.""" if not validar_cpf_local(cpf): return {"valido": False, "motivo": "CPF com formato inválido"} cpf_limpo = cpf.replace(".", "").replace("-", "") response = requests.get( f"https://api.cpfhub.io/cpf/{cpf_limpo}", headers={"x-api-key": "SUA_CHAVE_AQUI"}, timeout=10 ) data = response.json() if not data.get("success"): return {"valido": False, "motivo": "CPF não encontrado"} api_data = data["data"] # Comparação de nome com tolerância a variações similaridade = SequenceMatcher( None, nome_informado.upper().strip(), api_data.get("nameUpper", "") ).ratio() nome_valido = similaridade >= 0.85 # Comparação de data de nascimento nascimento_valido = ( nascimento_informado == api_data.get("birthDate") ) resultado = { "valido": nome_valido and nascimento_valido, "similaridade_nome": round(similaridade, 2), "nome_valido": nome_valido, "nascimento_valido": nascimento_valido } return resultado ``` A comparação de nomes utiliza similaridade textual para tolerar variações como acentos, abreviações e erros de digitação. --- ## Camada 4: análise comportamental Padrões de uso podem revelar tentativas de fraude mesmo quando os dados são tecnicamente corretos: - **Múltiplas consultas sequenciais** -- um mesmo IP consultando dezenas de CPFs diferentes em curto período indica tentativa de enumeração - **Variação geográfica** -- consultas originadas de localizações inconsistentes com o perfil do usuário merecem escrutínio - **Device fingerprinting** -- o mesmo dispositivo tentando cadastrar múltiplas identidades é um forte indicador de fraude - **Velocidade de preenchimento** -- formulários preenchidos instantaneamente sugerem automação por bots - **Horário atípico** -- tentativas de verificação em horários fora do padrão do serviço podem indicar abuso Implemente contadores por IP, por sessão e por dispositivo para aplicar regras de throttling e bloqueio automático. --- ## Proteções contra ataques comuns Ao expor um endpoint de verificação de identidade, proteja-se contra vetores conhecidos: - **Rate limiting agressivo** -- limite a 3-5 tentativas por sessão e 10-20 por IP por hora para evitar força bruta - **CAPTCHA adaptativo** -- apresente desafios após a segunda tentativa falha para bloquear bots - **Sanitização de entrada** -- nunca confie em dados do cliente, valide e sanitize CPF, nome e data antes de processar - **Respostas genéricas** -- não informe ao usuário se o CPF existe ou não, use mensagens como "dados não conferem" para prevenir enumeração - **Timeout de sessão** -- expire sessões de verificação após 10 minutos de inatividade ```javascript // Middleware de rate limiting para verificação de CPF const rateLimit = require("express-rate-limit"); const verificacaoLimiter = rateLimit({ windowMs: 60 * 60 * 1000, // 1 hora max: 15, message: { success: false, error: "Limite de tentativas excedido. Tente novamente em 1 hora." }, standardHeaders: true, legacyHeaders: false, keyGenerator: (req) => req.ip }); app.use("/api/verificar-identidade", verificacaoLimiter); ``` --- ## Perguntas frequentes ### Qual nível de similaridade de nome é seguro para aprovar uma verificação de identidade? Um limiar de 85% de similaridade textual (usando SequenceMatcher ou Levenshtein) é um ponto de partida conservador. Ele tolera abreviações e variações comuns, como "Maria J. Costa" para "Maria José Costa". Para operações de alto risco, eleve o limiar ou exija correspondência completa no sobrenome. ### O que acontece se a API de CPF estiver fora do ar durante a verificação? Implemente degradação controlada: permita que o fluxo continue com validação algorítmica local e agende a verificação via API para reprocessamento assim que a API voltar. Nunca aprove definitivamente sem a confirmação via API — armazene o CPF e os dados informados para verificação posterior. ### Rate limiting e análise comportamental são eficazes contra fraudes em APIs de identidade? São camadas complementares. Rate limiting por IP bloqueia ataques de volume, mas fraudadores sofisticados usam redes distribuídas. A análise comportamental — velocidade de preenchimento, device fingerprint, geolocalização — detecta padrões anômalos que passariam pelo rate limit. Juntas, elevam significativamente o custo do ataque. ### Como garantir conformidade com a LGPD ao usar uma API de CPF para verificação de identidade? Documente a base legal (execução de contrato ou obrigação legal), declare a finalidade na política de privacidade, armazene apenas o necessário — token ou hash em vez do CPF cru — e implemente controle de acesso estrito aos logs de consulta. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação devem seguir o princípio da necessidade. ### 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 A verificação de identidade baseada em CPF deve ser tratada como um processo em camadas, onde cada etapa adiciona confiança ao resultado final. Desde a validação algorítmica local até a análise comportamental, cada camada reduz o risco de fraude e protege tanto o titular dos dados quanto a sua organização. Comece pelo plano gratuito da [**CPFHub.io**](https://www.cpfhub.io/) — 50 consultas mensais sem cartão de crédito — e adicione a primeira camada de verificação de identidade à sua API em [cpfhub.io](https://www.cpfhub.io/).