API de CPF para sistemas legados: como integrar sem refatorar tudo

Integrar uma API de CPF em sistemas legados é possível sem reescrever a aplicação. Estratégias como microserviço intermediário, polling de banco de dados, proxy reverso e processamento em lote permitem conectar sistemas antigos — COBOL, Delphi, Visual Basic — à API da CPFHub.io usando o protocolo que cada sistema já domina. A escolha da abordagem depende principalmente do protocolo de comunicação suportado pelo sistema e da latência aceitável para o negócio.

Introdução

Sistemas legados representam uma parcela significativa da infraestrutura de TI de muitas empresas brasileiras. ERPs antigos, sistemas bancários em COBOL, aplicações em Delphi ou Visual Basic -- todos eles podem precisar validar CPFs, mas nem sempre oferecem suporte nativo a chamadas REST modernas. A boa notícia é que existem estratégias para conectar esses sistemas a uma API de CPF sem precisar reescrever a aplicação inteira.

Desafios comuns em sistemas legados

Sistemas legados enfrentam limitações técnicas que dificultam a integração direta com APIs REST modernas:

• Ausência de suporte a HTTPS/TLS -- Sistemas muito antigos podem não suportar conexões seguras modernas.

• Sem suporte a JSON -- Muitos sistemas legados trabalham com formatos proprietários, CSV ou XML, e não conseguem parsear JSON nativamente.

• Linguagens sem bibliotecas HTTP modernas -- COBOL, Clipper e outras linguagens legadas não possuem bibliotecas para consumir APIs REST.

• Arquitetura monolítica -- Qualquer mudança no sistema principal exige um ciclo completo de testes e homologação, o que pode levar semanas.

• Dependência de banco de dados compartilhado -- Muitos sistemas legados se comunicam exclusivamente via tabelas de banco de dados.

Estratégia 1: Microserviço intermediário (sidecar)

A abordagem mais comum é criar um pequeno serviço independente que atua como intermediário entre o sistema legado e a API de CPF. O sistema legado se comunica com o microserviço usando o protocolo que já conhece (banco de dados, arquivo ou HTTP simples), e o microserviço traduz essa comunicação para a API REST.

Exemplo: microserviço em Python com Flask

from flask import Flask, jsonify, request
import requests

app = Flask(__name__)

@app.route('/consultar-cpf', methods=['GET'])
def consultar_cpf():
    cpf = request.args.get('cpf', '').replace('.', '').replace('-', '')

    if not cpf or len(cpf) != 11:
    return jsonify({"erro": "CPF inválido"}), 400

    url = f"https://api.cpfhub.io/cpf/{cpf}"
    headers = {
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    }

    try:
    response = requests.get(url, headers=headers, timeout=10)
    dados = response.json()

    if dados.get("success"):
    # Retornar em formato simplificado para o sistema legado
    return jsonify({
    "cpf": dados["data"]["cpf"],
    "nome": dados["data"]["name"],
    "nascimento": dados["data"]["birthDate"],
    "genero": dados["data"]["gender"]
    })
    else:
    return jsonify({"erro": "CPF não encontrado"}), 404

    except requests.exceptions.Timeout:
    return jsonify({"erro": "Timeout na consulta"}), 504

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

O sistema legado pode então acessar http://servidor-interno:5000/consultar-cpf?cpf=12345678900 usando uma requisição HTTP simples, sem precisar lidar com autenticação por API key ou parsing de JSON complexo.

Estratégia 2: Integração via banco de dados

Para sistemas que se comunicam exclusivamente via banco de dados, o padrão "polling de tabela" é uma solução eficaz:

1. O sistema legado insere um registro na tabela fila_consulta_cpf com o CPF a ser consultado.
2. Um serviço externo monitora essa tabela periodicamente.
3. Para cada registro pendente, o serviço consulta a API e atualiza a tabela com os resultados.
4. O sistema legado lê os resultados da mesma tabela.

Exemplo do serviço de polling em Python

import requests
import time
import psycopg2

def processar_fila():
    conn = psycopg2.connect(
    host="localhost",
    database="sistema_legado",
    user="app_user",
    password="senha"
    )
    cursor = conn.cursor()

    # Buscar consultas pendentes
    cursor.execute("""
    SELECT id, cpf FROM fila_consulta_cpf
    WHERE status = 'pendente'
    ORDER BY criado_em ASC
    LIMIT 10
    """)

    pendentes = cursor.fetchall()

    for registro_id, cpf in pendentes:
    url = f"https://api.cpfhub.io/cpf/{cpf}"
    headers = {
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    }

    try:
    response = requests.get(url, headers=headers, timeout=10)
    dados = response.json()

    if dados.get("success"):
    cursor.execute("""
    UPDATE fila_consulta_cpf
    SET status = 'concluido',
    nome = %s,
    nascimento = %s,
    genero = %s,
    processado_em = NOW()
    WHERE id = %s
    """, (
    dados["data"]["name"],
    dados["data"]["birthDate"],
    dados["data"]["gender"],
    registro_id
    ))
    else:
    cursor.execute("""
    UPDATE fila_consulta_cpf
    SET status = 'nao_encontrado', processado_em = NOW()
    WHERE id = %s
    """, (registro_id,))

    except Exception as e:
    cursor.execute("""
    UPDATE fila_consulta_cpf
    SET status = 'erro', erro_msg = %s, processado_em = NOW()
    WHERE id = %s
    """, (str(e), registro_id))

    conn.commit()
    cursor.close()
    conn.close()

