Matriz de rateio

Montar, validar (dry-run) e selar a regra de repasse por deal/contrato. Motor de Rateio em app.kroz.co.

Em resumo

A matriz de rateio define quem recebe quanto quando uma parcela liquida. No app, ela vive no módulo Rateio (/rateio/), deck UI com dry-run seguro integrado.

É composta por:

• Deal, empreendimento, contrato/unidade, valor, parcela, forma (Pix/Boleto)
• Recebedores externos, terrenista, vendas, imobiliária (com walletId)
• SPE emissora, remainder automático (o que sobra após externos)
• Prova selada, hash e trilha após Validar rateio

Pré-requisito: recebedores cadastrados na Oficina de Recebedores com walletId validado. Ver Guia de início.

Abrir o Motor de Rateio

Menu: Operação → Rateio

Header: Motor de rateio · dry-run seguro

Sub-nav: Visão geral | Jornada | Payload | Atividade

Criar / ajustar o deal

1. Abrir o sheet de origem

1. Clique Ajustar deal
2. Sheet Origem do deal abre

2. Preencher campos

3. Salvar

Clique Salvar → toast: Deal atualizado.

O deck atualiza chips: PS-0421 · Unidade 1804, Parcela 2, valor formatado.

Montar o split

1. Abrir recebedores

1. Clique Recebedores
2. Sheet Split configurado abre

Hint: Escolha recebedores já cadastrados na oficina. O restante fica na SPE emissora.

2. Selecionar recebedores

Por linha:

1. Dropdown Selecione um recebedor → ex.: Terrenista Demo Ltda · Terrenista
2. Confirme identidade: CNPJ mascarado + status do walletId
3. Informe % no campo percentual

3. Adicionar ou remover

• + Adicionar recebedor, inclui próximo disponível no catálogo
• × (Remover recebedor), remove linha

Rodapé do sheet: Externos 28% · SPE 72% (atualiza em tempo real)

⚠️ Se externos > 100%, total fica em amarelo (is-warn). Corrija antes de salvar.

4. Salvar split

Clique Salvar → sheet fecha, deck recalcula distribuição.

Atalho: link Abrir oficina de recebedores no sheet → /recebedores/

Regra da 3ª parcela (comissão de vendas)

Regra automática no motor:

Comissão de vendas entra na 3ª parcela

Na Visão geral, tag na jornada: Comissão de vendas entra na 3ª parcela ou Todos os recebedores elegíveis nesta parcela.

Exemplo: parcela 2 de R$ 50.000 com matriz 72/18/10:

Validar rateio (dry-run)

1. Revisar antes de validar

Aba Visão geral: - Card Parcela em cobrança, valor e breakdown por recebedor - Card Distribuição, barra percentual + legenda

Aba Jornada: - Nós por recebedor com tags Elegível / Suspenso

Aba Payload: - JSON completo → Copiar JSON - Confirme split[] com walletId e percentualValue

2. Validar

1. Clique Validar rateio
2. Botão vira Rateio validado (desabilitado)
3. Status atividade: Prova selada
4. Mensagem: Rateio validado em modo seguro.

Evento registrado na aba Atividade com horário e origem Modo seguro.

3. Estrutura do payload (referência)

{
  "dryRun": true,
  "contractReference": "PS-0421",
  "value": 50000,
  "installmentNumber": 2,
  "billingType": "PIX",
  "externalReference": "KROZ-PS-0421-P02",
  "split": [
    { "walletId": "wallet_terrenista_demo", "percentualValue": 18, "role": "Terrenista" },
    { "walletId": "wallet_vendas_demo", "percentualValue": 10, "role": "Vendas" }
  ],
  "rule": { "salesSuppressed": true, "sealed": true }
}

SPE não aparece em split[] quando é remainder; percentual implícito em spePercent.

Modos de visualização

Matriz demo padrão

Referência do piloto PS-0421:

Label fiscal: CPC 47

Versionamento (estado atual e roadmap)

Hoje: matriz carregada do backend por contrato (split_matrices, version integer). Rateio UI monta payload a partir do deal + catálogo de recebedores.

Roadmap (Rule Engine): versões imutáveis com snapshot_hash, gatilhos e superseded_by. Ver Rule Engine.

Na prática

• ✅ Valide recebedores na Oficina antes de montar split
• ✅ Confira Externos X% · SPE Y% = 100% antes de Salvar
• ✅ Use aba Payload antes de ir ao Fechamento
• ✅ Teste percentuais isolados no Sandbox (/sandbox/) se necessário
• ❌ Não valide rateio com walletId pendente
• ❌ Não ignore tag Suspenso em parcelas 1–2, SPE absorve vendas de propósito
• ❌ Não edite payload manualmente, ajuste deal ou recebedores

Troubleshooting

Relacionado

• Conceitos, Matriz de rateio
• Contratos e unidades, configurar deal/contrato
• Fechamento, checklist pré-execução
• Cobranças, usar matriz carregada na Pagadoria
• Rule Engine, evolução versionada