# Como manter registros de auditoria (audit trail) para consultas de CPF > Aprenda a implementar registros de auditoria (audit trail) para consultas de CPF via API. Boas práticas para LGPD, compliance e segurança. **Publicado:** 13/03/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/registros-auditoria-audit-trail-consultas-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](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm) — 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? | Motivo | Detalhe | | --- | --- | | LGPD | Comprovar base legal e finalidade para tratamento de dados | | Regulamentação (BACEN, CVM) | Evidência de diligência em processos de KYC | | Investigações de fraude | Rastrear quem acessou dados e quando | | Solicitações de titulares | Responder a pedidos de acesso ou exclusão | | Auditorias internas/externas | Demonstrar controles implementados | --- ## Estrutura do registro Cada consulta deve gerar um registro com os seguintes campos: ```json { "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 ```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: ```python 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**](https://www.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. ### Leia também - [Privacy impact assessment (PIA): quando é obrigatório para dados de CPF](https://cpfhub.io/blog/privacy-impact-assessment-pia-dados-cpf) - [LGPD e CPF: dado pessoal sensível ou não?](https://cpfhub.io/blog/lgpd-cpf-e-dado-pessoal-sensivel-ou-nao-entenda-a-classificacao-correta) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) - [Como responder a incidentes de vazamento de dados de CPF](https://cpfhub.io/blog/como-responder-a-incidentes-de-vazamento-de-dados-de-cpf) --- ## 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**](https://www.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.