Auditoria e conformidade

Auditores, responsáveis pela conformidade e equipes de disputas usam essa camada para responder a uma pergunta: “Por que essa transação recebeu essa decisão?” O que muda na sua operação: a evidência de um controle deixa de ser “vou buscar os logs de N sistemas e conferir os timestamps” e passa a ser “aqui está o registro imutável, encadeado por criptografia, mostrando que essa transação recebeu essa decisão porque esta regra específica foi disparada neste momento.” Contrapartida: não existe “excluir” ou “editar” em registros de auditoria, por design. Um trigger TRUNCATE no nível do banco de dados bloqueia a exclusão em massa. O hash SHA-256 de cada registro inclui o hash do registro anterior, então remover ou reatribuir a data de um registro quebra a cadeia em tudo o que vem depois. Se você precisar remover um registro por motivos legais (como o direito ao esquecimento da GDPR sobre PII), a resposta é a minimização de dados desde o início, não a edição retroativa.

Para quem é este guia? Responsáveis pela conformidade e auditores que verificam o que o Tracer garante, equipes de disputas que consultam o histórico de validações, e desenvolvedores que criam relatórios a partir dos endpoints de auditoria. A seção de retenção não pressupõe nenhum conhecimento de API. As seções de consulta e verificação pressupõem conhecimento básico de REST.

O Tracer mantém uma imutável das 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.

Arquitetura da trilha de auditoria

O Tracer registra as decisões de POST /v1/validations com contexto completo para conformidade e investigação.

O que é registrado

O registro de auditoria de uma validação contém:

Dado	Descrição
Snapshot da requisição	Payload de entrada completo, conforme 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 dispararam (se houver)
Detalhes do limite	Informações de uso dos 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ção. Se você repetir uma requisição de validação com o mesmo requestId, o Tracer armazena apenas o primeiro evento de auditoria. Isso garante que a trilha de auditoria reflita eventos de negócio únicos, não padrões de nova tentativa da API.

Imutabilidade e cadeia de hash

Registros de auditoria são gravados uma única vez e encadeados por criptografia:

Você não pode modificar um registro após a criação.
Um trigger TRUNCATE protege a tabela de auditoria no nível do banco de dados e bloqueia a exclusão em massa.
Cada registro armazena um hash SHA-256 calculado sobre a identidade do registro, o timestamp, o ator e o hash do registro anterior, formando uma cadeia apenas de inserção. Remover, reordenar ou reatribuir a data de um registro faz com que todos os registros posteriores falhem na verificação.
Um pg_advisory_xact_lock serializa as gravações 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:

{
  "isValid": true,
  "totalChecked": 12345,
  "message": "Hash chain integrity verified successfully"
}

A verificação cobre a cadeia desde o primeiro registro até e incluindo o registro que você indicar. Quando todos os hashes ainda correspondem, isValid é true e message confirma isso. Quando um registro não corresponde mais ao seu hash armazenado, isValid é false. O campo message informa a adulteração. Em uma verificação com falha, firstInvalidId carrega um número de sequência interno do registro divergente. Não é um id de evento de auditoria, então não é um valor que você pode passar para GET /v1/audit-events/{id}.

Retenção de dados

Períodos de retenção

Tipo de dado	Período de retenção	Motivo
Regras (ativas/inativas)	Indefinido	Continuidade operacional
Regras / Limites (excluídos)	Exclusão lógica: a linha é mantida indefinidamente para auditoria, excluída das listagens da API	A trilha de conformidade deve sobreviver à visibilidade operacional
Limites	Indefinido	Continuidade operacional

Consultando o 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 validações em ordem cronológica reversa, com paginação por cursor.

Uma consulta sem datas cobre os últimos 90 dias, não o período completo de retenção. O Tracer aplica essa janela padrão apenas quando start_date e end_date estão ausentes. Envie um dos dois, ou ambos, para consultar um período mais antigo. Com apenas start_date, o período segue em frente a partir dessa data, sem fim. Com apenas end_date, o período segue para trás a partir dessa data, sem início.

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 período (inclusivo). Usa como padrão 90 dias atrás quando nenhuma data é informada
`end_date`	RFC3339	Fim do período (inclusivo). Usa como padrão o final do dia atual quando nenhuma data é informada
`decision`	enum	Filtra por ALLOW, DENY ou REVIEW
`account_id`	UUID	Filtra por conta
`segment_id`	UUID	Filtra por segmento
`portfolio_id`	UUID	Filtra por portfólio
`scheme`	string	Filtra por esquema de pagamento, como `CARD` ou `PIX`. `transaction_type` é o nome obsoleto desse filtro
`matched_rule_id`	UUID	Filtra pela regra que correspondeu
`exceeded_limit_id`	UUID	Filtra pelo limite que foi excedido

