Trilha de auditoria do Merchant

A trilha de auditoria é o log de atividades imutável do Merchant. Toda alteração relevante dentro de um Merchant — um conector criado, uma chave de API revogada, um endpoint de webhook atualizado, um perfil de roteamento editado — é registrada como uma entrada de log de auditoria que captura a entidade afetada, a ação realizada, quem (ou o que) a realizou, o estado antes e depois da alteração, e se a ação foi bem-sucedida.

A visualização Atividade do Dashboard para um Merchant é alimentada pelo único endpoint desta página. As entradas são somente de inserção (append-only) e não podem ser editadas ou excluídas, o que torna a trilha adequada para revisões de conformidade e investigação forense de incidentes — os campos registrados estão alinhados com os requisitos de log de auditoria do PCI DSS, incluindo o outcome explícito de cada evento.

Esta página cobre a trilha com escopo de Merchant. A atividade em nível de Organization (abrangendo todos os Merchants além de entidades no nível da Organization) está disponível em Trilha de auditoria da Organization, e o acesso programático com chaves de API está disponível por meio da API de logs de auditoria pública.

O objeto de entrada do log de auditoria

O par before_state / after_state é o que torna uma entrada revisável: compare os dois objetos (diff) para ver exatamente quais campos mudaram. Uma entrada created tem before_state: null; uma entrada deleted tem after_state: null.

Tipos de ator

Endpoints

GET/api/v1/merchant/activity

Retorna uma lista paginada das entradas da trilha de auditoria do Merchant, das mais recentes para as mais antigas. O contexto do Merchant vem do header x-merchant-id, que o Dashboard envia para o Merchant atualmente selecionado.

Headers

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/merchant/activity \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Exemplo de resposta — 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "org_123",
      "merchant_id": "mrc_123",
      "entity_type": "merchant_connector",
      "entity_id": "conn_a1b2c3",
      "action": "created",
      "actor_type": "user",
      "actor_id": "9c1de2f4-77aa-4b0e-9a3d-2f6c8b1e5d90",
      "before_state": null,
      "after_state": {
        "provider_slug": "acquirer_a",
        "status": "active"
      },
      "outcome": "success",
      "error_message": null,
      "ip_address": "203.0.113.42",
      "created_at": "2026-08-10T14:22:05.000Z"
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "organization_id": "org_123",
      "merchant_id": "mrc_123",
      "entity_type": "webhook_endpoint",
      "entity_id": "whe_5f8d2c",
      "action": "updated",
      "actor_type": "api_key",
      "actor_id": "b2f7c9a1-4e3d-4a6b-8c5e-1d9f0a7b3c62",
      "before_state": {
        "url": "https://example.com/webhooks/old"
      },
      "after_state": null,
      "outcome": "failure",
      "error_message": "Webhook endpoint URL failed validation",
      "ip_address": "198.51.100.7",
      "created_at": "2026-08-10T13:58:41.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

Diferentemente do envelope da API pública, este endpoint do dashboard retorna o payload diretamente — um array de entradas em data e os metadados de paginação em meta.

Metadados de paginação

Erros

Consulte Erros para ver o envelope completo e o catálogo de tipos.

Relacionados

• Trilha de auditoria da Organization — atividade em toda a Organization.
• API de logs de auditoria — acesso programático com chaves de API.
• Autenticação do Dashboard — como as sessões são estabelecidas.
• Organizations e Merchants — como funcionam a associação (membership) e os papéis (roles).