Problema resolvido
Quando a rede ou o BaaS retorna resposta ambígua (ex.: timeout, 5xx, EOF), o webhook atrasa ou a máquina de estados fica indecisiva, não se deve adivinhar o resultado. Workers de reconciliação reconsultam o status autoritativo (ex.:GET de transação por externalId) e aplicam o mesmo pipeline do processamento de webhook, com deduplicação se o evento atrasar.
Escopos (origem)
| Escopo | Objetivo |
|---|---|
| Cash-in | Desbloquear cash-ins PENDING / PROVIDER_RESULT_UNKNOWN / estados de conferência |
| Refund-in | Concluir refund pendentes ou ambíguos |
| Cash-out | Resolver PROVIDER_RESULT_UNKNOWN / RECONCILIATION_REQUIRED sem liberar reserva indevidamente |
pix_reconciliation_task no desenho do diagrama (fluxograma de reconciliação).
Por que o integrador ainda se importa
- Estados como
RECONCILIATION_REQUIREDnão são “ok para ignorar”: impactam a UI, bloqueio de entrega e podem exigir ação operacional. - A reconciliação interna da plataforma não dispensa a sua observabilidade: monitore idade de operações, reconcilie com o ledger e defina alertas. A origem cita, nas boas práticas, monitorar estados não terminais antigos (> 30 min) e alinhar com o suporte.
Regras de segurança (resumo, origem)
- Não marque falha definitiva por um
404sem política de idade/ evidência. - Não libere reserva de cash-out sem falha confirmada no parceiro.
- A revisão manual pode ser preferida a perder rastreio de dinheiro de forma silenciosa.
Desenho lógico (mermaid, origem)
Parâmetros operacionais (ilustrativos, não-SLA)
A origem lista variáveis comoCASH_IN_RECONCILE_WORKERS, CASH_IN_RECONCILE_POLL_SEC, CASH_IN_RECONCILE_STALE_SEC, CASH_IN_RECONCILE_MIN_ATTEMPTS_FOR_MANUAL, análogos de REFUND_IN_* e CASH_OUT_*, e outbox de despacho (CASH_OUT_DISPATCH_WORKERS etc.) — ajuste por ambiente; trate como notas de implementação, não como compromisso contratual de tempo.
TODO: tabela unificada com valores padrão oficiais por ambiente, se a operação publicar.