---
name: importacao-questor-plano-saude
description: Guia de manutenção/extensão da ferramenta "Importação de Plano de Saúde" do Portal De Paula (portal_api/planos_saude/, tela importacao-plano-saude.html). Nasceu como processo manual mensal só da TECNOMYL e hoje atende várias empresas/operadoras reais (9 parsers, 13 empresas com regra de custeio cadastrada). Documenta quais operadoras/empresas já estão parametrizadas e validadas com dado real, o que ainda falta pra TECNOMYL rodar 100% pela tela, e como adicionar uma operadora nova. Usar ao dar manutenção nos parsers, ao investigar uma divergência de valores numa importação, ou ao decidir se uma empresa/operadora nova pode ser cadastrada com segurança.
---

# Importação de Plano de Saúde: origem, migração e estado atual

## 0. O que este documento é (e o que não é)

Este SKILL.md documenta **o processo de negócio e sua migração** para dentro do Portal. É o complemento "por quê"/"cuidado com X" da documentação técnica, que já está exaustivamente descrita em `CLAUDE.md` (seção "Importação de Plano de Saúde (Utilitários)"). Antes de tocar em qualquer parser ou regra de custeio, ler os dois: `CLAUDE.md` pra arquitetura (models, endpoints, formato de `custeio_por_tipo`, "Regra empresa", "Vínculos de nome salvos"), este arquivo pra contexto de negócio e para a lista de pontos ainda não confirmados como equivalentes ao processo manual original.

## 1. Origem: processo manual mensal da TECNOMYL

Até a ferramenta existir, a importação de plano de saúde/odontológico da TECNOMYL (código Questor `1778`, operadoras AMIL/Unimed/Bradesco) era feita **à mão, todo mês**, com scripts Python ad-hoc (nunca versionados como projeto, só o protótipo em `Portal/projects/project/` ficou como referência) seguindo um runbook vivo por competência: `Plano de Saúde - TM\MM-AAAA\Memoria_Importacao_Questor.md` (fora deste repositório, só na máquina de quem processava). Esse runbook documenta, com exemplos numéricos reais validados com o cliente:

- Extração AMIL (PDF ou XLSX) por CPF, tipos T/D/A (agregado sempre 100% descontado do empregado, nunca custeado pela empresa).
- Extração Unimed por nome mais teto de R$ 661,61/família (titular e dependentes).
- Extração Bradesco por nome, valores já individualizados por beneficiário.
- Cerca de 30 pares de nome divergente entre operadora e Questor, descobertos e confirmados um a um ao longo de várias competências.
- Checklist de validação e um método de auditoria pós-importação comparando com o relatório `Plano de Saúde - Lançamentos` exportado do próprio Questor.

**Esse runbook por competência continua existindo e sendo o mais atualizado sobre a TECNOMYL especificamente.** Quem for decidir se pode aposentar o processo manual pra essa empresa deve ler a competência mais recente dele antes de qualquer coisa, não só este SKILL.md (que é sobre o processo em geral, não uma cópia congelada dos números de uma competência).

## 2. O que foi migrado para o Portal (`portal_api/planos_saude/`)

A ferramenta hoje é **genérica multi-empresa/multi-operadora** (não é "o robô da TECNOMYL"). TECNOMYL é só mais um `codigo_empresa` (`1778`) entre várias empresas que passam pela mesma tela. O pipeline, os parsers por operadora, o formato de custeio configurável e as regras gerais (nunca aproximar nome automaticamente, valor negativo nunca vai pro CSV final, um mesmo beneficiário pode aparecer em várias linhas/rubricas e precisa ser somado) estão descritos em detalhe no `CLAUDE.md`, não repetir aqui.

Confirmado hoje (rodada em que este documento foi atualizado) que já refletem regras específicas validadas com a TECNOMYL:

