Trazabilidad y bitácora de auditoría

Vecnet escribe una bitácora de auditoría de solo escritura en el registro de events. Ahí caen dos tipos de cosas:

1. Cada petición a la API: un evento http.request por llamada HTTP.
2. Cada evento de pago o de dominio: payment.approved, checkout_session.created y el resto.

Cada evento es inmutable una vez escrito, lleva marca de tiempo y queda cosido al resto del ciclo de vida de un pago por correlation_id, y a una sola llamada HTTP por request_id. Juntos permiten reconstruir exactamente qué pasó, en orden, con cualquier pago.

Cómo trabajan juntos los dos IDs

• correlation_id enlaza el ciclo de vida completo de un pago: la sesión de checkout, el intento, la aprobación o el rechazo y cualquier entrega de webhook. También coincide con transactions.correlation_id, así que puedes pivotar entre la bitácora y el registro de la transacción.
• request_id identifica una sola petición HTTP. Se devuelve en el encabezado de respuesta X-Request-Id, para que tu sistema lo cite al reportar un problema.

El encabezado X-Request-Id

Cada respuesta de la API incluye un encabezado X-Request-Id cuyo valor coincide con el request_id registrado en el evento http.request de esa llamada. Captúralo en tus logs: es lo primero que te pedirá soporte para encontrar tu petición exacta.

const res = await fetch("https://api.vecnet.io/checkout/v1/sessions", { method: "POST", headers, body });
console.log("vecnet request", res.headers.get("X-Request-Id"), res.status);

Reconstruir el ciclo de vida de un pago

La bitácora se consulta con GET /api/events. Para repetir todo lo que pasó con un solo pago, filtra por su correlation_id (el mismo valor que lleva la transacción), ordenado ascendentemente por tiempo.

curl "https://api.vecnet.io/api/events?correlation_id=corr_8f3c2a91&order=occurred_at&dir=asc" \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Merchant-Id: mrc_3f9a2c1b"

La respuesta es el sobre de lista estándar: un arreglo data de eventos más los metadatos de paginación. Un pago en línea con tarjeta típico se reconstruye en cuatro eventos:

{
  "data": [
    {
      "action": "checkout_session.created",
      "category": "checkout",
      "correlation_id": "corr_8f3c2a91",
      "request_id": "req_a1b2c3d4",
      "target_id": "cs_7Hn2pQ",
      "status_code": 201,
      "amount_cents": 150000,
      "currency": "MXN"
    },
    {
      "action": "checkout_session.viewed",
      "category": "checkout",
      "correlation_id": "corr_8f3c2a91",
      "request_id": "req_e5f6g7h8",
      "target_id": "cs_7Hn2pQ"
    },
    {
      "action": "payment.attempted",
      "category": "payment",
      "correlation_id": "corr_8f3c2a91",
      "request_id": "req_i9j0k1l2",
      "target_id": "cs_7Hn2pQ",
      "metadata": { "brand": "visa", "last4": "4242" }
    },
    {
      "action": "payment.approved",
      "category": "payment",
      "correlation_id": "corr_8f3c2a91",
      "request_id": "req_i9j0k1l2",
      "target_id": "txn_9Rm3sT",
      "metadata": { "brand": "visa", "last4": "4242" }
    }
  ],
  "count": 4,
  "limit": 50,
  "offset": 0
}

Los eventos payment.attempted y payment.approved comparten un request_id (vinieron de la misma llamada), mientras que los cuatro comparten un correlation_id, así que se leen como un solo ciclo de vida coherente.

Filtros útiles

GET /api/events acepta los parámetros de lista estándar más filtros propios de la bitácora:

• correlation_id: el ciclo de vida completo de un pago.
• request_id: una sola llamada HTTP.
• action: por ejemplo payment.declined, checkout_session.created.
• category: por ejemplo payment, checkout, webhook, error.
• target_id: todo lo que tocó un objeto (una sesión, una transacción).
• from / to: rango de fechas (YYYY-MM-DD).

# Todos los rechazos de un comercio en un rango de fechas
curl "https://api.vecnet.io/api/events?action=payment.declined&from=2026-06-01&to=2026-06-22" \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Merchant-Id: mrc_3f9a2c1b"