Conceitos

Entenda os objetos e termos fundamentais antes de usar a kroz. Esta página espelha a linguagem da mesa de operação em app.kroz.co.

Em resumo

A kroz gerencia recebíveis imobiliários com repasse automático na origem. Os objetos primários são Contrato, Matriz de rateio e Cobrança, operados na sequência Recebedores → Rateio → Fechamento → Pagadoria.

Regra de ouro:

Pagador compra. Recebedor recebe.

Pagador vs recebedor

Distinção central, confundir os dois quebra split e compliance.

Se o comprador aparecer na Oficina de Recebedores, pare. Pagador entra como cliente/cobrança, não como recebedor.

Split na origem

Quando o pagador quita PIX ou boleto, o valor já nasce repartido entre os recebedores definidos na matriz, sem que o dinheiro passe por conta central da incorporadora para repasse posterior.

Na UI: badge Split na origem (Pagadoria). Na prática: payload do parceiro BaaS com split[] na criação da cobrança, não depois.

Exemplo prático: PS-0421

Contrato demo PS-0421, Unidade 1804, parcela de R$ 10.000 com matriz 72/18/10:

O corretor recebe direto na origem, sem repasse via imobiliária.

Como saber se está certo?

Na aba Payload do Rateio, o JSON deve conter split[] com walletId de cada recebedor externo. SPE retém o remainder automaticamente.

Recebedor e subconta

Recebedor = quem recebe parte do split. Cadastrado na Oficina de Recebedores (/recebedores/).

Cada recebedor identificado possui subconta na instituição de pagamento (IP). Ao criar, o BaaS gera:

• walletId, usado no array split[] da cobrança
• apiKey, exibida uma vez; guarde com segurança

Tipos de recebedor (UI)

Rail de estado

Rascunho → Pendente → Validado → Pronto → Criado

No piloto, pare em Validado (dry-run). Criado = subconta real na parceiro BaaS.

Valores sugeridos

• Faturamento mensal aproximado: informe valor realista, impacta limites do BaaS
• Dry-run: sempre ative Manter em dry-run seguro até Fechamento aprovado

SPE emissora

Sociedade de Propósito Específico que emite a cobrança e retém a parcela da evolução da obra, tipicamente o maior percentual da matriz.

Na UI: - Aparece readonly na Pagadoria após Carregar matriz - Label SPE emissora no Rateio - Coluna SPE no livro da Governança

Como calcular: SPE = remainder. Se terrenista 18% + vendas 10%, SPE fica com 72% automaticamente.

Não aloque SPE manualmente como recebedor externo. O motor trata o remainder.

walletId

Identificador da subconta do recebedor no BaaS. Obrigatório no payload de split.

Armadilha: recebedor sem walletId validado → split falha na Pagadoria.

Empreendimento, unidade e contrato

Importante: não há telas dedicadas de cadastro hoje. Três caminhos:

1. Rateio → Ajustar deal: configura inline para o deal
2. Pagadoria → Contrato → Carregar matriz: referencia contrato existente no backend
3. Seed/backend: demo pré-carregado (Porto Sereno, PS-0421)

Exemplo de nomenclatura

Matriz de rateio

Versão das regras de repasse ligada a um contrato. Na UI: Matriz ou Matriz de rateio.

Demo padrão: SPE 72% · Landbank 18% · Vendas 10% (CPC 47)

Composta por:

• Alocações, recebedores + percentuais
• SPE emissora, remainder automático
• Prova selada, hash após Validar rateio

Regra de ouro

Versão validada é imutável para fins operacionais. Correção = nova versão (futuro: superseded_by no Rule Engine).

Comissão na 3ª parcela

Regra de negócio visível na UI:

Parcela < 3 → Comissão de vendas entra na 3ª parcela

Configure o número da parcela em Ajustar deal → Parcela.

Papéis (role no backend)

Basis (base de cálculo: Rule Engine)

