API de CPF com resposta em XML vs JSON: qual formato escolher

Para APIs de consulta de CPF, JSON é o formato recomendado: é mais compacto, mais rápido de parsear e nativamente suportado em todas as linguagens modernas. XML ainda é relevante para integrações com sistemas legados e ambientes SOAP, mas para a grande maioria dos projetos REST, JSON é a escolha superior.

Introdução

Ao integrar uma API de consulta de CPF em um sistema, uma das primeiras decisões técnicas é o formato de dados da resposta. Historicamente, XML (Extensible Markup Language) foi o padrão dominante em web services, especialmente em integrações com sistemas governamentais e legados. Nos últimos anos, JSON (JavaScript Object Notation) se consolidou como o formato preferido para APIs REST modernas.

A CPFHub.io retorna respostas exclusivamente em JSON, alinhada ao padrão do mercado. Este artigo compara os dois formatos e orienta a escolha certa para cada cenário.

XML vs JSON: visão geral

XML (Extensible Markup Language)

XML é um formato de marcação baseado em tags que foi amplamente adotado nos anos 2000, especialmente em protocolos como SOAP (Simple Object Access Protocol). É verboso, mas altamente estruturado e extensível.

Uma resposta de CPF em XML teria esta aparência:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <success>true</success>
    <data>
    <cpf>12345678900</cpf>
    <name>João da Silva</name>
    <nameUpper>JOAO DA SILVA</nameUpper>
    <gender>M</gender>
    <birthDate>15/06/1990</birthDate>
    <day>15</day>
    <month>6</month>
    <year>1990</year>
    </data>
</response>

JSON (JavaScript Object Notation)

JSON é um formato leve de troca de dados, baseado na sintaxe de objetos JavaScript. É o padrão de facto para APIs REST modernas.

A mesma resposta em JSON (formato utilizado pela CPFHub.io):

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Comparativo detalhado

Vantagens do JSON para APIs de CPF

Menor tamanho de payload

Para consultas de CPF, onde o volume de dados é relativamente pequeno, a diferença de tamanho pode parecer irrelevante. No entanto, em cenários de consulta em lote (centenas ou milhares de CPFs), a diferença acumula:

Uma redução de ~38% no tamanho do payload significa menor consumo de banda e tempos de transferência mais rápidos.

Parse mais rápido

O parsing de JSON é nativamente suportado em praticamente todas as linguagens modernas e é significativamente mais rápido que o parsing de XML:

// JSON: uma linha para parsear
const data = JSON.parse(responseText);
console.log(data.data.name); // "João da Silva"

// XML: requer parser dedicado
const parser = new DOMParser();
const xmlDoc = parser.parseFromString(responseText, 'text/xml');
const name = xmlDoc.getElementsByTagName('name')[0].textContent;

Tipagem nativa

Em JSON, números são números e booleanos são booleanos. Em XML, tudo é string e precisa ser convertido manualmente:

{
    "day": 15,
    "month": 6,
    "year": 1990,
    "success": true
}

No JSON acima, day, month e year já são inteiros, e success já é booleano. Em XML, esses mesmos valores seriam strings que precisariam de conversão.

Quando XML ainda faz sentido

Apesar das vantagens do JSON, existem cenários onde XML é necessário ou preferível:

Integração com sistemas legados

Muitos sistemas ERP, plataformas governamentais e web services corporativos ainda operam exclusivamente com XML/SOAP. Se o seu sistema precisa enviar dados de CPF para um desses sistemas, pode ser necessário converter a resposta JSON em XML.

Validação rigorosa de schema

XML Schema Definition (XSD) oferece validação mais rigorosa e detalhada do que JSON Schema. Em ambientes onde a conformidade de dados é regulada (como integrações bancárias ou governamentais), XSD pode ser um requisito.

Documentos complexos com namespaces

