# API de CPF: como lidar com inconsistências entre nome social e nome civil > Saiba como lidar com diferenças entre nome social e nome civil ao validar CPF via API. Boas práticas para comparação de nomes e inclusão. **Publicado:** 03/01/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-de-cpf-como-lidar-com-inconsistencias-entre-nome-social-e-nome-civil --- Quando uma API de CPF retorna o nome civil registrado no cadastro federal e o usuário informa o nome social, a comparação direta falha mesmo que a identidade seja legítima. A solução está em aplicar normalização, comparação parcial e métricas de similaridade — combinadas com uma política de revisão humana para casos ambíguos — garantindo segurança sem excluir pessoas. ## Introdução Quando uma aplicação válida a identidade de um usuário comparando o nome informado com o nome retornado pela API de CPF, uma situação recorrente surge: o nome informado pelo usuário pode ser o nome social, enquanto a API retorna o nome civil registrado no cadastro. Essa divergência, se não tratada adequadamente, pode resultar em rejeições indevidas de cadastros legítimos e uma experiência excludente para o usuário. --- ## Nome social versus nome civil ### Nome civil O nome civil é o nome registrado em cartório no nascimento ou alterado judicialmente. É o nome que consta oficialmente nos documentos de identidade e nos cadastros federais, incluindo o CPF. ### Nome social O nome social é aquele adotado por uma pessoa para ser identificada em conformidade com sua identidade de gênero. Desde 2018, a alteração do nome no registro civil é possível para pessoas transgênero, e o nome social também pode ser adotado em diversos contextos sem necessidade de alteração judicial. O [Decreto nº 8.727/2016](http://www.planalto.gov.br/ccivil_03/_ato2015-2018/2016/decreto/d8727.htm) regulamentou o uso do nome social no âmbito da administração pública federal. ### O que a API retorna A API da [**CPFHub.io**](https://www.cpfhub.io/) consulta o cadastro federal e retorna o nome civil registrado no campo `name`. Se a pessoa já alterou o nome oficialmente, esse campo refletirá o nome atualizado. Caso contrário, haverá divergência em relação ao nome social informado pelo usuário. ```bash curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" \ --max-time 10 ``` ```json { "success": true, "data": { "cpf": "12345678900", "name": "Maria Oliveira Santos", "nameUpper": "MARIA OLIVEIRA SANTOS", "gender": "F", "birthDate": "22/03/1985", "day": 22, "month": 3, "year": 1985 } } ``` Se a pessoa já alterou o nome oficialmente, o campo `name` refletirá o nome atualizado. Porém, se a alteração ainda não foi processada ou se a pessoa utiliza o nome social sem ter feito a alteração formal, haverá divergência. --- ## Cenários de inconsistência * **Nome social não formalizado** -- O usuário informa "Lucas Silva" (nome social), mas a API retorna "Maria Silva Santos" (nome civil). * **Nomes compostos abreviados** -- O usuário informa "Ana Santos", mas a API retorna "Ana Maria dos Santos Oliveira". * **Variações de grafia** -- O usuário digita "Joao" (sem acento) e a API retorna "João". * **Sobrenome do cônjuge** -- O usuário adicionou ou removeu um sobrenome após o casamento. --- ## Estratégias de comparação flexível ### Comparação com normalização A primeira etapa é normalizar os nomes antes de comparar, removendo acentos, convertendo para minúsculas e tratando espaços extras: ```python import unicodedata import re def normalizar_nome(nome): # Remover acentos nfkd = unicodedata.normalize('NFKD', nome) sem_acentos = ''.join(c for c in nfkd if not unicodedata.combining(c)) # Converter para minúsculas e remover espaços extras normalizado = re.sub(r'\s+', ' ', sem_acentos.lower().strip()) return normalizado # Exemplo nome_informado = "João da Silva" nome_api = "JOAO DA SILVA" print(normalizar_nome(nome_informado)) # "joao da silva" print(normalizar_nome(nome_api)) # "joao da silva" ``` ### Comparação parcial (containment) Verificar se o nome informado está contido no nome oficial, ou vice-versa: ```python def nomes_compativeis(nome_informado, nome_oficial): info = normalizar_nome(nome_informado) oficial = normalizar_nome(nome_oficial) # Correspondência exata if info == oficial: return True # Nome informado está contido no oficial if info in oficial: return True # Primeiro e último nome coincidem partes_info = info.split() partes_oficial = oficial.split() if len(partes_info) >= 2 and len(partes_oficial) >= 2: primeiro_coincide = partes_info[0] == partes_oficial[0] ultimo_coincide = partes_info[-1] == partes_oficial[-1] if primeiro_coincide and ultimo_coincide: return True return False ``` ### Similaridade com algoritmo de distância Para casos mais complexos, a distância de Levenshtein pode medir a similaridade entre dois nomes: ```python def distancia_levenshtein(s1, s2): if len(s1) < len(s2): return distancia_levenshtein(s2, s1) if len(s2) == 0: return len(s1) linha_anterior = range(len(s2) + 1) for i, c1 in enumerate(s1): linha_atual = [i + 1] for j, c2 in enumerate(s2): inserir = linha_anterior[j + 1] + 1 deletar = linha_atual[j] + 1 substituir = linha_anterior[j] + (c1 != c2) linha_atual.append(min(inserir, deletar, substituir)) linha_anterior = linha_atual return linha_anterior[-1] def similaridade_nomes(nome1, nome2, limiar=0.8): n1 = normalizar_nome(nome1) n2 = normalizar_nome(nome2) distancia = distancia_levenshtein(n1, n2) tamanho_max = max(len(n1), len(n2)) if tamanho_max == 0: return True similaridade = 1 - (distancia / tamanho_max) return similaridade >= limiar ``` --- ## Implementação completa com múltiplas estratégias Uma abordagem robusta combina as estratégias anteriores em uma função que retorna um nível de confiança: ```python import requests def validar_nome_cpf(cpf, nome_informado): url = f"https://api.cpfhub.io/cpf/{cpf}" headers = { "x-api-key": "SUA_CHAVE_DE_API", "Accept": "application/json" } response = requests.get(url, headers=headers, timeout=10) dados = response.json() if not dados.get("success"): return {"valido": False, "confianca": 0, "motivo": "CPF não encontrado"} nome_oficial = dados["data"]["name"] # Nível 1: Correspondência exata (normalizada) if normalizar_nome(nome_informado) == normalizar_nome(nome_oficial): return {"valido": True, "confianca": 100, "nivel": "exato"} # Nível 2: Correspondência parcial if nomes_compativeis(nome_informado, nome_oficial): return {"valido": True, "confianca": 80, "nivel": "parcial"} # Nível 3: Similaridade alta if similaridade_nomes(nome_informado, nome_oficial, limiar=0.75): return {"valido": True, "confianca": 60, "nivel": "similar"} # Nenhuma correspondência return { "valido": False, "confianca": 0, "nivel": "incompatível", "nome_oficial": nome_oficial } ``` --- ## Boas práticas para inclusão e segurança * **Permita campo de nome social** -- Ofereça um campo separado para nome social no formulário de cadastro, sem exigir que ele corresponda ao nome civil. * **Não rejeite automaticamente por divergência de nome** -- Em vez de bloquear o cadastro, sinalize a divergência para revisão humana quando a confiança for baixa. * **Use múltiplos fatores de validação** -- Combine a comparação de nome com a verificação de data de nascimento. Se a data confere mas o nome diverge, pode se tratar de nome social. * **Respeite a LGPD** -- Não armazene mais dados do que o necessário. Se o nome social é o que o usuário deseja usar, esse deve ser o nome principal no sistema. * **Documente o critério de aceitação** -- Defina claramente qual nível de confiança é aceitável para cada processo (onboarding, antifraude, emissão de NF). --- ## Perguntas frequentes ### A API de CPF retorna o nome social ou o nome civil? A API retorna o nome registrado no cadastro federal, que é o nome civil. Se a pessoa já formalizou a alteração de nome (inclusive para nome social), o campo `name` já virá atualizado. Caso a alteração não tenha sido processada, a comparação com o nome social informado pelo usuário resultará em divergência que precisa ser tratada pela aplicação. ### O que fazer quando o nível de confiança da comparação é baixo? Quando o score de similaridade fica abaixo do limiar definido, a melhor prática é não bloquear automaticamente o cadastro. Encaminhe o caso para revisão humana, registre a divergência e, se possível, solicite um documento adicional ao usuário. Bloqueio automático por divergência de nome pode excluir pessoas legítimas que simplesmente usam o nome social. ### Como equilibrar segurança e inclusão na comparação de nomes? Defina níveis de tolerância por contexto: para processos de onboarding básico, uma similaridade de 70% pode ser suficiente; para emissão de notas fiscais ou contratos de alto valor, exija correspondência parcial entre primeiro e último nome confirmada por data de nascimento. Documente o critério e revisão periódica é recomendada. ### Quanto tempo a API leva para retornar o nome cadastrado? A API da CPFHub.io retorna a resposta com latência de aproximadamente 900ms. O campo `name` traz o nome civil em formato título e `nameUpper` traz em caixa alta — utilize `nameUpper` se quiser normalização de maiúsculas antes de aplicar seus algoritmos de comparação. ### 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 Lidar com inconsistências entre nome social e nome civil é um desafio que exige equilíbrio entre segurança e inclusão. Uma comparação rígida de igualdade exata pode excluir pessoas legítimas, enquanto uma comparação muito permissiva pode abrir brechas para fraudes. A combinação de normalização, comparação parcial e métricas de similaridade permite criar um sistema que respeita a diversidade sem comprometer a verificação de identidade. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a construir fluxos de validação de nome que tratam corretamente tanto o nome civil quanto o nome social dos seus usuários.