Dry-run (modo seguro)

Simulação sem efeitos colaterais no BaaS. Valida payload, percentuais e cadastro antes de execução real.

Quando usar cada um

Regra: nunca desative dry-run sem Fechamento aprovado.

Cobrança (Pagadoria)

Cobrança = charge PIX ou boleto emitida contra o pagador, com split embutido.

Tipos de cobrança

Fluxo: Contrato carregado → Tipo de cobrança → Split na origem → Mensagem para o corretor

Campos comerciais (não alteram split)

Corretor, Gerente, Imobiliária, vão para captabilidade (CSV export), não para o payload de split.

Fechamento

Mesa de validação pré-execução, garante que contrato, recebedores, matriz e payload estão coerentes antes de cobrança real.

Estágios: Contrato → Recebedores → Rateio → Aprovação → Evidência

Exemplos de checks: Contrato possui referência externa, Soma da matriz fecha em 100%, Payload do parceiro BaaS gerado em sandbox.

Conciliação

Processo de baixa e resolução de divergências após liquidação.

Fluxo na UI:

Webhook BaaS → Agente + motor → Aprovação DF → Execução

Use quando valor pago ≠ valor esperado, multa/juros, ou atraso.

Governança, evidência e trilha

Governança = hub de tesouraria e auditoria.

Hero aside: Quem decidiu / O que mudou / Como provar

Colunas do livro: Evento, Valor, SPE, Terrenista, Vendas, Situação, Ações

RC 16 (sem conta-bolsão)

Resolução BCB nº 16/2025, exige identificação de recebedores em contas de pagamento.

Na prática para a kroz:

• ✅ Dinheiro vai direto ao destino (SPE, terrenista, corretor)
• ✅ Cada recebedor com subconta na IP
• ❌ Dinheiro não dorme em conta da incorporadora ou plataforma

Como validar com parceiro BaaS

Ver Compliance e Adaptadores BaaS.

BaaS e parceiro licenciado

BaaS (Banking as a Service) = parceiro regulado que processa Pix, boleto, subcontas e split.

Disclosure na UI (Recebedores, Pagadoria, Sandbox):

Serviços financeiros prestados pela instituição de pagamento parceira licenciada… A kroz atua exclusivamente como integradora tecnológica e não é instituição financeira.

O adaptador traduz matriz kroz → payload do parceiro BaaS (split[], walletId).

CPC 47

Regime fiscal exibido na matriz demo: CPC 47, referência contábil para reconhecimento de receita em incorporações. Aparece como label na matriz padrão 72/18/10.

Não altera o cálculo do split na UI; contextualiza a operação para o financeiro.

Rule Engine (visão conceitual)

Motor interno (em implementação) que formaliza o que a UI já faz:

• rule_versions, matriz versionada
• rule_triggers, gatilhos (ex.: payment_settled, installment_number_gte)
• domain_events, webhooks normalizados
• split_executions + audit_events, prova de qual regra gerou qual split

Nome comercial: "O contrato vira regra executável".
Não usar "smart contract".

Ver Rule Engine

Relações entre conceitos

graph TD
    DEV[Empreendimento] --> CTR["Contrato / unidade"]
    CTR --> RV[Matriz de rateio]
    REC[Recebedores + walletId] --> RV
    RV --> FECH[Fechamento]
    FECH --> COB[Cobrança / Pagadoria]
    COB --> BAAS[BaaS / Split na origem]
    BAAS --> CONC[Conciliação]
    CONC --> GOV[Governança / Trilha]
    RV --> AUD[Prova selada]

Glossário rápido (UI ↔ backend)

O que evitar

Leia também

• Guia de início, piloto passo a passo com nomes da UI
• Matriz de rateio, how-to detalhado
• Cobranças (Pagadoria), tipos e dry-run
• Auditoria e prova, trilha e export
• Compliance, RC 16 e subprocessadores