4. Árvore de decisão do cadastro no convênio

Nesta página: 1. Visão geral · 2. Tabela-mestra · 3. Árvores passo a passo · 4. Exemplos numéricos · 5. Checklist de conferência · 6. Continue por aqui

1. Visão geral — o sistema decide atributo por atributo

Toda vez que um item vai para uma guia (agendamento, orçamento, autorização, atendimento, pré-faturamento, lote/XML), o RABI monta esse item peça por peça. Para cada peça ele faz a mesma pergunta: "existe um valor específico para este item neste convênio?" — e, se não existir, desce para a regra mais geral.

Equipamentos não têm valor nos preços: não geram receita e não entram na conta do serviço.

Para cada serviço, subserviço, produto e taxa, o sistema decide separadamente:

1. Nome exibido e descrição;
2. Código (TUSS ou próprio) e tipo de código;
3. Tabela 87 (o domínio TISS que diz de que tabela é o item — ex.: 20 medicamentos, 19 materiais, 18 gases, 05 Brasíndice, 12 SIMPRO, 97 Taxa Própria);
4. Tipo de atendimento (só serviço) e parcelas máximas (só serviço);
5. Valor unitário;
6. se o item entra ou não na conta (Utiliza · Pacote · Zerar valor em pacotes);
7. o custo que vai para o Farol.

Desde 24/09/2026 todas as telas do convênio (abas Serviços, Produtos, Taxas e Farol) já mostram esses atributos convertidos — o que você vê na tela é o que vai para a guia.

2. Tabela-mestra: atributo × tipo de item × ordem de precedência

Leia cada célula da esquerda para a direita: o sistema usa o primeiro que estiver preenchido. Nível 3 = o item dentro do convênio (linha azul 🔁 "Convertido"). Nível 2 = política do convênio (só existe para o preço de produto). Catálogo = cadastro do item (nível 1, linha 🔒).

✅ Novo — 15/10/2026 Referências oficiais de produto — 1ª fase (#662): o código, a descrição e o preço do produto podem vir de publicações oficiais (SIMPRO, Brasíndice, CMED, TUSS…) conforme o bloco Referências oficiais por tipo de produto do convênio, na ordem conversão do produto no convênio > referências oficiais > política de preço por tipo de produto > catálogo. Código: item do convênio > código principal da publicação > cadastro. Descrição: item > descrição oficial (se marcado) > cadastro. Preço: item > preço vigente ÷ fator × (1 + ajuste %) (o Fator K do item substitui o ajuste) > política > cadastro. Convênio sem o bloco preenchido segue só a tabela acima. Cuidado: a carga de preços pela tela ainda não está disponível (importação retirada em 15/10) — confirme com o time Rabi. Ver Visão geral.

2.1 A regra de ouro "vazio ≠ zero", atributo por atributo

3. Árvores passo a passo

As árvores abaixo são a mesma regra vista por ângulos diferentes. Todas valem em produção desde 23–24/09/2026.

3.1 Valor do SERVIÇO

SERVIÇO S no convênio C
│
├─ A) VALOR PRÓPRIO (base) — é o que aparece na linha ✅ da aba Serviços
│     e na linha de procedimento do XML
│     ├─ Há valor convertido do serviço no convênio (linha 🔁)?  (0,00 conta como preenchido)
│     │     sim → base = esse valor  (muda SÓ a base — valor combinado NÃO é pacote)
│     │     não → "Definir preço do serviço pelos itens" marcado?
│     │               sim → base = 0  (linha ✅ 0,00; tooltip: "0,00 (sem preço próprio: itens cobrados à parte)")
│     │               não → base = Valor do cadastro do serviço
│
├─ B) ITENS — entram SEMPRE (desde 23/09/2026), cada um com as próprias conversões
│     para cada produto, taxa e subserviço da composição (quantidade q):
│         → passa pela árvore 3.5 (entra / não entra)
│         → se entra: soma q × valor do item (árvores 3.2, 3.3, 3.4)
│
├─ C) É PACOTE DE PREÇO FECHADO?  (decide só se o Zerar dos itens é lido)
│         Pacote marcado no convênio  E  (serviço de preço fixo  OU  valor convertido preenchido, inclusive 0)
│         sim → itens com "Zerar valor em pacotes" ficam fora (já estão no preço)
│         não → Zerar é ignorado; todos os itens com Utiliza entram
│               (inclusive com valor combinado preenchido: sem Pacote, não há pacote)
│
└─ TOTAL DO SERVIÇO = base + Σ itens que entram      → é o que o Farol do serviço usa
                                                        = linha Σ da coluna Valor ("o total") ✅ desde 24/09
                                                        (também no Farol / Expandir serviço)

