> ## 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 novas tentativas

> Recupere operações Pix automaticamente com jobs em segundo plano que repetem eventos com falha, conciliam devoluções e mantêm os dados consistentes.

O plugin do Pix recupera operações automaticamente com jobs em segundo plano e novas tentativas. Se uma chamada ao provedor der timeout ou um evento falhar no processamento, o plugin tenta de novo e concilia os dados sem trabalho manual.

## Novas tentativas automáticas

***

O plugin processa os eventos Pix de forma assíncrona. Se falhar ao processar um evento, o plugin tenta de novo no mesmo lugar e depois captura o evento em uma dead-letter queue, sem perda. Um operador reprocessa um evento estacionado, limitado a um número máximo de tentativas. Depois do limite, o registro continua estacionado para inspeção e o plugin nunca o descarta.

O plugin repete as chamadas de saída ao provedor em respostas 5xx e em timeouts. Cada nova tentativa usa backoff exponencial com jitter.

<Tip>
  O plugin deduplica eventos por ID durante uma janela de tempo fixa. Um evento repetido ou duplicado nunca é aplicado duas vezes, então os jobs continuam idempotentes.
</Tip>

## Conciliação de devoluções

***

Uma devolução pode ter sucesso no provedor e mesmo assim não ser registrada localmente, se o serviço cair entre os dois passos. O sweeper de conciliação de devoluções é a rede de segurança em segundo plano para esse caso.

O sweeper roda em um timer e encontra devoluções ainda travadas em pendente. Para cada uma, ele reexecuta os passos idempotentes (liquidar, confirmar ou encerrar), que o provedor deduplica pela referência da devolução. Ele estaciona para um operador a linha que ainda está no passo de criação, porque repetir a criação às cegas poderia causar uma devolução em duplicidade.

```mermaid theme={null}
sequenceDiagram
  participant Sweeper
  participant Provider
  participant DB
  Sweeper->>DB: Busca linhas de devolução pendentes
  Sweeper->>Provider: Reexecuta o passo faltante
  alt Success
    Provider-->>Sweeper: confirmado
    Sweeper->>DB: Marca como concluído
  else Still failing
    Provider-->>Sweeper: erro
    Sweeper->>DB: Registra a tentativa e recua
  else Attempts exhausted
    Sweeper->>DB: Estaciona a linha e dispara alerta
  end
```

Cada tentativa que falha espera mais que a anterior, de um minuto até uma hora. Depois de um número máximo de tentativas, o sweeper estaciona o registro e dispara um alerta. Ele não tenta para sempre. O sweeper é opcional e vem desligado por padrão.

## Configuração

***

Você pode ajustar o comportamento de novas tentativas e de conciliação com variáveis de ambiente:

| Variável                                     | Descrição                                                                                       | Padrão |
| :------------------------------------------- | :---------------------------------------------------------------------------------------------- | :----- |
| `DLQ_REPLAY_MAX_ATTEMPTS`                    | Quantas vezes um operador pode reprocessar um evento estacionado antes de ele ficar estacionado | 3      |
| `CONSUMER_DEDUP_TTL_SEC`                     | Janela de deduplicação, em segundos, que mantém o processamento de eventos idempotente          | 3600   |
| `REFUND_RECONCILIATION_SWEEPER_ENABLED`      | Liga o sweeper de conciliação de devoluções                                                     | false  |
| `REFUND_RECONCILIATION_SWEEPER_INTERVAL_SEC` | Tempo, em segundos, entre as varreduras                                                         | 30     |
| `REFUND_RECONCILIATION_SWEEPER_MAX_ATTEMPTS` | Tentativas antes de o sweeper estacionar um registro e disparar um alerta                       | 10     |

## O que você precisa fazer

***

O plugin gerencia as novas tentativas e a conciliação para você. As configurações padrão servem à maioria dos deploys. Para manter as operações saudáveis:

* Use IDs únicos e rastreáveis para suas transações e contas.
* Monitore a entrega dos eventos e o status das transações.
* Fale com a Lerian para visibilidade dos jobs ou suporte a reprocessamento de eventos.