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

# Governança

> Gerencie mapeamentos de PII de atores, baixe arquivos de logs de auditoria concluídos e reverifique a cadeia de hash de auditoria à prova de adulteração do Matcher — a superfície de conformidade para GDPR e auditoria.

A superfície de governança do Matcher agrupa as três capacidades voltadas à conformidade sob `/v1/governance`: **mapeamentos de atores** (vinculam IDs de atores opacos a PII, com pseudonimização/apagamento GDPR), **arquivos** (baixe arquivos de logs de auditoria concluídos do armazenamento frio) e **logs de auditoria** (histórico imutável, encadeado por hash, que você pode reverificar de forma independente). O tenant é sempre resolvido a partir do JWT — nunca de um caminho ou corpo.

<Note>Cada rota de governança é delimitada ao tenant do chamador. As leituras de mapeamentos de atores são divididas em dois níveis de autorização: a lista sem PII versus a leitura de desanonimização de um único registro, para que a resolução de identidade permaneça separável do acesso de navegação.</Note>

## Mapeamentos de atores

***

Um mapeamento de ator vincula um `actorId` opaco (por exemplo `user:550e8400-e29b-41d4-a716-446655440000`) a PII legível (`displayName`, `email`). As linhas da lista são **sem PII por design** — apenas o `GET` de um único registro retorna a identidade em texto claro.

### Listar mapeamentos de atores

Linhas paginadas por cursor, sem PII. Filtre por um prefixo de ID de ator.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/actor-mappings?actorId=user:&limit=25" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "actorId": "user:550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    }
  ],
  "limit": 25,
  "nextCursor": "",
  "hasMore": false
}
```

Parâmetros de consulta: `actorId` (filtro por prefixo), `limit` (padrão 25, limitado a 100) e `cursor`.

### Upsert de um mapeamento de ator

Cria ou atualiza a PII de um ID de ator. `PUT` é idempotente — a mesma chamada cria o registro no primeiro uso e o atualiza a partir de então. Você deve fornecer ao menos um entre `displayName` ou `email`.

```bash theme={null}
curl -X PUT "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "John Doe",
    "email": "john.doe@example.com"
  }'
```

```json theme={null}
{
  "actorId": "user:550e8400-e29b-41d4-a716-446655440000",
  "displayName": "John Doe",
  "email": "john.doe@example.com",
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}
```

### Obter um mapeamento de ator (desanonimizar)

Retorna a PII em texto claro de um único ID de ator. Esta **é** a primitiva de desanonimização, por isso é protegida pela permissão mais restrita `deanonymize` em vez da leitura simples.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN"
```

### Pseudonimizar (GDPR)

Substitui `displayName` e `email` por `[REDACTED]` mantendo o registro e seu vínculo com `actorId` — a trilha de auditoria permanece intacta, mas a PII desaparece. Responde `204 No Content`.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}/pseudonymize" \
  -H "Authorization: Bearer $TOKEN"
```

### Excluir (direito ao apagamento)

Remove permanentemente o mapeamento para o direito ao apagamento do GDPR. Responde `204 No Content`.

```bash theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN"
```

<Note>Pseudonimizar mantém o registro (com a PII removida); excluir o apaga por completo. Escolha pseudonimizar quando precisar reter o vínculo de auditoria, e excluir quando o próprio registro não deva persistir.</Note>

## Arquivos

***

Quando as partições de logs de auditoria expiram, elas são comprimidas e movidas para o armazenamento de objetos. Os endpoints de arquivos listam os arquivos concluídos e emitem URLs de download com tempo limitado.

### Listar arquivos

Paginados por offset. Filtre por intervalo de datas.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/archives?from=2024-01-01&to=2024-03-31&limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "partitionName": "audit_logs_2024_q1",
      "dateRangeStart": "2024-01-01T00:00:00Z",
      "dateRangeEnd": "2024-03-31T23:59:59Z",
      "rowCount": 150000,
      "compressedSizeBytes": 10485760,
      "storageClass": "GLACIER",
      "checksum": "sha256:abc123def456...",
      "status": "COMPLETE",
      "archivedAt": "2024-04-01T02:30:00Z"
    }
  ],
  "limit": 20,
  "hasMore": true
}
```

