Como manter registros de auditoria (audit trail) para consultas de CPF

Registros de auditoria para consultas de CPF devem capturar, no mínimo: quem consultou, quando, o CPF mascarado, a finalidade e o resultado. A LGPD — em seus artigos 37 e 38 — exige que o controlador comprove a base legal de cada tratamento, e o BACEN pode solicitar evidências de diligência em KYC com até 5 anos de retroatividade. O audit trail é a única forma confiável de atender a essas exigências sem depender de memória ou documentação dispersa.

Toda consulta de CPF via API envolve dados pessoais protegidos pela LGPD. Manter registros de auditoria (audit trail) dessas consultas não é apenas uma boa prática — é uma exigência legal e regulatória para muitos setores. Um audit trail bem implementado protege sua empresa em auditorias, investigações de fraude e solicitações de titulares de dados.

O que é um audit trail?

É um registro cronológico e imutável de todas as ações realizadas em um sistema. No contexto de consultas de CPF, ele deve registrar:

• Quem fez a consulta (usuário ou sistema).
• Quando a consulta foi realizada (timestamp).
• O que foi consultado (CPF mascarado).
• Resultado da consulta (sucesso/falha, status code).
• Finalidade da consulta (cadastro, KYC, antifraude, etc.).

Por que manter audit trail de consultas de CPF?

Estrutura do registro

Cada consulta deve gerar um registro com os seguintes campos:

{
    "id": "uuid-v4",
    "timestamp": "2026-03-13T14:30:00.000Z",
    "usuario": "operador@empresa.com",
    "sistema": "checkout-api",
    "cpf_mascarado": "123.***.**9-00",
    "finalidade": "validacao_cadastro",
    "status_code": 200,
    "sucesso": true,
    "latencia_ms": 890,
    "ip_origem": "192.168.1.100"
}

Importante: nunca armazene o CPF completo nos logs de auditoria. Use mascaramento (ex: 123.***.***-00) para proteger o dado pessoal.

Implementação em Python

import uuid
import json
import hashlib
from datetime import datetime, timezone
import requests

CPFHUB_API_KEY = 'SUA_CHAVE_DE_API'

def mascarar_cpf(cpf: str) -> str:
    return f'{cpf[:3]}.***.**{cpf[8]}-{cpf[9:]}'

def registrar_auditoria(registro: dict):
    # Em producao, envie para banco de dados, Elasticsearch ou servico de logging
    with open('audit_log.jsonl', 'a') as f:
    f.write(json.dumps(registro) + '\n')

def consultar_cpf_com_auditoria(cpf: str, usuario: str, finalidade: str) -> dict:
    cpf_limpo = cpf.replace('.', '').replace('-', '')
    inicio = datetime.now(timezone.utc)

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

    try:
    response = requests.get(url, headers=headers, timeout=10)
    resultado = response.json()
    latencia = int((datetime.now(timezone.utc) - inicio).total_seconds() * 1000)

    registro = {
    'id': str(uuid.uuid4()),
    'timestamp': inicio.isoformat(),
    'usuario': usuario,
    'cpf_mascarado': mascarar_cpf(cpf_limpo),
    'cpf_hash': hashlib.sha256(cpf_limpo.encode()).hexdigest(),
    'finalidade': finalidade,
    'status_code': response.status_code,
    'sucesso': resultado.get('success', False),
    'latencia_ms': latencia
    }

    registrar_auditoria(registro)
    return resultado

    except Exception as e:
    registro = {
    'id': str(uuid.uuid4()),
    'timestamp': inicio.isoformat(),
    'usuario': usuario,
    'cpf_mascarado': mascarar_cpf(cpf_limpo),
    'finalidade': finalidade,
    'status_code': 0,
    'sucesso': False,
    'erro': str(e)
    }
    registrar_auditoria(registro)
    raise

Boas práticas

1. Imutabilidade

Registros de auditoria não devem ser editáveis ou deletáveis. Use:

