2. Guia do Implantador — conversão de valores, tela por tela

1. Mapa das telas

2. Os 3 níveis, por tipo de item

2.1 Produto — a cadeia mais longa

O valor unitário do produto num convênio é resolvido assim (para no primeiro que tiver valor):

Cada um dos três campos (fonte, tipo de preço, Fator K) é herdado separadamente: a linha do convênio pode definir só o Fator K e herdar a fonte da política, por exemplo.

🟠 Roadmap Ainda não disponível: importação do arquivo de cada editora para carregar os preços (volta quando houver leitura do formato de cada editora).

Fontes de preço disponíveis:

Fator K é percentual: 0 = sem ajuste, 20 = +20%, -10 = −10%. Aceita de −100 a 2000.
Sem nenhuma fonte de preço resolvida e sem valor unitário convertido → valor 0.

Custo (para o Farol): aba Estoque › Última Compra. Com Padrão Calcular marcado usa a última entrada do estoque; desmarcado usa o valor digitado em Última Compra (Unidade). Produto com custo 0 → Farol roxo / Sem custo. Desde 12/10/2026 o custo do serviço no Farol soma também custos extras do convênio, prestadores e repasse (2.5).

2.2 Taxa

Taxa não tem Fator K, política de preço nem custo (é receita pura).

2.3 Serviço

Isso é o valor próprio (base) do serviço — o que sai na linha de procedimento do XML e na linha ✅ da aba Serviços. Os itens da composição (produtos, taxas, subserviços) entram por cima, sempre (seção 3). Serviço não tem Fator K nem política de preço.

✅ Novo em 23/09/2026 Na aba Serviços do convênio, a coluna Tipo de Atendimento também tem as 3 linhas (🔒 o do cadastro do serviço · 🔁 o escolhido para o convênio · ✅ o efetivo). Configure na linha 🔁 o tipo que a operadora exige e confira na linha ✅: o do convênio prevalece e vai para o atendimento, o pré-faturamento e o campo tipoAtendimento do XML.

2.4 Nome, descrição, código, tabela 87 e tipo de atendimento ✅ Em produção desde 24/09/2026

Todas as telas do convênio (abas Serviços, Produtos, Taxas e Farol) exibem o texto e o valor finais convertidos. A precedência é: nível 3 (o item no convênio) → nível 2 (política do convênio — só para o preço de produto) → catálogo (cadastro do item). Texto em branco conta como vazio e desce de nível.

Detalhe completo, com árvores e exemplos: Árvore de decisão do cadastro no convênio.

2.5 Custos extras do convênio, Serviços extras e repasse no custo do Farol ✅ Novo — 12/10/2026

