Tutorial

Tutorial: seu primeiro hash TISS do zero

Versão canônica no repo: docs/TUTORIAL.md. Esta página da wiki é a porta de entrada; o documento no repo é a fonte única de verdade.

Tempo estimado: 15 a 20 min. Nível: iniciante; se você nunca rodou um script Python, este guia é para você. O que você terá ao fim: um programa de 3 linhas que lê um arquivo XML e imprime um hash na tela.

Este é um tutorial: feito para você aprender fazendo, do começo ao fim, na ordem. Cada passo tem o comando exato e o que você deve ver acontecer. Se algo não bater com o esperado, pare e confira o passo anterior antes de seguir.

Para usar a lib de verdade no seu projeto (e nas outras 8 linguagens), veja Como usar. Para os conceitos por trás de tudo isto, veja Conceitos.

Três palavras que você vai ver o tempo todo

• Hash: um código de tamanho fixo calculado a partir de um conteúdo. Uma "impressão digital" do arquivo: muda um caractere, muda o hash inteiro. Aqui sai como 32 caracteres entre 0-9 e a-f (formato hexadecimal, ou "hex"). Exemplo sintético: 3aa0c578c95cdb861a125f480a8a4de5.
• MD5: o nome do algoritmo que produz esse hash. O Padrão TISS exige MD5.
• XML: um formato de arquivo de texto que guarda dados em "etiquetas" (tags) como <nome>João</nome>. A saúde suplementar brasileira troca dados nesse formato, no chamado Padrão TISS.

Os demais termos (parser, namespace, byte, encoding, epílogo, dependência, CLI) aparecem explicados no passo onde forem usados.

1. Instalar o Python

A lib deste tutorial é escrita em Python. Para rodá-la, seu computador precisa ter o Python instalado. Talvez já tenha. Abra o terminal (Linux/macOS: app "Terminal"; Windows: "PowerShell" ou "Prompt de Comando") e digite:

python3 --version

O que esperar: uma linha como Python 3.12.4. O número precisa ser 3.10 ou maior. Se aparecer 3.9 ou menos, ou "comando não encontrado", instale do site oficial: https://www.python.org/downloads/.

Dica para Windows: no instalador, marque "Add Python to PATH" antes de instalar. Sem isso, o terminal não acha o python3. Depois, feche e reabra o terminal e rode python3 --version de novo.

2. Pegar a biblioteca

Uma biblioteca (ou "lib", ou dependência) é código pronto que você reaproveita em vez de escrever do zero. A nossa se chama tiss-hash. Para instalar libs Python existe o pip, que vem junto com o Python.

Antes, crie um ambiente virtual (em inglês virtual environment, abreviado venv): uma "caixa" isolada onde você instala as libs de um projeto sem misturar com o resto do sistema.

python3 -m venv .venv

Ative o venv:

# Linux ou macOS:
source .venv/bin/activate

# Windows (PowerShell):
.venv\Scripts\Activate.ps1

O que esperar: o prompt passa a começar com (.venv). Tudo que o pip instalar daqui pra frente vai pra dentro dessa caixa. (Para sair depois, digite deactivate.)

Agora baixe o código do projeto. Clonar um repositório é copiar todos os arquivos do servidor para a sua máquina, com a ferramenta git:

git clone https://github.com/petrinhu/TISS_ANS_hash.git
cd TISS_ANS_hash/langs/python

Sem git? Baixe em https://git-scm.com/downloads, ou use o botão "Code" no repositório para baixar um .zip e descompactar.

Instale a lib a partir do código baixado:

pip install -e .

O -e significa "editável" (instala apontando para os arquivos baixados). O . é "a pasta atual" (você está em langs/python, que tem a configuração da lib).

O que esperar: linhas de progresso terminando em algo como Successfully installed tiss-hash-0.1.0 defusedxml-.... O defusedxml é a única dependência da lib (proteção de segurança ao ler o XML); o pip a instala sozinho. Confirme:

python3 -c "import tiss_hash; print('ok', tiss_hash.__version__)"

O que esperar: ok 0.1.0. Se aparecer ModuleNotFoundError, confira se o venv está ativo (prompt com (.venv)) e repita o pip install -e ..

3. Criar um XML TISS de exemplo

Agora você vai criar o arquivo de entrada. Usaremos um exemplo mínimo e sintético (inventado, sem dado real de paciente). Antes, dois termos:

• Namespace: um "sobrenome" dado às tags do XML para não confundir tags de origens diferentes. No TISS, as tags levam o prefixo ans:, ligado a um endereço oficial no atributo xmlns:ans="...". É só identificação; você não precisa acessar o endereço.
• Epílogo: a parte final da mensagem TISS, dentro da tag <ans:epilogo>. É onde mora a <ans:hash>, que recebe a impressão digital do conteúdo.

Crie um arquivo lote.xml (qualquer editor serve) com exatamente este conteúdo:

<?xml version="1.0" encoding="ISO-8859-1"?>
<ans:mensagemTISS xmlns:ans="http://www.ans.gov.br/padroes/tiss/schemas">
  <ans:cabecalho>
    <ans:tipoTransacao>ENVIO_LOTE_GUIAS</ans:tipoTransacao>
    <ans:sequencialTransacao>1</ans:sequencialTransacao>
  </ans:cabecalho>
  <ans:epilogo>
    <ans:hash></ans:hash>
  </ans:epilogo>
