# API de CPF com resposta em XML vs JSON: qual formato escolher > Comparativo entre XML e JSON para APIs de consulta de CPF. Entenda as diferenças e saiba por que JSON é o padrão moderno. **Publicado:** 07/06/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/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**](https://www.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 true 12345678900 João da Silva JOAO DA SILVA M 15/06/1990 15 6 1990 ``` ### 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): ```json { "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 | Critério | XML | JSON | | --- | --- | --- | | Verbosidade | Alta (tags de abertura e fechamento) | Baixa (pares chave-valor) | | Tamanho da resposta | ~40% maior | Menor e mais compacto | | Parse (desserialização) | Mais lento | Mais rápido | | Suporte nativo em JavaScript | Não | Sim (JSON.parse) | | Tipagem de dados | Apenas strings | Suporta strings, números, booleanos | | Validação de schema | XSD (robusto) | JSON Schema (adequado) | | Comentários | Suportados | Não suportados | | Namespaces | Suportados | Não suportados | | Uso em SOAP | Padrão | Não aplicável | | Uso em REST | Possível, mas incomum | Padrão | | Legibilidade humana | Razoável | Boa | | Ecossistema de ferramentas | Maduro | Moderno e em expansão | --- ## 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: | Formato | Tamanho da resposta (1 CPF) | Tamanho de 1.000 respostas | | --- | --- | --- | | XML | ~450 bytes | ~450 KB | | JSON | ~280 bytes | ~280 KB | 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: ```javascript // JSON: uma linha para parsear const data = JSON.parse(responseText); console.log(data.data.name); // "João da Silva" ``` ```javascript // 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: ```json { "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**](https://www.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 ```bash curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" ``` ### Python ```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 ```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 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 ```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 ```javascript 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: ```bash 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: ```python 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: ```javascript 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](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade. ### 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 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**](https://www.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](https://www.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.