> ## 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

> Como o Tracer mantém trilhas de auditoria para conformidade SOX/GLBA e como consultar o histórico de validações.

export const GSOX = ({children}) => <Tooltip headline="SOX" tip="Lei Sarbanes-Oxley — uma lei americana que exige padrões rigorosos de registro financeiro e auditoria, requerendo trilhas de auditoria imutáveis." cta="Ver glossário" href="/pt/glossary">
    {children}
  </Tooltip>;

export const GAuditTrail = ({children}) => <Tooltip headline="Trilha de auditoria" tip="Um registro cronológico e imutável de cada ação e transação no sistema — essencial para conformidade regulatória e resolução de disputas." cta="Ver glossário" href="/pt/glossary">
    {children}
  </Tooltip>;

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.

<Tip>
  **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.
</Tip>

O Tracer mantém uma <GAuditTrail>trilha de auditoria</GAuditTrail> 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                               |
| ------------------------------------- | ---------------------------------------------------- | -------------------------------------------------- |
| <GSOX>**SOX**</GSOX> (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                     |

<Note>
  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.
</Note>

### 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:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

***

## 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

```http theme={null}
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

```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 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

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

**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 |

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

### 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` | 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?"

```http theme={null}
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"

```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 regra

"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 utilização de limite

"Quais transações excederam limites de gastos este 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
```

***

## 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

<Warning>
  **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`. Para investigar, consulte `GET /v1/audit-events?resource_type=rule&resource_id={ruleId}` para 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.
</Warning>

### 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:

1. **Encontre o ID de validação** dos seus logs de transação ou histórico do Tracer
2. **Recupere detalhes completos** usando GET /v1/validations/{id}
3. **Revise o snapshot da requisição** para ver quais dados foram fornecidos
4. **Verifique regras correspondentes** para entender por que a decisão foi tomada
5. **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"`                          |
| Timeout de avaliação                        | Retorna HTTP 504 com o código de erro `0422`                | 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                                        |

<Note>
  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`.
</Note>

Falhas de infraestrutura (banco indisponível, cache desatualizado, timeout) **não** caem em ALLOW — elas vão para o 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    |