Registros de auditoría

Todo cambio de estado y todo acceso sensible en Tokeflow escribe una entrada de registro de auditoría — un registro de solo inserción (append-only) de quién hizo qué a qué recurso. Cada entrada captura al actor (un usuario del Dashboard, una clave de API, el sistema o un webhook de proveedor), la acción realizada, la entidad afectada, el estado antes y después del cambio, la dirección IP del cliente y si la operación se realizó correctamente o falló.

Los registros de auditoría son de solo lectura a través de la API: puedes listarlos y filtrarlos, pero nunca crearlos, modificarlos ni eliminarlos. Úsalos para responder "¿quién cambió este conector?", para reconstruir el historial de un pedido o de un perfil de enrutamiento, o para alimentar tu propio SIEM y tus flujos de generación de informes de cumplimiento. El campo outcome registra el éxito o el fracaso del evento, conforme a PCI DSS 10.3.1.

Los resultados están delimitados por la clave de API con la que te autenticas:

El objeto de registro de auditoría

Comparar before_state y after_state te muestra exactamente qué cambió un evento determinado — para la activación de un conector, por ejemplo, verías el estado antiguo y el nuevo uno junto al otro.

Tipos de entidad

El campo (y filtro) entity_type acepta:

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.

Acciones

El campo (y filtro) action acepta los siguientes valores, agrupados aquí según lo que describen:

Endpoints

GET/api/v1/audit-logs

Devuelve una lista paginada de entradas de registro de auditoría, delimitada por la clave de API autenticada. Combina filtros para acotar el registro — por ejemplo, todos los inicios de sesión fallidos de enero, o todos los cambios realizados alguna vez en un conector específico.

Parámetros de consulta

Ejemplo de solicitud

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"

Ejemplo de respuesta — 200 OK

El endpoint devuelve las entradas coincidentes en data (las más recientes primero) y los metadatos de paginación en 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
  }
}

Errores

Todos los errores usan el envoltorio estándar. Los casos más comunes para este recurso:

Consulta Errores para conocer el envoltorio completo y el catálogo de tipos.

Relacionado

• Paginación y filtrado — convenciones de listado usadas en toda la API.
• Errores — el envoltorio estándar de errores.
• Autenticación — aprovisiona claves y scopes.
• Transacciones — los eventos de pago a los que hacen referencia las entradas de auditoría.