Estos trabajos le dan resiliencia a tu sistema sin requerir intervención manual. Incluso si un webhook falla o una llamada PSTI se agota, el plugin sigue trabajando tras bambalinas para solucionarlo.
Trabajo de verificación de transacciones
Cada transacción Pix comienza como pendiente. En la mayoría de los casos, es rápidamente confirmada o rechazada por el PSTI, pero a veces esa confirmación se retrasa o se pierde.
El trabajo de verificación de transacciones escanea periódicamente las transacciones atascadas en pendiente y solicita una actualización al PSTI.
Flujo de trabajo: Verificación de Estado
Cómo funciona:
- Después de un breve retraso (30 segundos), el trabajo verifica cualquier transacción aún marcada como pendiente.
- Si la transacción está confirmada, se marca como confirmada.
- Si falla, el sistema revierte el débito y actualiza el estado a fallido.
- Si aún está pendiente, el trabajo programa otra verificación.
ConsejoEstos trabajos son idempotentes y transaccionales, por lo que pueden ejecutarse de forma segura en paralelo en diferentes entornos.
Cola de reintentos de webhook
Si tu sistema no procesa un webhook, por ejemplo, debido a un tiempo de espera o error del servidor, el plugin Pix no se rinde.
Las entregas de webhook fallidas se agregan a una cola de reintentos con backoff exponencial:
| Intento | Retraso antes del reintento |
|---|
| 1ro | Inmediato |
| 2do | 10 segundos |
| 3ro | 1 minuto |
| 4to | 5 minutos |
| … | Hasta 24 horas |
Mejor práctica
Siempre responde a los webhooks rápidamente (dentro de 5s). Si necesitas ejecutar lógica pesada, hazlo de forma asíncrona después de responder con 200.Recuperación de reversiones
En casos extremos raros, los intentos de reversión pueden tener éxito parcial, por ejemplo:
- El valor se acredita de vuelta al remitente.
- Pero se pierde el paso de confirmación
- O falla una entrega de webhook
El plugin Pix detecta estas situaciones durante sus escaneos rutinarios y vuelve a activar cualquier acción faltante (ej., notificar → persistir).
¿Qué hace esto confiable?
- Con estado por diseño: Cada transacción Pix incluye un registro de auditoría completo y estado del ciclo de vida.
- Lógica de compensación integrada: Si algo se rompe, el sistema sabe cómo completarlo o deshacerlo de forma segura.
- Respetando la idempotencia: Los reintentos y trabajos repetidos no producirán resultados duplicados.
Parámetros configurables
Puedes ajustar el comportamiento de los trabajos usando las siguientes variables de entorno:
| Variable | Descripción | Por defecto |
|---|
PENDING_JOB_INTERVAL | Con qué frecuencia verificar transacciones pendientes. | 30 segundos |
MAX_TRANSACTION_RETRIES | Intentos máximos antes de marcar como fallido. | 5 |
RETRY_BACKOFF_BASE | Retraso base para reintentos de webhook | 10 segundos |
MAX_RETRY_TTL | Duración máxima para reintentos de webhook | 24 horas |
Lo que necesitas hacer
No necesitas configurar nada; los trabajos son completamente gestionados por el plugin Pix. Para asegurar que todo funcione sin problemas:
- Usa IDs únicos y rastreables para tus transacciones y cuentas.
- Monitorea la entrega de webhooks y estados de transacciones.
- Avísanos si necesitas soporte para reproducción de webhooks o visibilidad en la ejecución de trabajos.
