Pular para conteúdo

0024 — Financiamento: gatilho por status, CFOP da Nota Futura e retenção no pagamento

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-25 · Decidido em: 2026-09-25

Contexto

O gate de envio ao X-Adm é a transição do pagamento para received. No financiamento o banco paga semanas depois, ou o pagamento nem aparece na PIED. Para não esperar, a Maxsul cadastrava esses pedidos à mão no X-Adm antes de o banco pagar. Quando o pagamento caía, o gate enviava o pedido de novo, e o X-Adm gravava um segundo pedido.

Medido em 25/09/2026:

  • três pedidos em ERRO_XADM (260080132, 260083887, 260083896): o passo estoque respondeu "cadastrado previamente" com o número do pedido manual, e o passo contratos criou outro número;
  • quatro duplicatas silenciosas, sem erro nenhum (o X-Adm respondeu "cadastrado com o código" com número novo): 260083407, 260081356, 260076582, 260081654;
  • 98 pedidos CAPTURADO em status de financiamento, todos já cadastrados à mão (confirmado pela Maxsul). Cada um duplicaria quando o banco pagasse.

A PIED não identifica financiamento no payment.type (vem boleto ou pix). O sinal está no dealStatus: Aguardando Financiamento, NF Faturamento Banco - Financiamento, Nota Futura Emitida. Esse status some depois do pagamento.

A Maxsul criou dois status novos para disparar o envio: Nota de Venda e Nota Futura (os literais da PIED, conferidos no webhook e no REST). Regras passadas pela Maxsul (Felype) e aceitas pelo X-Adm (Tiago):

  • Nota de Venda: pedido normal, como se estivesse pago.
  • Nota Futura: pedido normal com CFOP de entrega futura — kit 5.116 (SC) / 6.116; avulso 5.117 (SC) / 6.117. Sem distinção PF/PJ; Compl 0 em todos. A nota de simples faturamento a Maxsul continua emitindo à parte; no X-Adm entra só o pedido de entrega.
  • Nesses casos não há gatilho de pagamento, só a mudança de status.

Decisão

  1. Gatilho por status. No upsert de pied_pedido, um pedido CAPTURADO que muda para um status de PIED_GATE_FINANCIAMENTO_GATILHO vai para NA_FILA sem pagamento. "Muda para", não "está em": quem já estava no status antes do deploy foi cadastrado à mão e não pode sair. Pedido visto pela primeira vez já no status só sai com o resgate da 1ª captura (decisão 0023), pelas mesmas cercas.
  2. CFOP da Nota Futura. No mesmo statement do gatilho grava-se pied_pedido.nota_futura. O transform usa essa coluna, não o dealStatus corrente: o status muda depois do envio (OP Gerada, Despachado…), e um reenvio por erro mudaria o CFOP e o content_hash.
  3. Retenção no pagamento. Pedido visto em qualquer status de financiamento (os de PIED_GATE_FINANCIAMENTO_STATUS ou do gatilho) ganha financiamento_em (set-once) e não vai para a fila pelo pagamento nem pelo resgate. Fica CAPTURADO e pago, com o aviso "Financiamento" na home, e o operador escolhe Importar (envia) ou Dispensar (já está no X-Adm).
  4. Semeadura. A migração V14 marca financiamento_em nos CAPTURADO em status de financiamento no momento do deploy.

Os nomes dos status ficam em configuração (pied.gate.financiamento.*), não no código.

Alternativas descartadas

  • Liberar o Dispensar antes do pagamento, sem retenção. Depende de alguém marcar cada pedido à mão; com 98 abertos, o erro seria questão de tempo.
  • Consultar o X-Adm antes de enviar. Não existe consulta de "pedido já existe" no Integrador e criaria mais uma dependência. Também não pegaria o pedido manual lançado com outro cliente.
  • Depender só da correção no X-Adm. O X-Adm não reconheceu a duplicata em quatro dos sete casos.

Consequências

  • Pedido financiado deixa de exigir cadastro manual; o comercial para de cadastrar à mão depois do deploy, avisado pelo dono. Enquanto os dois convivem, um pedido movido para Nota de Venda/Nota Futura e também cadastrado à mão duplica.
  • Pedido que passou por Aguardando Financiamento e acabou pago à vista também fica retido: um clique em Importar. Custo aceito em troca de não duplicar.
  • Recusa ou cancelamento de pedido enviado sem pagamento não é detectado: o alerta de cancelamento pós-import depende de payment.status → cancelled. Mesmo buraco do pedido pago; fica para depois.
  • A mudança para Nota Futura pode chegar só pelo REST, sem webhook e com o mesmo lastUpdate (caso 260085433). O empate do guard de recência deixa passar, então o gatilho dispara no próximo poll. Um status de segundos (caso 260084861, 12 s em Nota de Venda) é pego porque a normalização aplica cada webhook em ordem cronológica.