portal_publico/.claude/skills/importacao-questor-plano-saude/SKILL.md

name

description

importacao-questor-plano-saude

Guia da etapa final específica do Questor na ferramenta "Importação de Plano de Saúde" do Portal De Paula (portal_api/planos_saude/) — como os dados já extraídos/validados (ver skill geral `importacao-plano-saude` primeiro) viram um Cadastro de Regras de custeio por empresa+operadora, a planilha padrão via SQL do Questor, e o CSV/ZIP final no leiaute do Questor. Documenta também como auditar manualmente uma importação já concluída contra o relatório de lançamentos do próprio Questor. Usar depois de já saber que o sistema contábil de destino é o Questor — pra extração do arquivo da operadora e regras de negócio genéricas (custeio, nome divergente), ver a skill geral primeiro.

Importação de Plano de Saúde → Questor: estruturação e leiaute final

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

Este SKILL.md documenta a etapa específica do Questor: como a informação já extraída do arquivo da operadora e já com as regras de negócio de custeio aplicadas (ver skill importacao-plano-saude — leitura e regras de negócio genéricas, sempre o ponto de partida) vira, de fato, um lançamento no leiaute de importação do Questor. Complementa CLAUDE.md (models, endpoints, formato de custeio_por_tipo, seção "Planilha padrão via Questor (SQL)") com o "por quê"/"cuidado com X" desta etapa.

Se a tarefa é adicionar/ajustar um parser de operadora (extração de um arquivo novo, casamento, regra de custeio negociada): pare aqui, esta skill não cobre isso. Carregar importacao-plano-saude (seção 4 — checklist e regras de negócio) antes de escrever qualquer código ou fazer qualquer pergunta ao usuário sobre o arquivo-modelo. Esta skill só entra depois que o parser já existe e a extração/casamento já estão certos — ela é sobre Cadastro de Regras, planilha padrão e leiaute final, não sobre ler o arquivo da operadora.

Hoje o Questor é o único sistema contábil de destino implementado — se em algum momento surgir uma importação com destino Contabit, não usar este guia pra estruturar a saída; ele ainda não foi implementado (ver gap 3 na skill geral).

1. Empresas com "Cadastro de Regras" salvo (consultar ao vivo, não uma lista fixa aqui)

Essa lista é dado puro do banco (codigo_empresa/razao social/operadora de RegraCusteioPlanoSaude), sem nenhuma análise em cima — mantê-la fixa aqui só garante que fique desatualizada a cada empresa nova cadastrada pela tela "Cadastro de Regras". Consultar direto quando precisar:

RegraCusteioPlanoSaude.objects.order_by("codigo_empresa").values_list("codigo_empresa", "nome")

Único ponto que não é só dado de banco: a empresa 221 (ROSSONI, PIOTTO & CIA LTDA) tem as 3 operadoras (Bradesco Saúde, Unimed e Itamed) com importação concluída — é a melhor empresa de referência hoje pra testar qualquer mudança no pipeline, exatamente por cobrir três parsers diferentes já validados.

2. Cadastro de Regras — por que vive aqui, não na skill geral

"Cadastro de Regras" por empresa+operadora (RegraCusteioPlanoSaude): decide "quem paga o quê" (empresa/empregado/regra específica) uma vez, reaproveitado todo mês em vez de decidido de novo a cada competência — mecanismo descrito em detalhe no CLAUDE.md. A decisão de custeio em si (quem paga quanto) é uma regra de negócio genérica, mas o cadastro dela nasce amarrado ao Questor de fato: codigo_empresa e codigo_operadora são resolvidos contra o banco de lá (portal_api/empresas_questor.py, resolve_nome_empresa(), ver "Nome da empresa (Questor)" no CLAUDE.md), e é essa combinação que restringe quais operadoras aparecem disponíveis pra uma empresa em "Nova Importação". Por isso o cadastro em si — ao contrário de "Regra empresa"/"Vínculos de nome" (skill geral), que não dependem de nenhum cadastro externo — fica documentado aqui.

Nenhuma empresa aparece no combobox de "Nova Importação" sem já ter uma regra cadastrada — cadastrar/editar uma regra pra uma empresa nova é sempre um passo anterior, feito em "Cadastro de Regras" (tela separada da execução, ver CLAUDE.md).

3. Gap conhecido: sem auditoria automática pós-importação

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 4 pra reproduzir esse método manualmente, se for pedido.

4. 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.