Skip to main content

​
O que a reconciliação automática resolve

Quando o parceiro não responde de forma conclusiva (timeout, 5xx, EOF), o webhook atrasa ou ocorre resposta ambígua, entram workers que consultam o status autoritativo no BaaS (ex.: GET de transação por externalId) e aplicam o mesmo pipeline do handler de webhook, com deduplicação se o evento atrasar. Escopos documentados: Cash-In, Refund-In e Cash-Out (cada qual com tarefa/fila lógica similar a pix_reconciliation_task na descrição de origem).

​
Estados ambíguos (ação do integrador)

EstadoNão conclua negócio crítico
PROVIDER_RESULT_UNKNOWNPode ainda evoluir após consulta ao parceiro.
RECONCILIATION_REQUIREDPode requerer tempo ou processo; não assuma pago/estorno sem evidência.
Siga a política status e a conciliação com o ledger.

​
Consultar x esperar webhook

  • Considere o webhook a fonte de baixa assíncrona para o comerciante, mas trate reentregas.
  • Se o operador vê a operação feita no banco, mas ainda há ambiguidade de lado clearpago, use GET de detalhe no recurso (/api/pix/.../{id}) com cadência e backoff — sem martelar a API. A reconciliação interna fechará a lacuna; eventualmente, alinhe com o suporte.

​
Regras de segurança (resumo da origem)

  • Não marque falha definitiva por um 404 sem política de idade/ evidência.
  • Não libere reserva de cash-out sem falha confirmada pelo parceiro.
  • Ambiguidades repetidas podem exigir revisão manual em vez de perda silenciosa de rastreio.

​
Variáveis de ambiente (operacional, ilustrativas)

Valores ilustrativos na origem: CASH_IN_RECONCILE_WORKERS, CASH_IN_RECONCILE_POLL_SEC, CASH_IN_RECONCILE_STALE_SEC, análogos de REFUND_IN_* e CASH_OUT_*, além de outbox de despacho (CASH_OUT_DISPATCH_WORKERS, CASH_OUT_DISPATCH_POLL_MS, CASH_OUT_DISPATCHED_STALE_SEC etc.). Ajuste por ambiente e acordo com a operação SRE — a fonte cita ainda leitura de arquivos como cash_out_outbox_dispatcher.go e api.go no repositório de implementação; isso não é parte pública de contrato HTTP. TODO: observabilidade — se a camada oferece trace ID para correlacionar com X-Correlation-ID do cliente; a origem não detalha além do echo descrito.

​
Onde aprofundar