Auditoria e conformidade

Auditores, oficiais de compliance e times de disputas usam esta camada para responder uma pergunta: “Por que esta transação recebeu esta decisão, e conseguimos provar que ninguém adulterou essa resposta?” O que muda na sua operação: a evidência de controle deixa de ser “vou puxar logs de N sistemas e reconciliar timestamps” e vira “este é o registro imutável, encadeado criptograficamente, mostrando que esta transação recebeu esta decisão porque esta regra específica disparou neste momento”. Essa mudança é o ponto inteiro. O trade-off honesto: não existe “deletar” ou “editar” em registros de auditoria — por design. Um trigger de TRUNCATE no nível do banco bloqueia deleção em massa; o hash SHA-256 de cada registro inclui o hash do anterior, então adulterar quebra a cadeia em tudo que vem depois. Se você precisa remover um registro por razão legal (GDPR direito ao esquecimento sobre PII, por exemplo), a resposta é minimização de dados na entrada, não edição retroativa.

Para quem é este guia? Oficiais de compliance e auditores checando o que o Tracer garante, times de disputas consultando histórico de validações e devs construindo relatórios contra os endpoints de auditoria. A visão geral de compliance e as seções de retenção não exigem conhecimento de API; as seções de consulta e verify assumem REST básico.

O Tracer mantém uma completa e imutável de todas as decisões de validação. Este guia explica como o sistema de auditoria funciona e como consultar o histórico de validações para relatórios de conformidade.

Visão geral de conformidade

O Tracer foi projetado para atender aos requisitos de auditoria de regulamentações financeiras, incluindo:

Regulamentação	Requisito	Como o Tracer atende
(Sarbanes-Oxley)	Trilha de auditoria completa de decisões financeiras	Toda validação é registrada com contexto completo
GLBA (Gramm-Leach-Bliley)	Proteção de dados financeiros do cliente	Dados criptografados em repouso e em trânsito
Auditoria geral	Capacidade de reconstruir decisões	Registros imutáveis com snapshots de entrada/saída

Arquitetura da trilha de auditoria

O Tracer registra cada decisão de validação com contexto completo para conformidade e investigação.

O que é registrado

Toda validação cria um registro de auditoria imutável contendo:

Dado	Descrição
Snapshot da requisição	Payload de entrada completo como recebido
Snapshot da resposta	Resposta completa incluindo decisão e detalhes
Decisão	ALLOW, DENY ou REVIEW
Motivo	Por que a decisão foi tomada
Regras avaliadas	Todas as regras que foram avaliadas
Regras correspondentes	Regras que foram acionadas (se houver)
Detalhes de limite	Informações de uso para limites verificados
Tempo de processamento	Quanto tempo a validação levou
Timestamp	Quando a validação ocorreu

Eventos de auditoria são deduplicados para validações de transações. Se uma requisição de validação for retentada com o mesmo requestId, apenas o primeiro evento de auditoria é armazenado. Isso garante que a trilha de auditoria reflita eventos de negócio únicos, não padrões de retentativa da API.

Imutabilidade e cadeia de hash

Registros de auditoria são write-once e encadeados criptograficamente:

Registros não podem ser modificados após a criação.
A tabela de auditoria é protegida no nível do banco de dados: um trigger de TRUNCATE bloqueia exclusões em massa.
Cada registro armazena um hash SHA-256 que inclui o hash do registro anterior, formando uma cadeia append-only. Adulterar qualquer registro passado quebra a cadeia para todos os registros subsequentes.
Um pg_advisory_xact_lock serializa as escritas da cadeia de hash para manter a ordem estável sob inserções concorrentes.

Você pode verificar a cadeia a qualquer momento usando GET /v1/audit-events/{id}/verify, que retorna:

{
  "valid": true,
  "totalChecked": 12345,
  "firstInvalidId": null
}

Se a cadeia estiver íntegra, valid é true e firstInvalidId é omitido. Se um registro foi modificado, valid é false e firstInvalidId aponta para o primeiro registro onde o hash recalculado diverge do hash armazenado. Essa é a base criptográfica para as garantias de evidência de adulteração exigidas por SOX/GLBA.

A trilha de auditoria foi projetada para auditorias de conformidade. Você pode reconstruir exatamente o que aconteceu em qualquer validação, mesmo anos depois, e provar que os registros não foram modificados a posteriori.

Retenção de dados

O Tracer retém dados de acordo com requisitos regulatórios e necessidades operacionais.

Períodos de retenção

