API de CPF com cache: como implementar para economizar consultas

Implementar cache em consultas de CPF via API significa armazenar temporariamente os resultados de consultas anteriores para evitar requisições repetidas ao mesmo documento. Com uma camada de cache usando Redis ou Map em memória, é possível reduzir o consumo de créditos do plano, diminuir a latência percebida pelo usuário e aumentar a resiliência da aplicação — tudo com poucos ajustes no código existente.

Introdução

Quando sua aplicação consulta a mesma API de CPF repetidas vezes para o mesmo documento, cada requisição consome um crédito do seu plano, mesmo que os dados não tenham mudado. Implementar uma camada de cache entre a aplicação e a API elimina essas consultas redundantes, economizando créditos e reduzindo o tempo de resposta para o usuário.

Por que usar cache em consultas de CPF

Os dados cadastrais associados a um CPF -- nome, gênero, data de nascimento -- mudam com pouca frequência. Isso torna a consulta de CPF um candidato ideal para cache, ao contrário de dados financeiros ou transacionais que mudam constantemente.

Benefícios do cache:

• Economia de créditos -- Evita consultas repetidas ao mesmo CPF, reduzindo o consumo mensal.

• Menor latência -- Respostas do cache são retornadas em milissegundos, enquanto a API leva aproximadamente 900ms.

• Maior resiliência -- Se a API estiver temporariamente indisponível, o cache pode servir dados recentes.

• Menor carga na API -- Reduz o número de requisições, respeitando os limites do seu plano.

Definindo o TTL (Time to Live) adequado

O TTL define por quanto tempo os dados ficam no cache antes de serem considerados obsoletos. Para dados cadastrais de CPF, os seguintes valores são recomendados:

A CPFHub.io retorna dados cadastrais estáveis — nome, gênero e data de nascimento — que raramente sofrem alterações, tornando TTLs mais longos uma escolha segura para a maioria dos cenários.

Implementação com Redis e Python

Redis é a escolha mais popular para cache de APIs devido à sua velocidade e suporte nativo a TTL.

import requests
import redis
import json
import hashlib

redis_client = redis.Redis(host='localhost', port=6379, db=0)

CACHE_TTL = 86400 # 24 horas em segundos

def consultar_cpf_com_cache(cpf):
    cpf_limpo = ''.join(filter(str.isdigit, cpf))

    # Gerar chave de cache segura (não armazenar CPF em texto puro)
    cache_key = f"cpf:{hashlib.sha256(cpf_limpo.encode()).hexdigest()}"

    # Verificar cache
    cached = redis_client.get(cache_key)
    if cached:
    print("Cache hit")
    return json.loads(cached)

    # Cache miss: consultar API
    print("Cache miss - consultando API")
    url = f"https://api.cpfhub.io/cpf/{cpf_limpo}"
    headers = {
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    }

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

    # Armazenar no cache apenas respostas bem-sucedidas
    if dados.get("success"):
    redis_client.setex(cache_key, CACHE_TTL, json.dumps(dados))

    return dados

    except requests.exceptions.Timeout:
    # Tentar retornar cache expirado se disponível
    return {"erro": "Timeout na consulta e sem cache disponível"}

# Primeira chamada: cache miss (consulta API)
resultado1 = consultar_cpf_com_cache("12345678900")
print(resultado1)

# Segunda chamada: cache hit (sem consultar API)
resultado2 = consultar_cpf_com_cache("12345678900")
print(resultado2)

Implementação com Redis e Node.js

const Redis = require('ioredis');
const crypto = require('crypto');

const redis = new Redis();
const CACHE_TTL = 86400; // 24 horas

async function consultarCPFComCache(cpf) {
    const cpfLimpo = cpf.replace(/\D/g, '');
    const cacheKey = `cpf:${crypto
    .createHash('sha256')
    .update(cpfLimpo)
    .digest('hex')}`;

    // Verificar cache
    const cached = await redis.get(cacheKey);
    if (cached) {
    console.log('Cache hit');
    return JSON.parse(cached);
    }

    // Cache miss: consultar API
    console.log('Cache miss - consultando API');
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

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

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

    // Armazenar no cache apenas respostas bem-sucedidas
    if (dados.success) {
    await redis.setex(cacheKey, CACHE_TTL, JSON.stringify(dados));
    }

    return dados;

    } catch (error) {
    clearTimeout(timeoutId);
    return { erro: 'Falha na consulta' };
    }
}

