# Manual de Utilização — para IA

Guia para um **agente de IA** operar o sistema **Versus — Custos e Precificação** (Alimentos Tia Sônia) pela **API HTTP**, pela **CLI** e pela **planilha de importação**. Para o passo a passo das telas, veja o manual para humanos (outra aba desta tela).

> Este manual é a única referência de API disponível em produção (o `/docs` e o `/openapi.json` ficam desligados lá). O catálogo de endpoints da seção 6 é gerado das rotas reais; o resto é escrito à mão.

## 1. Regras de ouro

1. **Leia antes de gravar.** Todo fluxo começa em consultas (`GET`). Só escreva (`POST`/`PUT`/`PATCH`/`DELETE`) o que o usuário pediu.
2. **Confirme antes de apagar ou sobrescrever.** Exclusões não se desfazem. Custos e preços não são "apagados" por padrão: linhas de formulação e gastos são **encerradas a partir de um mês** e a versão antiga fica no histórico.
3. **Tudo vale dentro de um Planejamento.** Cada Planejamento (ex.: "2026 Vrs. 01") tem os seus próprios cadastros, formulações, despesas, impostos, Centros de Resultados e volumes. Sempre diga em qual está trabalhando.
4. **Importação é tudo-ou-nada.** Uma única linha inválida cancela a carga inteira. Use sempre `previa` antes de `confirmar` e leia os erros.
5. **Não invente códigos.** Códigos (produto, insumo, Centro de Custo, conta, Direcionador…) vêm das consultas ou da planilha de referência. Código inexistente devolve `422`/`404`.
6. **Vazio não é zero.** Em planilha e em `PATCH`, campo vazio significa "não mexer". Para zerar um valor, envie `0`.
7. **O que o sistema não faz:** não emite nota fiscal, não controla estoque nem compras (Planejador de Estoques e de Compras são "em breve"), não calcula folha, não toca no TOTVS (só lê as planilhas exportadas dele).
8. **Dados são do cliente.** Não copie valores de custo, preço ou resultado para fora do que o usuário pediu.

## 2. Acesso e convenções da API

- **Base:** o prefixo é `/api` (ex.: `https://<servidor>/api/planejamentos`). Os caminhos do catálogo (seção 6) vêm **sem** esse prefixo.
- **Login:** `POST /api/auth/login` com `{"email": "...", "senha": "..."}`. A resposta define o cookie `sessao` (assinado, `HttpOnly`); envie-o em todas as chamadas seguintes. Há bloqueio temporário após várias senhas erradas. `POST /api/auth/logout` encerra a sessão; `GET /api/auth/eu` mostra o usuário e se ele é administrador.
- **Cabeçalho obrigatório nas escritas:** `X-Requested-With: fetch` (qualquer valor). Sem ele a API responde `403`. Por segurança, envie sempre.
- **Planejamento de trabalho:** cabeçalho `X-Planejamento: <codigo>` (ex.: `P2026V01`). Sem ele vale o Planejamento oficial (ou o mais recente). Rotas do tipo `/planejamentos/{codigo}/...` exigem que `{codigo}` seja o mesmo do cabeçalho; senão `409`. `GET /api/planejamentos` lista os disponíveis.
- **Perfis:** usuário comum lê e edita o Planejamento; **administrador** também importa planilhas e TOTVS, gerencia usuários e vê o Log de Ações (`403` para os demais).
- **Formatos:** JSON em UTF-8. Dinheiro e quantidades são **strings decimais** (`"12.50"`); mande ponto decimal. **Percentuais na API são frações** (`"0.205"` = 20,5%; vírgula decimal também é aceita). Na **planilha** digite `18%` (ou formate a célula como %); um número solto acima de 1 é recusado — assim ninguém grava 18 no lugar de 0,18. Datas de vigência/competência são `"AAAA-MM"`.
- **Erros:** `401` sem sessão; `403` sem permissão; `404` não existe; `409` conflito (ex.: Planejamento diferente do cabeçalho, exclusão bloqueada); `422` dado inválido — o texto em `detail` já diz o que corrigir, repasse-o ao usuário.
- **Arquivos:** as rotas de importação recebem o `.xlsx` **como corpo bruto** (`Content-Type: application/octet-stream`), **não** como formulário multipart.

Exemplo mínimo (curl):

```bash
curl -c jar -X POST https://SERVIDOR/api/auth/login -H "Content-Type: application/json" -H "X-Requested-With: fetch" -d '{"email":"voce@empresa.com","senha":"***"}'
curl -b jar -H "X-Planejamento: P2026V01" https://SERVIDOR/api/planejamentos/P2026V01/prontidao
```

## 3. Modelo de domínio