Tipo de dado	Período de retenção	Motivo
Registros de validação	Mínimo de 7 anos	Requisito de conformidade SOX/GLBA
Regras (ativas/inativas)	Indefinido	Continuidade operacional
Regras / Limites (excluídos)	Soft-delete: linha mantida indefinidamente para auditoria, excluída das listagens da API	A trilha de conformidade deve sobreviver à visibilidade operacional
Limites	Indefinido	Continuidade operacional
Logs de aplicação	90 dias	Debugging e troubleshooting

Considerações de conformidade

Requisito SOX: Manter registros por 7 anos a partir da data do relatório de auditoria
Requisito GLBA: Reter registros demonstrando conformidade com regras de privacidade
Exportação de dados: Registros podem ser exportados para sistemas de auditoria externos

Consultando histórico de validações

Use o endpoint GET /v1/validations para consultar validações históricas.

Consulta básica

GET /v1/validations
X-API-Key: {api_key}

Retorna as validações em ordem cronológica reversa com paginação por cursor. Não há janela de tempo implícita — use start_date e end_date para restringir o resultado, caso contrário a resposta cobre tudo dentro do período de retenção.

Consulta filtrada

GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-01-31T23:59:59Z&decision=DENY
X-API-Key: {api_key}

Filtros disponíveis

Parâmetro	Tipo	Descrição
`start_date`	RFC3339	Início do intervalo de datas (inclusivo)
`end_date`	RFC3339	Fim do intervalo de datas (exclusivo)
`decision`	enum	Filtrar por ALLOW, DENY ou REVIEW
`account_id`	UUID	Filtrar por conta
`segment_id`	UUID	Filtrar por segmento
`portfolio_id`	UUID	Filtrar por portfólio
`transaction_type`	enum	Filtrar por CARD, WIRE, PIX, CRYPTO
`matched_rule_id`	UUID	Filtrar por regra que correspondeu
`exceeded_limit_id`	UUID	Filtrar por limite que foi excedido

Requisito de formato de data

Parâmetros de data devem usar formato RFC3339 com timezone obrigatório. Formatos somente com data são rejeitados.

Válido:

start_date=2026-01-01T00:00:00Z
start_date=2026-01-01T00:00:00-03:00

Inválido:

start_date=2026-01-01  (rejeitado - faltando hora e timezone)

Paginação

Resultados usam paginação baseada em cursor. A resposta inclui campos nextCursor e hasMore para navegar pelos resultados.

Parâmetro	Padrão	Máximo	Descrição
`limit`	100	1000	Resultados por página
`cursor`	-	-	Cursor de paginação da resposta anterior

Ao usar paginação por cursor, sort_by e sort_order são fixados a partir da consulta original.

Ordenação

GET /v1/validations?sort_by=created_at&sort_order=DESC

Parâmetro	Opções	Padrão
`sort_by`	`created_at`, `processing_time_ms`	createdAt
`sort_order`	ASC, DESC	DESC

Obtendo detalhes de validação

Recupere detalhes completos para uma validação específica usando GET /v1/validations/{id}. A resposta contém tudo necessário para entender uma decisão de validação:

Snapshot da requisição: O payload de entrada completo como recebido
Snapshot da resposta: Resposta completa incluindo decisão e motivo
Regras avaliadas: Todas as regras que foram verificadas
Regras correspondentes: Regras que foram acionadas (se houver)
Detalhes de limites: Informações de uso para limites verificados
Timestamps: Quando a validação ocorreu e tempo de processamento

Consultando eventos de auditoria

Além dos registros de validação, o Tracer também expõe um log de eventos de auditoria genérico via GET /v1/audit-events. Essa é a única forma de ver mudanças de ciclo de vida em regras e limites — quem as criou, atualizou, ativou, desativou, voltou para rascunho ou excluiu.

Tipos de evento

`eventType`	Quando é emitido
`TRANSACTION_VALIDATED`	Uma requisição de validação foi processada (também disponível via `GET /v1/validations`)
`RULE_CREATED` / `RULE_UPDATED`	Regra criada ou modificada
`RULE_ACTIVATED` / `RULE_DEACTIVATED`	Regra movida para ACTIVE / INACTIVE
`RULE_DRAFTED`	Regra movida de INACTIVE de volta para DRAFT para reedição
`RULE_DELETED`	Regra deletada via soft-delete
`LIMIT_CREATED` / `LIMIT_UPDATED`	Limite criado ou modificado
`LIMIT_ACTIVATED` / `LIMIT_DEACTIVATED`	Limite movido para ACTIVE / INACTIVE
`LIMIT_DRAFTED`	Limite movido de INACTIVE de volta para DRAFT para reedição
`LIMIT_DELETED`	Limite deletado via soft-delete

