kroz docs
kroz.co Abrir app

Contratos e unidades

Empreendimento, unidade e contrato comercial, a base de todo repasse na kroz.

Em resumo

Um empreendimento agrupa unidades de um lançamento. Cada unidade vendida gera um contrato com comprador, condições de parcelamento e matriz de rateio vinculada.

Na kroz, o contrato ancora:

  • Referência externa (código ERP/CRM)
  • Unidade e empreendimento
  • Matriz de rateio versionada (split_matrices)
  • Operações de pagamento (cobranças)

Como funciona hoje (importante)

Não há telas dedicadas de cadastro de empreendimento, unidade ou contrato no app.

Três caminhos para configurar:

Caminho Onde Quando usar
Ajustar deal Rateio → Ajustar deal Configurar inline para operação imediata
Carregar matriz Pagadoria → Contrato + Carregar matriz Cobrança sobre contrato existente no backend
Seed / backend Supabase (developments, contracts) Piloto demo ou onboarding de incorporadora

Documentamos o comportamento real, não o roadmap. Telas de cadastro virão com escala de incorporadoras.

Entidades no backend

Conceito Tabela Campos-chave
Empreendimento developments nome, tenant
Contrato contracts reference, metadata.unidade, development_id
Matriz split_matrices version, receivers (jsonb), contract_id
SPE spes legal_name · SPE emissora

Demo seed: Porto Sereno / Jardim Oeste Residence, contrato PS-0421, unidade 1804.

Configurar via Rateio (Ajustar deal)

Menu: Operação → Rateio → Ajustar deal

Campo UI Mapeia para Exemplo
Empreendimento developments.name Jardim Oeste Residence
Contrato / unidade contracts.reference + metadata.unidade PS-0421 \| Unidade 1804
Valor Valor da parcela em operação 85000
Parcela Número da parcela 2
Forma Pix / Boleto PIX
  1. Preencha campos
  2. Salvar → toast Deal atualizado.
  3. Continue em Matriz de rateio para montar split

Formato recomendado, Contrato / unidade:

{CÓDIGO-ERP} | Unidade {NÚMERO}

Exemplos bons: PS-0421 | Unidade 1804, LT-1880 | Lote 12
Evitar: contrato novo, teste, UUIDs expostos

Configurar via Pagadoria (Carregar matriz)

Menu: Operação → Pagadoria

  1. Contrato → ex.: PS-0421 (só a referência, sem unidade)
  2. Carregar matriz
  3. Sucesso: Contrato PS-0421 carregado com matriz v1.
  4. SPE emissora preenchida readonly
  5. Resumo: SPE 72% · Landbank 18% · Vendas 10%

API: GET /api/platform-contracts (via KrozPlatform.getContract)

Erro comum: Contrato não encontrado, referência não existe no backend.

Vincular recebedores ao contrato

Recebedores não se vinculam ao contrato diretamente, vinculam à matriz de rateio:

  1. Cadastre recebedores na Oficina de Recebedores (/recebedores/)
  2. No Rateio, sheet Recebedores → selecione do catálogo
  3. Percentuais compõem a matriz do deal

Catálogo inclui recebedores demo + rascunhos da oficina (localStorage kroz.subaccount.draft.*).

Fechamento: visão consolidada

Menu: Operação → Fechamento

Mostra deal consolidado (read-mostly no demo):

Estágio Conteúdo
Contrato PS-0421 | Unidade 1804
Recebedores SPE, Terrenista, Vendas com walletId
Rateio Matriz 72/18/10
Aprovação Checklist 6/6
Evidência Export JSON

Checklist inclui: Contrato possui referência externa, Recebedor SPE validado, Soma da matriz fecha em 100%.

Ver Auditoria e prova.

URL Efeito
/pagadoria/?reference=PS-0421 Preenche contrato + carrega matriz
/governanca/?reference=PS-0421 Filtra trilha por contrato

Onboarding de incorporadora (piloto)

Checklist operacional para primeiro contrato real:

  • [ ] Tenant criado no Supabase
  • [ ] Empreendimento seeded ou referenciado no deal
  • [ ] Contrato com reference alinhada ao ERP
  • [ ] split_matrices v1 com percentuais acordados
  • [ ] Recebedores reais na Oficina (CNPJ + subconta)
  • [ ] Dry-run completo: Rateio → Fechamento → Pagadoria
  • [ ] Referência documentada para equipe comercial

Homologação com incorporadora: alinhar código de contrato antes de gerar cobranças reais.

Na prática

  • ✅ Use mesma referência na UI, ERP e docs internos
  • ✅ Padronize formato CÓDIGO | Unidade N
  • ✅ Carregue matriz na Pagadoria, não assuma percentuais de memória
  • ✅ Mantenha SPE emissora consistente entre Rateio e backend
  • ❌ Não crie contrato só no deal sheet sem backend (Pagadoria falha)
  • ❌ Não misturar referências (PS-0421 vs PS-421)

Roadmap

Hoje Próximo (Rule Engine)
Deal inline + seed backend CRUD de contratos na UI
Matriz por split_matrices.version rule_versions + gatilhos + hash
Referência manual Sync bidirecional ERP

Ver Rule Engine.

Relacionado