Logs de auditoria

Toda alteração de estado e todo acesso sensível na Tokeflow grava uma entrada de log de auditoria — um registro somente de inserção (append-only) de quem fez o quê em qual recurso. Cada entrada captura o ator (um usuário do Dashboard, uma chave de API, o sistema ou um webhook de provedor), a ação realizada, a entidade afetada, o estado antes e depois da alteração, o endereço IP do cliente e se a operação foi bem-sucedida ou falhou.

Os logs de auditoria são somente leitura pela API: você pode listá-los e filtrá-los, mas nunca criá-los, modificá-los ou excluí-los. Use-os para responder "quem alterou este conector?", para reconstruir o histórico de um pedido ou de um perfil de roteamento, ou para alimentar seu próprio SIEM e pipelines de relatórios de conformidade. O campo outcome registra o sucesso ou a falha do evento, em conformidade com o PCI DSS 10.3.1.

Os resultados são delimitados pela chave de API com a qual você se autentica:

O objeto de log de auditoria

Comparar before_state e after_state mostra exatamente o que um determinado evento alterou — para a ativação de um conector, por exemplo, você veria o status antigo e o novo lado a lado.

Tipos de entidade

O campo (e filtro) entity_type aceita:

organization, merchant, user, auth_session, merchant_connector, routing_profile, routing_rule_node, payment_instrument, order, api_key, user_membership, webhook_config, transaction, transaction_attempts, transaction_refund, transaction_refunds, audit_log.

Ações

O campo (e filtro) action aceita os seguintes valores, agrupados aqui pelo que descrevem:

Endpoints

GET/api/v1/audit-logs

Retorna uma lista paginada de entradas de log de auditoria, delimitada pela chave de API autenticada. Combine filtros para restringir a trilha — por exemplo, todo login que falhou em janeiro, ou toda alteração já feita em um conector específico.

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/audit-logs \
  -H "Authorization: Bearer sk_live_org_…" \
  --data-urlencode "merchant_id=mrc_123" \
  --data-urlencode "entity_type=merchant_connector" \
  --data-urlencode "outcome=success" \
  --data-urlencode "start_date=2026-01-01T00:00:00.000Z" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Exemplo de resposta — 200 OK

O endpoint retorna as entradas correspondentes em data (mais recentes primeiro) e os metadados de paginação em meta:

{
  "data": [
    {
      "id": "9d3f2c1e-7a45-4b8e-9c12-3f6a8d0e5b21",
      "organization_id": "org_123",
      "merchant_id": "mrc_123",
      "entity_type": "merchant_connector",
      "entity_id": "1f7c9a2d-5e83-4b06-a914-c2d7e8f0a634",
      "action": "activated",
      "actor_type": "user",
      "actor_id": "550e8400-e29b-41d4-a716-446655440000",
      "before_state": { "status": "inactive" },
      "after_state": { "status": "active" },
      "outcome": "success",
      "error_message": null,
      "ip_address": "203.0.113.42",
      "created_at": "2026-01-15T12:30:00.000Z"
    },
    {
      "id": "4b8a1d6f-2c93-47e5-b120-9e5f7a3c8d16",
      "organization_id": "org_123",
      "merchant_id": "mrc_123",
      "entity_type": "merchant_connector",
      "entity_id": "1f7c9a2d-5e83-4b06-a914-c2d7e8f0a634",
      "action": "updated",
      "actor_type": "system",
      "actor_id": null,
      "before_state": { "priority": 2 },
      "after_state": { "priority": 1 },
      "outcome": "success",
      "error_message": null,
      "ip_address": null,
      "created_at": "2026-01-14T09:12:44.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 87,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Erros

Todo erro usa o envelope padrão. Os casos mais comuns para este recurso:

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

Relacionados

• Paginação e filtragem — convenções de listagem usadas em toda a API.
• Erros — o envelope de erro padrão.
• Autenticação — provisione chaves e escopos.
• Transações — os eventos de pagamento aos quais as entradas de auditoria fazem referência.