| Conceito | O que é |
| --- | --- |
| **Planejamento** | Contexto de trabalho (um schema próprio no banco). Copiar um Planejamento cria uma nova versão editável. Pode ser "oficial". |
| **Plano de Contas / Centro de Custo** | Contas do resultado (custos, despesas, impostos) e centros onde os gastos são lançados (produtivos ou não). |
| **Direcionador** | Critério de alocação: Área → Macroprocesso → Processo → **Atividade** → **Direcionador** (base: `tempo`, `quantidade_produzida` ou `custo_primario`). |
| **Insumo** | Matéria-prima (`ingrediente`) ou `embalagem`, com valor de compra, frete, IPI e ICMS. |
| **Produto** | `acabado`, `semiacabado` (intermediário) ou `revenda`. **Cabeça** = produto marcado na **Tabela de Preços**: o custeio parte das cabeças e da estrutura que elas usam. |
| **Elementos de custo** | Quatro tipos que custam por hora: **Mão de obra** (colaboradores agrupados em **grupos Depto-Cargo**), **Instalações** (ambientes), **Máquinas** e **Outros**. Cada um tem gastos mensais por conta, horas úteis e classificação fixo/variável. |
| **Formulação (roteiro)** | Árvore de um produto: **insumos/semiacabados** (quantidade, unidade, perda) e **alocações de elementos de custo** (horas por bacia, por Atividade/Direcionador). Linhas têm `atualizado_em` (vigência por mês). |
| **Custeio** | Cálculo dos custos unitários das cabeças numa **competência** (`AAAA-MM`). Gravado como execução; a mais recente é a que vale. |
| **Meta de Lucro** | Única por Planejamento: % do preço destinado a sócios, reserva, expansão e outros (líquido de IR/CSLL). |
| **Precificação primária** | Preço sugerido e definido por cabeça, sem acréscimos de Centros. É "o resultado que a empresa almeja". |
| **Centro de Resultados** | Canal/recorte comercial com despesas adicionais, desconto, mix de destinos (UF) e quantidades próprias. O Centro especial **"Produção a alocar"** recebe a diferença entre a produção e a soma dos Centros. |
| **DRE Consolidada** | Soma dos Centros, por Plano de Contas, com reconciliação Primária → Consolidada. Desenvolve-BA aparece só como informativo. |
| **Histórico de Planejamento** | "Fotos" congeladas e imutáveis dos resultados, comparáveis com o Planejamento atual ou entre si. |

## 4. Cadeia de cálculo

Ordem em que os números nascem. Um passo só é confiável se os anteriores estiverem completos — `GET /planejamentos/{codigo}/prontidao` mostra o que falta.

1. **Insumos** → custo unitário (valor de compra + frete; IPI/ICMS conforme cadastro).
2. **Elementos de custo** → custo mensal de cada recurso (soma dos gastos do mês de competência) ÷ horas úteis = **custo por hora**. Mão de obra é agregada por grupo Depto-Cargo (custo e horas somados, média ponderada).
3. **Formulação** → o custo de um lote = insumos (com perdas e conversão de unidades) + horas × custo/hora de cada elemento alocado. Unitário = lote ÷ rendimento (un se o produto rende em unidades, senão kg). Intermediários entram pelo custo total deles.
4. **Planejamento de Produção** → quantidade/mês de cada cabeça (campo "informado"). O volume dos intermediários é **calculado pela estrutura** (explosão a partir das cabeças, com perda e rendimento) e somado ao que for informado.
5. **Ociosidade** → para cada elemento, as horas úteis não usadas × custo/hora, rateadas **por tipo** entre os produtos que o usam (peso = lotes × custo absorvido). O **total** do produto = custo unitário + ociosidade. O custo variável = parcelas variáveis + ociosidade dos elementos classificados como variáveis. O que ninguém usa fica como "ociosidade não alocada".
6. **Despesas** → fixas (valor/mês) formam um **pool por Direcionador**, dividido entre as cabeças que usam a Atividade (e têm volume) por um **% por produto que soma 100%**: a **sugestão** do critério do grupo (`custo_volume`, `quantidade`, `mistura`, `tempo`, `igual`; padrão = a base do Direcionador) ou o rateio **gravado** pelo gestor; depois ÷ quantidade produzida. Variáveis são % da receita bruta. As despesas adicionais de um Centro seguem a base do Direcionador, entre as quantidades do Centro.
7. **Impostos** → créditos por item (classes `icms`, `cbs`, `ir_csll`, cada uma com alíquota própria opcional; padrão vem de **Alíquotas** e de **ICMS Compras**); débitos: ICMS pelo **mix de destinos** (UF) de cada Centro (sem mix = 100% Bahia), CBS e IR/CSLL pela alíquota vigente. Modos: **contábil** (créditos abatem o custo) ou **financeira** (estima o % da receita que os impostos representam, iterando).
8. **Preço sugerido** = (custo total + despesa fixa unitária − créditos no modo contábil) ÷ (1 − %impostos − %despesas variáveis − %lucro ÷ (1 − alíquota IR/CSLL)). O **Preço Definido** (opcional) só substitui o sugerido na Análise e na DRE.
9. **Trava da primária** → `POST /precificacao/trava` congela rateio, Meta, Preços Definidos e modo dos impostos (e grava os % efetivos). Os Centros e `GET /dre/consolidada` só calculam com a primária **travada e atualizada**.
10. **Centros de Resultados** → recalculam preço e resultado a partir da primária com as despesas adicionais, o desconto e o mix; o desconto comercial faz `preço de tabela = líquido ÷ (1 − desconto)`.
11. **DRE Consolidada** e **Histórico** → resumem tudo.

## 5. Fluxos operacionais

Cada fluxo cita a rota por **grupo** do catálogo (seção 6) — confirme o caminho e os campos lá.

### 5.1 Diagnosticar o Planejamento
1. `GET /planejamentos` e escolha o código (cabeçalho `X-Planejamento`).
2. `GET /planejamentos/{codigo}/prontidao` → etapas `pronto | parcial | pendente | bloqueado | opcional`, com `falta` (itens) e `tela` (id do menu). Comece pelas etapas na ordem em que aparecem.

