Como Armazenar Respostas de APIs de CPF Sem Comprometer a Privacidade

Introdução

Para armazenar respostas de APIs de CPF sem comprometer a privacidade, aplique o princípio da minimização: guarde apenas os campos necessários para a finalidade declarada, criptografe os dados em repouso, defina prazo de retenção e descarte automático, e garanta que o log de validação seja armazenado separado dos dados transacionais — conforme exige a LGPD.

Ao consumir uma API de consulta de CPF, a resposta contém dados pessoais como nome completo, data de nascimento e gênero. Armazenar essas informações de forma inadequada pode transformar o seu banco de dados em um alvo para atacantes e gerar responsabilidade legal sob a LGPD. A questão não é apenas técnica, mas também jurídica: o princípio da minimização exige que você armazene somente o estritamente necessário e pelo tempo indispensável.

O Que a API do CPFHub Retorna

Para definir uma estratégia de armazenamento, é preciso primeiro entender a estrutura dos dados recebidos:

curl -s -X GET "https://api.cpfhub.io/cpf/12345678909" \
    -H "x-api-key: SUA_CHAVE_AQUI" | python3 -m json.tool

A resposta típica possui a seguinte estrutura:

{
    "success": true,
    "data": {
    "cpf": "12345678909",
    "name": "João da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "1990-05-15",
    "day": "15",
    "month": "05",
    "year": "1990"
    }
}

Cada campo é um dado pessoal protegido pela LGPD. A pergunta crítica é: você realmente precisa armazenar todos eles?

Princípio da Minimização na Prática

A LGPD determina que o tratamento de dados deve ser limitado ao mínimo necessário para a finalidade pretendida. Antes de armazenar qualquer resposta, classifique cada campo:

Na maioria dos casos de validação, basta armazenar o CPF (criptografado), o resultado da validação (booleano) e o timestamp da consulta.

Estratégias de Armazenamento Seguro

Existem diferentes abordagens dependendo do seu caso de uso:

• Armazenamento mínimo (validação) -- guarde apenas o hash do CPF e o resultado booleano da validação, sem nenhum dado pessoal adicional
• Armazenamento parcial (cadastro) -- armazene CPF criptografado e nome, descartando campos redundantes como nameUpper, day, month e year
• Armazenamento completo (obrigação legal) -- quando regulações específicas exigem o armazenamento integral, aplique criptografia em nível de campo com chaves gerenciadas
• Cache temporário -- mantenha a resposta completa em cache por tempo limitado para evitar chamadas repetidas, com expiração automática

import hashlib
import json
from cryptography.fernet import Fernet
from datetime import datetime, timedelta

# Chave de criptografia gerenciada externamente
ENCRYPTION_KEY = Fernet.generate_key()
cipher = Fernet(ENCRYPTION_KEY)

def armazenar_validacao_minima(cpf: str, api_response: dict):
    """Armazena apenas o mínimo necessário para validação."""
    cpf_hash = hashlib.sha256(cpf.encode()).hexdigest()
    registro = {
    "cpf_hash": cpf_hash,
    "validacao_sucesso": api_response.get("success", False),
    "timestamp": datetime.utcnow().isoformat(),
    "expiracao": (datetime.utcnow() + timedelta(days=90)).isoformat()
    }
    return registro

def armazenar_cadastro_parcial(cpf: str, api_response: dict):
    """Armazena dados para cadastro com criptografia."""
    data = api_response.get("data", {})
    cpf_encrypted = cipher.encrypt(cpf.encode()).decode()
    name_encrypted = cipher.encrypt(
    data.get("name", "").encode()
    ).decode()
    registro = {
    "cpf_encrypted": cpf_encrypted,
    "name_encrypted": name_encrypted,
    "timestamp": datetime.utcnow().isoformat(),
    "finalidade": "cadastro_cliente"
    }
    return registro

Cache com Expiração Automática

Para reduzir chamadas repetidas à API sem acumular dados pessoais, implemente um cache com TTL (Time-to-Live) curto:

