---
id: imobiliario/custo-obra-orcado-realizado
industria: Imobiliário
uso: comum
esforco: alto
grao: Obra x item da EAP na última versão do orçamento; título x item da EAP para o analítico de apropriações
---

# Custo de obra orçado x realizado

Orçado, comprometido e realizado de cada etapa da obra, com o desvio por subetapa e o avanço físico ao lado, batendo com o relatório do ERP.

## Resumo executivo

**Para quem:** Construtoras e incorporadoras que controlam custo de obra no ERP e querem esse relatório fora dele, cruzado com prazo.

**O que resolve**

- O custo por nível da EAP sai fora do ERP com os mesmos números do relatório oficial.
- A engenharia vê onde cada obra estoura o orçamento, por subetapa e item, a tempo de agir.
- Custo e avanço físico aparecem lado a lado, para saber se a obra gasta mais rápido do que avança.

**Por que importa:** O orçamento de obra é o maior compromisso de caixa da incorporadora, e a margem do empreendimento depende dele. O relatório do ERP mostra a obra inteira, mas não ranqueia desvios, não cruza com prazo e só chega à diretoria exportado em planilha. Com as regras certas, a mesma tabela serve ao engenheiro, ao financeiro e ao agente de IA.

**Perguntas de negócio que responde**

- Quanto de cada obra já está comprometido e quanto já foi pago contra o orçado?
- Quais subetapas e itens estão com maior sobrecusto?
- A obra está gastando mais rápido do que avança?
- Quanto temos de adiantamento e caução em aberto com cada fornecedor?
- Quanto do orçado de cada insumo já foi pedido?
- Quanto vale o estoque de material em cada canteiro?

**O que você precisa**

- ERP de obra conectado (Sienge ou UAU), com orçamento, contas a pagar e movimentos bancários
- O mapa de cada obra: id da obra, empresa (SPE) e centro de custo
- A ferramenta de planejamento conectada (Agilean ou Prevision), se quiser avanço físico

**O que você recebe**

- Uma tabela de custo por nível da EAP com orçado, comprometido e realizado
- Um ranking de desvios por subetapa e item
- Um analítico de apropriações por título e item, com pagamentos
- A curva de avanço físico planejado, reprogramado e real ao lado do custo

## Detalhado

### O problema

O orçamento da obra fica em versões, numa árvore de códigos da EAP, e os títulos do contas a pagar chegam com arrays aninhados que dizem quanto de cada um vai para cada obra e item. Quem soma todas as versões, soma pai e filho juntos ou ignora o percentual apropriado entrega um orçado dobrado e um realizado que não bate com o relatório do ERP. Sem isso, o desvio por etapa continua numa planilha manual.

### Regras de negócio