Para respostas que combinam dados de múltiplas fontes com namespaces distintos, XML oferece suporte nativo. Isso é raro em APIs de CPF, mas comum em integrações de nota fiscal eletrônica (NF-e).

Trabalhando com a resposta JSON da CPFHub.io

A API da CPFHub.io retorna JSON estruturado com os campos cpf, name, nameUpper, gender, birthDate, day, month e year. Veja exemplos de consumo nas principais linguagens:

cURL

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

Python

import requests

response = requests.get(
    "https://api.cpfhub.io/cpf/12345678900",
    headers={
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    },
    timeout=10
)

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

Java

import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.cpfhub.io/cpf/12345678900"))
    .header("x-api-key", "SUA_CHAVE_DE_API")
    .header("Accept", "application/json")
    .GET()
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

// Usar biblioteca como Gson ou Jackson para parsear
System.out.println(response.body());

Convertendo JSON para XML quando necessário

Se o seu sistema legado exige XML, é possível converter a resposta JSON da CPFHub.io:

Python

import requests
import dicttoxml
from xml.dom.minidom import parseString

# Consultar API (retorna JSON)
response = requests.get(
    "https://api.cpfhub.io/cpf/12345678900",
    headers={
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    },
    timeout=10
)

data = response.json()

# Converter para XML
xml_bytes = dicttoxml.dicttoxml(data, custom_root="response")
xml_string = parseString(xml_bytes).toprettyxml()
print(xml_string)

Node.js

const { js2xml } = require('xml-js');

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

const jsonData = await response.json();

// Converter para XML
const xmlString = js2xml(jsonData, { compact: true, spaces: 2 });
console.log(xmlString);

Boas práticas para consumo de APIs JSON

Sempre especifique o Accept header

Enviar o header Accept: application/json garante que a API retorne no formato esperado:

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

Trate erros de parsing

Sempre envolva o parsing JSON em blocos try/catch para lidar com respostas inesperadas:

try:
    data = response.json()
except ValueError:
    print("Resposta não é um JSON válido")

Valide a estrutura da resposta

Antes de acessar campos específicos, verifique se a resposta contém os campos esperados:

const data = await response.json();

if (data.success && data.data && data.data.name) {
    console.log(`Nome: ${data.data.name}`);
} else {
    console.log('Resposta inesperada da API');
}

Perguntas frequentes

JSON e XML retornam os mesmos dados na consulta de CPF?

Sim, o conteúdo é idêntico — nome, data de nascimento, gênero e status. A diferença está apenas na estrutura e no tamanho do payload. A CPFHub.io retorna exclusivamente JSON; se o seu sistema exige XML, a conversão deve ser feita na camada de integração.

É possível configurar a API da CPFHub.io para responder em XML?

Não. A API da CPFHub.io retorna apenas JSON. Para sistemas legados que exigem XML, basta converter o JSON recebido usando bibliotecas como dicttoxml (Python) ou xml-js (Node.js), conforme os exemplos neste artigo.

Qual o impacto real de usar XML em vez de JSON em consultas de CPF em lote?

Em 1.000 consultas, a resposta XML ocupa em média ~38% mais banda que o equivalente JSON — cerca de 170 KB a mais por lote. Em volumes menores isso é irrelevante, mas em integrações com milhares de consultas diárias, a diferença impacta latência e custo de transferência.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Conclusão

Para APIs modernas de consulta de CPF, JSON é o formato recomendado por ser mais leve, mais rápido de parsear e nativamente suportado em todas as linguagens de programação populares. XML ainda tem seu lugar em integrações com sistemas legados e ambientes que exigem validação rigorosa de schema, mas para a grande maioria dos casos de uso, JSON é superior.

A API da CPFHub.io adota JSON como único formato de resposta, garantindo compatibilidade imediata com qualquer stack moderna e tempos de resposta em torno de 900ms.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e integre a validação de CPF em JSON ao seu projeto hoje mesmo.