# Executar a cada 5 segundos
while True:
    processar_fila()
    time.sleep(5)

Estratégia 3: Proxy reverso com transformação de formato

Para sistemas legados que já fazem requisições HTTP mas esperam respostas em XML ou CSV, um proxy pode interceptar a requisição, consultar a API da CPFHub.io e retornar os dados no formato que o sistema espera, sem que seja necessário alterar qualquer linha do código legado.

Exemplo: proxy Express que retorna XML

const express = require('express');
const app = express();

app.get('/cpf/:cpf', async (req, res) => {
    const { cpf } = req.params;
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    try {
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpf}`,
    {
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    signal: controller.signal
    }
    );

    clearTimeout(timeoutId);
    const dados = await response.json();

    if (dados.success) {
    // Retornar como XML para o sistema legado
    res.set('Content-Type', 'text/xml');
    res.send(`<?xml version="1.0" encoding="UTF-8"?>
<consulta>
    <cpf>${dados.data.cpf}</cpf>
    <nome>${dados.data.name}</nome>
    <nascimento>${dados.data.birthDate}</nascimento>
    <genero>${dados.data.gender}</genero>
</consulta>`);
    } else {
    res.status(404).set('Content-Type', 'text/xml');
    res.send(`<?xml version="1.0"?><erro>CPF não encontrado</erro>`);
    }

    } catch (error) {
    clearTimeout(timeoutId);
    res.status(500).set('Content-Type', 'text/xml');
    res.send(`<?xml version="1.0"?><erro>Falha na consulta</erro>`);
    }
});

app.listen(8080);

Estratégia 4: Arquivo de troca (batch)

Para sistemas que processam dados em lote (batch), a integração pode ser feita via arquivos:

1. O sistema legado gera um arquivo CSV com os CPFs a consultar.
2. Um script processa o arquivo, consultando a API para cada CPF.
3. O resultado é salvo em um novo arquivo CSV que o sistema legado importa.

Essa abordagem é adequada para processos noturnos ou periódicos que não exigem resposta em tempo real.

Qual estratégia escolher

Perguntas frequentes

Qual estratégia de integração funciona para sistemas COBOL sem suporte a HTTP?

Para COBOL e linguagens sem bibliotecas HTTP modernas, a melhor abordagem é o polling de banco de dados: o sistema legado insere registros em uma tabela de fila e lê os resultados na mesma tabela, sem precisar fazer nenhuma chamada de rede diretamente. Um serviço externo (Python, Node.js ou qualquer linguagem moderna) cuida de consultar a API da CPFHub.io e gravar os resultados.

A API da CPFHub.io retorna HTTP 429 ou bloqueia quando o limite é atingido?

Não. A CPFHub.io nunca bloqueia requisições nem retorna HTTP 429. Ao superar o limite mensal do plano gratuito (50 consultas), cada consulta adicional é cobrada a R$0,15. Isso é especialmente útil em sistemas legados de difícil manutenção: não é preciso implementar lógica de retry por bloqueio.

Como proteger a API key em sistemas legados que não têm gerenciamento de secrets?

Armazene a chave no serviço intermediário (microserviço, proxy ou script de polling), nunca no sistema legado em si. Use variáveis de ambiente ou um arquivo de configuração com permissões restritas no servidor onde o serviço intermediário roda. O sistema legado jamais precisa conhecer a API key — ele só se comunica com o intermediário via protocolo interno.

Quanto tempo leva para implementar um microserviço sidecar para integração?

Um microserviço básico em Python com Flask ou Node.js com Express pode ser implementado em menos de 2 horas. O exemplo deste artigo já inclui tratamento de timeout, formatação de resposta simplificada para o sistema legado e rota HTTP pronta para uso. A parte mais demorada costuma ser a configuração do ambiente de rede interno e os testes de integração com o sistema legado.

Conclusão

Integrar uma API de CPF em sistemas legados não exige reescrever a aplicação inteira. Com um microserviço intermediário, uma integração via banco de dados ou um proxy de transformação de formato, é possível conectar sistemas antigos à API da CPFHub.io de forma incremental, sem risco de regredir funcionalidades existentes. A ANPD recomenda que qualquer integração com dados pessoais como o CPF contemple controles de acesso e registro de auditoria, independentemente da arquitetura adotada.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a integrar a validação de CPF ao seu sistema legado hoje mesmo, sem refatorar uma linha sequer do código existente.