# API de CPF: como tratar nomes com caracteres especiais e acentos > Aprenda a tratar corretamente nomes com acentos e caracteres especiais retornados pela API de consulta de CPF. **Publicado:** 01/08/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-cpf-tratar-nomes-caracteres-especiais-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](https://unicode.org) 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: ```json { "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 ```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 ```javascript 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 "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 ```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 ```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 ```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 ```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. ```sql -- 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: ```html ``` 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. ### 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) - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [APIs de CPF grátis e tempo de resposta: o que esperar](https://cpfhub.io/blog/apis-de-cpf-gratis-e-tempo-de-resposta-o-que-esperar) --- ## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.