API de CPF: como tratar nomes com caracteres especiais e acentos

A API de CPF retorna nomes em UTF-8, mas erros de encoding, normalização Unicode inconsistente e bancos de dados mal configurados podem corromper ou distorcer esses dados. Para tratar nomes com acentos e caracteres especiais corretamente, é preciso garantir UTF-8 explícito na leitura da resposta, normalizar strings para NFC antes de comparar, e configurar o banco de dados com charset utf8mb4. O padrão Unicode define as formas canônicas NFC e NFD que regem essas comparações.

Introdução

Nomes brasileiros frequentemente contêm acentos, cedilhas e caracteres especiais como José, Conceição, Gonçalves ou Inácio. Ao integrar uma API de consulta de CPF, tratar corretamente esses caracteres é essencial para evitar erros de comparação, problemas de exibição e inconsistências no banco de dados.

Como a API retorna nomes

A API da CPFHub.io retorna os dados em JSON codificado em UTF-8. A resposta inclui dois campos de nome:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Jose da Conceicao",
    "nameUpper": "JOSE DA CONCEICAO",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

• name -- Nome com formatação original.

• nameUpper -- Nome em letras maiúsculas.

Ambos os campos podem conter caracteres acentuados, e o encoding correto depende de como sua aplicação processa a resposta.

Problemas comuns com caracteres especiais

1. Encoding incorreto

Se o seu sistema não interpreta UTF-8 corretamente, nomes como "Conceição" podem aparecer como "Conceição" ou caracteres ilegíveis.

2. Comparação de strings falha

Comparar "José" com "José" pode falhar se um dos valores estiver normalizado de forma diferente (NFC vs. NFD).

3. Armazenamento truncado

Bancos de dados configurados com charset latin1 podem truncar ou corromper caracteres multibyte.

4. Problemas em URLs e query strings

Nomes com acentos precisam de encoding especial quando usados em URLs.

Garantindo UTF-8 na requisição

Python

import requests

url = 'https://api.cpfhub.io/cpf/12345678900'
headers = {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers, timeout=15)
response.encoding = 'utf-8'

data = response.json()
nome = data['data']['name']
print(f'Nome: {nome}')
print(f'Tipo: {type(nome)}')

A biblioteca requests em Python normalmente detecta UTF-8 automaticamente, mas definir response.encoding explicitamente evita problemas com detecção incorreta.

Node.js

const response = await fetch('https://api.cpfhub.io/cpf/12345678900', {
    method: 'GET',
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json; charset=utf-8'
    },
    signal: AbortSignal.timeout(15000)
});

const data = await response.json();
console.log(`Nome: ${data.data.name}`);

PHP

<?php
$cpf = '12345678900';
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.cpfhub.io/cpf/{$cpf}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
    'x-api-key: SUA_CHAVE_DE_API',
    'Accept: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

// Garantir UTF-8
$response = mb_convert_encoding($response, 'UTF-8', 'auto');
$data = json_decode($response, true);

echo 'Nome: ' . $data['data']['name'] . PHP_EOL;

Normalização Unicode

O Unicode permite representar o mesmo caractere de formas diferentes. O "á" com acento pode ser:

• NFC (composta) -- Um único code point: U+00E1

• NFD (decomposta) -- Dois code points: U+0061 + U+0301

Para comparações confiáveis, normalize os nomes para NFC:

Python

import unicodedata

nome_api = data['data']['name']
nome_normalizado = unicodedata.normalize('NFC', nome_api)

# Comparação segura
nome_formulario = 'Jose da Conceicao'
nome_formulario_normalizado = unicodedata.normalize('NFC', nome_formulario)

nomes_iguais = nome_normalizado.lower() == nome_formulario_normalizado.lower()

JavaScript

const nomeApi = data.data.name;
const nomeNormalizado = nomeApi.normalize('NFC');

const nomeFormulario = 'Jose da Conceicao';
const nomesIguais = nomeNormalizado.toLowerCase() === nomeFormulario.normalize('NFC').toLowerCase();

Removendo acentos para comparação flexível