Filtros

GET /v1/audit-events aceita os mesmos filtros de intervalo de datas e escopo que GET /v1/validations, mais filtros específicos para eventos de ciclo de vida:

Parâmetro	Tipo	Descrição
`start_date` / `end_date`	RFC3339	Intervalo de datas (início inclusivo, fim exclusivo)
`event_type`	enum	Filtrar por tipo de evento (veja tabela acima)
`action`	enum	`VALIDATE`, `CREATE`, `UPDATE`, `DELETE`, `ACTIVATE`, `DEACTIVATE`, `DRAFT`
`result`	enum	`SUCCESS`, `FAILED` (para CRUD) ou `ALLOW`, `DENY`, `REVIEW` (para validações)
`resource_type`	enum	`transaction`, `rule`, `limit`
`resource_id`	UUID	ID do recurso afetado
`actor_type` / `actor_id`	string	`user` ou `system`, mais o ID do ator
`account_id` / `segment_id` / `portfolio_id` / `transaction_type` / `matched_rule_id`	UUID/enum	Mesmos filtros de escopo das validações
`limit`, `cursor`, `sort_by`, `sort_order`	—	Paginação por cursor (padrão `limit` 100, máx 1000; `sort_by` aceita `created_at` ou `event_type`)

Casos de uso

Quem ativou esta regra? GET /v1/audit-events?resource_type=rule&resource_id={ruleId}&action=ACTIVATE
Todas as mudanças em regras na semana passada: GET /v1/audit-events?resource_type=rule&start_date=...&end_date=...
Todas as exclusões de limites em 2026: GET /v1/audit-events?resource_type=limit&action=DELETE&start_date=2026-01-01T00:00:00Z

Detalhe de um evento

Use GET /v1/audit-events/{id} para recuperar um registro de auditoria específico, incluindo o snapshot de estado no momento do evento.

Cenários de relatórios de conformidade

Consultas comuns para relatórios de auditoria e conformidade.

Cenário 1: Investigação de auditoria

“Por que esta transação foi negada em 15 de janeiro?”

GET /v1/validations/{id}

A resposta mostra a requisição exata recebida, todas as regras avaliadas, qual regra ou limite causou a negação, e o timestamp.

Cenário 2: Relatório mensal de conformidade

“Mostrar todas as transações negadas para contas corporativas em janeiro”

GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z&decision=DENY&segment_id=corporate-segment-uuid&limit=1000

Cenário 3: Análise de eficácia de regra

“Quais transações foram negadas por uma regra de fraude específica?”

GET /v1/validations?matched_rule_id=fraud-rule-uuid&decision=DENY&limit=1000

Cenário 4: Revisão de utilização de limite

“Quais transações excederam limites de gastos este mês?”

GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z&exceeded_limit_id=daily-limit-uuid

Melhores práticas para conformidade

Recomendações para manter a prontidão para auditorias.

Manutenção de registros

Armazene IDs de validação nos seus registros de transação para fácil referência cruzada
Registre o requestId que você envia para o Tracer para correlação
Exporte regularmente se você precisa de registros em sistemas de auditoria externos

Tropeços comuns ao ler a trilha de auditoria:

“Consigo ver a validação mas a regra que disparou já foi deletada.” Regras deletadas são soft-deletadas — a linha fica no banco, mas não aparece em GET /v1/rules. Pra investigar, consulte GET /v1/audit-events?resource_type=rule&resource_id={ruleId} pra ver o ciclo de vida daquela regra, incluindo ativações e o delete eventual.
“Duas retentativas do mesmo requestId produziram apenas um evento de auditoria.” Isso é por design (deduplicação via idx_audit_events_validation_dedup). A trilha reflete eventos únicos de negócio, não padrões de retry da API. Se sua retentativa produziu uma decisão diferente, vale investigar — o Tracer deveria retornar a resposta original em cache.
“O /verify diz que a cadeia está quebrada num registro que eu não toquei.” A cadeia liga todo registro ao anterior, então uma adulteração ou corrupção de banco em qualquer lugar faz tudo o que vem depois reportar inválido. O firstInvalidId aponta o ponto de divergência real — comece a investigação ali, não no registro que você consultou.

Preparação para auditoria