- **Teto Unimed de R$ 661,61/família**: migrado como `regra_empresa: unimed_1778_tecnomyl` (`portal_api/planos_saude/regras_empresa.py`), com prioridade dependente primeiro e titular absorve o residual, validado contra o mesmo exemplo do runbook original (Antonio Eduardo Petroni: 361,01 de mensalidade, 224,09 de empresa, 136,92 de desconto).
- **Cadastro de Regras por empresa+operadora** (`RegraCusteioPlanoSaude`): substitui a decisão manual "quem paga o quê" por combinação, configurar uma vez e reaproveitar todo mês.
- **Vínculos de nome salvos (DE/PARA)** (`VinculoNomeOperadora`): substitui a tabela de equivalência estática do runbook por um mecanismo que aprende. Confirmar manualmente uma vez ("Vincular pessoa") e o sistema reaplica sozinho nas competências seguintes. As cerca de 30 equivalências já conhecidas da TECNOMYL (seção 5 do runbook) **não foram pré-carregadas no banco**. Na prática, a primeira competência da TECNOMYL rodada pela tela vai gerar auditoria pra cada uma delas de novo, até serem confirmadas uma vez cada.

## 3. Operadoras e empresas já parametrizadas hoje (fotografia do banco em 25/08/2026)

A ferramenta deixou de ser "a automação da TECNOMYL", hoje atende várias empresas/operadoras reais. Os números abaixo vieram de consultar o banco de produção direto (`RegraCusteioPlanoSaude`/`ImportacaoPlanoSaude`) na rodada em que este documento foi escrito. **É uma fotografia, não um fato permanente**: cresce todo mês, reconsultar antes de confiar nela pra uma decisão importante (`python manage.py shell`, os dois models citados).

### 3.1 Os 9 parsers de operadora existentes: uso real até agora

| Operadora (`pipeline.OPERADORAS`) | Casamento | Importações no banco | Alguma concluída? |
|---|---|---|---|
| `unimed_saude` (5060, CSV ou 2 PDFs) | nome (mensalidade), CPF (coparticipação em PDF) | 8 | Sim (empresas 1123, 221, mais testes antigos) |
| `itamed_saude` (3755) | nome | 11 | Sim (221, 197, 1684, 626) |
| `dental_uni_odonto_mensalidade` (Dental Uni) | nome | 2 | **Não**, as 2 existentes estão em "revisão" |
| `unimed_oeste_pr_saude` (4709) | nome | 3 | Sim, mas de uma execução **anterior** à empresa 1601 hoje cadastrada (a de 1601 está em revisão) |
| `bradesco_saude` (1386) | nome | 1 | Sim (empresa 221) |
| `bradesco_dental_odonto_mensalidade` (3759) | nome | 1 | Sim (empresa 1684). **Ver ressalva abaixo** |
| `unimed_vitoria_saude` (4750) | nome | 1 | Sim (empresa 792) |
| `sulamerica_odonto_mensalidade` (4726) | CPF | 1 | Sim (empresa 792) |
| `amil_odonto_mensalidade` (898) | CPF | **0** | Nunca foi rodada nem uma vez dentro da ferramenta |

**Ressalva sobre a Bradesco Dental (3759):** o `CLAUDE.md` registra que este parser foi escrito só a partir de texto colado numa conversa, nunca confirmado contra o arquivo real. O banco, porém, já tem uma importação **concluída** pra esse operador (empresa 1684), ou seja, alguém rodou um arquivo real depois daquela ressalva ser escrita. "Concluída" só significa que o pipeline processou sem erro e o CSV foi gerado, **não** que os valores foram de fato conferidos linha a linha contra a fatura. Antes de remover a ressalva do `CLAUDE.md`, confirmar com o usuário se essa conferência manual aconteceu.

**AMIL nunca foi usada de verdade na ferramenta.** O parser existe, é o mesmo código portado do protótipo original, mas nenhuma empresa (TECNOMYL inclusive) passou um arquivo AMIL pela tela ainda. É o operador com menos garantia real de estar 100% certo hoje, mesmo sendo o mais simples dos 9.

### 3.2 Empresas com "Cadastro de Regras" salvo (13 empresas, 17 combinações empresa+operadora)