✅ em produção desde 24/09 Na coluna Valor do serviço, a aba Serviços mostra 4 linhas: 🔒 preço da casa (em serviço que soma itens, a soma dos itens a preço de casa, "(soma dos itens)") · 🔁 valor combinado · ✅ A) valor próprio · Σ o TOTAL DO SERVIÇO. Produtos, taxas e a coluna Tipo de Atendimento seguem com 3 linhas. O total também se lê no Farol do serviço (bolinha), na linha do serviço em Farol › Itens ou no painel Expandir serviço. A explicação do 0,00 aparece ao passar o mouse na linha ✅; um texto visível na própria linha chega no próximo ajuste.

Resumo da tabela-verdade (detalhe no Guia do Implantador):

3.2 Valor de cada PRODUTO dentro do serviço

PRODUTO P no convênio C
│
├─ Há "Valor Unitário" convertido na aba Produtos do convênio (linha 🔁)?  (0,00 conta)
│     sim → valor = Valor Unitário × (1 + Fator K DA MESMA LINHA / 100)
│           (Fator K vazio na linha = sem ajuste; NÃO herda o Fator K da política nem do cadastro)
│     não ↓
│
├─ Monta a regra campo a campo (cada campo desce sozinho, só quando vazio):
│     fonte de preço = linha do convênio → política do convênio p/ o Tipo de Produto (se ativa) → aba Estoque
│     tipo de preço  = linha do convênio → política → aba Estoque          (Preço 1 / 2 / 3 da tabela)
│     Fator K        = linha do convênio → política → aba Estoque → 0
│
├─ Qual é a fonte?
│     nenhuma                    → valor = 0
│     PRECO FIXO CADASTRADO      → Preço de venda tabela (SEM Fator K)
│     PRECO DA ULTIMA COMPRA     → última compra × (1 + Fator K/100)
│     PRECO DA ULTIMA PESQUISA   → preço da última pesquisa × (1 + Fator K/100)
│     PRECO MEDIO DE COMPRA      → preço médio × (1 + Fator K/100)
│     tabela de preços interna   → (valor do produto na tabela, senão Preço de venda tabela, senão 0)
│                                   × (1 + Fator K/100)
│
└─ "Zerar valor em pacotes" NUNCA muda este valor avulso — ele só decide, dentro de um
   pacote de preço fechado, se o produto entra na conta (árvore 3.5)

3.3 Valor de cada TAXA

TAXA T no convênio C
├─ Há valor convertido na aba Taxas do convênio (linha 🔁)?  (0,00 conta)
│     sim → valor = esse valor
│     não → valor = Valor do cadastro da taxa
├─ Sem Fator K, sem política, sem custo (a taxa é receita pura)
└─ Entra na conta?  → árvore 3.5 (Utiliza · pacote fechado + Zerar)

3.4 SUBSERVIÇO (a mesma árvore, de novo, um nível abaixo)

SUBSERVIÇO U dentro do serviço S, no convênio C
│
├─ 1. O convênio Utiliza U?
│       não → U e TUDO que está dentro dele ficam fora (custo conta, receita não).
│             É o ÚNICO corte que desce em cascata.
│
├─ 2. Calcula U com a árvore 3.1: base(U) + itens de U  (recursivo, de baixo para cima)
│       · o "contexto de pacote de preço fechado" de S (ou de qualquer ancestral) DESCE para dentro de U:
│         produto/taxa de U com Zerar marcado fica fora mesmo que U não esteja zerado
│       · se U também for pacote de preço fechado, os itens dele com Zerar também ficam fora
│
├─ 3. U tem "Zerar valor em pacotes" e está dentro de pacote de preço fechado?
│       sim → U perde SÓ a própria base (a linha dele vale 0).
│             Os produtos/taxas de dentro continuam, cada um pelo PRÓPRIO Zerar.
│             (desde 24/09/2026 — antes levava tudo junto)
│       não → U contribui com base(U) + itens de U
│
└─ Subserviço de preço fixo SEM Pacote: contribui com o valor dele + os itens de dentro
   (desde 23/09/2026 — antes o preço fixo "incluía" os itens)