### 5.2 Montar ou atualizar cadastros em massa (recomendado)
1. `GET /importacao/modelo?preenchido=true` (admin) baixa a planilha **com os dados atuais**; sem o parâmetro vem em branco com exemplos (`#`).
2. Edite **só as abas que precisa**; abas vazias ou removidas são ignoradas, e célula vazia não altera o registro. A importação **nunca apaga**.
3. `POST /importacao/previa` (corpo = bytes do `.xlsx`) → contagem de criados/atualizados e **lista de erros por linha**. Corrija e repita até zerar os erros.
4. `POST /importacao/confirmar` com o **mesmo arquivo** aplica tudo (ou nada).
5. Se mexeu em custos, rode o custeio (5.4).

**Abas da planilha** (ordem de dependência): Plano de Contas · Centros de Custo · Mão de obra · Instalações · Máquinas · Outros · Gastos · Áreas · Macroprocessos · Processos · Atividades · Direcionadores · Insumos · Produtos · Roteiros · Centros de Resultados (antiga "Cenários") · Planejamentos · Volumes · Despesas · Alíquotas · ICMS Destinos · ICMS Compras · Mix de Destinos · Desenvolve-BA · Premissas. Principais regras:

- **Atualizado em** (`AAAA-MM`): mês a partir do qual a linha vale. Vazio: registro novo = "desde o início"; existente = mês atual (a versão antiga fica no histórico).
- **Créditos** (Insumos, Gastos, Despesas, Produtos de revenda): colunas *Crédito ICMS/CBS/IR-CSLL* = `Sim`/`Não`/vazio (não mexe); *Alíquota própria (%)* só com `Sim`; *Origem da compra (ICMS)* = Bahia | Sul/Sudeste | N/NE/CO/ES.
- **Produtos:** Tipo = Acabado | Semiacabado | Revenda; *Tabela de Preços* = Sim marca a cabeça (vazio: novo = Sim para Acabado/Revenda e Não para Semiacabado).
- **Roteiros:** *Tipo de linha* = Mão de obra | Instalação | Máquina | Outros | Insumo | Semiacabado. Para os quatro elementos, informe as horas por lote e o **Direcionador** (base `tempo`; a Atividade tem de ser a dele). Mão de obra usa o **código do grupo Depto-Cargo** (ex.: `1.1-CG01-F`; o código FOPAG de um colaborador também vale).
- **Despesas:** Tipo = Fixa (exige Direcionador e valor) | Variável (exige % da receita > 0). *Centro de Resultados* preenchido = despesa adicional só dele (não aceita "Produção a alocar").
- **Mix de Destinos:** única exceção ao "nunca apaga": as linhas de um Centro **substituem** o mix dele e precisam somar 100%.
- **Desenvolve-BA:** uma linha só; `Ativo`, % dilatado, % pago à vista, % Fundo de Pobreza, conta da reserva.

Cargas do **TOTVS** (admin): `POST /totvs/produtos|estrutura|ndc/previa` e `/confirmar` com a planilha exportada (corpo bruto; `?vigencia=AAAA-MM` define o mês a partir do qual os custos/estruturas valem). Estrutura TOTVS cria/atualiza produtos e insumos e trava as linhas que vieram de lá (`origem = totvs`, somente leitura nas telas); `GET /totvs/estrutura/conferencia` compara com as formulações.

### 5.3 Editar pontualmente
Use as rotas do grupo correspondente: `insumos`, `produtos`, `elementos` (Mão de obra, Instalações, Máquinas, Outros e seus gastos), `formulacoes`/`estrutura` (linhas de insumo), `alocacao` (elementos de custo da formulação, copiar entre produtos), `direcionadores`, `despesas`, `impostos` (classificação de créditos, alíquotas, destinos, mix, Desenvolve), `producao` (produção e volumes por Centro).
- Alterar uma linha com vigência: informe `atualizado_em` (`AAAA-MM`); a versão anterior continua valendo nos meses anteriores.
- Encerrar uma linha: `DELETE` com `em=AAAA-MM`.

### 5.4 Calcular custos
`POST /planejamentos/{codigo}/custeio` com `{"competencia": "AAAA-MM"}` (opcional; padrão o mês atual). Depois: `GET /planejamentos/{codigo}/custos` (unitários das cabeças), `.../custos/{produto}/estrutura` (composição) e `.../custos/execucoes` (histórico). Recalcule **sempre** depois de mudar custo, formulação, produção, despesa ou imposto.

### 5.5 Precificar e conferir
1. Defina a Meta de Lucro (`PUT /precificacao/meta`) e o modo dos impostos (`/precificacao/configuracao`).
2. `GET /precificacao/primaria` (preço sugerido/definido e spread) · `GET /precificacao/analise` (Unitário × Total) · `GET /precificacao/tabela` (por faixa de ICMS, também `.xlsx`) · `GET /precificacao/dre`.
3. Preço manual: `PUT /precificacao/primaria/{produto}` com `{"preco_definido": "15"}`; vazio volta a seguir o sugerido.
4. **Rateio das despesas fixas:** `GET /precificacao/rateio` traz, por Direcionador, o pool, o critério, a sugestão e o % que vale por produto (frações: `0.25` = 25%) e o resumo por produto. Redistribua com `PUT /precificacao/rateio/{direcionador}` e `{"percentuais": {"P1": "0.6", "P2": "0.4"}}` (**soma 1**, só produtos elegíveis; recusado com 422 se não fechar). `PUT .../criterio` (`{"criterio": "mistura", "peso_quantidade": "0.5"}`) troca o critério e descarta o gravado; `DELETE .../{direcionador}` volta à sugestão.
5. **Trave a primária:** `POST /precificacao/trava` (422 lista as pendências: sem custeio, sem Meta, Direcionador sem produto para ratear, produto novo sem % no rateio gravado). `GET /precificacao/trava` devolve `situacao` = `aberta` | `travada` | `desatualizada` (travada, mas custo, quantidade ou despesa mudaram depois). `DELETE /precificacao/trava` reabre. Com a primária travada, `PUT /precificacao/meta`, `PUT /precificacao/primaria/{produto}`, `PUT /precificacao/configuracao` e as rotas de rateio respondem **409**.
6. Centros: cadastre (`/cenarios`), lance despesas adicionais (`/despesas?cenario=`), mix e quantidades (`/centros/{codigo}/quantidade/{produto}`), e leia `/centros/{codigo}/precificacao|analise|tabela`.
7. `GET /dre/consolidada` fecha o resultado; `GET /planejamentos/{codigo}/producao/consistencia` aponta produtos alocados nos Centros acima da produção (ajuste com `POST .../producao/ajustar-aos-centros`).

