API de CPF: como funciona o versionamento e 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:

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:

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:

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:

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:

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:

// 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.

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 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.

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 — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.