Para validar um XML TISS de graça, use um validador online ou instale a biblioteca tiss com pip install tiss. Confira a estrutura XSD, o hash do epílogo e as regras aplicáveis à operadora. Se o arquivo precisar ficar na sua máquina, rode a biblioteca Python localmente, sem enviar o XML à API.
Solano Todeschini · Voa Health · Fundador, CEO
Acesso remoto: a API e o MCP exigem uma chave da organização para operações fora do sandbox. Crie a chave no painel da organização, com os escopos necessários, e siga a documentação de autenticação. A biblioteca Python continua disponível para processamento local.
Consultar acesso e autenticação no README do tiss.
O que um validador XML TISS online precisa checar?
Um bom validador não se limita a dizer se o arquivo “abre”. Ele separa pelo menos três verificações: estrutura, integridade e regras de negócio. Cada uma responde a uma pergunta diferente e pede uma correção diferente.
Estrutura XSD. O XSD descreve a estrutura XML esperada para uma versão do Padrão TISS: elementos, ordem, tipos, tamanhos e campos obrigatórios. A ANS publica o componente de comunicação, que define as mensagens XML, e seus arquivos de esquema. No pacote consultado do tiss, os XSDs empacotados são das versões 4.02.00 e 4.03.00. O código escolhe a versão declarada no XML, a menos que você informe outra. Se a versão não estiver incluída no pacote, a biblioteca informa que ela não é suportada; não troca o padrão silenciosamente.
O pacote não baixa um XSD novo durante a validação. Ele mantém os arquivos localmente e confere os hashes da proveniência e dos arquivos antes de compilar o esquema. Isso ajuda a detectar um pacote incompleto ou alterado. A versão de comunicação 4.03.00 aparece na página do Padrão TISS da ANS; confira sempre a publicação vigente para o seu fluxo.
Hash do epílogo. O epílogo contém um hash que permite conferir se o conteúdo considerado no cálculo corresponde ao valor declarado. Uma alteração posterior no XML — inclusive uma regravação que mude o conteúdo considerado pelo algoritmo — pode causar divergência. O achado lote.hash_divergente aponta esse problema e tem associação ao código de glosa 5014 no catálogo do projeto. Recalcular o hash só faz sentido depois de concluir as alterações no lote; o cálculo não corrige campos clínicos nem substitui assinatura digital.
Regras de negócio e da operadora. Um XML pode ser estruturalmente correto e ainda assim ter inconsistências de cadastro, autorização, valor, vigência ou contrato. O validador consegue aplicar verificações internas e regras de um pacote da operadora. Isso não transforma a resposta em autorização de pagamento: elegibilidade, cobertura, documentos e análise do retorno pertencem ao processo da operadora.
Erro de schema e glosa não são sinônimos. O primeiro indica que o XML não corresponde ao formato esperado. A glosa é uma mensagem relacionada à cobrança, geralmente registrada no retorno da operadora. Um validador pode antecipar alguns motivos prováveis, mas não prevê toda decisão administrativa nem garante que um lote será aceito.
Como validar um XML TISS no navegador?
Abra o playground TISS, use um exemplo sintético ou cole um XML de teste e solicite a validação. O resultado mostra se o lote passou e lista os achados, com código, descrição e localização no XML quando disponível. Comece pelo primeiro erro estrutural e valide de novo depois da correção; erros posteriores podem depender do campo que faltava.
O playground é o caminho mais curto para uma conferência pontual, sem instalar Python. Ele envia o XML para o endpoint remoto de validação da Voa. Portanto, “usar pelo navegador” não é o mesmo que executar offline. Para testar, prefira os exemplos sintéticos do projeto. Se o XML tiver dados identificáveis, confirme antes se o uso do serviço remoto está aprovado pelas regras da sua instituição.
O tutorial de validação de um lote mostra a sequência com um arquivo de exemplo. Leia os achados como pistas técnicas: confira o campo no XML, a versão do padrão e a orientação da operadora antes de alterar um lote real.
Como validar XML TISS com Python sem enviar o arquivo?
Para manter o processamento local, instale a biblioteca com pip install tiss a partir do PyPI. Ela requer Python 3.10 ou superior. Os exemplos distribuídos pelo pacote são sintéticos; o código abaixo usa lote-com-erros, disponível em src/tiss/examples/.
Saída real do exemplo, no pacote consultado:
validate(xml) verifica o XML recebido e devolve a versão detectada e uma lista de achados. parse_lote(xml) converte o arquivo para o modelo JSON público. check(lote) aplica verificações estruturais e de negócio; se você passar um pacote de regras, ele também considera esse contexto. apply_fixes(lote, relatorio) devolve uma cópia com os patches determinísticos encontrados. Revise o resultado e valide novamente; correção automática não deve inventar dados ausentes.
hash_epilogo(xml) calcula o digest do epílogo conforme a implementação do pacote. No exemplo, ele imprime o valor calculado para o XML sintético, que contém erros. Isso não significa que o arquivo inteiro esteja válido nem que esse valor deva ser aplicado a um lote de produção sem revisão.
O arquivo original continua sob o seu controle. A biblioteca local não envia telemetria durante a validação. Se a integração precisar de um fluxo repetível, use primeiro dados sintéticos e compare o resultado com o exemplo distribuído pelo pacote. O repositório aberto contém o código, os schemas empacotados e os exemplos. A licença do projeto é Apache-2.0. Consulte também a documentação do tiss.
Como conectar Claude Code, Codex ou Cursor pelo MCP?
O MCP permite que um agente de programação chame ferramentas do tiss, como validar um XML e explicar achados. No Claude Code, copie do README o comando claude mcp add --transport http tiss https://tiss-api.voa.health/mcp. O servidor é remoto; a configuração não torna o processamento local.
No Codex, o README orienta a registrar tiss em ~/.codex/config.toml. No Cursor, a configuração usa a chave mcpServers em mcp.json. Consulte as instruções atualizadas em Conectar agentes no README, pois o formato dos clientes pode mudar.
Depois de conectar, peça ao agente que valide o arquivo, explique cada achado e aplique apenas correções determinísticas. Confirme os campos corrigidos e valide novamente antes de enviar. Para testar uma integração, use um XML sintético. O agente e o MCP são dois componentes remotos distintos: verifique as políticas do serviço de IA escolhido e do endpoint antes de fornecer dados identificáveis.
Quais erros aparecem com mais frequência e como corrigir?
Use o código e a localização do achado para ir ao ponto certo. Códigos internos do tiss identificam verificações do pacote; números como 5014, 1818 e 3209 são mensagens da Tabela 38. Eles não significam, por si só, que um validador tenha emitido uma decisão final da operadora.
Achado ou mensagem | Causa provável | Como corrigir |
|---|---|---|
| Campo obrigatório ausente, elemento fora da ordem ou valor incompatível com o tipo esperado pela versão. | Confirme a versão em |
| O hash declarado no epílogo difere do digest calculado. A Tabela 38 descreve 5014 como hash inválido. | Termine as alterações, gere o XML e recalcule o hash com a rotina compatível. Evite editar o arquivo depois do cálculo. |
| Um pacote de regras aponta procedimento que exige autorização prévia e a guia não traz a senha esperada. | Confira a autorização e a senha no registro de origem. Se a informação não existir, solicite-a; não invente um número. |
| O achado local identifica número de guia repetido. Já 3209 descreve cobrança de procedimento ou item assistencial em duplicidade. São verificações diferentes. | Compare guia, código, data, quantidade e item com o atendimento e o retorno. Remova ou corrija apenas a cobrança realmente repetida. |
Os achados internos seguem um catálogo estável e podem incluir fix quando existe patch determinístico. Alguns também associam uma glosa provável; por exemplo, o pacote mapeia lote.hash_divergente para 5014 e regra.exige_autorizacao para 1818. 3209 está no catálogo Tabela 38, mas não é o código interno usado para identificar toda duplicidade. A biblioteca também oferece uma verificação própria para números de guia repetidos.
A Tabela 38 reúne mensagens de glosas, negativas e outras. Confira a descrição do código no catálogo oficial aplicável e no catálogo de achados do projeto. O visualizador FHIR da ANS apresenta a tabela; a versão exibida na página consultada é 202309. O catálogo de glosas empacotado pelo projeto identifica a fonte da versão 202609. A versão consultada importa: compare a publicação oficial pertinente à competência do atendimento.
As regras da operadora mudam o resultado?
Sim. Um pacote JSON pode expressar verificações como campo obrigatório, padrão de valor, combinação proibida, limite de itens e exigência de autorização. O check aplica essas regras ao lote quando recebe o pacote correspondente. O formato e as primitivas estão descritos na documentação de regras por operadora.
No estado consultado do repositório, src/tiss/rules/ contém o pacote 000000.json, identificado como operadora simulada e marcado como não oficial. Ele usa dados sintéticos e serve para demonstrar o mecanismo; não representa as regras contratuais de uma operadora real. O repositório não oferece um pacote pronto para cada operadora.
Para uma conferência real, confirme se a sua instituição possui um pacote publicado e atualizado. Compare a versão e a fonte de cada regra com o contrato, o manual de faturamento e as orientações oficiais da operadora. Regras próprias podem complementar o XSD, mas não substituem o padrão TISS nem decidem cobertura, pagamento ou recurso.
O que acontece com os dados e com a LGPD?
O local onde a validação ocorre muda o fluxo dos dados:
Biblioteca Python local: a validação, o
check, as correções e o cálculo do hash rodam na máquina. O README declara que a biblioteca local permanece offline e não envia telemetria.Playground e API remota: o playground envia o XML ao endpoint
tiss-api.voa.health/v1/validate. Segundo o README do projeto, o serviço não armazena nem registra payloads e não os usa para treinar modelos. A telemetria agregada, quando ativada no serviço, inclui operação, códigos de achados, registro ANS, versão TISS e data; o cliente pode pedir para desligá-la comX-Voa-Telemetry: off.MCP remoto: as chamadas de ferramenta vão ao endpoint remoto. Além disso, o coding agent pode processar o arquivo conforme a configuração e a política do provedor escolhido.
“Não armazenar o payload” não quer dizer que o XML não transite por um serviço externo. Para qualquer fluxo com dados identificáveis, avalie a política da ferramenta, o acesso, o contrato e os procedimentos de privacidade da sua instituição antes do envio. Comece com exemplos sintéticos. Para contexto geral sobre uso de dados, veja também IA na saúde e LGPD; a configuração técnica do validador não substitui uma avaliação jurídica ou de privacidade.
Quais dúvidas aparecem ao validar XML TISS?
Como validar XML TISS online?
Abra o playground, carregue um XML sintético e solicite a validação. O serviço remoto retorna a versão detectada e os achados. Para não enviar o arquivo à API, rode validate localmente com a biblioteca Python.
Existe um validador XML TISS gratuito?
O tiss é publicado sob licença Apache-2.0 e oferece playground, biblioteca Python, API e MCP. Confira as condições e o acesso atuais na documentação; use o modo local se precisar manter o processamento no seu ambiente.
Onde encontrar um XML TISS de exemplo?
O pacote oferece exemplos sintéticos, incluindo lote-valido e lote-com-erros. Em Python, carregue um com examples.load("lote-com-erros"). Não use XML real de paciente como exemplo público.
Como validar o hash TISS?
Use hash_epilogo(xml) para calcular o digest conforme a implementação do pacote. Se o achado for lote.hash_divergente, revise as alterações e recalcule ao final. Um hash compatível não corrige outros erros do lote.
Um XML válido no XSD evita glosa?
Não. O XSD verifica estrutura e tipos. A cobrança ainda pode depender de autorização, contrato, cadastro, elegibilidade, documentação e regras da operadora. A validação não garante pagamento ou aceitação.
Meus dados de paciente são enviados ao validar XML TISS online?
No playground, o XML é enviado à API remota para validação. Na biblioteca executada localmente, a validação não envia o arquivo. Antes de usar dados identificáveis, avalie o fluxo e as políticas aplicáveis; para testes, use os exemplos sintéticos.
Para conferir um lote de teste, abra o playground TISS. Para revisar a implementação e os schemas, acesse o GitHub do tiss.
O mapa de rejeição hospedado é uma coleta separada, opcional e desligada por padrão. Se ativado, envia agregados por prestador, código, regra e mês; confira seu escopo e retenção na documentação. A descrição de payloads e telemetria de validação acima não deve ser estendida a essa coleta.
Conheça o Voa TISS para prestadores e operadoras e consulte a documentação de integração.
Artículos relacionados