### 5.6 Congelar e comparar
`POST /planejamentos/{codigo}/versoes` guarda a foto (exige Meta de Lucro e custeio); `GET /planejamentos/{codigo}/versoes`, `.../versoes/{numero}` e `.../versoes/comparar?a=&b=` listam, abrem e comparam (foto × atual, foto × foto); `GET /planejamentos/comparar?a=&b=` compara dois Planejamentos ao vivo. Uma foto não muda depois, só o rótulo e a observação.

### 5.7 Nova versão do Planejamento
`POST /planejamentos` copiando de um existente cria o novo com todos os dados. Mude nele e compare com o anterior. Excluir um Planejamento apaga **tudo** dele (admin; peça confirmação explícita).

## 6. Catálogo de endpoints

Colunas: método, caminho (sem o prefixo `/api`), o que faz e parâmetros. `?` = opcional. Parâmetros de caminho aparecem como `{nome}`. Corpos de arquivo (importação) são bytes brutos.

<!-- CATALOGO:INICIO (gerado por scripts/gerar_manual_ia.py; não edite à mão) -->

### Grupo `alocacao`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/alocacao` | listar | consulta: busca?, tipo?, so_sem_alocacao? |
| POST | `/alocacao/copiar` | Copia os elementos de custo de um produto para um ou vários (tudo-ou-nada), valendo a partir de `atualizado_em`. | corpo JSON: origem, destinos, substituir?, atualizado_em? |
| GET | `/alocacao/opcoes` | opcoes |  |
| GET | `/alocacao/{codigo}` | O produto e os intermediários que ele consome, cada um com os seus elementos de custo e o custo deles. |  |
| POST | `/alocacao/{codigo}/linhas` | adicionar | corpo JSON: tipo, recurso_codigo, direcionador_codigo, horas_bacia, atualizado_em? |
| PATCH | `/alocacao/{codigo}/linhas/{tipo}/{linha_id}` | alterar | corpo JSON: horas_bacia, direcionador_codigo?, atualizado_em? |
| DELETE | `/alocacao/{codigo}/linhas/{tipo}/{linha_id}` | Encerra a linha a partir do mês `em` (padrão o atual); ela segue valendo nos meses anteriores. | consulta: em? |

### Grupo `atividade`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/atividade` | Escritas feitas pela API, da mais recente para a mais antiga; `antes` = id do último item da página anterior. | consulta: usuario?, recurso?, antes?, limite? |
| GET | `/atividade/filtros` | filtros |  |

### Grupo `auth`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/auth/eu` | eu |  |
| POST | `/auth/login` | login | corpo JSON: email, senha |
| POST | `/auth/logout` | logout |  |
| POST | `/auth/senha` | trocar senha | corpo JSON: senha_atual, senha_nova |

### Grupo `cenarios`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/cenarios` | listar cenarios |  |
| POST | `/cenarios` | criar cenario | corpo JSON: codigo?, nome?, descricao?, percentual_desconto? |
| GET | `/cenarios/painel` | obter painel |  |
| PATCH | `/cenarios/{codigo}` | alterar cenario | corpo JSON: codigo?, nome?, descricao?, percentual_desconto? |
| DELETE | `/cenarios/{codigo}` | excluir cenario |  |

### Grupo `centros`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/centros/{codigo}/analise` | obter analise |  |
| GET | `/centros/{codigo}/precificacao` | obter precificacao |  |
| PUT | `/centros/{codigo}/preco/{produto}` | definir preco | corpo JSON: preco_definido? |
| PUT | `/centros/{codigo}/quantidade/{produto}` | definir quantidade | corpo JSON: quantidade |
| GET | `/centros/{codigo}/tabela` | obter tabela |  |
| GET | `/centros/{codigo}/tabela.xlsx` | baixar tabela |  |
| GET | `/dre/consolidada` | A DRE por Plano de Contas da soma dos Centros de Resultados (ou de um só, com `centro`), com a reconciliação Primária → Consolidada. | consulta: centro? |

### Grupo `custos`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| POST | `/planejamentos/{codigo}/custeio` | calcular custos | corpo JSON: competencia? |
| GET | `/planejamentos/{codigo}/custos` | Custos unitários dos produtos da Tabela de Preços (as cabeças) na execução mais recente ou na indicada. | consulta: execucao_id? |
| GET | `/planejamentos/{codigo}/custos/execucoes` | Histórico de custeio do Planejamento: a competência mais recente primeiro. |  |
| GET | `/planejamentos/{codigo}/custos/execucoes/{execucao_id}/entradas` | Snapshot das entradas de custo usadas numa execução (ou null, se for anterior ao histórico). |  |
| GET | `/planejamentos/{codigo}/custos/{produto}/estrutura` | A composição do produto (MP, embalagem, intermediários…) com os custos unitários da própria execução. | consulta: execucao_id? |