• Bancos append-only.
• Serviços como Elasticsearch ou CloudWatch Logs.
• Assinaturas digitais para detectar adulteração.

2. Retenção adequada

• Setor financeiro: mínimo 5 anos (exigência BACEN).
• LGPD: manter apenas pelo tempo necessário para a finalidade.
• Defina uma política de retenção clara e documentada.

3. Controle de acesso

• Apenas pessoal autorizado deve acessar os logs.
• Implemente controle de acesso baseado em função (RBAC).
• Registre também os acessos aos próprios logs.

4. Hash do CPF para buscas

Armazene um hash SHA-256 do CPF para permitir buscas sem expor o dado:

cpf_hash = hashlib.sha256(cpf_limpo.encode()).hexdigest()

Isso permite responder a solicitações de titulares ("quais consultas foram feitas com meu CPF?") sem armazenar o CPF em texto claro.

Dashboard da CPFHub.io

O painel da CPFHub.io exibe um resumo das consultas realizadas pela sua chave de API:

• Total de consultas realizadas no mês.
• Histórico de requisições por período.
• Consumo da cota do plano.

Esse dashboard complementa (mas não substitui) o audit trail interno da sua aplicação. Para fins de LGPD e compliance regulatório, os registros gerados pelo seu sistema têm precedência, pois contêm a finalidade e o operador responsável por cada consulta.

Perguntas frequentes

Quais campos são obrigatórios em um audit trail de CPF para fins de LGPD?

A LGPD exige que o controlador comprove a base legal e a finalidade do tratamento. Por isso, os campos indispensáveis são: timestamp, identificação do operador (usuário ou sistema), CPF mascarado ou hash, finalidade da consulta e resultado. O IP de origem e a latência são recomendados para investigações de fraude, mas não há exigência legal específica para esses campos.

Por quanto tempo os registros de auditoria de CPF devem ser mantidos?

Depende do setor e da base legal do tratamento. Para instituições financeiras sujeitas ao BACEN, o prazo mínimo é de 5 anos. Para fins exclusivamente de compliance com a LGPD, o critério é manter apenas pelo tempo necessário à finalidade — mas como o audit trail serve como defesa em caso de questionamento, manter por 5 anos é uma referência segura para a maioria dos setores. Documente essa política no seu RIPD.

É possível armazenar o CPF completo nos logs para facilitar buscas?

Não é recomendado. Armazenar o CPF completo em logs amplia desnecessariamente a superfície de exposição e viola o princípio da minimização de dados da LGPD. A alternativa é armazenar um hash SHA-256 do CPF: você consegue buscar todas as consultas referentes a um titular específico sem expor o número em texto claro — exatamente o que é necessário para responder a solicitações de titulares.

O audit trail da CPFHub.io substitui o registro interno da minha aplicação?

Não. O dashboard da CPFHub.io mostra o volume e histórico de chamadas à API, mas não contém a finalidade, o operador interno nem o contexto de negócio de cada consulta. Para LGPD e auditorias regulatórias, você precisa manter seu próprio audit trail, que registra quem na sua empresa consultou o CPF, por qual motivo e em qual fluxo do sistema.

Conclusão

Manter registros de auditoria para consultas de CPF é indispensável para conformidade com a LGPD, atendimento às regulamentações do BACEN e resposta eficiente a incidentes de fraude. Com mascaramento de CPF, hash para buscas, registros imutáveis e controle de acesso restrito, você protege dados pessoais e mantém evidências concretas para qualquer auditoria.

A CPFHub.io oferece latência média de ~900ms e SLA de 99,9% — parâmetros que você deve registrar no seu audit trail para demonstrar que a validação ocorreu em tempo real durante o processo de negócio. Comece no plano gratuito (50 consultas/mês, sem cartão) e escale para o Pro (R$149/mês, 1.000 consultas) quando o volume crescer. Se ultrapassar a cota, a API não bloqueia: cobra R$0,15 por consulta adicional.