1. **Só a última versão do orçamento.** building_cost_estimation_items guarda cada versão do orçamento. Por obra e unidade construtiva, fique só com o maior versionNumber. Somar todas as versões multiplica o orçado pelo número de revisões. Guarde a versão usada numa coluna, para quem compara com o ERP saber qual é. (Evite: Somar totalPrice de todas as linhas da tabela de orçamento.)
2. **Folha para somar, rollup para mostrar.** O wbsCode é hierárquico (por exemplo, 01, 01.002, 01.002.003). Para totais, some só as folhas da árvore, porque o pai já é a soma dos filhos. Para o relatório por nível, cada código recebe a soma de todos os descendentes (o próprio código e os que começam com ele seguido de ponto), e não só os lançamentos feitos exatamente nele. (Evite: Somar pai e filhos, ou cruzar lançamentos só pelo código exato.)
3. **Comprometido e realizado são colunas diferentes.** Comprometido é tudo que foi lançado no contas a pagar para o item, pago ou não. Realizado é o que já foi pago. Os dois saem dos mesmos títulos apropriados à obra, com o percentual de cada item. Orçado menos comprometido é o saldo a contratar; comprometido menos realizado é o que falta pagar. (Evite: Uma coluna 'custo' que às vezes é lançado e às vezes é pago.)
4. **Apropriação pelo percentual do item.** Cada título tem o array buildingsCosts com obra, unidade, item da EAP (costEstimationSheetId) e rate. Valor apropriado ao item = valor do título x rate / 100, arredondado em centavos por linha. Movimento bancário apropriado usa o array buldingCosts (com o erro de grafia da API) e sinal pela operação: saída ('S') soma, entrada subtrai. (Evite: Lançar o título inteiro em cada item ou obra que ele cita.)
5. **Desvio só em item 100% medido.** Desvio = comprometido - orçado: positivo é sobrecusto, negativo é economia. Em item ainda em execução, comprometido abaixo do orçado é só contrato que falta, não economia. Ranqueie desvios só de itens com percentComplete = 100, por subetapa (nível 1) e por item da subetapa (nível 2). Os demais aparecem como 'em execução', com o % medido. (Evite: Ranking de economia que inclui itens recém-iniciados.)
6. **Confira a apropriação contra o centro de custo.** O mesmo título traz o percentual por centro de custo e categoria financeira (paymentsCategories) e o percentual por obra (buildingsCosts). Quando os dois discordam para a mesma obra, o título está mal apropriado. Gere uma lista de distorções por título com os dois percentuais, para o financeiro corrigir no ERP antes do fechamento. (Evite: Confiar em um dos arrays sem conferir o outro.)
7. **Obra ligada por ids, com um mapa.** A obra aparece como buildingId no orçamento e nos títulos, como costCenterId no estoque e nos centros de custo, e como companyId (a SPE) no financeiro. Mantenha um mapa com obra, empresa e centro de custo. Quando só houver o nome, o centro de custo costuma terminar com a sigla da obra: case pelo sufixo exato, nunca por 'contém'. (Evite: Achar a obra procurando a sigla em qualquer parte do nome.)
8. **Adiantamento e caução pelo tipo de documento.** Adiantamento a fornecedor e caução retida são títulos do contas a pagar, identificados por documentIdentificationName. Saldo de adiantamento = balanceAmount dos títulos de adiantamento de obra, por credor. A caução é apropriada à obra pelo buildingsCosts como qualquer título. A API não liga esses títulos ao contrato de fornecimento: número do contrato e data de medição não vêm, e o agente deve dizer isso. (Evite: Inventar o contrato da caução pelo credor.)
9. **Avanço físico vem da ferramenta de planejamento.** Avanço planejado, reprogramado e real (mensal e acumulado), IDP e PPC vêm do Agilean ou do Prevision. Ligue à obra do ERP pelo id gravado na ferramenta (no Prevision, siengeprojectid = id do centro de custo do Sienge). Mostre só meses até o mês atual. Compare o % comprometido do orçamento com o % de avanço real acumulado: custo muito à frente do avanço é alerta. (Evite: Estimar avanço pelo percentual de custo pago.)
10. **Insumo é único dentro da base de custo.** O mesmo código de insumo pode significar coisas diferentes em bases de custo diferentes. A chave do insumo é base de custo + código. A chave do item é obra + unidade + código da EAP até o nível usado. Orçado x solicitado por insumo compara a quantidade da composição do orçamento com a apropriada nas solicitações atendidas, por obra e subetapa. (Evite: Somar o mesmo código de insumo entre bases de custo.)

### De onde vem cada valor da obra

Campos padrão do conector Sienge.

- **building_cost_estimation_items, maior versionNumber** → Orçado (`totalPrice`)
- **building_cost_estimation_items** → Medido (`percentComplete, measuredQuantity`)
- **outcome x buildingsCosts, lançado** → Comprometido (`valor x rate / 100`)
- **outcome x buildingsCosts, pago** → Realizado (`payments`)
- **bank_movement x buldingCosts** → Apropriação bancária (`sinal por operationType 'S'`)
- **documentIdentificationName de adiantamento** → Adiantamento a fornecedor (`balanceAmount`)
- **documentIdentificationName de caução** → Caução retida (`sem contrato na API`)
- **stock_inventories por costCenterId** → Estoque no canteiro (`quantity x averagePrice`)
- **Agilean ou Prevision** → Avanço físico e IDP (`real x planejado acumulado`)
- **comprometido - orçado em item 100% medido** → Desvio (`positivo = sobrecusto`)

### Definições

