# API de CPF: como funciona o versionamento e breaking changes > Entenda como funciona o versionamento de APIs de CPF, o que são breaking changes e como proteger sua integração contra mudancas. **Publicado:** 15/10/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-cpf-versionamento-breaking-changes --- APIs de CPF evoluem ao longo do tempo: novos campos são adicionados, formatos mudam e endpoints podem ser redesenhados. Quando essas mudanças quebram integrações existentes, são chamadas de breaking changes. A CPFHub.io adota uma política de versionamento estável, mas saber como se proteger é essencial para qualquer integração de longa duração. ## Introdução APIs evoluem. Novos campos são adicionados, formatos de resposta mudam e endpoints podem ser redesenhados. Quando essas mudancas quebram integrações existentes, são chamadas de breaking changes. Saber como o versionamento funciona e como proteger sua aplicação contra essas mudancas e essencial para manter a estabilidade do sistema. --- ## O que é versionamento de API Versionamento é a prática de manter diferentes versões de uma API disponíveis simultaneamente, permitindo que consumidores migrem no seu próprio ritmo. As estrategias mais comuns são: * **URL path** -- `https://api.exemplo.com/v1/recurso` * **Header** -- `Accept: application/vnd.api+json;version=1` * **Query parameter** -- `https://api.exemplo.com/recurso?version=1` Cada abordagem tem vantagens e desvantagens, mas todas buscam o mesmo objetivo: permitir evolucao sem quebrar consumidores existentes. --- ## O que são breaking changes Um breaking change é qualquer alteracao que faz uma integração existente parar de funcionar. Exemplos: | Tipo de mudanca | Breaking? | Exemplo | | --- | --- | --- | | Adicionar campo novo na resposta | Não | Adicionar `gender` ao JSON | | Remover campo existente | Sim | Remover `name` da resposta | | Renomear campo | Sim | Mudar `name` para `fullName` | | Alterar tipo de dado | Sim | Mudar `year` de number para string | | Mudar método HTTP | Sim | Mudar de POST para GET | | Alterar formato da URL | Sim | Mudar `/api/cpf` para `/cpf/{cpf}` | | Adicionar campo obrigatório no request | Sim | Exigir novo header | --- ## Construindo integração resiliente ### 1. Ignore campos desconhecidos Sua aplicação deve aceitar campos novos sem quebrar. Nunca valide que a resposta tenha **exatamente** os campos esperados: ```python import requests def processar_resposta_cpf(cpf): 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=15) data = response.json() if data.get('success'): # Acessar apenas os campos que voce precisa # Campos novos sao ignorados automaticamente return { 'nome': data['data'].get('name'), 'genero': data['data'].get('gender'), 'nascimento': data['data'].get('birthDate') } return None ``` ### 2. Use `.get()` com valores padrão Sempre acesse campos com fallback para evitar `KeyError` se um campo for removido: ```python nome = data['data'].get('name', 'Nome nao disponivel') genero = data['data'].get('gender', 'N/A') ano = data['data'].get('year', 0) ``` ### 3. Valide campos críticos Defina quais campos são essenciais para o seu fluxo e valide apenas esses: ```python CAMPOS_OBRIGATORIOS = ['cpf', 'name'] def validar_resposta(data): if not data.get('success'): return False for campo in CAMPOS_OBRIGATORIOS: if campo not in data.get('data', {}): return False return True ``` --- ## Testes de contrato Testes de contrato verificam que a API continua retornando a estrutura esperada. Execute-os periodicamente: ```python import pytest import requests @pytest.mark.contract def test_contrato_api_cpfhub(): """Verifica se a API mantém o contrato esperado.""" url = 'https://api.cpfhub.io/cpf/00000000000' headers = { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' } response = requests.get(url, headers=headers, timeout=15) assert response.status_code in [200, 404] data = response.json() assert 'success' in data if data['success']: assert 'data' in data campos_esperados = ['cpf', 'name', 'nameUpper', 'gender', 'birthDate'] for campo in campos_esperados: assert campo in data['data'], f'Campo {campo} ausente' # Verificar tipos assert isinstance(data['data']['cpf'], str) assert isinstance(data['data']['name'], str) assert isinstance(data['data']['gender'], str) ``` --- ## Camada de abstração (adapter pattern) Crie uma camada intermediaria que isola seu código de negócios da estrutura da API: ```javascript // cpfAdapter.js class CPFAdapter { constructor(apiKey) { this.apiKey = apiKey; this.baseUrl = 'https://api.cpfhub.io'; } async consultar(cpf) { const response = await fetch(`${this.baseUrl}/cpf/${cpf}`, { method: 'GET', headers: { 'x-api-key': this.apiKey, 'Accept': 'application/json' }, signal: AbortSignal.timeout(15000) }); const raw = await response.json(); return this._normalizar(raw); } _normalizar(raw) { // Se a API mudar, ajuste APENAS aqui if (!raw.success) { return { encontrado: false, dados: null }; } return { encontrado: true, dados: { cpf: raw.data.cpf, nomeCompleto: raw.data.name || raw.data.fullName || '', nomeUppercase: raw.data.nameUpper || '', genero: raw.data.gender || 'N/A', dataNascimento: raw.data.birthDate || null, ano: raw.data.year || null } }; } } // O codigo de negocios nao conhece a estrutura da API const adapter = new CPFAdapter(process.env.CPFHUB_API_KEY); const resultado = await adapter.consultar('12345678900'); ``` Se a API renomear um campo, você ajusta apenas o método `_normalizar()` sem tocar no resto do sistema. --- ## Monitorando mudanças * **Testes de contrato diarios** -- Execute em CI/CD para detectar mudancas automaticamente. * **Changelogs** -- Acompanhe a documentação do provedor para anuncios de mudancas. * **Alertas de schema** -- Compare a estrutura da resposta com um schema salvo. ```python import json SCHEMA_ESPERADO = { 'success': bool, 'data': { 'cpf': str, 'name': str, 'nameUpper': str, 'gender': str, 'birthDate': str, 'day': int, 'month': int, 'year': int } } def verificar_schema(resposta, schema, path=''): for chave, tipo_esperado in schema.items(): if chave not in resposta: print(f'Campo ausente: {path}.{chave}') continue if isinstance(tipo_esperado, dict): verificar_schema(resposta[chave], tipo_esperado, f'{path}.{chave}') elif not isinstance(resposta[chave], tipo_esperado): print(f'Tipo alterado: {path}.{chave} (esperado {tipo_esperado.__name__}, ' f'recebido {type(resposta[chave]).__name__})') ``` --- ## Checklist de resiliência * Usar `.get()` com valores padrão para todos os campos. * Ignorar campos desconhecidos na resposta. * Criar camada de abstração (adapter) entre a API e o código de negócios. * Executar testes de contrato periodicamente. * Monitorar changelogs e documentação do provedor. * Ter fallback definido para quando campos críticos estiverem ausentes. --- ## Perguntas frequentes ### O que é necessário para implementar validação de CPF neste contexto? A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em cerca de 900ms, permitindo a verificação em tempo real durante o cadastro ou transação. ### A API CPFHub.io funciona para todos os volumes de consulta? Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional. ### 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. ### Quanto tempo leva para integrar a API CPFHub.io? A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens. ### 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 Versionamento e breaking changes são parte natural da evolucao de APIs. A melhor defesa é construir integrações resilientes com camadas de abstração, validação flexível e testes de contrato. Dessa forma, quando mudancas ocorrerem, o impacto no seu sistema sera mínimo. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.