Recorrências (Gerenciar cobranças recorrentes)

Pré-requisitos de acesso

• Permissão (módulo): processPaymentQueue
• Licença/Feature: Nenhuma específica.
• Contêiner do menu: GERAL → grupo Cobranças (rota /manage-recurrences)

O que é / quando usar

Esta é a tela de listagem e gestão das cobranças recorrentes mensais que debitam usuários por um período definido (data de início → data fim). É o ponto de entrada do grupo Cobranças (a rota-raiz /manage-recurrences do menu): aqui o operador vê todas as recorrências já cadastradas, cria novas e remove as existentes.

O cadastro em si (campos do formulário, geração de parcelas, trilho BRL × token) está documentado em detalhe em Cadastro de cobranças para usuários — esta página foca na listagem, colunas e ações da tela.

Diferente das Cobranças automáticas (perpétuas, executadas por dia do mês) e da Folha de pagamento (que paga o usuário em nome da empresa), as recorrências têm janela fechada: ao salvar, o backend gera uma parcela por mês entre as duas datas e um job do FinanceManagementService (FMS) aplica cada parcela na data devida.

Pré-condições

• Permissão: processPaymentQueue cadastrada para a role do operador (permissão dupla — enum CPM no backend + módulo dinâmico no DB; sem o módulo no DB o item de menu/botão não aparece, mesmo com o enum correto).
• Licença/Feature: Nenhuma específica.
• Dependências de outras telas: o usuário-alvo de cada cobrança deve existir e estar APPROVED — a cobrança debita o saldo dele (carteira de cripto ou conta digital BRL). A listagem resolve o e-mail de cada cobrança cruzando o userIdTo com a lista de usuários (CPM).

Passo a passo

1. Acesse Cobranças → Recorrências (rota /manage-recurrences).
2. A página carrega em paralelo as recorrências (GET /v1/recurrently) e a lista de usuários, e exibe a tabela já em ordem decrescente de criação (vinda do backend).
3. Para criar, clique em Criar nova cobrança — abre o modal de cadastro (RecurrencyModalComponent). Os campos e regras estão em Cadastro de cobranças para usuários.
4. Para inspecionar o cliente de uma linha, clique no ícone de olho (visibilidade): navega para os Detalhes do usuário.
5. Para remover uma cobrança, clique no ícone de lixeira.

Filtros e colunas

A tela é uma listagem (sem filtros de busca): mostra todas as recorrências cadastradas, paginadas (5/10/25/100 por página, padrão 25).

Coluna	O que mostra	Origem do dado
Data de início	Primeira competência da cobrança	creationDate (creation_date)
Data fim	Última competência	expirationDate (expiration_date)
Descrição	Texto que vai ao extrato/transação	description
Valor	Quantia debitada por parcela	amountRequested (amount_requested) — tratado como BigNumber no processamento
Moeda	Símbolo da moeda da cobrança	unitOfMoneyRequested (unit_of_money_requested) — define o trilho (BRL via conta digital × token via carteira)
Usuário	E-mail do cliente debitado	resolvido a partir do userIdTo cruzando com a lista de usuários (CPM); não é armazenado na própria cobrança
Ações	Ícones lixeira (excluir) e olho (abrir usuário)	—

A coluna Usuário mostra o e-mail, mas o que a cobrança grava é o userIdTo (ID interno). Se o usuário não for encontrado na lista, o e-mail aparece vazio — a cobrança continua válida.

Ações e modais

• Criar nova cobrança: abre o RecurrencyModalComponent. Ao salvar, envia POST /v1/recurrently/create; em sucesso, a lista é recarregada. Ver campos e validações em Cadastro de cobranças para usuários.
• Excluir (lixeira): chama POST /v1/recurrently/delete com o recurrencyId. Remove a cobrança e as parcelas mensais ainda não aplicadas; a página é recarregada após o sucesso. Não há modal de confirmação — o clique já dispara a exclusão.
• Visualizar usuário (olho): navega para /users/informations/details do destinatário (Detalhes do usuário).

Regras de negócio / cuidados

Atenção

• Excluir não tem confirmação: um clique na lixeira já remove a recorrência e as parcelas pendentes. Confira a linha (usuário, descrição, valor) antes.
• Excluir apaga as parcelas pendentes, mas não estorna parcelas já aplicadas (débitos já feitos).
• A Moeda define o trilho de débito: BRL debita pela conta digital; qualquer outro símbolo debita pela carteira cripto. É um dado escolhido no cadastro — confira-o na coluna Moeda ao revisar uma cobrança existente.
• A listagem não filtra/busca: em bases grandes, use a paginação para localizar a recorrência.

• Valores financeiros: o Valor é tratado como BigNumber no scheduler do FMS — sem arredondamento; confira as casas decimais da moeda/token.
• Idempotência: cada parcela é aplicada com externalId igual ao id da parcela. Em reprocessamento após crash, o FinLib retorna E00021 ("already processed") — isso é sucesso, não erro: o valor já foi debitado e a parcela permanece marcada como aplicada.
• Status APPROVED: o usuário-alvo precisa estar aprovado para que o débito (carteira ou conta digital) seja efetivado.

Telas relacionadas

• Cadastro de cobranças para usuários (modal de criação e geração de parcelas)
• Cobranças automáticas
• Folha de pagamento
• Filas de Pagamento
• Voltar ao índice Financeiro