### Grupo `despesas`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/despesas` | As despesas do Planejamento (sem `cenario`) ou as adicionais de um Centro de Resultados (`cenario` = código). | consulta: cenario? |
| POST | `/despesas` | criar despesa | corpo JSON: codigo?, titulo?, tipo?, plano_de_contas_codigo?, centro_de_custo_codigo?, direcionador_codigo?, valor?, percentual_receita?, descricao?, creditos?, cenario_codigo? |
| PATCH | `/despesas/{codigo}` | atualizar despesa | corpo JSON: codigo?, titulo?, tipo?, plano_de_contas_codigo?, centro_de_custo_codigo?, direcionador_codigo?, valor?, percentual_receita?, descricao?, creditos?, cenario_codigo? |
| DELETE | `/despesas/{codigo}` | excluir despesa |  |

### Grupo `direcionadores`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/direcionadores/arvore` | obter arvore |  |
| POST | `/direcionadores/{nivel}` | criar no | corpo JSON: valores |
| PATCH | `/direcionadores/{nivel}/{codigo}` | atualizar no | corpo JSON: valores |
| DELETE | `/direcionadores/{nivel}/{codigo}` | excluir no |  |

### Grupo `elementos`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/elementos/grupos` | Grupos Depto-Cargo (formados pelos colaboradores) com a capacidade operacional: horas úteis, consumidas, ociosidade e custo. |  |
| GET | `/elementos/{tipo}` | listar elementos |  |
| POST | `/elementos/{tipo}` | criar elemento | corpo JSON: valores, atualizado_em? |
| PATCH | `/elementos/{tipo}/{chave}` | atualizar elemento | corpo JSON: valores, atualizado_em? |
| DELETE | `/elementos/{tipo}/{chave}` | excluir elemento |  |
| GET | `/elementos/{tipo}/{chave}/folha` | Os campos fixos de gasto do recurso (valor vigente) + os outros gastos (somente leitura). |  |
| PUT | `/elementos/{tipo}/{chave}/folha` | Grava os campos informados (vazio não mexe). Mês posterior guarda a versão antiga no histórico. | corpo JSON: valores, atualizado_em? |
| POST | `/elementos/{tipo}/{chave}/gastos` | adicionar gasto | corpo JSON: plano_de_contas_codigo, desembolso, retencao?, atualizado_em? |
| PATCH | `/elementos/{tipo}/{chave}/gastos/{gasto_id}` | Altera o valor de um gasto guardando o antigo no histórico (válido até o mês `atualizado_em`). | corpo JSON: plano_de_contas_codigo?, desembolso?, retencao?, atualizado_em? |
| DELETE | `/elementos/{tipo}/{chave}/gastos/{gasto_id}` | Encerra um gasto a partir do mês `em` (padrão o atual): some do custo daí em diante, mas fica no histórico. | consulta: em? |
| GET | `/elementos/{tipo}/{chave}/historico` | Versões dos parâmetros do recurso (horas, absenteísmo) e versões antigas dos seus gastos. |  |
| GET | `/lookups` | obter lookups |  |

### Grupo `estrutura`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/centros-de-custo` | listar centros |  |
| POST | `/centros-de-custo` | criar centro | corpo JSON: nome?, pai_id?, sufixo?, sintetico?, ativo?, descricao?, gestor_id?, produtivo? |
| PATCH | `/centros-de-custo/{no_id}` | atualizar centro | corpo JSON: nome?, pai_id?, sufixo?, sintetico?, ativo?, descricao?, gestor_id?, produtivo? |
| DELETE | `/centros-de-custo/{no_id}` | excluir centro |  |
| GET | `/plano-de-contas` | listar plano |  |
| POST | `/plano-de-contas` | criar conta | corpo JSON: nome?, pai_id?, sufixo?, sintetico?, ativo?, tipo?, codigo_reduzido?, codigo_externo?, observacoes? |
| PATCH | `/plano-de-contas/{no_id}` | atualizar conta | corpo JSON: nome?, pai_id?, sufixo?, sintetico?, ativo?, tipo?, codigo_reduzido?, codigo_externo?, observacoes? |
| DELETE | `/plano-de-contas/{no_id}` | excluir conta |  |

### Grupo `formulacoes`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/produtos/{codigo}/estrutura` | Árvore explodida da formulação (todos os níveis) com quantidade, perda e custo de cada nó, no mês `competencia`. | consulta: competencia? |
| GET | `/unidades/conversoes` | listar conversoes |  |
| POST | `/unidades/conversoes` | criar conversao | corpo JSON: item_tipo, item_codigo, unidade, fator |
| DELETE | `/unidades/conversoes/{conversao_id}` | excluir conversao |  |

### Grupo `importacao`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| POST | `/importacao/confirmar` | Revalida e grava, tudo ou nada: se houver qualquer erro, nada é gravado. |  |
| GET | `/importacao/modelo` | Modelo .xlsx para preencher (a aba Referência traz o Plano de Contas e as Atividades atuais). Com `preenchido=true`, | consulta: preenchido? |
| POST | `/importacao/previa` | Valida a planilha e mostra o que seria criado/atualizado e os erros — sem gravar nada. |  |