Requisito de formato de data

Os parâmetros de data devem usar o formato RFC3339 com fuso horário obrigatório. O Tracer rejeita formatos que contêm apenas a data.

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  (rejected - missing time and timezone)

Paginação

Os resultados usam paginação baseada em cursor. A resposta inclui os 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

A paginação por cursor mantém sort_by e sort_order 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`	`created_at`
`sort_order`	ASC, DESC	DESC

Obtendo detalhes da validação

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

Snapshot da requisição: os dados da requisição
Snapshot da resposta: a resposta completa, incluindo decisão e motivo
Regras avaliadas: todas as regras que o Tracer verificou
Regras correspondentes: regras que dispararam (se houver)
Detalhes do limite: informações de uso dos limites verificados
Timestamps: quando a validação ocorreu e o tempo de processamento

Consultando eventos de auditoria

Além dos registros de validação, o Tracer também expõe um log genérico de eventos de auditoria via GET /v1/audit-events. Essa é a única forma de ver as mudanças de ciclo de vida de regras e limites: quem os criou, atualizou, ativou, desativou, colocou em 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 nova edição
`RULE_DELETED`	Regra excluída logicamente
`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 nova edição
`LIMIT_DELETED`	Limite excluído logicamente
`RESERVATION_RESERVED` / `RESERVATION_CONFIRMED` / `RESERVATION_RELEASED` / `RESERVATION_EXPIRED`	Ciclo de vida de reserva em duas fases na integração com o ledger: capacidade retida, confirmada, devolvida em caso de aborto ou expirada

Filtros

GET /v1/audit-events aceita os mesmos filtros de período e escopo que GET /v1/validations, além de filtros específicos para eventos de ciclo de vida:

