Retorno DAVOS¶

O que é¶

Etapa final do ciclo de cessao: depois que o cliente paga a parcela e o operador marca o pagamento como repassado ao fundo, gera-se um arquivo CNAB de retorno informando à DAVOS quais parcelas cedidas foram efetivamente pagas. Regra central do ciclo: só é possível gerar retorno de uma parcela que tem cessão — ou seja, que já tem linha em cnab_remessa_linhas.

Como funciona¶

Tela /carteira/cessao/retorno-davos (apps/crm-menos-juros/client/src/pages/carteira/cessao/retorno-davos.tsx, hooks em apps/crm-menos-juros/client/src/hooks/use-retorno-davos.ts; backend retorno-davos.controller.ts, gerar-retorno-davos.use-case.ts, retorno-davos.repository.ts).

Pré-requisito: repasse ao fundo¶

Antes do retorno existe uma etapa intermediária fora desta tela: na tela /carteira/conciliacao, depois que a parcela é paga (fluxo_pagamentos.status_pagamento = pago/baixa manual/baixa por quitação etc.), o operador marca a parcela como repassada ao fundo (fluxo_pagamentos.repassado_fundo='SIM'), individualmente ou em lote. Ver repasse-ao-fundo.

Parcelas Pendentes¶

São cnab_remessa_linhas com cessao='DAVOS' cujo fluxo_pagamentos.repassado_fundo='SIM', operacoes.cedido=true, nome_arquivo_retorno IS NULL e cancelado_em IS NULL. Em outras palavras: cedida + repassada + ainda não retornada.

Gerar Arquivo de Retorno¶

O botão "Gerar Arquivo de Retorno" (GerarRetornoDavosUseCase) toma as parcelas pendentes (todas ou só as selecionadas), monta o CNAB 400 (buildCnab400), calcula nome e sequência do arquivo, e carimba essas linhas de cnab_remessa_linhas com nome_arquivo_retorno, data_retorno e sequencia_arquivo_retorno (marcarComoRetornado), além de disparar o download do arquivo. Depois disso as linhas saem de Pendentes e passam a aparecer no Histórico de Retornos.

Cancelar Selecionadas¶

Reverte o repasse: marca cnab_remessa_linhas.cancelado_em e zera fluxo_pagamentos.repassado_fundo, fazendo a parcela voltar para a tela /carteira/conciliacao para ser repassada de novo (ou não).

Parcelas "Não incluídas no retorno"¶

Seção colapsável nesta mesma tela. Endpoint GET /v2/cessao/retorno-davos/nao-incluidos (BuscarNaoIncluidosRetornoQuery + buscarNaoIncluidos no repositório; hook useRetornoDavosNaoIncluidos). Lista parcelas com repassado_fundo='SIM' em operações cessao='DAVOS' que não têm linha ativa em cnab_remessa_linhas (anti-join por fluxo_pagamento_id) — foram marcadas como repassadas, mas não existe cessão para elas (não entraram em nenhum arquivo, nem por importação nem por "Gerar CNAB"). Como não têm cessão, não é possível gerar retorno delas: é o alerta de quebra da invariante do ciclo (repassado sem cessão). É agregada por cliente (CPF distinto) — a badge conta clientes e a tabela lista nome, CPF, número de parcelas e valor. Em produção (2026-07-16): 10 parcelas / 10 clientes nessa condição.

Invariante do ciclo¶

/carteira/cessao (não cedidas)
  → [Gerar CNAB / Importar CNAB]  → [cessao-davos](<./cessao-davos.md>)
  → Cedidos
  → [pagamento + repasse ao fundo] → [repasse-ao-fundo](<../conceitos/repasse-ao-fundo.md>) (tela /carteira/conciliacao)
  → Retorno DAVOS — Pendentes
  → [Gerar Arquivo de Retorno]
  → Histórico de Retornos

A tabela "Não incluídas no retorno" é o sinal de que a invariante foi quebrada em algum ponto: existe repasse sem cessão correspondente.

Onde vive no código¶

CRM: apps/crm-menos-juros/client/src/pages/carteira/cessao/retorno-davos.tsx, apps/crm-menos-juros/client/src/hooks/use-retorno-davos.ts
API: retorno-davos.controller.ts, gerar-retorno-davos.use-case.ts, retorno-davos.repository.ts, BuscarNaoIncluidosRetornoQuery (dentro de apps/api-menos-juros/src/v2/carteira/cessao/)
DB: cnab_remessa_linhas (nome_arquivo_retorno, data_retorno, sequencia_arquivo_retorno, cancelado_em), fluxo_pagamentos (repassado_fundo, status_pagamento)

Relacionado¶

carteira · cessao · cessao-davos · cnab · repasse-ao-fundo

Histórico¶

2026-07-16 — página criada: geração do CNAB 400 de retorno, parcelas pendentes, cancelamento, e a nova seção "Não incluídas no retorno" (alerta de repasse sem cessão).