API de CPF: como lidar com inconsistências 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 regulamentou o uso do nome social no âmbito da administração pública federal.

O que a API retorna

A API da 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.

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

{
    "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:

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:

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:

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:

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.

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 — 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.