</ans:mensagemTISS>

O que cada parte faz:

• A primeira linha (<?xml ...?>) é a "ficha técnica": diz que é XML e qual o encoding declarado.
• <ans:mensagemTISS ...> envolve tudo; o xmlns:ans="..." define o namespace.
• <ans:cabecalho> tem dois dados de exemplo.
• <ans:hash></ans:hash> está vazia de propósito: é o espaço reservado do hash. A lib ignora o que estiver aqui dentro e calcula o hash do resto.

Por que a <ans:hash> fica vazia? Porque o hash é calculado sobre todo o conteúdo, exceto o próprio campo de hash (senão seria impossível calcular). A lib zera esse campo internamente. Você pode deixar vazio ou com qualquer lixo dentro: o resultado é o mesmo.

Salve o lote.xml na mesma pasta onde você está no terminal (langs/python).

4. Rodar: calcular o hash

Crie um arquivo meu_hash.py, na mesma pasta, com estas três linhas:

from tiss_hash import hash_tiss_file

digest = hash_tiss_file("lote.xml")
print(digest)

Linha a linha:

1. from tiss_hash import hash_tiss_file traz a função pronta da lib. Função é um pedaço de código com nome que você manda executar.
2. digest = hash_tiss_file("lote.xml") chama a função passando o nome do arquivo; ela lê o XML e devolve o hash, guardado na variável digest.
3. print(digest) mostra o resultado na tela.

Execute (você está usando a CLI, command-line interface, a forma de mandar comandos digitando texto no terminal):

python3 meu_hash.py

O que esperar: uma única linha com 32 caracteres hex, parecida com esta (valor ilustrativo, só para você ver o formato):

3aa0c578c95cdb861a125f480a8a4de5

O hash que você vai ver pode ser diferente deste, porque depende exatamente do conteúdo do seu lote.xml (espaços, quebras de linha, acentos). O valor acima é um hash sintético do projeto, mostrado só como exemplo de formato. O que importa: saiu uma linha com 32 caracteres hex, sem erro. Se foi isso, você calculou seu primeiro hash TISS.

5. Entender o que aconteceu

Em uma frase: a lib leu os bytes do seu XML, juntou em sequência o texto de todas as tags-folha (as que não têm tags-filhas), tratou esse texto como UTF-8 e calculou o MD5 desses bytes, devolvendo 32 caracteres hex. Dois termos que faltavam:

• Byte: a menor unidade de dado do computador (um número de 0 a 255). Um arquivo de texto é, no fundo, uma sequência de bytes.
• Encoding: a regra que diz como cada caractere (por exemplo ç ou ã) vira bytes. A mesma letra acentuada vira bytes diferentes em UTF-8 e em ISO-8859-1, e por isso o encoding muda o hash.

Aqui mora o detalhe mais importante (e a razão deste projeto existir): o manual do TISS sugere ISO-8859-1, mas o hash que a ANS de fato aceita é calculado em UTF-8. A lib já faz a coisa certa nas 9 linguagens; você não decide nada sobre encoding, só passa os bytes do arquivo. A regra exata está no SPEC; o "porquê" conceitual em Conceitos.

6. Erros comuns de iniciante

XML inválido (InvalidTissXml)

Se o conteúdo não for um XML bem-formado (uma tag aberta e não fechada, por exemplo), a lib avisa com o erro InvalidTissXml (o parser, que lê e interpreta o XML, não entende o arquivo). Teste de propósito: troque o conteúdo por <isto-nao-fecha> e rode. Você verá um traceback terminando em tiss_hash._core.InvalidTissXml: .... Conserte o XML (toda tag aberta <x> precisa de uma fechada </x>) e volte ao conteúdo do passo 3.

Arquivo não encontrado

Nome errado ou rodar de uma pasta diferente da do lote.xml gera:

FileNotFoundError: [Errno 2] No such file or directory: 'lote.xml'

Confirme que meu_hash.py e lote.xml estão na mesma pasta e que você roda python3 meu_hash.py de dentro dela. Use ls (Linux/macOS) ou dir (Windows) para conferir.

Encoding: não converta o arquivo "na mão"

Iniciantes às vezes abrem o arquivo como texto e reconvertem antes de passar para a lib. Não faça isso. A lib precisa dos bytes brutos para acertar o encoding internamente. Usando hash_tiss_file("lote.xml") (como aqui) você nem corre esse risco, porque ela mesma abre o arquivo do jeito certo. Detalhe na seção de pegadinhas de Como usar.

Resumo

Você instalou o Python (3.10+), criou um venv, instalou a lib tiss-hash, escreveu um XML TISS mínimo com a <ans:hash> vazia, rodou um script de 3 linhas, obteve 32 caracteres hex e entendeu, em alto nível, o que o algoritmo faz e por que o encoding é UTF-8.

Próximos passos

• Usar a lib de verdade, com receitas práticas e as outras 8 linguagens: Como usar.
• Entender a fundo o conceito e a história do hash do epílogo: Conceitos.
• Tirar dúvidas rápidas e ver o glossário: FAQ.
• Consultar a regra exata do algoritmo: SPEC.