Exemplo curto: pacote fechado de 500,00 contendo o subserviço "Aplicação" (80,00, Zerar ✔),
que contém taxa 40,00 (Zerar ✘) e material 10,00 (Zerar ✔):
      500,00 + 0 (Aplicação zerada) + 40,00 (taxa entra) + 0 (material zerado) = 540,00

3.5 O item ENTRA ou NÃO ENTRA na conta?

1. O convênio Utiliza o item?
      não → FORA (Conta no total = Não · motivo NAO_UTILIZA_NO_CONVENIO)
            subserviço: tudo dentro dele também fora (motivo PAI_FORA_DO_TOTAL)
            orçamento: a linha sai a R$ 0,00 · custo continua no Farol
2. Há pacote de preço fechado acima (o serviço pai ou um ancestral)?
      não → ENTRA  ("Zerar" nem é lido — inclusive em serviço que só soma itens)
3. O PRÓPRIO item tem "Zerar valor em pacotes"?
      não → ENTRA  (cobrado à parte do pacote, quantidade inteira)
4. É subserviço?
      não → FORA (motivo ZERADO_EM_PACOTE) · orçamento: a quantidade da composição sai a R$ 0
            e só o EXCEDENTE (o que passar do previsto) é cobrado
      sim → só a linha do subserviço vale 0; cada item de dentro volta ao passo 1

"Definir preço do serviço pelos itens" não aparece nesta árvore de propósito: desde 23/09/2026 ele decide só o valor próprio do serviço. O motivo antigo "pai de preço fixo que não soma itens" deixou de existir.

Onde ver o resultado desta árvore: no Expandir serviço, o item que ficou FORA aparece esmaecido, com Conta no total = Não e a coluna Motivo com o rótulo do passo que o tirou: "Convênio não utiliza" (passo 1), "Subserviço pai fora do total" (passo 1, dentro de subserviço sem Utiliza) ou "Zerado em pacote" (passo 4).

3.6 Como tudo vira o FAROL

FAROL DE UM ITEM (abas Produtos/Taxas do convênio)
      índice = receita do item ÷ custo do item × 100
      produto: receita = valor convertido (3.2) · custo = aba Estoque
      taxa: só a taxa · produto: só o produto

FAROL DO SERVIÇO (aba Serviços, bolinha da linha ✅; aba Farol › Serviços; relatórios)
      receita = TOTAL do serviço (3.1: base + itens que entram) = linha Σ da coluna Valor
      custo   = Σ custo de TODOS os produtos da árvore (inclusive os que ficaram fora)
              + custos extras do convênio + prestadores + repasse do profissional   ← desde 12/10/2026
                (sem profissional definido: o MAIOR repasse entre quem atende e aceita o convênio)
      índice  = receita ÷ custo × 100

FAROL › ITENS (desde 24/09/2026 — cada linha reflete só ela)
      produto/taxa → valor efetivamente considerado (0 se fora), custo, receita, margem, farol da linha
      subserviço   → total do que está dentro dele
      serviço      → total do serviço (= Farol do serviço)
      coluna "Conta no total": Sim / Não (+ motivo)
      mesmos números no painel Expandir serviço e na bolinha do Farol (mesma fonte no banco)

FAROL CONSOLIDADO (orçamento, agendamento, autorização)
      índice = Σ receita de TODOS os serviços, produtos e taxas
               ÷ Σ custo (produtos + custos extras + prestadores + repasse) × 100
      é ele que bloqueia e que a aprovação por nível de alçada olha;
      com "Custos extras (convênio, prestadores e repasse) também bloqueiam" DESMARCADO (padrão),
      o bloqueio e a alçada usam a cor SEM os custos novos (a cor exibida inclui tudo);
      cada linha mantém a própria cor só para orientar

CORES (Configurações › Parâmetros › aba Valores: Parâmetro Vermelho (%) e Parâmetro Amarelo (%))
      acima do Amarelo → 🟢 · do Vermelho (inclusive) até o Amarelo → 🟡 (pode pedir nível 2)
      abaixo do Vermelho → 🔴 bloqueia (pode ser liberado por nível 3, se a clínica permitir)
      há produto com custo 0 (sem custo cadastrado) → 🟣 roxo (sempre bloqueia)
      custo total = 0 → sem cor   (desde 12/10/2026: serviço sem produto, mas com repasse ou
                                   custo extra, passa a ter cor)

