Bandeja de eventos de integración

Una pasarela de pago envía a Factuarea un evento por todo lo que ocurre en tu cuenta: un cobro con éxito, una devolución emitida, un ciclo de suscripción cobrado, un payout que llega. La mayoría de esos eventos producen algo — una factura, una rectificativa, un registro de pago. Algunos no producen nada, y cuando eso pasa la pregunta interesante siempre es la misma: ¿por qué este cobro no acabó en factura?

La bandeja de eventos de integración la contesta. Cada evento que Factuarea recibe queda registrado con lo que produjo y, cuando no produjo nada, con un motivo de descarte tipado salido de un catálogo cerrado. Sin adivinar en los logs, sin abrir un ticket de soporte: el motivo es un valor por el que puedes filtrar y, en los motivos sobre los que puedes actuar, viene con el siguiente paso y, a veces, con la posibilidad de reprocesar el evento.

La bandeja es agnóstica de la pasarela. Registra eventos de cualquier integración que escriba historial — incluidas las pasarelas que todavía no están liberadas y los eventos históricos de una que se retire — porque ocultar esas filas te dejaría sin explicación para cobros que nunca se facturaron.

La exponen tres endpoints:

La misma superficie existe como tools MCP — list_integrations_events, get_integrations_event y replay_integrations_event — con los mismos scopes.

Recorrer la bandeja

Del más reciente al más antiguo, acotado a la empresa autenticada. Paginación por cursor con limit (de 1 a 100; 25 por defecto) y starting_after:

curl -G https://api.factuarea.com/v1/integrations/events \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "provider=stripe" \
  --data-urlencode "status=skipped" \
  --data-urlencode "limit=50"

{
  "data": [
    {
      "id": "0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f",
      "object": "integration_event",
      "provider": "stripe",
      "event_type": "invoice.paid",
      "direction": "inbound",
      "status": "skipped",
      "discard_reason": "subscription_autoinvoicing_disabled",
      "discard_reason_label": "Auto-facturación de suscripciones desactivada",
      "is_actionable": true,
      "is_replayable": true,
      "error_message": null,
      "duration_ms": 412,
      "created_at": "2026-07-14T09:31:07Z"
    }
  ],
  "has_more": true,
  "next_cursor": "84120"
}

Trata next_cursor como opaco: en este listado es una cadena numérica, no un UUID v7 como los cursores de los listados de documentos. Devuélvelo tal cual en starting_after.

discard_reason_label llega siempre en español, el idioma de la interfaz del producto, sea cual sea el idioma de tu integración. Si construyes un panel en otro idioma, apoya tus propios textos en discard_reason — ese valor es el identificador estable y cerrado.

Filtros

discard_reason es el eje cerrado; event_type no es un enum. La columna event_type mezcla a propósito dos convenciones: las ramas instrumentadas más tarde guardan el tipo crudo de la pasarela (charge.refunded), mientras que las preexistentes conservan su propio valor semántico (autoinvoice.*). Búscalo por coincidencia exacta cuando sepas qué persigues, pero no lo modeles nunca como un conjunto cerrado — estarías modelando algo que la columna no garantiza.

is_parked=false no es lo mismo que omitir el parámetro. El primero excluye los eventos parqueados; el segundo no excluye nada.

Un valor fuera de su catálogo devuelve 422, y un parámetro de consulta desconocido devuelve 400 parameter_unknown en lugar de ignorarse en silencio — un filtro que se cae sin avisar te entrega una página que crees acotada y no lo está.

El catálogo de motivos de descarte

Veinte motivos tipados, uno por cada rama de descarte del pipeline de webhooks de las pasarelas. Cada uno declara dos decisiones de negocio que no son banderas decorativas:

• Accionable — ¿puede hacer algo el titular de la cuenta? Solo los motivos accionables avisan. Avisar a alguien de un descarte que no puede resolver le enseña a ignorar la bandeja, y así es como se pierde el aviso que sí importaba.
• Parqueado — ¿reprocesar el mismo contenido podría dar otro resultado? Solo los eventos parqueados guardan su contenido cifrado y admiten un reproceso.

La regla detrás de la columna de parqueo: un evento se parquea cuando el descarte lo causó un estado externo que puedes cambiar (un ajuste apagado, una cuenta conectada que se desvinculó, una moneda todavía sin tipo de cambio). No se parquea cuando la causa es el contenido del propio evento (malformado, duplicado, de tipo no cubierto, importe cero, ciclo ya facturado) — reprocesarlo tomaría exactamente la misma rama y solo escribiría una segunda fila. De ahí el invariante: todo motivo parqueado es accionable, y seis de los nueve accionables se parquean.