Parâmetros de consulta: `from`, `to` (`YYYY-MM-DD` ou RFC 3339), `limit` (1–200, padrão 20) e `offset`. Apenas os arquivos `COMPLETE` são listados — os arquivos em andamento e com falha nunca são expostos.

### Baixar um arquivo

Retorna uma URL pré-assinada mais o checksum para verificação de integridade.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/archives/{id}/download" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "downloadUrl": "https://s3.amazonaws.com/bucket/archive.gz?X-Amz-Signature=...",
  "expiresAt": "2026-02-05T13:00:00Z",
  "checksum": "sha256:abc123def456..."
}
```

<Warning>Os arquivos nas classes de armazenamento `GLACIER` ou `DEEP_ARCHIVE` exigem uma restauração antes que a URL de download seja resolvida. `STANDARD`, `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING` e `GLACIER_IR` são imediatamente legíveis.</Warning>

## Logs de auditoria

***

Toda mudança relevante para a governança é gravada em um log de auditoria imutável, por tenant. Cada registro é encadeado em uma cadeia de hash SHA-256 à prova de adulteração (`recordHash` = `SHA-256(prevHash || conteúdo canônico)`), de modo que um cliente pode reverificar a integridade de forma independente.

### Listar logs de auditoria

Paginados por cursor, com filtros detalhados.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs?actor=user@example.com&action=CREATE&entity_type=context&date_from=2025-01-01&date_to=2025-01-31&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "550e8400-e29b-41d4-a716-446655440001",
      "entityType": "reconciliation_context",
      "entityId": "550e8400-e29b-41d4-a716-446655440002",
      "action": "CREATE",
      "actorId": "user@example.com",
      "changes": { },
      "truncated": false,
      "originalSize": 0,
      "createdAt": "2025-01-15T10:30:00Z",
      "tenantSeq": 42,
      "recordHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "hashVersion": 1
    }
  ]
}
```

Parâmetros de consulta: `actor`, `action`, `entity_type`, `date_from`, `date_to` (`YYYY-MM-DD` ou RFC 3339), `limit` (1–200, padrão 20) e `cursor`.

Quando um diff excede o limite de payload do outbox, `changes` carrega um envelope com marcador de truncamento em vez do diff completo, e `truncated` passa a `true`, com `originalSize` informando o tamanho em bytes anterior ao truncamento.

### Verificar a cadeia de auditoria

Reverifica que cada registro inspecionado se encadeia ao anterior e corresponde ao seu hash armazenado. É estritamente somente leitura — comprova a resistência à adulteração, nunca altera um registro.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify?maxRecords=10000" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "intact": true,
  "verifiedCount": 1024,
  "firstBrokenSeq": 0,
  "truncated": false
}
```

`intact` é `true` quando todo o trecho inspecionado está intacto; se uma quebra for encontrada, `firstBrokenSeq` informa o `tenantSeq` do primeiro registro que falha e `verifiedCount` informa quantos se mantiveram antes dele. `truncated` é `true` quando a cadeia contém mais registros do que o limite de inspeção `maxRecords` permitia.

### Obter um log de auditoria

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

<Note>Você também pode listar o histórico de uma entidade diretamente com `GET /v1/governance/entities/{entityType}/{entityId}/audit-logs` (paginado por cursor), o que é conveniente quando você já conhece a entidade que está auditando.</Note>

## Códigos de resposta

***

| Status | Significado                                                                                      |
| ------ | ------------------------------------------------------------------------------------------------ |
| `200`  | Dados de mapeamento, arquivo ou auditoria retornados                                             |
| `204`  | Mapeamento de ator pseudonimizado ou excluído                                                    |
| `400`  | Entrada inválida (falta displayName/email, data/paginação incorreta)                             |
| `403`  | Falta o nível de permissão necessário (por exemplo, `deanonymize` para PII de um único registro) |
| `404`  | Mapeamento de ator, arquivo ou log de auditoria não encontrado                                   |
| `422`  | Campo malformado (por exemplo, formato de email inválido)                                        |