✅ Novo — 12/10/2026 Os custos extras do convênio (aba Custos extras), os prestadores (painel Serviços extras) e o repasse entram só no custo do Farol: não mudam guia, XML, valores cobrados nem o repasse pago. Detalhes e cadastro na Visão Geral.

3.7 Como sai na GUIA / XML

ATENDIMENTO → congela, no momento em que o serviço entra: valor do cadastro do serviço, valor convertido,
              código, tipo de código, tabela 87, nome, tipo de atendimento e a conversão de cada produto/taxa
              (mudar o cadastro depois não altera atendimentos já criados)

PRÉ-FATURAMENTO → trabalha sobre o congelado; "Atualizar Valores em Massa" refaz pela mesma cadeia
                  (valor específico do convênio respeitado mesmo se 0; vazio → cadastro); lote fechado não recalcula

XML TISS (Administrar Lotes › Baixar XML)
├─ Linha de PROCEDIMENTO (o serviço)
│     valor         = valor PRÓPRIO do serviço (congelado) × quantidade      ← igual à linha ✅ da aba Serviços
│     código        = código no convênio → código do convênio → código do cadastro → TUSS
│     tabela 87     = convênio → cadastro
│     tipoAtendimento = tipo de atendimento do convênio → cadastro do serviço
├─ PRODUTOS → nas áreas deles, agrupados pela tabela 87 (20/05 medicamentos · 19/00 materiais · 18 gases),
│             cada um com valor, código e nome convertidos
├─ TAXAS    → na área de taxas, com valor, código e nome convertidos
└─ Fora do XML: itens anulados no pré-faturamento e guias filhas (só a guia mãe entra)

Quem SOMA tudo é o Farol (e a linha Σ da coluna Valor, em produção desde 24/09);
a linha de procedimento do XML NÃO soma produtos e taxas.

3.8 Onde conferir cada decisão — o painel Expandir serviço ✅ Novo — 26/09/2026

