Documentação

Português

English
Español

Português

English
Español

Appearance

Filas de Pagamento ​

Pré-requisitos de acesso

  • Permissão (módulo): processPaymentQueue (controla os botões na UI) + manageToken (exigida pelo backend das rotas de fila)
  • Licença/Feature: Nenhuma específica.
  • Contêiner do menu: GERAL → grupo Cobranças (rota /manage-payment-queues)

O que é / quando usar ​

As Filas de Pagamento modelam estruturas de resgate/recompra de NFTs por prioridade — típico de dívidas com ordem de pagamento, como precatórios, dívidas públicas (TCU/União), debêntures ou obrigações corporativas tokenizadas. Cada fila é uma regra: ela seleciona quais NFTs entram (por coleção + atributo + valor de atributo), define a prioridade de pagamento e o tipo (à vista ou parcelado).

Esta tela trata da configuração das filas. A execução item a item (cada NFT a ser paga, na ordem de prioridade) acontece na tela Ordens da fila de pagamento, onde o operador aprova o pagamento de cada NFT: o sistema paga ao detentor o price_paid da NFT a partir da carteira da plataforma e devolve a NFT ao TKN_OWNER.

Pré-condições ​

  • Permissão: processPaymentQueue cadastrada para liberar os botões na UI (permissão dupla — enum CPM + módulo dinâmico no DB). As rotas de criação/edição/exclusão são validadas no API-Gateway com manageToken; sem esse enum a operação retorna erro mesmo com o botão visível.
  • Licença/Feature: Nenhuma específica.
  • Dependências de outras telas: a coleção e o atributo/valor referenciados precisam existir nas NFTs emitidas — é por eles que o sistema sabe quais NFTs pertencem à fila.

Passo a passo ​

  1. Acesse Cobranças → Filas de Pagamento (rota /manage-payment-queues).
  2. A listagem mostra as filas com Nome e Prioridade.
  3. Clique em Criar nova para abrir o modal de configuração.
  4. Preencha Nome, Coleção, Prioridade, Atributo, Valor do atributo e o Tipo de pagamento.
  5. Se o tipo for Parcelado, informe Percentual e Meses.
  6. Confirme em Salvar. Para editar, use o ícone de lápis; para remover, o de lixeira.

Campos (modal de fila) ​

CampoO que éObrigatório?Efeito no sistema/backend
NomeIdentificação da filaSimGrava name em payment_queue (TokenController). Bloqueado em edição (não pode ser alterado depois de criado).
ColeçãoID da coleção de NFTs que a fila atendeSimGrava collectionId. Junto com atributo/valor, delimita o universo de NFTs elegíveis.
PrioridadeOrdem de precedência da fila no pagamentoSimGrava priority (numérico). Define qual fila/NFT é paga antes na ordenação das ordens. Aceita apenas números.
AtributoNome da característica que marca a NFT como parte da filaSimGrava attribute. Casado com Valor do atributo para selecionar as NFTs.
Valor do atributoValor esperado do atributo acimaSimGrava value. Ex.: atributo tipo com valor precatorio.
Tipo de pagamentoÀ vista (Antecipado / A) ou Parcelado / PSimGrava payment_type (A ou P). Ao trocar para A, limpa percentage e months. Define se o valor da NFT é pago de uma vez ou fracionado.
Percentual(Parcelado) % do valor pago por parcelaCondicional (tipo P)Grava percentage. Define o tamanho de cada parcela em relação ao valor da NFT.
Meses(Parcelado) número/intervalo de parcelasCondicional (tipo P)Grava months. Define em quantos meses o valor é distribuído.

O botão Salvar só é habilitado quando nome, prioridade, valor do atributo, atributo e coleção estão preenchidos.

Ações e modais ​

  • Criar nova: abre o PaymentQueueModalComponent em modo de criação → POST /v1/assets/createPaymentQueues.
  • Editar (lápis): abre o mesmo modal com a fila carregada (modo edição) → POST /v1/assets/updatePaymentQueues. O Nome fica bloqueado.
  • Excluir (lixeira): chama POST /v1/assets/deletePaymentQueues. Após o sucesso a página recarrega.

Regras de negócio / cuidados ​

Atenção

  • A seleção de NFTs é feita por coleção + atributo + valor: se o atributo/valor não bater exatamente com o que está nas NFTs, a fila fica vazia.
  • O Nome é imutável após a criação.
  • A Prioridade é o que ordena o pagamento — filas com prioridade conflitante podem produzir uma ordem de pagamento inesperada. Planeje a numeração.
  • Configurar como Parcelado sem informar Percentual/Meses deixa a regra de fracionamento incompleta.
  • Valores financeiros: os valores efetivamente pagos vêm do price_paid de cada NFT (na execução) e são tratados como BigNumber — sem arredondamento.
  • Idempotência: a execução de cada ordem é protegida (uma NFT já paga não é paga de novo) e as transações seguem a idempotência do FinLib (E00021 = já processado = sucesso).

Telas relacionadas ​