| Cód. empresa | Razão social | Operadora(s) cadastrada(s) |
|---|---|---|
| 92 | PRESCINOTTI & CIA LTDA. | Unimed |
| 129 | SOCIEDADE CIVIL NOSSA SENHORA APARECIDA | Unimed |
| 197 | ENTREGA COMÉRCIO DE MÓVEIS LTDA - EPP | Itamed |
| **221** | ROSSONI, PIOTTO & CIA LTDA | Bradesco Saúde, Unimed e Itamed (**3 operadoras, todas com importação concluída**, melhor empresa de referência hoje pra testar qualquer mudança no pipeline) |
| 626 | MTI SERVIÇOS E COMÉRCIO EXTERIOR LTDA | Itamed |
| 792 | WEITNAUER BRASIL IMPORTADORA E EXPORTADORA DE PERFUMES E COSMÉTICOS LTDA | SulAmérica Odonto e Unimed Vitória |
| 1006 | COPYVIC LOCAÇÃO DE EQUIPAMENTOS LTDA | Itamed |
| 1084 | LUSIA DALA ROSA VOLPATO LTDA | Dental Uni |
| 1123 | VÍDEO UP COMUNICAÇÃO LTDA | Unimed |
| 1601 | LABORATÓRIO DE ANÁLISES CLÍNICAS OSWALDO CRUZ DE MEDIANEIRA LTDA | Unimed Oeste do Paraná |
| 1604 | T & F JOALHEIROS E ACESSÓRIOS LTDA - ME | Itamed |
| 1684 | FRT CONSOLIDADORA LTDA | Itamed e Bradesco Dental |
| 2028 | LAS WINE BAR LTDA | Dental Uni |

**TECNOMYL (1778) não está nesta lista, não tem nenhuma `RegraCusteioPlanoSaude` cadastrada hoje**, nem pra Unimed, nem AMIL, nem Bradesco. Existe um único registro de importação histórico pra ela na tabela `ImportacaoPlanoSaude` (Unimed, com `regra_empresa=unimed_1778_tecnomyl` já setado), mas ficou em status **"revisão"**, nunca chegou a gerar o CSV, e é de antes da separação do "Cadastro de Regras" (não tem `regra_custeio_salva` vinculada). Não apareceria hoje no fluxo atual de "Nova Importação" sem primeiro cadastrar a regra pela tela "Cadastro de Regras". Isto confirma, com dado real, o que a seção 4 abaixo já levanta como suspeita: **a migração da TECNOMYL nunca foi finalizada de ponta a ponta dentro da ferramenta**, nem para a Unimed (que já tem o algoritmo de teto pronto no código).

## 4. Pontos NÃO confirmados como equivalentes (verificar antes de confiar na tela pra TECNOMYL)

Isto é o motivo mais provável pelo qual a TECNOMYL específica ainda pode estar rodando pelo processo manual, mesmo com a ferramenta existindo: as regras abaixo são regras de negócio reais, validadas com o cliente no processo manual, e **não têm evidência de estarem implementadas na ferramenta genérica** (verificado lendo o código dos parsers na rodada em que este documento foi escrito):

1. **AMIL, tipo "A" (agregado) vs. "D" (dependente direto):** o parser genérico (`operadoras/amil/odonto_mensalidade.py`) extrai o tipo (`T`/`D`/`A`), mas o resto do pipeline trata `D` e `A` como o mesmo "dependente" pra efeito de custeio (`matcher._regra_para_pessoa`, ver `CLAUDE.md`). A regra da TECNOMYL exige que **todo tipo A seja 100% descontado do empregado, independente da regra configurada para dependente** (que pra TECNOMYL costuma custear D pela empresa). Rodar a TECNOMYL pela tela sem resolver isso faria um agregado ser custeado pela empresa por engano.
2. **Bradesco, dependente sem linha no modelo do Questor:** regra manual, acumular o valor desse dependente na linha do **titular** (não é regra geral do leiaute, é específica). O `matcher.py` genérico, na ausência dessa regra, deve estar tratando esse caso como "sem cadastro", indo pra auditoria (comportamento padrão do resto do sistema), o que é uma saída **segura** (não lança valor errado, só some do CSV até alguém resolver), mas não é o mesmo resultado do processo manual.
3. **Auditoria pós-importação contra o relatório do Questor** (`Plano de Saúde - Lançamentos - Competência MM/AAAA`): não existe essa feature na ferramenta. Ver seção 6 abaixo pra reproduzir esse método manualmente, se for pedido.
4. **Sistema Contabit** (seção 10 do runbook, formato alternativo de rubricas 338/200/201): fora do escopo da ferramenta, que só gera o leiaute do Questor.