Concluído em 25/09/2026 (#625). Clique na seta da linha do serviço em Configurações › Convênios › [convênio] › aba Serviços — ou em Configurações › Serviços › [serviço] › aba Convênios, que agora mostra, por convênio, o Farol (linha inteira colorida) e a linha ✅ efetiva (descrição, tipo de código, código, Tabela 87 e valor que vai na guia). Abre a árvore do serviço naquele convênio, como sai na guia, com os mesmos números da aba Farol › Itens e da bolinha do Farol. Cada decisão desta página tem a sua coluna:

É a forma mais rápida de responder "o que a guia vai cobrar?" e "por que este serviço está vermelho?" — sem filtrar milhares de linhas na aba Farol › Itens. Alterou valor, Pacote ou Zerar na linha do serviço e salvou? A lista expandida se atualiza sozinha. ✅ Novo — 29/09/2026 Passando o mouse na bolinha do Farol de cada linha aparecem a margem, a receita e o custo; não há linha de total no fim da lista — o total do serviço é a linha Σ da coluna Valor (e a linha do próprio serviço, no topo da árvore). O tipo de atendimento não é coluna do painel — confira-o na coluna Tipo de Atendimento da aba Serviços (linhas 🔁/✅).

4. Exemplos numéricos completos

Nomes, códigos e valores dos exemplos 4.1 e 4.2 são ilustrativos. O exemplo 4.3 é um caso real. Farol na régua padrão (Parâmetro Vermelho 100 · Amarelo 120).

4.1 Serviço simples — Consulta no Particular e no Convênio Alfa

Cadastro: "Consulta" · Valor 300,00 · código TUSS 10101012 · "Definir preço do serviço pelos itens" desmarcada · sem composição.
Particular (Pago no ato): Utiliza ✔, nada digitado na linha 🔁. Convênio Alfa: Utiliza ✔, Valor 🔁 180,00, nome de conversão 🔁 CONSULTA ELETIVA, código 🔁 vazio, tipo de atendimento 🔁 escolhido para o Alfa.

Tipo de atendimento: no Particular, o do cadastro; no Alfa, o escolhido na linha 🔁 (vai para o atendimento, o pré-faturamento e o tipoAtendimento do XML). Linha ✅ da aba Serviços: 300,00 e 180,00 — igual à linha de procedimento do XML. Sem itens na composição, a linha Σ mostra o mesmo número.

* Desde 12/10/2026, se o profissional tem repasse cadastrado (ou o convênio tem custo extra), o custo deixa de ser zero e a Consulta passa a ter cor no Farol. Ex.: repasse de R$ 120,00 no Alfa → 180 ÷ 120 = 150% → 🟢 na régua 100/120. Sem profissional escolhido, vale o maior repasse entre quem atende.

4.2 Serviço composto com produto e taxa, SEM Pacote — Convênio Beta

Cadastro: "Aplicação de medicamento X" · Valor 100,00 · soma itens ✘ · composição: Medicamento X (1), Seringa (1), Soro (1), Taxa de sala (1).
Convênio Beta: serviço com Utiliza ✔, Pacote ✘, Valor 🔁 90,00. Política de Preço por Tipo de Produto: Medicamento → tabela interna, Preço 1, Fator K 10.

• Linha ✅ da aba Serviços = 90,00 (valor próprio). O Farol do serviço e a linha do serviço em Farol › Itens mostram 182,00 — que é o total, o número da linha Σ da coluna Valor (em produção desde 24/09).
• Valor combinado não é pacote: os 90,00 digitados na linha 🔁 são só o preço do serviço — por isso os itens somam por cima. É a regra vigente.
• XML: procedimento 90,00 · medicamento 55,00 (área de medicamentos) · seringa 2,00 (materiais) · taxa de sala 35,00 (taxas). O soro não é cobrado.
• Orçamento: 90,00 + 55,00 + 2,00 + 35,00 + soro a R$ 0,00 = 182,00 (quantidades inteiras).
• Antes de 23/09/2026 (histórico): por ser preço fixo sem Pacote, os itens não entravam — Farol com receita 90,00; orçamento cobrava 90,00 + só o excedente.
• Desde 12/10/2026: o custo de 33,50 acima considera só os produtos. Se o Beta tiver custo extra (ex.: 5% da receita = 9,10) e o profissional repasse (ex.: 50,00), o custo vai a 92,60 → 182,00 ÷ 92,60 ≈ 197% → continua 🟢, mas com margem bem menor. Os valores cobrados não mudam.

Variante — o contrato diz que os 90,00 já incluem seringa e taxa de sala: o valor combinado sozinho não resolve; no Beta, marque Pacote no serviço e Zerar valor em pacotes na seringa e na taxa (o medicamento fica com Zerar ✘). Resultado: 90,00 + 55,00 = 145,00 de receita (linha Σ = 145,00; linha ✅ continua 90,00); custo continua 33,50 → 🟢 433%. No orçamento, a quantidade prevista de seringa e taxa sai a R$ 0,00 e só o excedente é cobrado. Ver a Receita I.

4.3 Caso real — "Noripurum aplicado EV" no Bradesco (antes × depois)

Configuração: serviço com Pacote ✔ e valor combinado 0,01 no Bradesco (pacote de preço fechado — o 0,01 é intencional e foi mantido). Dentro dele, o subserviço "Aplicação endovenosa promocional" com Zerar valor em pacotes ✔; dentro do subserviço, 10 materiais e 5 taxas — entre elas a Taxa de sala de R$ 73,99, sem Zerar.

"≥ 90,02" = 16,03 + 73,99, considerando que a taxa de sala é o único item do subserviço sem Zerar, como no caso relatado; qualquer outro item de dentro sem Zerar também entra. A guia já cobrava a taxa de sala — agora o Farol concorda com a guia. Se a taxa estivesse incluída no pacote, o certo seria marcar Zerar na própria taxa.

5. Checklist de conferência para o implantador

Para cada convênio, depois de configurar (ordem: Especialidades (Atende) → Utiliza → valores convertidos → textos/códigos → tipo de atendimento → Pacote e Zerar → Custos extras — sempre Liberar para edição → alterar → Salvar no cabeçalho). Na conferência, deixe o convênio em modo consulta (é como ele abre; nada é gravado) — se acabou de configurar, clique em Bloquear edição antes de conferir:

6. Continue por aqui

• Visão Geral — a ideia em uma página.
• Guia da Clínica — receitas prontas "quero cobrar assim, como configuro?" e a aba Farol › Itens em linguagem simples.
• Guia do Implantador — tela por tela, tabela-verdade completa, diagnóstico.
• Guia para IA — algoritmo recursivo, invariantes e casos de teste T1–T26.