Parâmetro	Tipo	Descrição
`start_date` / `end_date`	RFC3339	Período (ambos inclusivos). Se nenhum for informado, a consulta cobre os últimos 90 dias
`event_type`	enum	`TRANSACTION_VALIDATED`, ou um tipo de evento de regra, limite ou reserva
`action`	enum	`VALIDATE`, `CREATE`, `UPDATE`, `DELETE`, `ACTIVATE`, `DEACTIVATE`, `DRAFT`, `RESERVE`, `CONFIRM`, `RELEASE`, `EXPIRE`, `SKIP`
`result`	enum	`SUCCESS`, `FAILED` (para CRUD) ou `ALLOW`, `DENY`, `REVIEW` (para validações)
`resource_type`	enum	`transaction`, `rule`, `limit`, `reservation`
`resource_id`	UUID	O ID do recurso afetado
`actor_type` / `actor_id`	string	`user`, `api_key` ou `system`, mais o ID do ator
`account_id` / `segment_id` / `portfolio_id` / `scheme` / `matched_rule_id`	UUID/enum	Mesmos filtros de escopo das validações
`limit`, `cursor`, `sort_by`, `sort_order`	—	Paginação por cursor (`limit` padrão 100, máximo 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 de regra na última semana: GET /v1/audit-events?resource_type=rule&start_date=...&end_date=...
Todas as exclusões de limite 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 do 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 essa transação foi negada em 15 de janeiro?”

GET /v1/validations/{id}

A resposta mostra exatamente a requisição 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 de 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 regras

“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 uso de limite

“Quais transações excederam limites de gastos neste 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

Boas práticas para conformidade

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

Manutenção de registros

Armazene os IDs de validação nos seus registros de transação para facilitar a referência cruzada
Registre o requestId que você envia ao Tracer para correlação
Exporte regularmente se precisar dos registros em sistemas de auditoria externos

Armadilhas comuns ao ler a trilha de auditoria:

“Consigo ver a validação, mas a regra que disparou já foi excluída.” Regras excluídas passam por exclusão lógica. A linha permanece no banco de dados, mas não aparece em GET /v1/rules. Para investigar, consulte GET /v1/audit-events?resource_type=rule&resource_id={ruleId} para ver o ciclo de vida dessa regra, incluindo suas ativações e a exclusão.
“Duas novas tentativas com o mesmo requestId produziram apenas um evento de auditoria.” Isso é proposital (deduplicação via idx_audit_events_validation_dedup). A trilha de auditoria reflete eventos de negócio únicos, não padrões de nova tentativa da API. Se sua nova tentativa produziu uma decisão diferente, vale a pena investigar. O Tracer deveria retornar a resposta original em cache.
“/verify diz que a cadeia está quebrada em um registro que eu não toquei.” A cadeia liga cada registro ao anterior, então uma adulteração ou corrupção no banco de dados em qualquer ponto faz com que tudo a partir dali seja relatado como inválido. Rode /verify em registros progressivamente mais antigos para delimitar onde a cadeia quebra pela primeira vez.
“Minha consulta de auditoria voltou vazia para o ano passado.” Uma consulta sem start_date e sem end_date cobre os últimos 90 dias. Informe o período que você quer.

Preparação para auditoria

Teste consultas antes da temporada de auditoria para garantir que você consegue recuperar os dados necessários
Verifique se os períodos funcionam corretamente com os requisitos de fuso horário

Fluxo de investigação

Ao investigar uma transação específica:

Encontre o ID de validação nos logs da sua transação ou no histórico do Tracer
Recupere os detalhes completos usando GET /v1/validations/
Revise o snapshot da requisição para ver os dados da requisição
Verifique as regras correspondentes para entender o motivo da decisão
Verifique o status do limite, se houver limites aplicáveis

Comportamento sem correspondência e auditoria

Quando uma validação é executada e nenhuma regra corresponde, o Tracer retorna uma decisão padrão configurada em vez de tratar a ausência de correspondência como um erro. Esse é um fallback por requisição, não uma estratégia de resiliência de infraestrutura. A variável de ambiente DEFAULT_DECISION_WHEN_NO_MATCH determina a decisão (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"`
Timeout na avaliação	Retorna HTTP 504 com código de erro `0422`	Nenhum registro de validação; um evento de falha de auditoria pode ser emitido
Erro de banco de dados durante a verificação de limite	Retorna HTTP 500; toda a transação de validação sofre rollback	Nenhum registro de validação é persistido

Defina DEFAULT_DECISION_WHEN_NO_MATCH=DENY. O serviço registra um aviso na inicialização se isso permanecer no padrão ALLOW.

Falhas de infraestrutura (banco de dados fora do ar, cache desatualizado, timeout) não recorrem ao ALLOW. Elas aparecem como erros HTTP para o cliente, 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 principais 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
Regras/limites ativos	Indefinido

Visão geral

Guias

Console

Operações

Auditoria e conformidade

Arquitetura da trilha de auditoria

O que é registrado

Imutabilidade e cadeia de hash

Retenção de dados

Períodos de retenção

Consultando o histórico de validações

Consulta básica

Consulta filtrada

Filtros disponíveis

Requisito de formato de data

Paginação

Ordenação

Obtendo detalhes da 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 regras

Cenário 4: revisão de uso de limite

Boas práticas para conformidade

Manutenção de registros

Preparação para auditoria

Fluxo de investigação

Comportamento sem correspondência e auditoria

Referência rápida

Endpoints

Resumo de retenção

​Arquitetura da trilha de auditoria

​O que é registrado

​Imutabilidade e cadeia de hash

​Retenção de dados

​Períodos de retenção

​Consultando o histórico de validações

​Consulta básica

​Consulta filtrada

​Filtros disponíveis

​Requisito de formato de data

​Paginação

​Ordenação

​Obtendo detalhes da 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 regras

​Cenário 4: revisão de uso de limite

​Boas práticas para conformidade

​Manutenção de registros

​Preparação para auditoria

​Fluxo de investigação

​Comportamento sem correspondência e auditoria

​Referência rápida

​Endpoints

​Resumo de retenção

Arquitetura da trilha de auditoria

O que é registrado

Imutabilidade e cadeia de hash

Retenção de dados

Períodos de retenção

Consultando o histórico de validações

Consulta básica

Consulta filtrada

Filtros disponíveis

Requisito de formato de data

Paginação

Ordenação

Obtendo detalhes da 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 regras

Cenário 4: revisão de uso de limite

Boas práticas para conformidade

Manutenção de registros

Preparação para auditoria

Fluxo de investigação

Comportamento sem correspondência e auditoria

Referência rápida

Endpoints

Resumo de retenção