Em produção desde 12/10/2026 (#655). O custo que o Farol usa ficou mais completo:

CUSTO = produtos (todos os da árvore do serviço)
      + custos extras do convênio      (aba Custos extras do convênio)
      + prestadores                    (painel Serviços extras do serviço no convênio)
      + repasse do profissional        (aba Vínculo e Repasse do colaborador)

• Aba Custos extras (Configurações › Convênios › [convênio], 10ª aba): botão Novo custo extra com Descrição; Tipo (Percentual da receita ou Valor fixo por execução); Percentual (%) ou Valor (R$); Incide sobre (Tudo (serviços, produtos e taxas) / Só serviços / Só produtos / Só taxas / Serviços específicos); Credor (fornecedor) — opcional; Grupo do DRE (só classificação); Início e Fim da vigência (vazio = "Sempre"). O percentual incide sobre a receita cobrada de cada linha (5% em cada linha = 5% da guia); o valor fixo vale por execução × quantidade × sessões. Ex.: uma operadora que desconta 5% de taxa administrativa sobre o que paga. A aba grava na hora (fora do Salvar do cabeçalho), obedece ao modo consulta, tem histórico próprio e a opção "Mostrar inativos".
• Serviços extras (prestadores terceiros — ex.: cooperativa, transporte): expanda a linha do serviço na aba Serviços do convênio e informe Prestador (do cadastro de Fornecedores), Descrição, Valor (fixo por execução), quantidade e Vigência. Vale só naquele convênio. Percentual de prestador ainda não existe.
• Repasse do profissional: com o profissional escolhido (orçamento, agendamento, autorização), entra o repasse dele — a regra do serviço ou o repasse geral (Configurações › Colaboradores › aba Vínculo e Repasse); sem profissional definido, o Farol usa o maior repasse entre quem atende o serviço e aceita o convênio (pior caso).
• Passe o mouse no Farol ou expanda o serviço: aparece a composição — Produtos, Custo extra do convênio, Prestadores (serviços extras), Repasse, Custo total, Receita, Índice. No orçamento e no agendamento, o diálogo de custos mostra "Custo do convênio", "Prestador" e "Repasse", com a regra usada ("Regra do profissional para o serviço", "Regra geral do profissional", "Profissional sem repasse cadastrado" ou "Estimado: maior repasse entre quem atende").

Na implantação: cadastre os custos extras de cada convênio (Liberar para edição → aba Custos extras — grava na hora) e o repasse dos profissionais (com a linha de repasse geral) antes da conferência pelo Farol; deixe a opção de bloqueio desmarcada até rodar "Ver serviços que mudam de cor" e combinar com a clínica.

3. Serviço composto — a regra única ✅ Em produção desde 23–24/09/2026

3.1 As quatro chaves

3.2 A fórmula

valor(serviço, convênio) = BASE + Σ quantidade × contribuição(item)

BASE = Valor convertido do serviço no convênio, se preenchido (inclusive 0)
       senão → 0 se soma itens · Valor do cadastro se é fixo

Os itens (produtos, taxas, subserviços) são SEMPRE considerados   ← desde 23/09/2026
("soma itens" só decide a BASE; antes, os itens só entravam se "soma itens" OU Pacote)

contribuição(item) = 0, se Utiliza(item) desmarcado
                       (se o item é SUBSERVIÇO: ele e TODA a subárvore ficam fora)
                   = 0, se há PACOTE DE PREÇO FECHADO acima (o próprio serviço ou um ancestral)
                       e o item tem Zerar valor em pacotes
                       (se o item é SUBSERVIÇO zerado: some só a BASE dele; os itens de dentro
                        seguem cada um o próprio Zerar — não cascateia, desde 24/09/2026)
                   = valor do item no convênio (pelos 3 níveis), nos demais casos
                   → para subserviço: o valor dele calculado por esta mesma fórmula, de baixo para cima

PACOTE DE PREÇO FECHADO = Pacote ✔ E (preço fixo OU Valor convertido preenchido — inclusive 0)
                          (também chamado de "pacote de preço manual")
                          Valor convertido SEM Pacote ✔ → NÃO é pacote: muda só a BASE; os itens somam por cima

CUSTO = sempre a soma integral de todos os produtos da árvore (sem filtro)

3.3 Tabela-verdade ✅ Em produção desde 23/09/2026

Em todas as linhas: item sem Utiliza fica fora (subserviço sem Utiliza leva tudo que está dentro dele); o custo soma tudo. Nas linhas ✘ ✘, "valor fixo (convertido, se houver)" significa que o valor combinado substitui o preço fixo do cadastro só como preço do serviço — os itens continuam somando por cima.

3.3.1 Valor combinado NÃO é pacote ✅ Regra vigente (decisão do Diretor 25/09/2026)

• O Valor 🔁 do serviço no convênio (valor combinado) muda só a base do serviço. Taxas, produtos e subserviços com Utiliza continuam somando por cima, cada um com o seu preço. Ex.: combinado 100 → total = 100 + aplicação + medicamento.
• Preço fechado que já inclui itens exige os três: (1) valor combinado na linha 🔁 (ou preço fixo do cadastro); (2) Pacote ✔ na linha do serviço; (3) Zerar valor em pacotes ✔ em cada item incluso (abas Produtos, Taxas ou Serviços do convênio). Item sem Zerar segue cobrado à parte. Desde 25/09/2026, criar o vínculo marcando só Pacote não liga o Zerar sozinho — ele é marcado item a item.
• Sem Pacote, o Zerar valor em pacotes dos itens não é consultado.
• Pacote é sempre marcação por convênio. O cadastro do serviço (catálogo) só tem preço fixo ou soma dos itens; ambos definem só o preço do serviço.
• Na API: valorInternoConvenio sozinho não fecha pacote — envie pacote: true no serviço e zerarValor: true nos itens inclusos (Implantação pela API).

3.4 Exemplos de conferência

Valores dos exemplos são ilustrativos.

3.5 Regras de subserviço ✅ Em produção desde 23–24/09/2026

• Um subserviço contribui com o próprio valor (base) + os produtos/taxas/subserviços cadastrados dentro dele, cada um com as suas conversões — inclusive quando ele é de preço fixo sem Pacote. Mudou em 23/09/2026: antes, o preço fixo do subserviço "já incluía" os itens de dentro. Para que o preço do subserviço inclua os itens, marque Pacote nele (no convênio) e Zerar valor em pacotes nos itens inclusos.
• Zerar valor em pacotes de um subserviço só age quando ele está dentro de um pacote de preço fechado, e zera só o valor dele. Os itens dentro dele continuam avaliados um a um: cada produto/taxa só fica fora se o próprio Zerar estiver marcado. Mudou em 24/09/2026: antes, subserviço zerado levava junto tudo que estava dentro dele.
• O contexto "pacote de preço fechado" desce para todos os níveis: um produto marcado com Zerar dentro de um subserviço, dentro de um pacote fechado, fica fora — mesmo que o subserviço não esteja zerado.
• O que tira toda a subárvore é só a falta de Utiliza no subserviço (o convênio não cobre aquele subserviço).
• Zerar nunca zera o serviço cobrado sozinho, nem a base do serviço raiz.
• O sistema protege contra ciclos (serviço A contém B que contém A).

3.6 Linha ✅ do serviço na aba Serviços = valor do próprio serviço ✅ Em produção desde 23/09/2026

Cada subaba do convênio (Serviços, Produtos, Taxas) mostra, na linha ✅, como aquele item vai sair na guia/XML, com as conversões dele. No serviço, isso é o valor do próprio serviço — o valor combinado do convênio, senão o do cadastro; zero se o serviço "soma itens" e não tem valor combinado — ou seja, a linha de procedimento do XML. A linha ✅ não soma produtos e taxas: eles vão para as próprias áreas do XML, cobrados com as próprias conversões. Quem soma tudo é só o Farol do serviço (que consolida subserviços, produtos e taxas); o Farol da taxa olha só a taxa e o do produto, só o produto (passe o mouse na bolinha para ver receita e custo).

Exemplo: "Noripurum aplicado EV" com valor combinado 0,01 mostrava 16,03 na linha ✅ (a soma); hoje mostra 0,01.

3.6.1 Coluna Valor do serviço com 4 linhas ✅ em produção desde 24/09

Em produção desde 24/09/2026 (noite): a subaba Serviços expõe somarItens e o total do serviço no convênio, e a coluna Valor mostra "(soma dos itens)" e o total. Só a coluna Valor do serviço tem a 4ª linha; produtos, taxas e a coluna Tipo de Atendimento seguem com 3 linhas.

Cada linha tem uma dica (tooltip). Caso que motivou a mudança: "Ferinject aplicado" no convênio Particular, com "Definir preço do serviço pelos itens" marcado, mostrava ✅ R$ 0,00 e parecia erro. O mesmo total também se lê no Farol do serviço, na linha do serviço em Farol › Itens e no painel Expandir serviço. Na API do sistema (usada pela tela), o item do serviço traz somarItens e efetivo.totalConvenio (= receita total do Farol); na API externa, efetivo.totalConvenio não aparece no Swagger.

3.7 Expandir serviço ✅ Novo — 26/09/2026 (concluído em 25/09, #625)

Onde: Configurações › Convênios › [convênio] › aba Serviços e também Configurações › Serviços › [serviço] › aba Convênios. Nesta última, cada convênio agora mostra a coluna Farol (linha inteira colorida) e a linha ✅ efetiva (descrição, tipo de código, código, Tabela 87 e valor que vai na guia) — igual à aba Serviços do convênio — e também expande.

Clicando na seta da linha, abre (sob demanda) a árvore do serviço naquele convênio, como sai na guia. Colunas, nesta ordem:

Farol · Item tipo (Serviço / Subserviço / Produto / Taxa) · Item nome · Tipo código · Código · Tabela 87 · Zerar valor · Somar itens · Conta no total · Utiliza · Motivo · Unidade de medida · Quantidade · Custo unitário · Receita unitária · Custo total · Receita

• Item que não entra na cobrança aparece esmaecido; a coluna Motivo mostra "Convênio não utiliza", "Zerado em pacote" ou "Subserviço pai fora do total" (seção 6).
• Cada linha tem o próprio farol; a linha do subserviço traz o total da sua subárvore.
• Os números são os mesmos da aba Farol › Itens e da bolinha do Farol (mesma fonte no banco) — nunca recalculados na tela. Alterou valor, Pacote ou Zerar na linha do serviço e salvou → a lista expandida se atualiza sozinha.
• ✅ Novo — 29/09/2026 Tooltip do Farol: passando o mouse na bolinha do Farol de cada linha aparecem margem, receita e custo da linha.
• ✅ Novo — 29/09/2026 Não há linha de total no fim da lista expandida: o total do serviço no convênio é a linha Σ da coluna Valor (3.6.1) — e a linha do próprio serviço, no topo da árvore.
• Carregamento sob demanda e cache das listas: a aba ficou mais rápida.

Uso na implantação: é a forma recomendada de conferir o que a guia vai cobrar e de diagnosticar "por que este serviço está vermelho?" sem filtrar milhares de linhas na aba Farol › Itens. Confira todo pacote montado: os itens inclusos devem aparecer esmaecidos com "Zerado em pacote"; os cobrados à parte, com Conta no total = Sim.

4. Ordem recomendada de configuração

1. Taxas (valor da casa) — vêm antes das tabelas de preço internas e dos convênios, que dependem delas.
2. Produtos (catálogo): aba Estoque → Preço de venda tabela, Fonte de Preço, Fator K, e custo.
3. Serviços simples (preço fixo), depois serviços compostos (abas Produtos, Taxas, Servicos) — cadastre os subserviços antes dos serviços pais. Serviço de medicamento exige o produto já cadastrado.
4. Tabelas precos internos (se a clínica usa tabelas de referência de preço de produto) — depois de Taxas, Produtos e Serviços e antes dos convênios.
5. Convênio › Dados do convênio: Pago no ato do atendimento?, parcelas, Política de Preço por Tipo de Produto. Primeiro passo: abra o convênio e clique em Liberar para edição antes de qualquer alteração, em qualquer aba (convênio recém-criado já abre liberado); ao terminar, Salvar no cabeçalho. A liberação vale só nesta visita — saiu da tela, abriu outro convênio ou recarregou, clique de novo. ✅ Novo — 12/10/2026 Preencha também a Conta de recebimento do convênio (aba Dados), usada no Gerar Contas a Receber do lote. ✅ Novo — 15/10/2026 Se o contrato usar publicações oficiais, o bloco Referências oficiais por tipo de produto fica logo abaixo da Política de preço (opcional, 1ª fase — veja os cuidados).
6. Convênio › aba Especialidades ✅ Novo — 29/09/2026: marque Atende em cada especialidade que o convênio cobre — antes de configurar serviços e colaboradores do convênio, e Salvar. No cadastro do convênio ela já vale (serviço de especialidade não atendida fica "Não atendida" e não aceita Utiliza); no agendamento a trava está desligada desde 06/10/2026 (#628 — veja o aviso).
7. Convênio › abas Produtos / Serviços / Taxas (com a edição liberada — Liberar para edição): Utiliza primeiro; depois valores convertidos; na aba Serviços, a coluna Tipo de Atendimento (3 linhas — escolha na 🔁 o tipo que a operadora exige e confira na ✅); por último Pacote e Zerar valor em pacotes. Passo a passo da aba Serviços para cada serviço:
   1. Preço igual ao da casa → Valor 🔁 vazio. Preço diferente → digite o valor combinado na 🔁 (muda só o preço do serviço).
   2. O contrato diz que esse preço já inclui itens? → marque Pacote na linha do serviço e Zerar valor em pacotes em cada item incluso (abas Produtos, Taxas ou Serviços) — marcar Pacote não liga o Zerar sozinho (desde 25/09/2026). Valor combinado sem Pacote não embute nada — os itens somam por cima.
   3. Itens cobrados à parte → Utiliza ✔ e Zerar ✘.
   4. Salvar no cabeçalho do convênio (as alterações das abas ficam destacadas como pendentes até aqui).
   5. Confira o total: linha Σ da coluna Valor; e, item a item, o painel Expandir serviço (seta da linha).
8. Convênio › aba Custos extras ✅ Novo — 12/10/2026 (se a operadora cobra algo à parte) e, no painel Serviços extras de cada serviço, os prestadores terceiros — grava na hora (2.5).
9. Parâmetros › Valores (régua do Farol): Parâmetro Vermelho (%), Parâmetro Amarelo (%), regras de aprovação por nível — ajuste antes da conferência pelo Farol; os demais parâmetros ficam para o fim da implantação (Parâmetros e Permissões). Em Parâmetros › Orçamento, mantenha Custos extras (convênio, prestadores e repasse) também bloqueiam desmarcado até rodar Ver serviços que mudam de cor.
10. Conferir pelo Farol (seção 6).

Na implantação completa da clínica, esses passos se encaixam na ordem prática oficial: Empresa → Depósito mínimo → Locais e tipos → Operadoras/Fornecedores → Taxas → Produtos (catálogo) → Equipamentos → Serviços (subserviços antes dos pais) → Colaboradores → Convênios (dados, depois abas) → Conferência pelo Farol → Financeiro/Estoque → Pacientes → Parâmetros e Permissões. Ver o Guia de Implantação.

Ferramentas de produtividade nas três abas do convênio (copiar, importar e "selecionar todos" só com a edição liberada; exportar funciona também em modo consulta):

• Copiar (Copiar configurações de outro Convênio) — mostra lado a lado "Atual" × "Origem" antes de copiar e grava na hora (leva também os prestadores; os custos extras têm cópia própria). 🟡 #639 Evite usar para montar um convênio: a correção do Copiar convênio não foi confirmada — se usar, confira tudo depois (Expandir serviço e Histórico).
• Exportar Excel / Importar Excel — o template traz as colunas aceitas. No import de serviços há as colunas Pacote e Zerar Valor Em Pacotes. O import grava na hora.
• Menu ⋮ da coluna Utiliza: Selecionar Todos / Desativar Todos — grava na hora. 🟡 #639 Na aba Serviços, o "Selecionar/Desmarcar todos" só mexe no Utiliza, qualquer que seja a coluna escolhida — para Retorno, Autorização e Pacote, marque linha a linha.
• Com alteração pendente nas abas, essas ações pedem antes: "Há alterações não salvas no convênio. Clique em Salvar (ou descarte em "Bloquear edição") antes de usar esta ação."

5. Impacto em cada módulo

6. Como conferir

1. Convênio › aba Serviços › seta da linha (Expandir serviço) ✅ Novo — 26/09/2026 → forma recomendada: a árvore do serviço como sairá na guia, com farol, custo e receita por item; o que ficou fora vem esmaecido com o Motivo. Também em Serviços › [serviço] › aba Convênios, para ver o mesmo serviço em todos os convênios (3.7).
2. Convênio › aba Farol › Serviços → clique no serviço → sub-aba Itens ✅ por linha desde 24/09/2026: cada linha reflete só ela — valor efetivamente considerado (zero quando fora), custo, receita, margem e farol da própria linha; a linha do serviço traz o total do serviço; a de um subserviço, o total do que está dentro dele. Colunas Receita item, Conta no total, Caminho na árvore. Use esta sub-aba para varrer todos os serviços do convênio; para um serviço específico, o Expandir serviço é mais rápido (mesmos números). O que está com "Conta no total = Não" ficou fora — e o motivo é um destes (no Expandir serviço aparece o rótulo em português):

   Motivo (código)	Rótulo no Expandir serviço	Significado
   NAO_UTILIZA_NO_CONVENIO	Convênio não utiliza	Utiliza desmarcado no item
   ZERADO_EM_PACOTE	Zerado em pacote	Item com Zerar dentro de pacote de preço fechado (em subserviço, só a linha dele)
   PAI_FORA_DO_TOTAL	Subserviço pai fora do total	O item está dentro de um subserviço sem Utiliza (só a falta de Utiliza leva a subárvore)

   Histórico: o motivo PAI_NAO_SOMA_ITENS (pai de preço fixo sem Pacote) deixou de existir em 23/09/2026, quando os itens passaram a entrar sempre. A sub-aba Farol › Serviços, que mostrava "0 registros" para todos os convênios, foi corrigida.
3. Relatórios › Agenda › Validação de Configuração Por Convênio — exporta Valor, Política de Preço, Fator K, Utiliza, Pacote, Zerar Valor.
4. Relatórios › Cadastro › Serviços × Convênios — Farol de Margem — Receita Total, Custo Total, Margem/Resultado %.
5. Orçamento/agendamento de teste › Custos.

7. Diagnóstico rápido

8. Limitações conhecidas (para orientar o cliente)

• Zerar valor em pacotes é por item no convênio: não é possível o mesmo produto ser embutido no pacote A e cobrado à parte no pacote B do mesmo convênio.
• Equipamentos não têm valor: não entram em receita.
• Modo consulta do convênio (#632, em produção desde 29/09): a liberação de edição vale só para a visita atual; não há bloqueio automático por tempo nem registro de quem liberou (decisão do Diretor em 29/09) — mas toda alteração gravada aparece no Histórico (#638). A aba Convênios do colaborador continua editável sem o botão, e a API externa grava normalmente.
• A coluna Atende da aba Especialidades vale no cadastro do convênio, mas não restringe o agendamento nem o orçamento desde 06/10/2026 (trava desligada temporariamente — #628). A consulta de disponibilidade da IA (TalkMe, #633) é a exceção: respeita a coluna Atende.
• #639 (parcial): "Selecionar/Desmarcar todos" da aba Serviços só alterna o Utiliza; "Copiar convênio" sem correção confirmada — evite.
• Serviços extras (prestadores): só valor fixo por execução — percentual de prestador ainda não existe (#655).
• Referências oficiais de produto (#662): 1ª fase em produção desde 15/10, sem carga de preços pela tela (importação retirada) — confirme com o time Rabi (veja).
• O cálculo exibido na tela de cadastro do serviço (soma dos itens) usa preços da casa; o valor por convênio está na aba Serviços do convênio (linha ✅ = valor próprio; linha Σ = total) e na aba Farol.

Continue por aqui: Visão Geral · Guia da Clínica · Guia para IA · Árvore de decisão do cadastro