---
id: imobiliario/financeiro-erp-por-spe
industria: Imobiliário
uso: muito usado
esforco: alto
grao: Parcela de título (billId + installmentId) para em aberto; baixa para pagas e recebidas
---

# Contas a pagar e a receber por empresa e SPE

A pagar, a receber, pagas e recebidas de todas as empresas do grupo numa visão só, batendo centavo a centavo com os relatórios do ERP.

## Resumo executivo

**Para quem:** Holdings imobiliárias e incorporadoras com uma SPE ou CNPJ por empreendimento ou negócio, que precisam de visão consolidada do financeiro.

**O que resolve**

- Uma visão única de contas a pagar e a receber de todas as empresas, sem abrir o ERP empresa por empresa.
- Os números batem com os relatórios oficiais do ERP, linha a linha.
- O custo pago por centro de custo para de inflar com substituições e cancelamentos de título.

**Por que importa:** O financeiro só confia num painel que bate com o relatório que ele já conhece. Uma diferença de 30% causada por tipo de operação ou por um join entre grãos diferentes derruba o projeto inteiro. Com o grupo numa visão só, o fechamento sai mais rápido e indicadores como custo administrativo sobre receita passam a ser mensais.

**Perguntas de negócio que responde**

- Qual o saldo a pagar e a receber de cada empresa do grupo hoje?
- Quanto foi pago por centro de custo e por categoria no mês?
- Quanto entrou de caixa de verdade, sem reparcelamentos e substituições?
- Quais títulos vencem nos próximos 30 dias, por empresa?
- Qual o custo administrativo sobre a receita recebida nos últimos 12 meses?

**O que você precisa**

- O ERP conectado na Nekt, com todas as empresas do grupo
- Os relatórios oficiais do ERP de um período fechado, em planilha, para a validação
- A lista de empresas, SPEs e centros de custo com o empreendimento de cada um

**O que você recebe**

- Quatro tabelas: a pagar, a receber, pagas e recebidas, com os nomes de coluna do relatório
- Uma validação automática contra o relatório oficial, que bloqueia o uso se divergir
- Dashboard do grupo por empresa, centro de custo e mês
- Um agente de IA que responde sobre o financeiro sem misturar grãos

## Detalhado

### O problema

Cada SPE ou CNPJ é uma empresa separada no ERP, e o grupo quer uma visão só que bata com o relatório oficial. Os títulos vêm com arrays aninhados de baixas, categorias e obras, e com tipos de operação que não são dinheiro. Somar sem filtrar o tipo de operação infla o pago em 30% a 50%, e juntar parcelas com baixas sem agregar duplica linhas.

### Regras de negócio