Teste consultas antes da temporada de auditoria para garantir que você consegue recuperar os dados necessários
Verifique intervalos de data funcionam corretamente com seus requisitos de timezone
Documente o alinhamento da sua política de retenção com a retenção de 7 anos do Tracer

Fluxo de trabalho de investigação

Ao investigar uma transação específica:

Encontre o ID de validação dos seus logs de transação ou histórico do Tracer
Recupere detalhes completos usando GET /v1/validations/
Revise o snapshot da requisição para ver quais dados foram fornecidos
Verifique regras correspondentes para entender por que a decisão foi tomada
Verifique status do limite se limites estavam envolvidos

Comportamento de no-match e auditoria

Quando uma validação executa e nenhuma regra corresponde, o Tracer retorna uma decisão padrão configurada em vez de tratar a falta de correspondência como erro. Isso é um fallback por requisição, não uma estratégia de resiliência a falhas de infraestrutura. A decisão é governada pela variável de ambiente DEFAULT_DECISION_WHEN_NO_MATCH (padrão: ALLOW).

Cenário	Comportamento	Registro de auditoria
Nenhuma regra corresponde	Retorna `DEFAULT_DECISION_WHEN_NO_MATCH` (padrão `ALLOW`)	Registrado com `reason: "No matching rules found"`
Orçamento de avaliação excedido	Retorna HTTP 504 com TRC-0229	Sem registro de validação; um evento de falha de auditoria pode ser emitido
Erro de banco durante verificação de limite	Retorna HTTP 500; toda a transação de validação é revertida	Sem registro de validação persistido

Defina DEFAULT_DECISION_WHEN_NO_MATCH=DENY para semântica fail-closed em deployments de alta segurança. O serviço loga um aviso no startup se essa variável permanecer no padrão ALLOW.

Falhas de infraestrutura (banco indisponível, cache desatualizado, timeout) não caem em ALLOW — elas vão pro cliente como erros HTTP, e a transação original não tem registro de auditoria. Operadores devem monitorar tracer_audit_persist_failures_total e o endpoint /readyz para detectar esses casos.

Referência rápida

Endpoints-chave e informações de retenção.

Endpoints

Operação	Método	Endpoint
Listar validações	GET	`/v1/validations`
Obter validação	GET	`/v1/validations/{id}`
Listar eventos de auditoria	GET	`/v1/audit-events`
Obter evento de auditoria	GET	`/v1/audit-events/{id}`
Verificar cadeia de hash	GET	`/v1/audit-events/{id}/verify`

Resumo de retenção

Dado	Retenção
Registros de validação	7+ anos
Regras/limites ativos	Indefinido
Logs de aplicação	90 dias

Documentation Index

​Visão geral de conformidade

​Arquitetura da trilha de auditoria

​O que é registrado

​Imutabilidade e cadeia de hash

​Retenção de dados

​Períodos de retenção

​Considerações de conformidade

​Consultando histórico de validações

​Consulta básica

​Consulta filtrada

​Filtros disponíveis

​Requisito de formato de data

​Paginação

​Ordenação

​Obtendo detalhes de validação

​Consultando eventos de auditoria

​Tipos de evento

​Filtros

​Casos de uso

​Detalhe de um evento

​Cenários de relatórios de conformidade

​Cenário 1: Investigação de auditoria

​Cenário 2: Relatório mensal de conformidade

​Cenário 3: Análise de eficácia de regra

​Cenário 4: Revisão de utilização de limite

​Melhores práticas para conformidade

​Manutenção de registros

​Preparação para auditoria

​Fluxo de trabalho de investigação

​Comportamento de no-match e auditoria

​Referência rápida

​Endpoints

​Resumo de retenção

Visão geral de conformidade

Arquitetura da trilha de auditoria

O que é registrado

Imutabilidade e cadeia de hash

Retenção de dados

Períodos de retenção

Considerações de conformidade

Consultando histórico de validações

Consulta básica

Consulta filtrada

Filtros disponíveis

Requisito de formato de data

Paginação

Ordenação

Obtendo detalhes de validação

Consultando eventos de auditoria

Tipos de evento

Filtros

Casos de uso

Detalhe de um evento

Cenários de relatórios de conformidade

Cenário 1: Investigação de auditoria

Cenário 2: Relatório mensal de conformidade

Cenário 3: Análise de eficácia de regra

Cenário 4: Revisão de utilização de limite

Melhores práticas para conformidade

Manutenção de registros

Preparação para auditoria

Fluxo de trabalho de investigação

Comportamento de no-match e auditoria

Referência rápida

Endpoints

Resumo de retenção