### Grupo `impostos`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/impostos/aliquotas` | listar aliquotas |  |
| PUT | `/impostos/aliquotas/{classe}/{vigencia}` | definir aliquota vigencia | corpo JSON: aliquota_pct, nota? |
| DELETE | `/impostos/aliquotas/{classe}/{vigencia}` | remover aliquota vigencia |  |
| GET | `/impostos/classificacao` | Todos os itens que podem gerar crédito (insumos, gastos de mão de obra/instalações/máquinas, despesas, revenda) por sessão, com as classes marcadas. |  |
| GET | `/impostos/classificacao/itens` | Os itens classificáveis de um cadastro (o insumo, os gastos de uma máquina/instalação/colaborador, a despesa…) para marcar as classes no próprio cadastro. | consulta: secao, codigo |
| POST | `/impostos/classificacao/lote` | Liga ou desliga uma classe de crédito em vários itens de uma vez (os "visíveis" da tela). | corpo JSON: itens, classe, marcar? |
| PUT | `/impostos/classificacao/{origem}/{origem_id}` | Define (substitui) as classes de crédito de um item; lista vazia = o item não gera crédito. | corpo JSON: classes |
| GET | `/impostos/icms` | Tudo do ICMS da venda: faixas, UFs com alíquota, mix de destinos de cada Centro de Resultado e o Desenvolve-BA. |  |
| PUT | `/impostos/icms/compras/{faixa}` | Alíquota do crédito de ICMS das compras de uma origem (dentro da Bahia, Sul/Sudeste exceto ES, demais). | corpo JSON: aliquota_pct |
| PUT | `/impostos/icms/desenvolve` | definir desenvolve | corpo JSON: ativo?, pct_dilatado?, pct_pago_a_vista?, pct_fundo_pobreza?, plano_de_contas_codigo?, observacao? |
| POST | `/impostos/icms/desenvolve/simular` | Aplica os parâmetros do Desenvolve a um saldo devedor mensal informado (a conta do benefício, sem depender do Planejamento). | corpo JSON: saldo_devedor |
| PUT | `/impostos/icms/destinos/{uf}` | atualizar destino icms | corpo JSON: aliquota_pct?, reducao_base_pct?, frete_adicional_pct? |
| PUT | `/impostos/icms/faixas/{faixa}` | Muda a alíquota de todas as UFs de uma faixa de uma vez. | corpo JSON: aliquota_pct |
| PUT | `/impostos/icms/mix/{cenario}` | Define o mix de destinos da venda do Centro de Resultado (fração da receita por UF; a soma fecha 100%; vazio limpa). | corpo JSON: linhas |

### Grupo `insumos`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/insumos` | listar insumos |  |
| POST | `/insumos` | criar insumo | corpo JSON: codigo?, nome?, tipo?, unidade?, valor_compra_unitario?, frete?, ipi_pct?, icms_pct?, atualizado_em? |
| PATCH | `/insumos/{codigo}` | Nome e tipo mudam direto; preço, frete, IPI e ICMS mudam com histórico (versão antiga guardada). | corpo JSON: codigo?, nome?, tipo?, unidade?, valor_compra_unitario?, frete?, ipi_pct?, icms_pct?, atualizado_em? |
| DELETE | `/insumos/{codigo}` | excluir insumo |  |
| GET | `/insumos/{codigo}/historico` | historico do insumo |  |

### Grupo `manual`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/manual/{qual}` | Texto em markdown de um manual: `humano` (por tela, para quem usa o sistema) ou `ia` (para um agente operar a API/CLI). |  |

### Grupo `outros`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/health` | health |  |

### Grupo `planejamentos`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/planejamentos` | listar planejamentos |  |
| POST | `/planejamentos` | Postgres: copia por inteiro o Planejamento `origem` (cadastros, formulações, alocações, volumes…). Sem `origem` | corpo JSON: codigo?, nome?, origem?, ano?, oficial? |
| PATCH | `/planejamentos/{codigo}` | Renomeia e/ou marca como oficial (só um é oficial por vez). | corpo JSON: codigo?, nome?, origem?, ano?, oficial? |
| DELETE | `/planejamentos/{codigo}` | excluir planejamento |  |

### Grupo `precificacao`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/precificacao/configuracao` | obter configuracao |  |
| PUT | `/precificacao/configuracao` | definir configuracao | corpo JSON: modo_impostos |

### Grupo `precificacao-primaria`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/precificacao/analise` | obter analise |  |
| GET | `/precificacao/dre` | obter dre |  |
| GET | `/precificacao/meta` | obter meta |  |
| PUT | `/precificacao/meta` | definir meta | corpo JSON: percentual_socios?, percentual_reserva?, percentual_expansao?, percentual_outros? |
| GET | `/precificacao/primaria` | obter primaria |  |
| PUT | `/precificacao/primaria/{produto}` | definir preco definido | corpo JSON: preco_definido? |
| GET | `/precificacao/tabela` | obter tabela |  |
| GET | `/precificacao/tabela.xlsx` | baixar tabela |  |

### Grupo `premissas`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| POST | `/planejamentos/{codigo}/premissas` | criar premissa | corpo JSON: codigo, tipo, texto |
| GET | `/planejamentos/{codigo}/resumo` | obter resumo |  |
| PATCH | `/premissas/{codigo}` | atualizar premissa | corpo JSON: tipo?, texto? |
| DELETE | `/premissas/{codigo}` | excluir premissa |  |

