Pular para o conteúdo principal
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.
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.

​
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. 
curl -X GET "https://api.matcher.example.com/v1/governance/actor-mappings?actorId=user:&limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "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. 
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"
  }'

{
  "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. 
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. 
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. 
curl -X DELETE "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN"
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.

​
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. 
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"

{
  "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. 
curl -X GET "https://api.matcher.example.com/v1/governance/archives/{id}/download" \
  -H "Authorization: Bearer $TOKEN"

{
  "downloadUrl": "https://s3.amazonaws.com/bucket/archive.gz?X-Amz-Signature=...",
  "expiresAt": "2026-02-05T13:00:00Z",
  "checksum": "sha256:abc123def456..."
}
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.

​
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. 
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"

{
  "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. 
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify?maxRecords=10000" \
  -H "Authorization: Bearer $TOKEN"

{
  "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

curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/{id}" \
  -H "Authorization: Bearer $TOKEN"
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.

​
Códigos de resposta

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