> ## 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 funciona a trilha de auditoria imutável e encadeada por hash do Tracer, e consulte o histórico de validações para relatórios de 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.

> [!TIP]
>
> **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 trilha de auditoria (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.) 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 |

> [!NOTE]
>
> 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.

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

```http theme={null}
GET /v1/validations
X-API-Key: {api_key}
```

Retorna validações em ordem cronológica reversa, com paginação por cursor.

> [!WARNING]
>
> **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 |
| `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

> [!WARNING]
>
> 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 |

> [!NOTE]
>
> 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**: 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?"

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

> [!WARNING]
>
> **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:

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 |

> [!NOTE]
>
> 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.