Cache em memória para aplicações simples

Se sua aplicação não usa Redis, um cache em memória com Map do JavaScript pode ser suficiente para cenários com baixo volume:

const cacheMemoria = new Map();
const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 horas

function getCacheEntry(cpf) {
    const entry = cacheMemoria.get(cpf);
    if (!entry) return null;

    if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
    cacheMemoria.delete(cpf);
    return null;
    }

    return entry.data;
}

function setCacheEntry(cpf, data) {
    cacheMemoria.set(cpf, {
    data,
    timestamp: Date.now()
    });
}

async function consultarCPF(cpf) {
    const cached = getCacheEntry(cpf);
    if (cached) return cached;

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    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) {
    setCacheEntry(cpf, dados);
    }

    return dados;
}

Atenção: o cache em memória é perdido ao reiniciar a aplicação e não é compartilhado entre múltiplas instâncias. Use Redis para cenários que exigem persistência ou escala.

Boas práticas de cache para APIs de CPF

• Nunca armazene o CPF em texto puro como chave de cache -- Use um hash (SHA-256) para proteger o dado em conformidade com a LGPD.

• Armazene apenas respostas bem-sucedidas -- Erros temporários (5xx) ou timeouts não devem ser cacheados para não mascarar problemas.

• Implemente invalidação manual -- Permita que administradores invalidem o cache de um CPF específico quando necessário.

• Monitore a taxa de hit/miss -- Uma taxa de cache hit baixa pode indicar que o TTL está muito curto ou que os CPFs consultados raramente se repetem.

• Dimensione o armazenamento -- Cada registro de CPF ocupa cerca de 300-500 bytes no cache. Para 10.000 CPFs únicos, serão necessários aproximadamente 5 MB.

Estimativa de economia com cache

Considere uma aplicação que consulta 1.500 CPFs por mês, dos quais 40% são repetidos:

Nesse cenário, o cache economiza R$ 75/mês e evita a necessidade de migrar para um plano superior.

Perguntas frequentes

O cache de CPF é compatível com a LGPD?

Sim, desde que o CPF não seja armazenado em texto puro como chave de cache. Use um hash SHA-256 do CPF como identificador — assim o dado pessoal fica protegido e a operação de cache atende ao princípio da minimização exigido pela LGPD (Lei 13.709/2018). Armazene apenas respostas bem-sucedidas e defina TTLs compatíveis com a finalidade declarada.

Qual TTL é recomendado para cache de CPF em onboarding?

Para fluxos de onboarding e cadastro, um TTL de 24 horas é o ponto de equilíbrio entre atualidade dos dados e economia de créditos. Dados cadastrais de CPF — nome, gênero e data de nascimento — raramente mudam em intervalos curtos, tornando esse TTL adequado para a maioria das aplicações. Para antifraude em tempo real, prefira TTLs entre 1 e 6 horas.

O cache em memória é suficiente ou devo usar Redis?

Depende da escala. O cache em memória com Map é adequado para aplicações com baixo volume e instância única — é simples de implementar e não requer infraestrutura adicional. Se sua aplicação roda em múltiplas instâncias ou precisa que o cache persista entre reinicializações, Redis é a escolha correta. Para produção com mais de 1.000 consultas/mês, Redis é recomendado.

Quanto tempo leva para integrar cache na API CPFHub.io?

A implementação básica de cache em uma integração já existente leva menos de 1 hora. O padrão é: antes de chamar a API, consulte o cache pela chave hash do CPF; em caso de miss, chame GET https://api.cpfhub.io/cpf/{CPF} com o header x-api-key e armazene a resposta com TTL definido. Os exemplos em Python e Node.js deste artigo cobrem o fluxo completo.

Conclusão

Implementar cache em consultas de CPF via API é uma estratégia eficaz para economizar créditos, reduzir latência e aumentar a resiliência da aplicação. Com Redis e um TTL adequado, a implementação é simples e os benefícios são imediatos, especialmente em aplicações que consultam os mesmos CPFs com frequência.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a implementar cache nas suas consultas de CPF hoje mesmo.