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

# Gobernanza

> Gestiona los mapeos de PII de actores, descarga archivos de logs de auditoría completados y vuelve a verificar la cadena de hash de auditoría a prueba de manipulaciones de Matcher — la superficie de cumplimiento para GDPR y auditoría.

La superficie de gobernanza de Matcher agrupa las tres capacidades orientadas al cumplimiento bajo `/v1/governance`: **mapeos de actores** (vinculan IDs de actores opacos con PII, con pseudonimización/borrado GDPR), **archivos** (descarga archivos de logs de auditoría completados desde almacenamiento en frío) y **logs de auditoría** (historial inmutable, encadenado por hash, que puedes volver a verificar de forma independiente). El inquilino siempre se resuelve desde el JWT — nunca desde una ruta o un cuerpo.

<Note>Cada ruta de gobernanza está delimitada al inquilino del llamante. Las lecturas de mapeos de actores se dividen en dos niveles de autorización: la lista sin PII frente a la lectura de des-anonimización de un solo registro, para que la resolución de identidad se mantenga separable del acceso de navegación.</Note>

## Mapeos de actores

***

Un mapeo de actor vincula un `actorId` opaco (por ejemplo `user:550e8400-e29b-41d4-a716-446655440000`) con PII legible (`displayName`, `email`). Las filas de la lista son **sin PII por diseño** — solo el `GET` de un solo registro devuelve la identidad en texto claro.

### Listar mapeos de actores

Filas paginadas por cursor, sin PII. Filtra por un prefijo de ID de actor.

```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 prefijo), `limit` (predeterminado 25, con tope de 100) y `cursor`.

### Upsert de un mapeo de actor

Crea o actualiza la PII de un ID de actor. `PUT` es idempotente — la misma llamada crea el registro en el primer uso y lo actualiza a partir de entonces. Debes proporcionar al menos uno de `displayName` o `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"
}
```

### Obtener un mapeo de actor (des-anonimizar)

Devuelve la PII en texto claro de un solo ID de actor. Esta **es** la primitiva de des-anonimización, por lo que está protegida por el permiso más restringido `deanonymize` en lugar de la lectura simple.

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

### Pseudonimizar (GDPR)

Reemplaza `displayName` y `email` con `[REDACTED]` mientras conserva el registro y su vínculo con `actorId` — la pista de auditoría permanece intacta pero la 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"
```

### Eliminar (derecho al olvido)

Elimina permanentemente el mapeo para el derecho al olvido de 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 mantiene el registro (con la PII depurada); eliminar lo borra por completo. Elige pseudonimizar cuando debas conservar el vínculo de auditoría, y eliminar cuando el propio registro no deba persistir.</Note>

## Archivos

***

Cuando las particiones de logs de auditoría caducan, se comprimen y se mueven a almacenamiento de objetos. Los endpoints de archivos listan los archivos completados y emiten URLs de descarga con tiempo limitado.

### Listar archivos

Paginados por offset. Filtra por rango de fechas.

```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` o RFC 3339), `limit` (1–200, predeterminado 20) y `offset`. Solo se listan los archivos `COMPLETE` — los archivos en curso y fallidos nunca se exponen.

### Descargar un archivo

Devuelve una URL prefirmada más el checksum para la verificación de integridad.

```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>Los archivos en las clases de almacenamiento `GLACIER` o `DEEP_ARCHIVE` requieren una restauración antes de que la URL de descarga se resuelva. `STANDARD`, `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING` y `GLACIER_IR` son legibles de inmediato.</Warning>

## Logs de auditoría

***

Todo cambio relevante para la gobernanza se escribe en un log de auditoría inmutable, por inquilino. Cada registro se enlaza en una cadena de hash SHA-256 a prueba de manipulaciones (`recordHash` = `SHA-256(prevHash || contenido canónico)`), de modo que un cliente puede volver a verificar la integridad de forma independiente.

### Listar logs de auditoría

Paginados por cursor, con filtros detallados.

```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` o RFC 3339), `limit` (1–200, predeterminado 20) y `cursor`.

Cuando un diff excede el tope de payload del outbox, `changes` lleva un envoltorio con marcador de truncamiento en lugar del diff completo, y `truncated` pasa a `true`, con `originalSize` informando el tamaño en bytes previo al truncamiento.

### Verificar la cadena de auditoría

Vuelve a verificar que cada registro inspeccionado se enlaza con el anterior y coincide con su hash almacenado. Es estrictamente de solo lectura — prueba la resistencia a manipulaciones, nunca modifica un 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` es `true` cuando todo el tramo inspeccionado está intacto; si se encuentra una rotura, `firstBrokenSeq` informa el `tenantSeq` del primer registro que falla y `verifiedCount` informa cuántos se mantuvieron antes de él. `truncated` es `true` cuando la cadena contiene más registros de los que permitía el límite de inspección `maxRecords`.

### Obtener un log de auditoría

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

<Note>También puedes listar el historial de una entidad directamente con `GET /v1/governance/entities/{entityType}/{entityId}/audit-logs` (paginado por cursor), lo cual resulta conveniente cuando ya conoces la entidad que estás auditando.</Note>

## Códigos de respuesta

***

| Estado | Significado                                                                             |
| ------ | --------------------------------------------------------------------------------------- |
| `200`  | Datos de mapeo, archivo o auditoría devueltos                                           |
| `204`  | Mapeo de actor pseudonimizado o eliminado                                               |
| `400`  | Entrada inválida (falta displayName/email, fecha/paginación incorrecta)                 |
| `403`  | Falta el nivel de permiso requerido (p. ej. `deanonymize` para PII de un solo registro) |
| `404`  | Mapeo de actor, archivo o log de auditoría no encontrado                                |
| `422`  | Campo mal formado (p. ej. formato de email inválido)                                    |