### Grupo `producao`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/planejamentos/{codigo}/producao` | obter producao |  |
| POST | `/planejamentos/{codigo}/producao/ajustar-aos-centros` | Produção := soma dos volumes dos Centros de Resultado, para os produtos divergentes que têm previsão em algum Centro. |  |
| GET | `/planejamentos/{codigo}/producao/consistencia` | Produtos cuja produção não bate com a soma dos volumes projetados nos Centros de Resultado. |  |
| GET | `/planejamentos/{codigo}/producao/plano` | Produção a produzir por produto (itens da tabela de preços atual; `todos` lista todos os produtos), os intermediários | consulta: todos? |
| PUT | `/planejamentos/{codigo}/producao/plano/{produto}` | definir producao | corpo JSON: quantidade |
| PUT | `/planejamentos/{codigo}/volumes/{cenario}/{produto}` | definir volume | corpo JSON: quantidade |
| DELETE | `/planejamentos/{codigo}/volumes/{cenario}/{produto}` | remover volume |  |

### Grupo `produtos`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/produtos` | listar produtos |  |
| POST | `/produtos` | criar produto | corpo JSON: codigo?, nome?, tipo?, custo_compra?, rendimento_kg?, rendimento_un?, qtd_estimada_producao_mes?, atualizado_em?, unidade?, base_quantidade?, perda_pct?, rendimento_real?, na_tabela_de_precos? |
| POST | `/produtos/tabela-de-precos` | Marca ou desmarca vários produtos como cabeça da Tabela de Preços (tudo ou nada: código inexistente recusa o lote). | corpo JSON: codigos, marcado |
| PATCH | `/produtos/{codigo}` | Nome e produção estimada mudam direto; rendimento muda com histórico. | corpo JSON: codigo?, nome?, tipo?, custo_compra?, rendimento_kg?, rendimento_un?, qtd_estimada_producao_mes?, atualizado_em?, unidade?, base_quantidade?, perda_pct?, rendimento_real?, na_tabela_de_precos? |
| DELETE | `/produtos/{codigo}` | excluir produto |  |
| POST | `/produtos/{codigo}/duplicar` | Novo Produto com o mesmo tipo, rendimentos e as linhas atuais do roteiro (valendo de `atualizado_em`). | corpo JSON: codigo, nome, atualizado_em? |
| GET | `/produtos/{codigo}/ficha` | Roteiro com o custo de cada linha e os totais, como seriam no mês `competencia` (padrão o atual). | consulta: competencia? |
| GET | `/produtos/{codigo}/historico` | historico do produto |  |
| GET | `/produtos/{codigo}/roteiro` | obter roteiro |  |
| POST | `/produtos/{codigo}/roteiro/{tipo}` | Nova linha de roteiro, valendo a partir do mês `atualizado_em` (padrão o atual). | corpo JSON: atividade_codigo, recurso_codigo?, insumo_codigo?, insumo_produto_codigo?, quantidade, unidade?, perda_pct?, atualizado_em? |
| PATCH | `/produtos/{codigo}/roteiro/{tipo}/{linha_id}` | alterar linha | corpo JSON: quantidade, unidade?, perda_pct?, atualizado_em? |
| DELETE | `/produtos/{codigo}/roteiro/{tipo}/{linha_id}` | Encerra a linha a partir do mês `em` (padrão o atual); ela segue valendo nos meses anteriores. | consulta: em? |

### Grupo `prontidao`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/planejamentos/{codigo}/prontidao` | O que já está pronto e o que falta no Planejamento, etapa por etapa (na ordem de uso do sistema). |  |

### Grupo `rateio-despesas`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/precificacao/rateio` | obter rateio |  |
| PUT | `/precificacao/rateio/{direcionador}` | gravar rateio | corpo JSON: percentuais |
| DELETE | `/precificacao/rateio/{direcionador}` | voltar a sugestao |  |
| PUT | `/precificacao/rateio/{direcionador}/criterio` | trocar criterio | corpo JSON: criterio, peso_quantidade? |
| GET | `/precificacao/trava` | obter trava |  |
| POST | `/precificacao/trava` | travar |  |
| DELETE | `/precificacao/trava` | reabrir |  |

### Grupo `totvs`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/totvs/cargas` | listar cargas | consulta: fonte? |
| GET | `/totvs/estrutura/conferencia` | Último relatório aplicado × formulação do sistema, pai a pai (só as linhas de origem TOTVS entram na comparação). | consulta: busca?, situacao? |
| GET | `/totvs/estrutura/conferencia/{pai}` | conferencia do pai |  |
| POST | `/totvs/estrutura/confirmar` | Revalida e grava, tudo ou nada: com qualquer erro nada é gravado (`gravado` = false). | consulta: vigencia?, arquivo? |
| POST | `/totvs/estrutura/previa` | Lê o relatório e mostra o que seria criado/alterado/removido, com avisos e erros — sem gravar nada. | consulta: vigencia?, arquivo? |
| POST | `/totvs/ndc/confirmar` | confirmar ndc | consulta: vigencia?, arquivo? |
| POST | `/totvs/ndc/previa` | Lê a NDC e mostra quais custos mudariam (anterior → novo), os itens sem custo e os que não estão nela — sem gravar. | consulta: vigencia?, arquivo? |
| POST | `/totvs/produtos/confirmar` | confirmar produtos | consulta: vigencia?, arquivo? |
| POST | `/totvs/produtos/previa` | Lê a aba Totvs_Cad_Prod e mostra os nomes que mudariam e os itens de produção do cadastro que ainda não têm estrutura. | consulta: vigencia?, arquivo? |

### Grupo `usuarios`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/usuarios` | listar |  |
| POST | `/usuarios` | criar | corpo JSON: email, nome, senha, admin? |
| PATCH | `/usuarios/{usuario_id}` | alterar | corpo JSON: nome?, admin?, ativo?, senha? |

### Grupo `versoes`