1. **Segmente por empresa e consolide no fim.** Toda tabela carrega o id da empresa (companyId no Sienge, a fonte de origem no Omie, o realm no QuickBooks). A administradora do grupo é uma empresa como as outras. Consolide só quando a pergunta for do grupo, e mostre a abertura por empresa ao lado. (Evite: Somar tudo direto e perder qual SPE deve ou tem a receber.)
2. **Dois grãos, quatro tabelas.** A pagar e a receber têm grão de parcela de título (billId + installmentId), em aberto ou quitada. Pagas e recebidas têm grão de baixa: uma parcela pode ter várias baixas. Para saber quanto foi pago de um título, agregue as baixas por parcela antes de cruzar. (Evite: Juntar contas a pagar com contas pagas linha a linha.)
3. **Pago é só pagamento e adiantamento.** No array payments do Sienge, conte apenas operationTypeName 'Pagamento' e 'Adiantamento'. 'Substituição' e 'Cancelamento' são movimentações de título, não custo, e inflam a soma em 30% a 50%. Com essa regra, o warehouse bateu com o BI anterior com desvio abaixo de 0,5%. (Evite: Somar todo o array payments.)
4. **Recebido é só recebimento.** No array receipts, receita recebida é operationTypeName 'Recebimento', pelo valor líquido (netAmount). Reparcelamento, distrato e substituição são reclassificações da carteira e ficam fora. Juros, correção monetária, multa e desconto ficam em colunas próprias. (Evite: Somar todos os receipts como entrada de caixa.)
5. **Cada coluna do relatório tem um campo.** No Sienge, 'Valor no vencimento' do a pagar é correctedBalanceAmount (saldo já corrigido pelo indexador). 'Desconto' do relatório é taxAmount, que são as retenções de ISS, INSS e IR. 'Valor original' do a receber é balanceAmount (saldo não corrigido), e não o originalAmount do título. (Evite: Usar originalAmount e discountAmount porque os nomes parecem certos.)
6. **Rateie pelos percentuais do título.** Desaninhe paymentsCategories e multiplique por financialCategoryRate / 100 (nulo vale 100). Para obra, desaninhe buildingsCosts e aplique o rate da obra. No Omie, desaninhe departamentos e use n_distr_percentual. Sem aplicar o percentual, cada categoria recebe o valor inteiro. (Evite: Desaninhar o array e somar o valor cheio em cada linha.)
7. **Baixa não é movimento bancário.** Uma baixa com juros gera duas ou mais linhas em sienge_bank_movement (principal e acréscimos). O grão de pagas e recebidas é a baixa. Movimentos bancários avulsos (tarifas, aportes entre empresas, retiradas de sócio, rendimentos) entram com uma coluna de origem, porque são caixa, mas ficam fora da comparação com o relatório de títulos. (Evite: Contar cada linha do movimento bancário como uma baixa.)
8. **Saldo em aberto sem a retenção.** Comprometido em aberto = (balanceAmount - taxAmount - discountAmount) x rate / 100, datado pelo vencimento. Notas de serviço em aberto com retenção de imposto inflavam o saldo quando o imposto não saía. (Evite: Usar balanceAmount cheio como saldo a pagar.)
9. **Uma fonte por empresa, unidas com origem.** No Omie, cada empresa é uma conexão. Trate cada uma com a mesma transformação e una com uma coluna de origem. Datas do Omie chegam como texto dd/mm/aaaa e precisam de conversão explícita. Em QuickBooks, exclua Transfer e Journal Entry do fluxo de caixa e nunca some a visão de caixa puro com a categorizada: o pagamento da fatura do cartão é o mesmo dinheiro. (Evite: Copiar a query por empresa com pequenas diferenças, ou somar caixa e categorizado.)
10. **Só publique o que passou na validação.** Compare cada tabela com o relatório oficial por empresa e mês, com tolerância de 0,01. Classifique em OK, OK explicado (diferença conhecida e nomeada, item a item) ou Diferença. Qualquer Diferença bloqueia o painel e o export até ser explicada. (Evite: Publicar o painel e descobrir a divergência na reunião de fechamento.)

### Relatório do ERP para campo

Mapa validado contra os relatórios oficiais do Sienge.

- **A pagar: Valor no vencimento** → Saldo corrigido pelo indexador (`correctedBalanceAmount`)
- **A pagar: Desconto** → Retenções de ISS, INSS e IR (`taxAmount`)
- **A receber: Valor original** → Saldo devedor não corrigido (`balanceAmount`)
- **Contas pagas** → Baixas de pagamento e adiantamento (`payments.operationTypeName IN ('Pagamento','Adiantamento')`)
- **Substituição, Cancelamento** → Não é custo (`payments.operationTypeName`)
- **Contas recebidas** → Recebimento de caixa, valor líquido (`receipts.operationTypeName = 'Recebimento'`)
- **Reparcelamento, Distrato, Substituição** → Reclassificação da carteira, fora (`receipts.operationTypeName`)
- **Rateio por categoria** → Percentual da categoria, nulo vale 100 (`financialCategoryRate / 100`)
- **Rateio por obra** → Percentual da obra (`buildingsCosts.rate / 100`)

### Definições

| Métrica | Definição |
|---|---|
| Saldo a pagar | soma do saldo em aberto das parcelas com vencimento no período, por empresa, rateado por categoria |
| Saldo a receber | soma de balanceAmount das parcelas em aberto, por empresa e vencimento |
| Valor pago | soma de payments.grossAmount x financialCategoryRate / 100 com tipo Pagamento ou Adiantamento, pela data da baixa |
| Receita recebida | soma de receipts.netAmount com tipo Recebimento, pela data do recebimento |
| Vencido a pagar | saldo em aberto de parcelas com vencimento anterior à data de corte |
| Custo administrativo sobre receita | custo pago do centro de custo da administração central / receita recebida de todas as obras, mensal e acumulado 12 meses, ambos em caixa |
| Diferença de validação | valor da tabela menos valor do relatório oficial, por empresa e mês; OK quando abaixo de 0,01 |

