Para calcular o hash do epílogo TISS com tiss, carregue um XML sintético e chame hash_epilogo(xml). A função retorna o digest MD5 hexadecimal conforme a implementação do pacote, usando os textos folha do XML e codificação ISO-8859-1. Depois de alterar campos, calcule novamente o digest e valide o lote.
O que é o hash do epílogo TISS?
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 epílogo é uma parte da mensagem TISS que contém um campo hash. Ele registra um digest calculado sobre o conteúdo do XML. A ANS descreve no Componente Organizacional o uso de hash MD5 no padrão. A função pública hash_epilogo do pacote tiss calcula um valor hexadecimal a partir do XML fornecido.
Um hash permite comparar o resultado calculado com o valor escrito na mensagem. Se o conteúdo coberto mudar sem a atualização do epílogo, a comparação pode acusar divergência. Por isso, o hash é sensível ao conteúdo e à forma como ele é codificado. Uma diferença de codificação, um campo alterado, um texto em branco ou um valor acrescentado podem resultar em outro digest.
Hash não é criptografia reversível e não revela os dados originais. Também não substitui assinatura digital, autenticação, autorização do procedimento, verificação de cobertura ou auditoria da cobrança. Sua função é detectar divergências entre o conteúdo considerado no cálculo e o valor armazenado no epílogo.
O que a ANS descreve sobre o algoritmo?
O Componente Organizacional do Padrão TISS identifica a função como MD5 e descreve a geração do valor do epílogo com codificação ISO-8859-1. Consulte a seção “HASH MD-5” na versão organizacional publicada pela ANS para conferir a descrição oficial vigente. Não confunda esse campo do epílogo com o MD5 usado em outros pontos de sistemas, por exemplo, para senha.
Na implementação do pacote tiss disponível no commit consultado, hash_epilogo(xml) faz parse do XML, seleciona os elementos folha considerados no cálculo, concatena seus textos na ordem do documento, codifica o resultado em ISO-8859-1 e calcula MD5. A função retorna o digest em hexadecimal. A regra exata de quais textos entram vem do código; veja _hash_leaves em _lote_codec.py.
Essa distinção é importante. O algoritmo criptográfico é MD5; a entrada do algoritmo é determinada pela regra de serialização do conteúdo que será resumido. Espaços, caracteres, ordem e codificação podem alterar o digest. Não calcule o MD5 do arquivo inteiro, dos bytes do XML serializado, nem de uma sequência inventada sem comparar com a especificação e com a implementação usada na integração.
O pacote não apresenta o digest como garantia de autenticidade. Se alguém modifica o conteúdo e recalcula o hash, o novo digest pode corresponder ao novo conteúdo. Portanto, a validação do hash identifica divergência, não prova quem produziu a mensagem nem torna o conteúdo confiável por si só.
Como calcular o hash com Python?
Instale a biblioteca com pip install tiss. O código a seguir usa um exemplo sintético incluído no pacote e imprime o hash calculado:
Saída executada no snapshot do produto:
O exemplo escolhido tem achados propositais e é apenas um teste técnico. A saída mostra o digest que essa versão do pacote calcula para os bytes carregados. Ela não afirma que o XML seja aceito por um plano de saúde ou que esteja pronto para faturamento.
Se o conteúdo for uma string Python, a função a codifica como ISO-8859-1. Se for bytes, o pacote faz o parse dos bytes diretamente. Isso importa quando o XML tem caracteres acentuados: evite converter para UTF-8 de forma silenciosa antes do cálculo ou alterar o cabeçalho de encoding sem atualizar os bytes e validar o resultado.
Para gerar um lote de teste válido, use o builder público e o conjunto de exemplos, em vez de montar manualmente valores de hash. A biblioteca expõe build_lote para gerar um XML TISS e inclui dados sintéticos em tiss.examples. Se você altera o XML após gerar o lote, recalcule e valide novamente; a saída do builder não mantém o hash correto depois de mudanças posteriores.
Como validar o hash gravado no XML?
Calcular o digest e conferir se o campo existente corresponde a ele são operações relacionadas, mas diferentes. hash_epilogo(xml) retorna o digest calculado; validate(xml) verifica a estrutura e aponta o achado lote.hash_divergente quando o hash do epílogo não corresponde ao cálculo implementado.
Uma sequência segura de trabalho é:
Preserve o arquivo original e trabalhe em uma cópia sintética ou controlada.
Valide o XML para identificar problemas de schema, hash e demais regras.
Corrija os campos na origem do dado ou no fluxo aprovado.
Recalcule o hash depois de todas as alterações.
Grave o digest no epílogo pelo builder ou mecanismo validado.
Execute a validação novamente e revise todos os achados.
Não atualize o hash primeiro e continue alterando os dados depois. Qualquer valor coberto pelo cálculo pode mudar o resultado. Tampouco substitua o conteúdo do epílogo sem saber qual versão ou processo gerou o XML: o receptor pode usar uma implementação ou versão diferente do padrão.
O achado lote.hash_divergente é um código técnico interno do relatório do tiss. A Tabela 38 da ANS descreve o código 5014 como “CÓDIGO HASH INVÁLIDO. MENSAGEM PODE ESTAR CORROMPIDA”. O código de catálogo e o identificador de achado do pacote pertencem a camadas distintas; o validador não transforma automaticamente um erro em glosa aplicada.
Quais erros de hash aparecem com frequência?
Os problemas mais comuns são a alteração do XML depois do cálculo, uso de bytes com codificação diferente, leitura de uma versão antiga do campo hash, inclusão de dados parciais ou geração do digest com regras de concatenação diferentes.
Sinal | Causa possível | Próxima verificação |
|---|---|---|
| O conteúdo mudou após o cálculo ou o digest veio de outro procedimento. | Compare o XML de entrada com a fonte de dados e recalcule ao final. |
Código 5014 no demonstrativo | A Tabela 38 descreve hash inválido e possibilidade de mensagem corrompida. | Revalide o arquivo transmitido e a resposta recebida; consulte a justificativa do destinatário. |
O mesmo conteúdo gera outro valor em dois sistemas | Codificação ou regra de seleção/concatenação pode divergir. | Confirme bytes, encoding, versão e algoritmo de ambos os lados. |
Erro de parse antes do hash | XML malformado ou bytes incompatíveis com o cabeçalho. | Corrija a sintaxe e o encoding antes de recalcular. |
Não conclua que toda glosa 5014 foi causada pelo método hash_epilogo do seu sistema. O código na tabela é uma descrição padronizada. A investigação precisa do arquivo efetivamente transmitido, do relatório técnico e do canal usado.
Se o XML passou pelo XSD e o hash diverge, isso não é contraditório: o XSD descreve estrutura e tipos, e o digest confere integridade do conteúdo selecionado. Da mesma forma, um hash compatível não torna o XML válido no schema. Trate cada camada separadamente.
Posso corrigir o hash automaticamente?
O pacote fornece um cálculo determinístico para o conteúdo informado, mas o uso de correção deve respeitar o processo que gera a mensagem. Primeiro defina a fonte de verdade dos dados; depois corrija campos e gere o XML final. Alterar o valor do hash para “fazer o erro sumir” sem verificar o conteúdo pode mascarar uma alteração indevida ou uma conversão de caracteres.
Uma correção segura não significa substituir automaticamente cada digest encontrado. Ela significa executar um fluxo conhecido: gerar ou reconstruir a mensagem a partir dos dados validados, atualizar o epílogo e rodar as verificações novamente. Conserve logs técnicos mínimos necessários à rastreabilidade sem expor XML com dados de pacientes em registros ou exemplos públicos.
Se a biblioteca indicar que um texto não pode ser codificado em ISO-8859-1, não descarte acentos nem transforme o texto sem validação clínica e administrativa. Procure o sistema de origem e a norma técnica aplicável. A função lança um erro quando encontra caracteres que não pode codificar segundo a regra implementada.
Como o hash se relaciona com o XML TISS 4.03.00?
O hash do epílogo não substitui a validação pelo XSD da versão. O tiss declara suporte a schemas TISS 4.02.00 e 4.03.00 no snapshot consultado. A versão selecionada pode influenciar a validação estrutural, mas o procedimento de cálculo do digest continua sendo uma função específica.
Em uma migração, teste os arquivos produzidos pela sua integração com amostras sintéticas para cada tipo de mensagem. Compare o digest calculado pela implementação local com a validação completa. Não use um único XML de teste para presumir compatibilidade de todos os canais, componentes ou versões.
Para entender o restante da mensagem, comece pelo pilar do Padrão TISS 4.03.00. Ele explica a combinação entre componentes, XSD e vigência. Para erros de lote, veja também o artigo sobre validação de XML TISS e a referência da Tabela 38 da ANS.
Quais dúvidas aparecem sobre o hash TISS?
Como calcular hash TISS?
No tiss, instale o pacote e chame hash_epilogo(xml). A função retorna o digest calculado pela implementação do pacote. Para validar o XML completo, use também validate(xml) e analise o relatório.
O hash TISS é MD5?
O Componente Organizacional da ANS descreve a seção do hash como MD5. A implementação consultada calcula MD5 hexadecimal a partir de textos de elementos folha codificados em ISO-8859-1. Confira a versão da norma e do pacote usadas na integração.
Como validar o hash do XML TISS?
Use a função pública validate(xml) para receber o relatório da validação e procure o achado lote.hash_divergente. hash_epilogo(xml) calcula um digest, mas não valida sozinho o restante da estrutura ou das regras do lote.
O que significa o código 5014?
Na Tabela 38, 5014 identifica “código hash inválido; mensagem pode estar corrompida”. Ele é um código de tabela, não o mesmo que o nome interno lote.hash_divergente. Revise o XML transmitido e a justificativa do destinatário.
Um hash válido prova que o XML não foi alterado?
O hash permite comparar o conteúdo calculado com o digest. Ele não autentica o remetente nem prova que o conteúdo seja verdadeiro. Uma alteração seguida de novo cálculo gera outro digest compatível com aquele novo conteúdo.
Posso fazer hash TISS online?
O playground é um serviço remoto: o XML é enviado à API para processamento. Se precisar manter o arquivo no seu ambiente, instale a biblioteca Python e execute hash_epilogo localmente com dados sintéticos ou sob os controles da sua organização.
Onde calcular e consultar o código?
Consulte o código e a licença no GitHub do tiss, instale a biblioteca no PyPI ou leia o tutorial de validação. Para navegar pelo contexto das versões, abra o pilar TISS 4.03.00, a página de validação XML e a explicação da Tabela 38.
Autor: Solano Todeschini · Voa Health · Fundador, CEO
Conheça o Voa TISS para prestadores e operadoras e consulte a documentação de integração.
Artículos relacionados