| Métrica | Definição |
|---|---|
| Orçado | soma de totalPrice das folhas da EAP na última versão do orçamento, por obra, unidade e item |
| Comprometido | soma do valor apropriado ao item (valor x rate / 100) de todos os títulos lançados, pagos ou não, até a data de corte |
| Realizado | soma do valor pago apropriado ao item, pelas baixas de pagamento e adiantamento, até a data de corte |
| Saldo a contratar | orçado - comprometido, por item e por nível da EAP |
| Desvio | comprometido - orçado em itens com 100% medido; desvio % = desvio / orçado x 100 |
| % comprometido | comprometido / orçado da obra, comparado ao avanço físico real acumulado no mesmo mês |
| IDP | índice de desempenho de prazo da ferramenta de planejamento: avanço real acumulado / avanço planejado acumulado, por obra e mês |
| Saldo de adiantamento | soma de balanceAmount dos títulos de adiantamento de obra em aberto, por credor e obra |
| Estoque no canteiro | quantity x averagePrice por obra e insumo, na data da carga |

### Armadilhas

- **Orçado dobrado.** A tabela de orçamento somada inteira juntava versões antigas e itens pai com filhos, e o orçado da obra saiu várias vezes maior. Como evitar: Última versão e só folhas nos totais.
- **Nível 1 vazio.** O cruzamento pelo código exato só achava lançamentos feitos no próprio código, e as subetapas apareciam com comprometido zero. Como evitar: Rollup por prefixo do wbsCode.
- **Economia que era contrato faltando.** O ranking mostrava grandes economias em itens que tinham acabado de começar. Como evitar: Ranqueie só itens 100% medidos.
- **Obra trocada pelo nome.** O centro de custo de uma obra foi casado por 'contém' a sigla e trouxe lançamentos de outra obra com sigla parecida. Como evitar: Use o mapa de ids ou o sufixo exato do nome.
- **Estoque sem mínimo.** O time pediu estoque mínimo e quantidade reservada, que não existem em stock_inventories e só vêm numa stream opcional que estava desligada. Como evitar: Habilite building_resources ou diga que o dado não existe.
- **Caução sem contrato.** O financeiro pediu a caução por contrato e medição, e a API do contas a pagar não traz esse vínculo. Como evitar: Entregue por credor e obra e registre a ausência no context document.

### Teste de aceitação

- [ ] Para uma obra, código, descrição, unidade, quantidade, preço unitário e preço total do orçamento batem com o relatório de orçamento do ERP na versão vigente.
- [ ] Orçado, comprometido e realizado de cada subetapa batem com o relatório de custo por nível do ERP, com tolerância de centavos.
- [ ] Em cada obra, a soma dos itens folha é igual ao total do nível mais alto da EAP.
- [ ] O saldo de adiantamento por credor bate com o relatório sintético do ERP.
- [ ] Nenhum item com menos de 100% medido aparece no ranking de desvios.

### Context document

```text
Custo de obra orçado x realizado
- Orçado = totalPrice da última versão (maior versionNumber) por obra e unidade. Totais somam só as folhas da EAP.
- Relatório por nível: cada código soma todos os descendentes (rollup por prefixo do wbsCode).
- Comprometido = títulos lançados, pagos ou não; realizado = pago. Sempre lado a lado.
- Valor apropriado ao item = valor do título x rate / 100 de buildingsCosts. No movimento bancário, buldingCosts, com saída somando e entrada subtraindo.
- Desvio = comprometido - orçado, só em itens 100% medidos. Positivo = sobrecusto.
- Obra: buildingId (orçamento e títulos) = costCenterId (estoque) = companyId da SPE pelo mapa de obras. Nunca case obra por 'contém'.
- Adiantamento e caução pelo documentIdentificationName. A API não traz contrato nem data de medição da caução: diga isso.
- Avanço físico e IDP vêm da ferramenta de planejamento, só até o mês atual.
- Estoque = quantity x averagePrice. Estoque mínimo e reservado não existem sem building_resources.
Exceções por cliente:
- <cliente>: obras <sigla> = buildingId <id>, companyId <id>, centro de custo '<nome>'.
- <cliente>: tipo de documento de adiantamento = '<nome>'.
- <cliente>: a versão do orçamento <n> da obra <sigla> é a vigente por decisão da engenharia.
```

### Variações

- **UAU:** Mesma lógica com o planejamento total e a composição de insumos do UAU, atualizada uma vez por semana por empresa e obra.
- **Suprimentos:** Tempo da solicitação ao pedido e à entrega por insumo; solicitação atendida é a que virou pedido emitido.
- **Obra com financiamento:** Liberação mensal do banco contra medição: compare o comprometido aprovado e ainda não pago com o cronograma de desembolso.