Liquidações (Settlements)

Pré-requisitos de acesso

• Permissão (módulo): creditDisburse (executar/operar liquidações).
• Licença/Feature: CREDIT_INVESTMENTS habilitada na licença do tenant (Vault).
• Contêiner do menu: TOKENIZAÇÃO → grupo Crédito Tokenizado

O que é / quando usar

A tela de Liquidações mostra a distribuição final do dinheiro de um Deal quando os recebíveis são pagos. Uma liquidação aplica o Template de Cascata (Waterfall) do deal, dividindo o valor recebido entre os destinatários (investidores, casa, taxas) em uma ordem de prioridade. Cada liquidação tem um conjunto de itens ordenados, cada um com tipo, recebível/destinatário e valor.

Use esta tela para acompanhar quais deals já foram liquidados (total ou parcialmente), o valor total distribuído e o detalhamento item a item de cada liquidação.

Pré-condições

• Permissão: creditDisburse (permissão dupla — enum CPM + módulo dinâmico no DB).
• Licença/Feature: CREDIT_INVESTMENTS habilitada. Sem ela o grupo nem aparece no menu.
• Dependências de outras telas: o Deal precisa ter sido financiado/desembolsado e ter Cobranças pagas; o Template de Cascata determina a ordem dos itens.

Passo a passo

1. Acesse o menu Crédito Tokenizado → Liquidações.
2. Filtre por Status (Todas / Pendente / Processando / Concluída / Falha).
3. Clique em Visualizar numa liquidação para abrir o painel de detalhes com os itens ordenados.
4. Feche o painel para voltar à lista.

Filtros e colunas

Filtro/Coluna	O que mostra	Origem do dado
Número do Deal	Deal liquidado	Settlement.dealNumber / dealId
Status	PENDING, PROCESSING, COMPLETED, FAILED	Settlement.status (filtro statusFilter)
Valor total	Montante distribuído nesta liquidação	Settlement.totalAmount (BigNumber)
Data de liquidação	Quando foi processada	Settlement.settlementDate
Nº de itens	Quantidade de linhas de distribuição	Settlement.items.length
Criado em	Data de criação do registro	Settlement.createdAt

Detalhe de cada item (SettlementItem): order (prioridade), itemType, receivableId/destinatário, amount. Os itens são exibidos ordenados por order — exatamente a ordem da cascata.

Ações e modais

• Visualizar: abre o painel lateral com os itens da liquidação, ordenados por prioridade (getOrderedItems). Não há ação destrutiva nesta listagem — a execução da liquidação é disparada pelo fluxo de desembolso/executeSettlement (módulo creditDisburse), que monta os settlementItems (itemType, recipientPartyId, toAccountId, amount, priority) conforme a cascata.

Regras de negócio / cuidados

Atenção

• A ordem da cascata é a ordem de pagamento. O order/priority de cada item segue o Template de Cascata do deal — itens de prioridade menor são pagos primeiro; mudar a cascata depois não reescreve liquidações já feitas.
• Liquidação parcial existe. Um deal pode ficar PARTIALLY_SETTLED enquanto nem todos os recebíveis foram pagos; novas liquidações vão somando até o SETTLED.
• Status FAILED pede atenção. Uma liquidação FAILED indica falha no repasse — investigue antes de reprocessar.

Irreversível

• Distribuição de liquidação é definitiva. Ao executar, o dinheiro é repassado aos destinatários on/off-chain. Não há rollback automático — correções exigem novo evento financeiro (ex.: Recompra ou ajuste manual).

• Valores financeiros: totalAmount e amount de cada item são BigNumber no backend; a soma dos itens deve fechar com o total — não arredonde ao conferir.
• Idempotência: o repasse passa pela FinLib e é idempotente por externalId — em reprocessamento, E00021 ("already processed") é sucesso, não erro. Ver [[reference_finlib_idempotency]].

Telas relacionadas

• Desembolsos
• Templates de Cascata (Waterfall)
• Razão de Crédito
• Negócios / Deals
• Crédito Tokenizado (índice do grupo)