Un motivo sin nada que hacer lo dice explícitamente. Once de los veinte son informativos, y el contrato no se inventa una instrucción para ellos: el endpoint de detalle devuelve recommended_action: null en lugar de una frase fabricada para rellenar el campo.

Avisos: solo lo que puedes arreglar

Un descarte accionable avisa a los administradores de la cuenta. Uno informativo no avisa nunca.

El aviso lleva throttling: si ya existe un aviso sin leer de la misma empresa, la misma pasarela y el mismo motivo dentro de las últimas 24 horas, no se crea un segundo — un webhook mal configurado dispara cientos de eventos idénticos. La condición es sin leer a propósito: una vez lo has leído, si siguen llegando descartes, el siguiente sí avisa. Eso no es ruido, significa que la incidencia sigue viva.

El parqueo y la ventana de 30 días

Cuando un motivo es parqueable, Factuarea guarda el evento crudo cifrado en reposo, para poder reprocesarlo más tarde. Ese contenido nunca se devuelve por la API — ni en el listado, ni en el detalle. Contiene datos personales de tus clientes finales y datos de pago, y existe para exactamente un propósito: hacer posible el reproceso.

El contenido se purga a los 30 días de parquearse el evento. La fila sobrevive: su motivo, su estado, su fecha y su marca is_parked siguen en tu bandeja indefinidamente, porque el registro de que un cobro no produjo factura es historial que puedes necesitar mucho después de que el contenido caduque.

El detalle: qué hacer a continuación

El endpoint de detalle devuelve todo lo del listado, más recommended_action: una frase en imperativo con el siguiente paso para ese motivo concreto, o null cuando el motivo es informativo.

curl https://api.factuarea.com/v1/integrations/events/0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

La frase distingue a propósito los motivos reproducibles («… y reprocesa el evento») de los que no lo son («… emítela a mano»), de modo que nunca te apunta a una operación que respondería 422.

Un evento de otra empresa y un evento que no existe devuelven el mismo 404 resource_not_found. El endpoint nunca revela si un id existe en otro sitio.

Reprocesar un evento parqueado

Vuelve a procesar un evento de la pasarela que quedó parqueado, una vez que ya no está la causa que le impidió producir su efecto — has reactivado la auto-facturación, has vuelto a vincular la cuenta conectada, ya está disponible el tipo de cambio oficial del día.

curl -X POST https://api.factuarea.com/v1/integrations/events/0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f/replay \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Cuatro propiedades de esta operación importan más que su firma:

• No duplica facturas. El reproceso pasa por el mismísimo control de idempotencia que el intento original, así que si ese cobro ya produjo una factura, el job se detiene solo y no crea nada.
• Es asíncrono. 202 significa aceptado y encolado, no completado. El cuerpo devuelve el evento tal como está ahora — su is_replayable sigue siendo true —, no el resultado del reintento. El resultado aparece como un evento nuevo en la bandeja, así que consulta GET /v1/integrations/events para ver cómo acabó.
• Si la causa sigue presente, el evento se descarta otra vez y se registra de nuevo. Es correcto, y es observable.
• No admite entrada. Cualquier parámetro de consulta o clave del cuerpo devuelve 400 parameter_unknown en lugar de ignorarse. Enviar uno significa que crees estar configurando algo del reintento — un modo, una serie, una fecha — que esta operación no soporta, y aceptarlo en silencio confirmaría esa expectativa falsa sobre una acción que puede emitir una factura. Un cuerpo vacío, o directamente ningún cuerpo, es el caso normal.

Cuando se rechaza un reproceso

is_replayable: true es el contrato: cuando vale true, el reproceso no responde 422. Es la conjunción de tres condiciones — el evento está parqueado, todavía conserva su contenido y su motivo admite reproceso —, evaluadas en ese mismo orden por el propio handler que guarda el reproceso. Eso es lo que te permite ofrecer un botón de reintento sin adivinar.

Los tres rechazos devuelven 422 business_rule_violation y te dicen cuál es a través del subcode:

Dónde encaja esto

• Auto-facturación con Stripe — el flujo que produce la mayoría de los eventos que encontrarás aquí, incluidos los ciclos de suscripción cuyo ajuste está detrás de subscription_autoinvoicing_disabled.
• Payouts y conciliación bancaria — la ingesta de payouts que hay detrás de payout_missing_id y payout_connected_account_missing.
• Modo de prueba y sandbox — valida tu tratamiento de la bandeja con una clave fact_test_ antes de conectar un botón de reproceso a una credencial de producción.
• Gestión de errores — el envelope de las respuestas 400, 404 y 422 citadas más arriba.