Documentação

Português

English
Español

Português

English
Español

Appearance

Cadastro de cobranças para usuários ​

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 tela cria cobranças recorrentes mensais que debitam o usuário dentro de uma janela de datas (início e fim). É a ferramenta para mensalidades, assinaturas, taxas administrativas e qualquer débito que precise se repetir por alguns meses contra o saldo de um cliente.

Diferente da Folha de pagamento (que paga o usuário em nome da empresa) e das Cobranças automáticas (perpétuas, por dia do mês), esta cobrança tem período definido: ao salvar, o backend calcula quantos meses cabem entre a data de início e a data de fim e agenda uma parcela por mês. Um job no FinanceManagementService (FMS) percorre essas parcelas pendentes e as aplica 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 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 deve existir e estar APPROVED — a cobrança debita o saldo dele (carteira de cripto ou conta digital BRL). O ID informado no modal é o userIdTo (identificador interno do usuário), não o e-mail.

Passo a passo ​

  1. Acesse Cobranças → Cadastro de cobranças para usuários (rota /manage-recurrences).
  2. A listagem traz todas as cobranças já cadastradas, em ordem decrescente de criação, com o e-mail do usuário resolvido a partir do userIdTo.
  3. Clique em Criar nova cobrança para abrir o modal de cadastro.
  4. Preencha ID do usuário, Descrição, Moeda, Valor, Data de início e Data fim (formato dd/mm/aaaa).
  5. Confirme em Salvar. O backend grava a cobrança e gera as parcelas mensais entre as duas datas.
  6. Para remover uma cobrança, use o ícone de lixeira na linha; para abrir o usuário, use o ícone de olho (visibilidade), que navega para os detalhes do usuário.

Campos (modal de cadastro) ​

CampoO que éObrigatório?Efeito no sistema/backend
ID do usuárioIdentificador interno (userIdTo) do cliente que será debitadoSimGrava user_id_to em recurrently_charges (FMS). É o ID interno, não o e-mail. Define de quem o valor sai a cada mês.
DescriçãoTexto livre que aparece no extrato/transaçãoSimVira transactionDescription da transação de carteira ou o descritivo do crédito BMS. Máx. 250 caracteres no formulário / 140 no banco.
MoedaSímbolo da moeda da cobrança (ex.: BRL, tBRL, símbolo de token)SimGrava unit_of_money_requested. Decide o trilho de pagamento: se BRL, o débito é feito via conta digital (BMS giveUserBalance contra a conta principal); qualquer outro valor é tratado como transação de carteira cripto para a walletForBonus.
ValorQuantia a debitar por parcelaSim (> 0)Grava amount_requested. Tratado como BigNumber no processamento (sem arredondamento). O mesmo valor é replicado em cada parcela mensal.
Data de inícioPrimeira competência da cobrança (dd/mm/aaaa)SimGrava creation_date. É a data da primeira parcela.
Data fimÚltima competência (dd/mm/aaaa)Sim (≥ início)Grava expiration_date. O backend calcula o nº de meses entre início e fim e cria uma parcela (recurrently_charges_payments) por mês. Se o intervalo for menor que ~1 mês, nenhuma parcela mensal extra é gerada.
Como as parcelas são geradas

Ao salvar, o FMS calcula a diferença em dias entre início e fim e converte em meses (dias / 30). Para cada mês, cria um registro de parcela com applied = false e a data daquele mês. O scheduler de recorrências varre as parcelas pendentes e aplica cada uma na sua data, marcando applied = true ao concluir.

Ações e modais ​

  • Criar nova cobrança: abre o modal RecurrencyModalComponent. Valida que todos os campos estão preenchidos, valor > 0 e data fim ≥ data início antes de habilitar Salvar.
  • Salvar: envia para POST /v1/recurrently/create. Em sucesso, fecha o modal e recarrega a lista.
  • Excluir (lixeira): chama POST /v1/recurrently/delete com o recurrencyId. Remove a cobrança e as parcelas mensais ainda não aplicadas. Após a confirmação a página é recarregada.
  • Visualizar usuário (olho): navega para os Detalhes do usuário do destinatário.

Regras de negócio / cuidados ​

Atenção

  • O campo ID do usuário é o identificador interno (userIdTo), não o e-mail. Pegue-o nos Detalhes do usuário.
  • A Moeda define o trilho: BRL debita pela conta digital; qualquer outro símbolo debita pela carteira cripto. Informar a moeda errada faz o débito sair do lugar errado (ou falhar por saldo/rota inexistente).
  • O número de parcelas depende exclusivamente do intervalo início → fim. Datas muito próximas podem não gerar nenhuma parcela mensal.
  • Excluir uma cobrança apaga as parcelas pendentes, mas não estorna parcelas já aplicadas.
  • Valores financeiros: tratados como BigNumber no scheduler — sem arredondamento; confira as casas decimais da moeda/token.
  • Idempotência: cada parcela é aplicada com externalId igual ao id da parcela. Se o serviço reprocessar após crash, o FinLib retorna E00021 ("already processed") — isso é sucesso, não erro: o valor já foi debitado e a parcela é marcada como aplicada.
  • Status APPROVED: o usuário-alvo precisa estar aprovado para que o débito (carteira ou conta digital) seja efetivado.

Exemplos ​

Cenário 1 — Mensalidade de 6 meses em BRL

O operador cria uma cobrança para o usuário u-1234, descrição "Mensalidade Plano Pro", moeda BRL, valor 49,90, início 01/06/2026 e fim 01/12/2026. Ao salvar, o FMS gera 6 parcelas mensais (junho a dezembro). A cada mês o scheduler debita R$ 49,90 da conta digital do usuário para a conta principal via BMS, e marca a parcela como aplicada. Em dezembro, encerrada a janela, não há mais parcelas pendentes.

Cenário 2 — Taxa administrativa em token utilitário

Cobrança em moeda UTK (token utilitário), valor 10, início 01/06/2026, fim 01/09/2026. Como a moeda não é BRL, cada parcela vira uma transação de carteira que move 10 UTK da carteira do usuário para a walletForBonus configurada. São 3 parcelas (junho, julho, agosto). Útil para descontar taxas em token sem tocar a conta bancária.

Cenário 3 — Correção por exclusão antes do primeiro débito

Operador percebe que digitou o valor errado logo após cadastrar. Como nenhuma parcela foi aplicada ainda, ele clica na lixeira: a cobrança e todas as parcelas pendentes são removidas. Em seguida cria a cobrança novamente com o valor correto. Nenhum débito foi feito no intervalo.

Telas relacionadas ​