> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Auditoria e conformidade
> Entenda como a trilha de auditoria imutável e encadeada por hash do Tracer atende aos requisitos da SOX e da GLBA, e consulte o histórico de validações para relatórios de conformidade.
export const GSOX = ({children}) =>
{children}
;
export const GAuditTrail = ({children}) =>
{children}
;
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, e podemos provar que ninguém adulterou essa resposta?"*
**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 que vale reconhecer:** 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. As seções de visão geral de conformidade e retenção não pressupõem nenhum conhecimento de API. As seções de consulta e verificação pressupõem conhecimento básico de REST.
O Tracer mantém uma trilha de auditoria 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 é projetado para atender aos requisitos de auditoria de regulamentações financeiras, incluindo:
| Regulamentação | Requisito | Como o Tracer atende |
| ------------------------------------- | ----------------------------------------------------- | -------------------------------------------------- |
| **SOX** (Sarbanes-Oxley) | Trilha de auditoria completa das decisões financeiras | Cada validação é registrada com contexto completo |
| **GLBA** (Gramm-Leach-Bliley) | Proteção dos 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
Cada validação cria um registro de auditoria imutável contendo:
| 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:
```json theme={null}
{
"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. Essa é a base criptográfica para as garantias de evidência de adulteração exigidas por SOX/GLBA.
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}`.
A trilha de auditoria é projetada para auditorias de conformidade. Você pode reconstruir exatamente o que aconteceu para qualquer validação, mesmo anos depois. Você também pode provar que os registros nunca mudaram depois do fato.
***
## 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)** | 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 |
| **Logs de aplicação** | 90 dias | Depuração e solução de problemas |
### Considerações de conformidade
* **Requisito da SOX:** manter registros por 7 anos a partir da data do relatório de auditoria
* **Requisito da GLBA:** reter registros que demonstrem conformidade com as regras de privacidade
* **Exportação de dados:** você pode exportar registros para sistemas de auditoria externos
***
## Consultando o histórico de validações
***
Use o endpoint `GET /v1/validations` para consultar validações históricas.
### Consulta básica
```http theme={null}
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
```http theme={null}
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 |
| `transaction_type` | enum | Filtra por CARD, WIRE, PIX, CRYPTO |
| `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
```http theme={null}
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**: o payload de entrada completo, conforme recebido
* **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` / `RESERVATION_SKIPPED` | Ciclo de vida de reserva em duas fases na integração com o ledger: capacidade retida, confirmada, devolvida em caso de aborto, expirada ou ignorada em um fail-open do ledger |
Eventos de reserva aparecem no log, mas nenhum filtro os seleciona. Os parâmetros `event_type`, `action` e `resource_type` aceitam apenas os valores listados na tabela abaixo. Cada um rejeita um valor de reserva com o erro `0009`. Para ler eventos de reserva, consulte por período e navegue pelos resultados.
### 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 ciclo de vida de regra ou limite |
| `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 | O 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 (`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?"
```http theme={null}
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"
```http theme={null}
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?"
```http theme={null}
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?"
```http theme={null}
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
* **Documente o alinhamento** da sua política de retenção com a retenção de 7 anos do Tracer
### Fluxo de investigação
Ao investigar uma transação específica:
1. **Encontre o ID de validação** nos logs da sua transação ou no histórico do Tracer
2. **Recupere os detalhes completos** usando GET /v1/validations/{id}
3. **Revise o snapshot da requisição** para ver os dados da requisição
4. **Verifique as regras correspondentes** para entender o motivo da decisão
5. **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` para semântica fail-closed em deploys de alta segurança. 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 |
| ---------------------- | ---------- |
| Registros de validação | 7+ anos |
| Regras/limites ativos | Indefinido |
| Logs de aplicação | 90 dias |