Em alguns casos, você precisa comparar nomes ignorando acentos (por exemplo, quando o usuário digita sem acentos):

Python

import unicodedata

def remover_acentos(texto):
    nfkd = unicodedata.normalize('NFKD', texto)
    return ''.join(c for c in nfkd if not unicodedata.combining(c))

nome_api = 'Jose da Conceicao'
nome_sem_acentos = remover_acentos(nome_api)
# Resultado: 'Jose da Conceicao'

nome_digitado = 'jose da conceicao'
match = remover_acentos(nome_api).lower() == remover_acentos(nome_digitado).lower()

JavaScript

function removerAcentos(texto) {
    return texto.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
}

const nomeApi = 'Jose da Conceicao';
const nomeDigitado = 'jose da conceicao';

const match = removerAcentos(nomeApi).toLowerCase() === removerAcentos(nomeDigitado).toLowerCase();

Armazenamento no banco de dados

Garanta que seu banco de dados suporte UTF-8 corretamente:

• MySQL -- Use charset utf8mb4 (não utf8, que suporta apenas 3 bytes).

• PostgreSQL -- Encoding UTF8 é o padrão, mas verifique a collation.

• SQLite -- Suporta UTF-8 nativamente.

• MongoDB -- Armazena strings como UTF-8 por padrão.

-- MySQL: verificar charset da tabela
ALTER TABLE clientes CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- PostgreSQL: verificar encoding
SHOW server_encoding;

Exibição no frontend

Certifique-se de que o HTML declare UTF-8:

<meta charset="UTF-8">

E que respostas da sua API intermediária também retornem o header correto:

Content-Type: application/json; charset=utf-8

Checklist de boas práticas

• Definir encoding UTF-8 explicitamente ao consumir a API.

• Normalizar strings para NFC antes de armazenar e comparar.

• Usar funções de remoção de acentos para comparações flexíveis.

• Configurar banco de dados com charset utf8mb4 (MySQL) ou UTF8 (PostgreSQL).

• Declarar charset UTF-8 no HTML e nos headers da sua API.

• Testar com nomes que contêm acentos, cedilhas e caracteres especiais.

Perguntas frequentes

Como a API de CPF retorna nomes com acentos?

A API da CPFHub.io retorna o JSON sempre em UTF-8. Os campos name e nameUpper preservam acentos e cedilhas conforme o cadastro da Receita Federal. O problema costuma estar no cliente que consome a resposta: se a biblioteca HTTP não declarar o encoding correto, os bytes multibyte são interpretados de forma errada e o nome aparece corrompido.

Qual forma Unicode devo usar para comparar nomes de CPF?

Use NFC (forma composta) tanto para o valor retornado pela API quanto para o valor digitado pelo usuário. Em Python, aplique unicodedata.normalize('NFC', texto); em JavaScript, texto.normalize('NFC'). Sem essa normalização, "José" em NFC e "José" em NFD são strings diferentes, mesmo que visualmente idênticas, o que causa falsos negativos na comparação.

O banco de dados MySQL precisa de configuração especial para nomes acentuados?

Sim. O charset utf8 do MySQL suporta apenas 3 bytes por caractere e pode corromper alguns caracteres Unicode. O correto é usar utf8mb4 com a collation utf8mb4_unicode_ci. Para converter uma tabela existente: ALTER TABLE clientes CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci.

Como lidar com usuários que digitam o nome sem acentos no formulário?

Normalize os dois lados para NFKD e remova os combining characters antes de comparar. Em Python: unicodedata.normalize('NFKD', texto) seguido de um filtro que elimina caracteres de categoria "Mn". Em JavaScript: texto.normalize('NFD').replace(/[\u0300-\u036f]/g, ''). Assim, "Jose" bate com "José" na comparação.

Conclusão

Tratar corretamente nomes com caracteres especiais e acentos é decisivo para a qualidade da sua integração com APIs de CPF. Com normalização Unicode, encoding UTF-8 consistente e banco de dados configurado corretamente, você evita erros de comparação e garante integridade dos dados cadastrais.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito.