> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Trabajos y lógica de reintentos
> Recupera transacciones Pix con jobs en segundo plano que resuelven estados pendientes, reintentan webhooks y mantienen la consistencia.
El plugin de Pix incluye trabajos internos que se ejecutan en segundo plano para garantizar la consistencia de los datos, completar transacciones pendientes y recuperarse automáticamente de errores.
Estos trabajos le dan resiliencia a tu sistema sin requerir intervención manual. Incluso si falla un webhook o una llamada PSTI expira, el plugin sigue trabajando en segundo plano 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
```mermaid theme={null}
sequenceDiagram
participant Job as Trabajo
participant PixPlugin as Plugin Pix
Job->>PixPlugin: Verificar estado de transacción
alt Estado = confirmado
PixPlugin-->>Job: confirmado
Job->>DB: Marcar como confirmado
else Estado = fallido
PixPlugin-->>Job: fallido
Job->>PixPlugin: Revertir fondos
Job->>DB: Marcar como fallido
else Estado = aún pendiente
PixPlugin-->>Job: pendiente
Job-->>Job: Esperar y reintentar más tarde
end
```
**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.
Estos trabajos son idempotentes y transaccionales, por lo que pueden ejecutarse de manera segura en paralelo en diferentes entornos.
## Cola de reintentos de webhooks
***
Si tu sistema no logra procesar un webhook, por ejemplo, debido a un tiempo de espera agotado o un error del servidor, el plugin de Pix no se rinde.
Las entregas de webhooks fallidas se añaden a una cola de reintentos con **retroceso exponencial**:
| Intento | Retraso antes del reintento |
| :------ | :-------------------------- |
| 1º | Inmediato |
| 2º | 10 segundos |
| 3º | 1 minuto |
| 4º | 5 minutos |
| … | Hasta 24 horas |
Si el evento aún no es reconocido después de todos los reintentos, se marca como no entregable y se registra.
Siempre responde a los webhooks rápidamente (en menos 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 el paso de confirmación se pierde
* O falla la entrega de un webhook
El plugin de Pix detecta estas situaciones durante sus escaneos de rutina y vuelve a activar cualquier acción faltante (ej., notificar → persistir).
### ¿Qué hace esto confiable?
* **Diseño con estado**: 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 falla, el sistema sabe cómo completarlo o deshacerlo de forma segura.
* **Respeta 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 | Predeterminado |
| :------------------------ | :---------------------------------------------------- | :------------- |
| `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 de Pix. Para asegurar que todo funcione sin problemas:
* Usa IDs únicos y rastreables para tus transacciones y cuentas.
* Monitorea la entrega de webhooks y los estados de las transacciones.
* Avísanos si necesitas soporte para reproducción de webhooks o visibilidad en la ejecución de trabajos.