> ## 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.

# Jobs e lógica de retentativa

> Recupere transações Pix automaticamente com jobs em segundo plano que resolvem status pendentes, retentam webhooks e mantêm a consistência.

Esses jobs dão resiliência ao seu sistema sem exigir intervenção manual. Mesmo que um webhook falhe ou uma chamada ao PSTI expire, o plugin continua trabalhando nos bastidores para resolver.

## Job de verificação de transações

***

Toda transação Pix começa como pendente. Na maioria dos casos, ela é rapidamente confirmada ou rejeitada pelo PSTI, mas às vezes essa confirmação atrasa ou se perde.

O **job de verificação de transações** periodicamente escaneia transações travadas em pendente e consulta o PSTI para uma atualização.

### Fluxo: Verificação de status

```mermaid mermaid theme={null}
sequenceDiagram
  participant Job
  participant PixPlugin as Pix Plugin
  Job->>PixPlugin: Check transaction status
  alt Status = confirmed
    PixPlugin-->>Job: confirmed
    Job->>DB: Mark as confirmed
  else Status = failed
    PixPlugin-->>Job: failed
    Job->>PixPlugin: Reverse funds
    Job->>DB: Mark as failed
  else Status = still pending
    PixPlugin-->>Job: pending
    Job-->>Job: Wait and retry later
  end
```

**Como funciona:**

* Após um breve atraso (30 segundos), o job verifica se há transações ainda marcadas como pendentes.
* Se a transação foi confirmada, ela é marcada como confirmada.
* Se falhou, o sistema reverte o débito e atualiza o status para falha.
* Se ainda está pendente, o job agenda outra verificação.

<Tip>
  Esses jobs são idempotentes e transacionais, então podem rodar com segurança em paralelo entre ambientes.
</Tip>

## Fila de retentativa de webhooks

***

Se o seu sistema falha ao processar um webhook, por exemplo, devido a um timeout ou erro do servidor, o plugin Pix não desiste.

Entregas de webhook que falharam são adicionadas a uma fila de retentativa com **backoff exponencial**:

| Tentativa | Atraso antes da retentativa |
| :-------- | :-------------------------- |
| 1a        | Imediato                    |
| 2a        | 10 segundos                 |
| 3a        | 1 minuto                    |
| 4a        | 5 minutos                   |
| ...       | Até 24 horas                |

Se o evento ainda não for reconhecido após todas as retentativas, ele é marcado como não entregue e registrado nos logs.

<Tip>
  Sempre responda a webhooks rapidamente (dentro de 5s). Se você precisa executar lógica pesada, faça isso **de forma assíncrona** após responder com `200`.
</Tip>

## Recuperação de estorno

***

Em casos raros, tentativas de estorno podem ter sucesso parcial, por exemplo:

* O valor é creditado de volta ao remetente.
* Mas a etapa de confirmação é perdida
* Ou a entrega do webhook falha

O plugin Pix detecta essas situações durante suas varreduras rotineiras e re-aciona quaisquer ações faltantes (ex.: notificar → persistir).

### O que torna isso confiável?

* **Stateful por design**: Toda transação Pix inclui uma trilha de auditoria completa e status do ciclo de vida.
* **Lógica de compensação nativa**: Se algo quebra, o sistema sabe como completar ou desfazer com segurança.
* **Respeito à idempotência**: Retentativas e jobs repetidos não produzem resultados duplicados.

## Parâmetros configuráveis

***

Você pode ajustar o comportamento dos jobs usando as seguintes variáveis de ambiente:

| Variável                  | Descrição                                          | Padrão      |
| :------------------------ | :------------------------------------------------- | :---------- |
| `PENDING_JOB_INTERVAL`    | Com que frequência verificar transações pendentes. | 30 segundos |
| `MAX_TRANSACTION_RETRIES` | Máximo de tentativas antes de marcar como falha.   | 5           |
| `RETRY_BACKOFF_BASE`      | Atraso base para retentativas de webhook           | 10 segundos |
| `MAX_RETRY_TTL`           | Duração máxima para retentativas de webhook        | 24 horas    |

## O que você precisa fazer

***

Você não precisa configurar nada; os jobs são totalmente gerenciados pelo plugin Pix. Para garantir que tudo funcione bem:

* Use IDs únicos e rastreáveis para suas transações e contas.
* Monitore a entrega de webhooks e os status das transações.
* Nos avise se precisar de suporte para replay de webhooks ou visibilidade na execução dos jobs.