| Método | Caminho | Para que serve | Parâmetros |
| --- | --- | --- | --- |
| GET | `/planejamentos/comparar` | Diferença B − A entre os resultados ao vivo de dois Planejamentos (cada um com os seus dados). | consulta: a, b |
| GET | `/planejamentos/{codigo}/versoes` | listar versoes |  |
| POST | `/planejamentos/{codigo}/versoes` | Congela os resultados de hoje do Planejamento (Meta de Lucro, DRE Consolidada, Centros de Resultados, Premissas e linhas por produto). | corpo JSON: rotulo, observacao? |
| GET | `/planejamentos/{codigo}/versoes/comparar` | Diferença B − A entre duas versões (ou uma versão e o 'atual', calculado na hora). | consulta: a, b |
| GET | `/planejamentos/{codigo}/versoes/{numero}` | obter versao |  |
| PATCH | `/planejamentos/{codigo}/versoes/{numero}` | Só rótulo, observação e o marcador de oficial mudam; os números da versão são imutáveis. | corpo JSON: rotulo?, observacao?, oficial? |
| DELETE | `/planejamentos/{codigo}/versoes/{numero}` | excluir versao |  |

<!-- CATALOGO:FIM -->

## 7. CLI (para quem tem acesso ao servidor)

`python -m custos_precificacao.cli <comando> --help`. Opera direto no banco do Planejamento padrão, **sem passar pelo login** — use só em ambiente controlado e nunca em produção sem ordem do usuário. Comandos: `cadastro list|get|create|update|delete <entidade> [chave] [campo=valor …]` (CRUD genérico dos cadastros simples), `roteiro add-maquina|add-ambiente|add-mao-de-obra|add-insumo`, `roteiro list|remove|alterar`, `gasto add|list|remove|alterar`, `planejamento volume-set|volume-list|resumo`, `despesa aloca`, `custeio-run`, `usuario criar|listar|senha|ativar|desativar` e `cenario ligar|desligar|status` (rateio por Centro, mantido só por compatibilidade). Prefira a API e a planilha: elas respeitam login, auditoria (Log de Ações) e a validação tudo-ou-nada.

## 8. Erros e armadilhas comuns

| Sintoma | Causa provável | O que fazer |
| --- | --- | --- |
| `403` em escrita | Faltou `X-Requested-With`, ou a rota é só de administrador | Envie o cabeçalho; peça a um administrador |
| `409` "O Planejamento … não é o selecionado" | `{codigo}` da rota ≠ `X-Planejamento` | Alinhe os dois |
| `422` ao criar linha de formulação | Atividade, Direcionador ou recurso inexistente; Direcionador de outra Atividade | Consulte `alocacao/opcoes` e as listas |
| Custo do produto "—" ou ausente | Produto novo depois do último custeio, ou fora da Tabela de Preços | Rode o custeio; confira "cabeça" |
| Preço sugerido não aparece | Falta Meta de Lucro ou custeio | `GET .../prontidao` |
| Divisor ≥ 100% / erro no Centro | %impostos + %variáveis + lucro ≥ 100% | Revise Meta, despesas variáveis e alíquotas |
| Despesa fixa sem quantidade para ratear | Nenhum produto consome a Atividade do Direcionador, ou sem volume | Ajuste o Direcionador/produção |
| `409` "A Precificação Primária está travada" | Escrita na Meta, preço definido, modo dos impostos ou rateio com a primária travada | `DELETE /precificacao/trava`, altere e trave de novo |
| Centros e DRE Consolidada vazios com `aviso` sobre a primária | Primária aberta ou trava desatualizada | `GET /precificacao/trava`; confira o rateio e `POST /precificacao/trava` |
| `422` ao gravar o rateio ("precisa somar 100%") | Os % do Direcionador não somam 1 | Ajuste (ou `normalizar` no cliente) e reenvie |
| Importação recusada inteira | Uma linha com erro (tudo-ou-nada) | Leia `erros`, corrija, repita a prévia |
| Mix de destinos recusado | Não soma 100% | Ajuste as linhas do Centro |
| Unidades incoerentes | Linha de insumo em unidade sem conversão para a do insumo | Cadastre a conversão em Unidades e Conversões |
| Quantidades dos Centros maiores que a produção | Soma dos Centros > produção do produto | Ajuste a produção ou use o ajuste aos Centros |
| Valor 100x errado | Percentual enviado como inteiro (`20`) em vez de fração (`0.20`) | Na API use fração; na planilha, `20%` |

## 9. Como conferir o resultado

- `GET .../prontidao` deve ter todas as etapas obrigatórias em `pronto`.
- No custeio, a soma dos totais dos elementos + ociosidade não alocada fecha com o custo mensal dos elementos ligados.
- Na Análise de Preço × Lucro, ao **preço sugerido** o *Resultado Final* é zero e o *Spread* é zero; ao preço definido, o Spread mostra a diferença para a Meta.
- A DRE por conta (`/precificacao/dre` e `/dre/consolidada`) traz em cada linha `desembolso`, `retencao` e `valor` (Total), com `desembolso + retencao = valor`; só os custos dos elementos de custo têm retenção (a coluna *Retenção* dos gastos), o resto é inteiro em desembolso, e nas linhas de resultado `retencao` é o efeito negativo das provisões. Fotos antigas devolvem `null` nas duas colunas.
- A DRE por conta fecha com a Análise (mesmo Resultado Operacional); a DRE Consolidada fecha com a soma dos Centros e a reconciliação mostra o efeito de cada Centro sobre a primária.
- Depois de qualquer importação, rode a prévia de novo com o arquivo preenchido (`modelo?preenchido=true`): deve dar **0 criados e 0 atualizados**.