• TTL de 15 a 60 minutos -- adequado para fluxos de cadastro onde o usuário pode repetir etapas
• Chave do cache baseada em hash -- nunca use o CPF como chave direta do cache
• Criptografia em memória -- mesmo em cache Redis, criptografe os valores armazenados
• Limpeza automática -- configure políticas de eviction para garantir que dados expirados sejam removidos
• Sem persistência em disco -- configure o cache para operar exclusivamente em memória

import redis
import hashlib
import json

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

def cache_resposta_api(cpf: str, resposta: dict, ttl_segundos=900):
    """Cache da resposta por 15 minutos usando hash como chave."""
    cache_key = f"cpf_cache:{hashlib.sha256(cpf.encode()).hexdigest()}"
    redis_client.setex(
    cache_key,
    ttl_segundos,
    json.dumps(resposta)
    )

def buscar_cache(cpf: str):
    """Busca resposta em cache antes de chamar a API."""
    cache_key = f"cpf_cache:{hashlib.sha256(cpf.encode()).hexdigest()}"
    cached = redis_client.get(cache_key)
    if cached:
    return json.loads(cached)
    return None

Auditoria e Rastreabilidade

Mesmo com armazenamento mínimo, mantenha registros de auditoria que permitam rastrear quem acessou os dados, quando e por qual motivo:

• Log de acesso -- registre cada leitura ou escrita no banco com identificação do operador
• Justificativa obrigatória -- exija que o sistema registre a finalidade de cada consulta ao dado armazenado
• Imutabilidade -- logs de auditoria não devem ser editáveis ou deletáveis por operadores comuns
• Revisão periódica -- audite trimestralmente os registros para identificar acessos indevidos
• Alinhamento com RIPD -- os registros de auditoria alimentam o Relatório de Impacto à Proteção de Dados

Perguntas frequentes

Quais campos da resposta da API de CPF precisam ser armazenados para fins de compliance?

Para fins de KYC e auditoria, os campos mínimos são: CPF consultado (pode ser hashado), timestamp da consulta, resultado (encontrado/não encontrado), correspondência de nome (sim/não) e identificador da transação associada. Nome completo e data de nascimento devem ser armazenados apenas se necessários para a finalidade específica.

Por quanto tempo os logs de validação de CPF devem ser mantidos?

Depende da finalidade. Para compliance financeiro (PLD/FT), o mínimo é 5 anos conforme a Lei Antilavagem. Para onboarding geral, o prazo típico é a duração do contrato mais o prazo prescricional aplicável (5 anos para a maioria das obrigações civis). Após o prazo, os dados devem ser eliminados ou anonimizados.

Como criptografar dados de CPF armazenados sem comprometer a capacidade de consulta?

Use hash com salt (bcrypt, Argon2) para armazenar o CPF de forma não reversível quando só precisa comparar se dois CPFs são iguais. Use criptografia simétrica (AES-256) quando precisar recuperar o valor original para processos internos. Tokenização é a melhor opção para sistemas que precisam do CPF em múltiplos pontos sem expor o valor real.

A ANPD pode auditar os logs de validação de CPF armazenados por uma empresa?

Sim. Em fiscalizações ou investigações, a ANPD pode solicitar acesso aos logs de tratamento de dados pessoais. Os registros de validação de CPF devem demonstrar base legal, finalidade e segurança adequada. Logs organizados e acessíveis são um indicador de maturidade de compliance que a ANPD considera positivamente.

Conclusão

Armazenar respostas de APIs de CPF de forma segura exige uma combinação de minimização de dados, criptografia em múltiplas camadas e políticas claras de retenção. Avalie criticamente cada campo retornado pela API e descarte tudo o que não for estritamente necessário para a sua finalidade. A API da CPFHub.io foi desenvolvida com privacidade em mente — comece com 50 consultas gratuitas por mês e implemente as boas práticas descritas aqui desde o primeiro dia em cpfhub.io.