Lição: Orçamento de Procedimentos

1. Objetivo do módulo e onde fica

O módulo de Orçamento serve para montar, enviar e acompanhar orçamentos de procedimentos eletivos: cirurgias, planos de tratamento e atendimentos particulares. Você monta o orçamento com serviços, produtos consumidos, taxas e equipamentos; o paciente recebe a proposta em PDF; aprovado, o botão Agendar abre o agendamento já preenchido e o fluxo financeiro — sem redigitar nada.

Onde fica (menu / rota): Agenda → Orçamento.

2. Como um orçamento é estruturado

Um orçamento tem um cabeçalho (paciente, local, profissional responsável, status, observação) e uma lista de Serviços. Cada serviço pode conter:

• Produtos consumidos — ampolas, gases, materiais descartáveis etc.
• Taxas — taxa de sala cirúrgica, taxa de equipamento etc.
• Equipamentos utilizados — com grade de tempo de uso.
• Profissional responsável pelo serviço.

Ou seja, o valor total do orçamento é a soma dos serviços, e cada serviço soma seus produtos, taxas e equipamentos.

3. Campos do orçamento

Os campos abaixo aparecem ao criar/editar (OrcamentoForm.tsx). Datas seguem o formato dd/mm/aaaa e valores em R$ 1.234,56.

4. Status do orçamento

✅ Novo — 26/09/2026 Os status abaixo são os nomes que aparecem no sistema (código de produção). Correção de 26/09/2026: esta lição listava nomes que não existem no sistema (RASCUNHO, AGUARDANDO_APROVACAO, APROVADO_CLIENTE, REJEITADO_CLIENTE, CONFIRMADO, AGENDADO, REALIZADO, EXPIRADO) e um "cron diário" de expiração.

Resumo: travam a edição só Recusado e Aprovado pela Assistência; Vencido e Aprovado pela Assistência aparecem como pendência no board. Não existe status "Confirmado" nem "Realizado" no orçamento: ao agendar a partir dele, cada sessão agendada conta como usada, e cancelar o agendamento devolve a sessão ao orçamento.

5. Botões e ações

6. Passo a passo — criar, aprovar e agendar um orçamento

1. Vá em Agenda → Orçamento e clique em Novo (/portal/agenda/orcamento/criar).
2. Busque e selecione o paciente (por nome ou CPF).
3. Informe local e profissional responsável.
4. Adicione um ou mais serviços; para cada um, informe a quantidade e, se preciso, os produtos, taxas e equipamentos.
5. Se houver desconto, aplique — o sistema validará seu nível de alçada.
6. Clique em Salvar e revise o total. Imprima a proposta para o paciente (enquanto não aprovada, ela sai com o aviso "RASCUNHO" e a validade).
7. Registre a resposta mudando o status — por exemplo, Aprovado pelo Paciente (ou Recusado, Solicitar nova proposta, Em negociação).
8. Com o orçamento aprovado, clique em Agendar: a tela de agendamento abre pré-preenchida; defina data e horário e salve. Cada sessão agendada conta como usada no orçamento.
9. Passou da validade sem aprovação? O orçamento aparece como Vencido (pendência no board) e continua editável para ser renovado.

7. Aprovação → botão "Agendar"

Com o orçamento aprovado, o botão Agendar gera o agendamento pré-preenchido com os dados do orçamento — você não precisa recriar os dados; basta conferir e salvar. Na API interna do sistema, a aprovação é POST /orcamento/:id/aprovar. Sequência:

1. Orçamento aprovado (ex.: Aprovado pelo Paciente) → botão Agendar.
2. O sistema abre a tela de agendamento pré-preenchida.
3. Ao salvar, a sessão agendada passa a contar como usada no orçamento (não existe status "Confirmado" no orçamento).
4. No pagamento/atendimento, a movimentação financeira fica vinculada ao orçamento (orçamentos criados a partir de 25/09: um financeiro único — ver 7.2).
5. Cancelou um agendamento? A sessão volta ao saldo do orçamento. Não existe status "Realizado" no orçamento: o acompanhamento é pelo uso das sessões.