### Armadilhas

- **Pago 40% maior que o real.** A soma de todo o array de pagamentos incluía substituições e cancelamentos de título. Como evitar: Filtre Pagamento e Adiantamento antes de somar.
- **Join que duplica.** Cruzar a tabela de parcelas com a de baixas multiplicou o saldo de títulos pagos em várias vezes. Como evitar: Agregue as baixas por parcela antes do join.
- **Desconto que não era desconto.** A coluna Desconto do relatório não batia com discountAmount porque, no relatório, desconto são as retenções. Como evitar: Use taxAmount e valide coluna a coluna.
- **Títulos antigos sumidos.** Títulos anteriores a um certo ano não vinham no endpoint padrão de contas a pagar. Como evitar: Complete com o endpoint por título e confira o total de um ano antigo.
- **Cota da API estourada.** A carga histórica do ERP parou no meio porque a API tem cota diária pequena. Como evitar: Faça o histórico em blocos de 12 meses com uma tabela de estado da carga.
- **Empresa esquecida no consolidado.** Uma SPE nova foi cadastrada no ERP e ficou fora da visão do grupo por semanas. Como evitar: Compare a lista de empresas do ERP com a da tabela a cada carga e alerte quando surgir uma nova.

### Teste de aceitação

- [ ] Para um período fechado, o contas a pagar por vencimento bate com o relatório oficial do ERP em número de linhas e em valor, por empresa (diferença abaixo de 0,01).
- [ ] O contas pagas do período bate linha a linha com o relatório de contas pagas por data.
- [ ] O contas a receber bate com o relatório oficial em saldo total e número de parcelas.
- [ ] A soma por empresa é igual ao consolidado do grupo.
- [ ] Nenhum valor pago tem tipo de operação diferente de Pagamento ou Adiantamento.

### Context document

```text
Financeiro multiempresa (ERP)
- Toda análise é por empresa (companyId). Consolide só quando a pergunta for do grupo e mostre a abertura por empresa.
- Grãos: a pagar e a receber = parcela de título (billId + installmentId). Pagas e recebidas = baixa. Nunca junte os dois sem agregar as baixas por parcela.
- Valor pago = payments.grossAmount x financialCategoryRate / 100, só com operationTypeName 'Pagamento' ou 'Adiantamento'. Substituição e Cancelamento não são custo.
- Receita recebida = receipts.netAmount com operationTypeName 'Recebimento'. Reparcelamento, distrato e substituição ficam fora.
- financialCategoryRate nulo vale 100. Rateio por obra usa buildingsCosts.rate.
- Relatório a pagar: Valor no vencimento = correctedBalanceAmount; Desconto = taxAmount (retenções). Relatório a receber: Valor original = balanceAmount.
- Movimentos bancários avulsos (tarifas, aportes, retiradas, rendimentos) são caixa, mas não aparecem no relatório de títulos: vêm marcados pela origem.
- Só use as tabelas quando a validação contra o relatório oficial estiver OK ou OK explicado.
Exceções por cliente:
- <cliente>: empresa <id> é a administradora; SPEs <ids> correspondem a <empreendimentos>.
- <cliente>: centro de custo da administração central = <id>.
- <cliente>: diferenças conhecidas e aceitas na validação: <lista nomeada>.
```

### Variações

- **Custo administrativo sobre receita:** Custo pago do centro de custo da administração dividido pela receita recebida de todas as obras, com e sem distribuição de lucros.
- **Omie e Conta Azul:** Omie: uma conexão por empresa, departamentos por n_distr_percentual. Conta Azul: desaninhe o rateio por categoria e depois por centro de custo da parcela.
- **QuickBooks com P&L por SPE:** P&L por empresa e mês validado contra o relatório nativo, saldos entre empresas do grupo e semáforo de liberação por empresa.