Nenhum desses é motivo pra não usar a ferramenta, são pontos que **quem for migrar a TECNOMYL de vez pra tela precisa resolver primeiro** (ou confirmar que já deixaram de ser relevantes, ex.: se a TECNOMYL não tiver mais nenhum beneficiário tipo A). Até resolver, mais seguro tratar qualquer resultado da tela pra TECNOMYL como "conferir manualmente contra o runbook" antes de subir ao Questor, em vez de confiar de olhos fechados.

## 5. Como adicionar/ajustar um parser de operadora

Ver `CLAUDE.md` (tabela de operadoras registradas, `OperadoraParser.extrai()`, `pipeline.OPERADORAS`) para o mecanismo técnico. Regras de negócio que **nunca devem ser reinterpretadas** sem confirmar de novo com o usuário, válidas pra qualquer operadora nova:

- Nome divergente nunca é resolvido por aproximação automática (fuzzy match). Sempre confirmação humana explícita, mesmo que pareça óbvio.
- Nenhum valor negativo entra no CSV final, vira auditoria, nunca é zerado/truncado silenciosamente.
- Um mesmo beneficiário pode gerar várias linhas/rubricas no arquivo da operadora (mensalidade mais retroativo, por exemplo). Sempre somar por indivíduo antes de decidir o valor final, nunca tratar cada linha isoladamente.
- PDF sem texto selecionável precisa de OCR (`docling`), não `pdfplumber`. Testar `page.chars`/`extract_text()` contra o arquivo real antes de escolher qual usar (ver nota em `operadoras/bradesco/saude.py`).
- Todo parser novo em PDF só deve ser considerado confiável depois de rodado contra o arquivo real (nunca só a partir de texto colado numa conversa). Ver [[feedback_pdf_parser_precisa_arquivo_real]].

## 6. Auditoria pós-importação contra o relatório do Questor (ainda manual)

Se for pedido pra conferir se o que foi gerado bateu com o que ficou lançado no Questor, e a pessoa tiver em mãos o PDF `Plano de Saúde - Lançamentos - Competência MM/AAAA` exportado do próprio sistema:

1. Extrair o texto do PDF (`pdfplumber`) e parsear por bloco de funcionário: linhas `Total Titular`/`Total Dependente <código> - <nome>` (já somam mensalidade e coparticipação daquela pessoa) e `Total Operadora <código> - <nome>`. A linha `Total Operadora` só aparece **depois** dos totais daquele bloco, não antes (bufferizar e atribuir a operadora só quando essa linha aparecer).
2. Recompor o valor esperado por pessoa somando os CSVs de mensalidade e coparticipação já gerados.
3. Cruzar por **nome exato** (os nomes do PDF vêm do próprio Questor, sem precisar de tabela de equivalência aqui, diferente do cruzamento com o arquivo da operadora).
4. Pessoa com `VALOREMPRESA=0` e `VALOR=0` pode não gerar lançamento nenhum no sistema, não é divergência.
5. Confirmar que ninguém da lista de pendências/auditoria aparece lançado no sistema.
6. A linha `Total Empresa` no fim do PDF é o total geral de todas as operadoras, serve de conferência rápida contra a soma dos CSVs antes de entrar no detalhe pessoa a pessoa.

## 7. Onde está o histórico real de competências já processadas

Fora deste repositório, só na máquina de quem processa hoje: `Plano de Saúde - TM\MM-AAAA\` (por competência: `Memoria_Importacao_Questor.md`, os CSVs gerados, `Faltantes_Questor_MM_AAAA.xlsx`, `Auditoria_Importacao_Questor_MM_AAAA.xlsx`). **Isso é uma limitação real pro objetivo de "qualquer contribuidor consegue dar andamento sem precisar desta máquina"**, nada neste SKILL.md substitui esse runbook, só resume o que ele documenta de mais estável. Se for necessário que outra pessoa continue esse processo (manual ou via tela) sem acesso a esta máquina, os arquivos dessa pasta precisam ser trazidos para algum lugar compartilhado (git ou outro), decisão que envolve dados de funcionários reais (nomes, valores), então não fazer isso sem o usuário confirmar onde/como.