Orçamentos cancelados podem ser reabertos em /portal/agenda/orcamento/:idOrcamentoCancelado/reabrir — o sistema cria um novo orçamento a partir do cancelado, que começa em Pendente de aprovação interna.

✅ Novo — jul/2026 O caminho inverso também existe: é possível vincular o orçamento a partir do agendamento (#359). Entregue no ciclo de julho/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

7.1. Trava de edição pós-aprovação ✅ Novo — set/2026

Entregue no ciclo de setembro/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

• Quem trava e quem continua editável ✅ Novo — 26/09/2026 (regra revista em 25/09/2026 — substitui o "orçamento aprovado nunca edita"): travam a edição apenas os status Recusado e Aprovado pela Assistência (enfermagem). Aprovado pelo Paciente e Aprovado pelo Convênio continuam editáveis, e o Vencido também (para renovar). Continua valendo o #614: impressão e proposta mostram o valor congelado do orçamento, e uma edição ignorada em orçamento travado gera aviso na tela.
• Botão "Abrir Proposta" desabilitado: no orçamento aprovado, o botão "Abrir Proposta" fica desabilitado, impedindo reabrir a proposta de um orçamento já fechado com o paciente.
• Cópia de documentos também na edição: os documentos anexados ao orçamento passam a ser copiados para o agendamento também quando o orçamento é editado — antes isso só acontecia na criação, e anexos incluídos depois não chegavam ao agendamento.
• Impressão com aviso RASCUNHO e data de validade (#611): a impressão do orçamento voltou a exibir o aviso de RASCUNHO (quando ainda não aprovado) e a data de validade — o paciente vê claramente que a proposta é preliminar e até quando vale.
• Status do orçamento destravado (#607): corrigidos cenários em que o status do orçamento ficava travado e não avançava — o ciclo de vida volta a fluir normalmente nesses casos.

7.2. Orçamento com várias sessões — financeiro único ✅ Novo — 26/09/2026

Em produção desde 24/09/2026 (noite). Vale para orçamentos criados a partir de 25/09/2026 — os antigos seguem como eram.

• Uma cobrança só: todas as sessões de um orçamento compartilham UMA movimentação financeira, com o valor total do orçamento (nunca "valor × número de sessões"). Cada nova sessão reaproveita a mesma cobrança, em vez de gerar outra.
• Onde pagar: na tela do orçamento (opcional) ou no acolhimento. Pagou de um lado, aparece pago nos dois.
• Agendar sem pagar pode; acolher sem pagar não: orçamento particular com financeiro pode ser agendado sem estar pago, mas não pode ser acolhido sem estar pago — o pagamento é feito ali mesmo, no acolhimento. Mensagem: "Não é possível acolher: o orçamento (id N) ainda não foi pago." Orçamento só de convênio (sem parcelas) não entra nesta regra.
• Trocar o status pelo menu do check-in para um status que só se alcança pelo acolhimento também exige o orçamento pago ("Não é possível mudar o status: o orçamento ainda não foi pago. Faça o acolhimento com o pagamento.").
• Depois de pago, o valor TRAVA: não se altera valor nem se dá desconto ("O orçamento desta sessão já foi pago — não é possível alterar o valor nem dar desconto."). Antes de pago, desconto ou ajuste feito no acolhimento vale para o orçamento e para todas as sessões (é o mesmo financeiro).
• Proteções contra cobrança errada (orçamentos novos): o acolhimento bloqueia quando a sessão está sem a movimentação do orçamento, quando o financeiro da sessão está diferente do total do orçamento, quando duas sessões do mesmo orçamento têm movimentações diferentes (cobrança em dobro) e quando o agendamento está ligado a mais de um orçamento com financeiro ("separe as sessões por orçamento").
• NFS-e por parcela: em orçamento 100% particular com financeiro próprio, a nota das sessões sai pelo lado do orçamento, por parcela paga (sem duplicar). Orçamento misto (particular + convênio) ou sem financeiro próprio segue emitindo pela movimentação, como antes.
• Contagem de sessões corrigida (25/09): conta o uso real pelos agendamentos; cancelar um agendamento devolve a sessão ao orçamento/autorização (pela tela de cancelar, pelo cancelamento da autorização e pelo portal do paciente). A aba de orçamentos "com saldo" deixou de listar orçamentos já 100% consumidos.

8. Regras de negócio — descontos por nível

Ao aplicar desconto, o sistema chama o validacaoDescontoController, que confere o nível de permissão do colaborador via ParametrosDeDesconto:

✅ Novo — ago/2026 O "nível de desconto" foi renomeado para "nível de alçada" (#557) e as aprovações por nível de alçada foram entregues (épico #571): a solicitação de aprovação notifica todos os usuários do nível e, quando um responde, a pendência é resolvida para todos (#558). Entregue no ciclo de agosto/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

✅ Novo — 26/09/2026 Aprovações em tempo real (24/09/2026): os pedidos de aprovação de farol, desconto e edição/cancelamento de Atendido chegam em tempo real a todos os aprovadores do nível exigido ou superior (ex.: um pedido de Nível 2 chega ao Nível 2 e ao Nível 3); quando um responde, o pedido some da tela dos demais. Os canais são isolados por clínica.

Atenção — desconto depois do pagamento: no orçamento com financeiro já pago, o valor trava e não se dá mais desconto (ver 7.2). Desconto é antes do pagamento.

9. Regras de negócio — validade e expiração

Todo orçamento tem validade em ParametrosOrcamento.diasValidos (Parâmetros › Orçamento; padrão 30 dias). Passada a validade, o orçamento aparece como Vencido — um status virtual, calculado na leitura (data de criação + dias de validade < hoje) e nunca gravado: não há rotina que troque o status. O vencido aparece como pendência no board e continua editável para ser renovado. Também há versões: cada alteração relevante (valor ou escopo) gera uma nova versão para o cliente comparar antes de aprovar; o histórico fica preservado.

10. Permissões necessárias

O Orçamento é controlado pela permissão ORCAMENTO, só com as quatro ações do modelo (hierárquicas: DELETE inclui UPDATE, que inclui CREATE, que inclui VIEW). Desde 15/09/2026 as permissões granulares (#395) permitem montar perfis e grupos com essas ações.

✅ Correção — 30/09/2026 Versões anteriores desta lição listavam ORCAMENTO.APROVAR, ORCAMENTO.CANCELAR, ORCAMENTO.REABRIR e ORCAMENTO.OVERRIDE_VALOR: essas permissões não existem no sistema.

11. Erros comuns e como resolver

12. Farol de resultado — ENTREGUE ✅ Novo — jul/2026

✅ Novo — set/2026 Impressão do orçamento corrigida (#614 — 24/09/2026): o valor da impressão divergia da proposta (mesmo com o orçamento aprovado) e havia falha silenciosa ao salvar. Corrigido: a impressão sai com o mesmo valor da proposta e toda gravação agora tem confirmação na tela.

Novidades de 15–23/10/2026 ✅ Novo — 23/10/2026

Conferidas no código de produção em 23/10/2026.

• Recusado não aparece como Vencido; Vencido continua calculado pelo prazo de validade.
• Marca d'água de rascunho no orçamento impresso enquanto ele está em Pendente de Aprovação Interna ou Em negociação.
• Os textos do formulário seguem o tipo (Orçamento / Acolhimento / Agendamento).
• Quem aprova: colaborador com conselho + a ação Ver Valores (excepcional) pode aprovar orçamento (21/10) — ver a lição de Configurações.
• Cancelar o orçamento encerra os títulos e os links de pagamento dele (22/10); pagamento parcial vira parcela paga + saldo em aberto.
• ✅ Novo — 26/10/2026 Aprovar sem acesso a Colaboradores (23/10): o médico que não tem acesso à tela de Colaboradores agora consegue aprovar o orçamento — opções como "Aprovado pela Assistência" deixam de ficar desabilitadas por falta dessa permissão.

Pontos-chave

• Orçamento fica em Agenda → Orçamento (/portal/agenda/orcamento) e está em produção.
• Estrutura: cabeçalho + serviços; cada serviço agrega produtos, taxas e equipamentos.
• Os 9 status reais: Pendente de aprovação interna, Em negociação, Cancelado, Solicitar nova proposta, Recusado, Aprovado pelo Paciente, Aprovado pelo Convênio, Aprovado pela Assistência e Vencido (virtual, nunca gravado). Não existem Rascunho/Confirmado/Realizado/Expirado como status (o "RASCUNHO" é só o aviso impresso, #611).
• Com o orçamento aprovado, o botão Agendar abre o agendamento pré-preenchido — não redigite os dados; cada sessão agendada conta como usada e cancelar devolve a sessão.
• Desconto é validado por nível (5% / 10% / 20% / sem limite) — desde ago/2026 o nível chama-se "nível de alçada" (#557) e as aprovações notificam todos do nível, resolvendo para todos quando um responde (épico #571).
• Validade padrão de 30 dias (Parâmetros › Orçamento); passado o prazo, aparece Vencido — calculado na leitura, nunca gravado, pendência no board e editável para renovar.
• Farol de resultado (#390/#434) foi entregue em jul/2026: cores + índice; no 🔴 vermelho o sistema bloqueia e a liberação exige nível superior.
• Novidades de ago/2026: visão geral do farol/cruzamentos (#435), farol ROXO para erro de preço com bloqueio (#545), farol considerando taxas (#550), farol consolidado serviço+produto+taxa no agendamento e na autorização (#551/#552, épico #570), crítica de quantidades a partir do orçamento/autorização (#553/#554), aprovações por nível de alçada (épico #571) e notificação de orçamentos solicitados com link e prazos (#446).
• Novidades de set/2026: trava de edição pós-aprovação — desde 25/09 só travam Recusado e Aprovado pela Assistência; Aprovado pelo Paciente, Aprovado pelo Convênio e Vencido seguem editáveis —, o botão "Abrir Proposta" fica desabilitado no aprovado, os documentos anexados são copiados para o agendamento também na edição do orçamento (não só na criação), a impressão volta a trazer o aviso RASCUNHO e a data de validade (#611), o status do orçamento foi destravado em vários cenários (#607) e, em 24/09, a impressão passou a sair com o mesmo valor da proposta e toda gravação tem confirmação (#614).
• Desde 23/09/2026 o Farol do orçamento é consolidado: Σ receita de tudo ÷ Σ custo de tudo × 100 — a aprovação por alçada olha o consolidado, a cor por linha só orienta, item sem custo/preço deixa o conjunto roxo e bloqueia, e 0,00 é preço zero (só campo vazio desce de nível).
• Desde 23–24/09/2026 (toda a série de preços em produção): item sem Utiliza entra a R$ 0,00 (custo sem receita); taxas, produtos e subserviços sempre entram — "somar itens" decide só o valor próprio do serviço; preço fixo sem Pacote cobra os itens na quantidade inteira (para incluir: Pacote + Zerar nos itens); Zerar é por item, sem cascata; confira pela aba Farol › Itens e pelo botão Expandir serviço.
• Valor combinado NÃO é pacote (regra vigente): sozinho, ele muda só o preço do serviço e os itens somam por cima. Preço fechado = valor combinado + Pacote (marcação por convênio) + Zerar nos itens inclusos. Em produção desde 24/09: a linha Σ da coluna Valor mostra o total do serviço no convênio (= receita do Farol).
• Financeiro único (orçamentos criados a partir de 25/09): todas as sessões compartilham uma movimentação com o valor total; paga-se na tela do orçamento ou no acolhimento; orçamento particular com financeiro agenda sem pagar, mas só acolhe pago; depois de pago, valor e desconto travam; NFS-e do orçamento 100% particular sai por parcela paga; cancelar um agendamento devolve a sessão.
• Pedidos de aprovação (farol, desconto, edição/cancelamento de Atendido) chegam em tempo real a todos os aprovadores do nível exigido ou superior e somem da tela dos demais quando um responde.
• 🟠 Roadmap #628 (Sprint 12): a marcação Atende da aba Especialidades do convênio vai limitar o orçamento (e o agendamento e a autorização) aos profissionais, especialidades e serviços que o convênio atende — hoje não tem efeito. Revise a aba Especialidades dos convênios antes da mudança. ✅ Atualização 13/10: entrou e foi desligada temporariamente em 06/10 no orçamento e no agendamento (vale no cadastro do convênio). A consulta de disponibilidade da IA (TalkMe, #633) é a exceção: ela respeita a coluna Atende — por isso a IA pode dizer que não há horário num caso que a recepção consegue agendar.
• ✅ Novo — out/2026 Desde 12/10 o custo do Farol = produtos + custo extra do convênio + prestadores + repasse (sem profissional: o maior repasse entre quem atende); o bloqueio por esses custos nasce desligado (Parâmetros › Orçamento). Status 10–13 (Pago, Agendado, Concluído, Renegociado) já aparecem, mas a troca automática ainda não está ativa (#656). Lista com colunas, Responsável e Exportar Excel (#657); pedido de desconto mostra paciente e serviço (#637).
• ✅ Novo — 15/10/2026 Desde 13–15/10: Recusado não aparece mais como Vencido; desconto por sessão espelhado no financeiro do agendamento; 5 senhas de aprovação erradas em 15 min bloqueiam; a IA não oferece serviço bloqueado pelo Farol ou que exige aprovação (#664).

O que a prova vai cobrar

• Os status reais do orçamento e o que cada um significa — inclusive que Vencido é virtual e que só Recusado e Aprovado pela Assistência travam a edição.
• Que, aprovado o orçamento, o botão Agendar gera o agendamento pré-preenchido e cada sessão agendada conta como usada.
• Os limites de desconto por nível de permissão.
• Validade padrão (30 dias) e o status Vencido calculado na leitura (sem rotina de expiração; o vencido é renovado editando).
• Saber que o Farol de resultado (#390/#434) foi entregue em jul/2026: cores + índice e bloqueio no vermelho com liberação por nível superior. A visão geral de cruzamentos (#435) e o farol roxo de erro de preço (#545) foram entregues em ago/2026, e o farol passou a considerar taxas (#550).
• Saber que desde 23/09/2026 o Farol do orçamento/agendamento/autorização é consolidado (Σ receita ÷ Σ custo de tudo), que a aprovação por alçada se refere ao consolidado e que 0,00 é preço zero — só o campo vazio faz o sistema descer de nível.
• Saber que, desde 23–24/09/2026, os itens (taxas, produtos, subserviços) sempre entram na conta do serviço, que "somar itens" decide só o valor próprio do serviço, que o preço fixo sem Pacote cobra os itens na quantidade inteira (para embutir: Pacote + Zerar nos itens) e que Zerar é por item, sem cascata — só a falta de Utiliza no subserviço tira tudo o que está dentro dele.
• Saber que o valor combinado sozinho não fecha pacote: sem Pacote marcado na linha do serviço no convênio, os itens somam por cima e o "Zerar valor em pacotes" nem é consultado.
• Saber que, no orçamento com várias sessões, há um financeiro só (valor total, nunca valor × sessões); que o orçamento particular com financeiro pode ser agendado sem pagamento, mas não acolhido; e que depois de pago o valor trava (sem alteração nem desconto).
• Saber quais status travam a edição do orçamento: Recusado e Aprovado pela Assistência (Aprovado pelo Paciente, Aprovado pelo Convênio e Vencido seguem editáveis).
• ✅ Novo — out/2026 O que compõe o custo do Farol desde 12/10 (produtos + custo extra do convênio + prestadores + repasse) e que o bloqueio por esses custos é opcional (desmarcado por padrão); e que os status automáticos do orçamento (#656) ainda não estão ativos.
• ✅ Novo — 15/10/2026 Que orçamento Recusado nunca aparece como Vencido e o limite de 5 tentativas de senha na aprovação de desconto (15 minutos de espera ou aprovação remota).