voa-health/tiss

Valide, corrija e gere lotes TISS, entenda glosas e concilie demonstrativos, tudo em código aberto: uma biblioteca Python que roda offline, uma API HTTP e um MCP remoto para o seu agente de IA.

Tip

Usa Claude Code, Codex ou Cursor? Conecte o MCP e peça em português, por exemplo "valide este lote e corrija o que der". Veja Conectar agentes.

Início rápido

pip install tiss

from tiss import examples, validate

report = validate(examples.load("lote-com-erros"))
[(finding.code, finding.severity) for finding in report.findings]

Cada achado traz um código estável, a localização e, quando possível, a correção pronta. Requer Python 3.10+.

Prefere testar no navegador? Abra o playground.

CLI

Instale a CLI com pip install tiss ou execute sem instalar com uvx tiss validate lote.xml.

Os códigos de saída são 0 para sucesso, 1 para achados ou itens não encontrados e 2 para uso inválido ou entrada ilegível. Para integração com GitHub Actions, use tiss validate --format github lote.xml.

Para quem é

Como funciona

Você não precisa escrever XML TISS à mão. O ciclo é sempre o mesmo:

1. Valide o lote com check ou validate.
2. Corrija com apply_fixes: as correções são determinísticas, em JSON Patch.
3. Revalide até zerar os erros. Se faltar algum dado, needs diz exatamente qual perguntar.
4. Gere o XML com build_lote e calcule o hash do epílogo com hash_epilogo.

Depois do envio, parse_demonstrativo lê o retorno da operadora, glosa explica cada código da Tabela 38 e plan_reconciliation concilia o que foi pago com o que foi cobrado. Para testar sem operadora real, use a operadora simulada.

O que vem no pacote

• Biblioteca Python: validação, correção, geração, hash, auditoria, demonstrativos, TUSS, operadoras, rede hospitalar e referência D-TISS.
• API HTTP: as mesmas operações em https://tiss-api.voa.health, com OpenAPI.
• MCP remoto: 25 ferramentas e 3 prompts para agentes, no registro oficial de MCP.
• Operadora simulada: envie lotes e receba protocolo, demonstrativo e glosas sem tocar em produção.
• Agente faturista: um agente completo para adaptar ao seu fluxo.
• TISS-Bench: 40 tarefas sintéticas para medir agentes com e sem o MCP.

Por que confiar

• Offline e determinístico: validar, corrigir e gerar roda na sua máquina, sem telemetria; a mesma entrada dá sempre a mesma saída.
• XSD fixado por hash: a validação usa o esquema TISS oficial, conferido por hash.
• À prova de prompt injection: texto livre da guia é dado, nunca instrução.
• Seus dados não ficam com a gente: veja a política de payloads e telemetria em API HTTP.
• Medido: no TISS-Bench, com quatro modelos, o acerto médio subiu de 58% sem o MCP para 81% com ele. Gerar um lote do zero ainda fica em 16% nos dois modos.

Conectar agentes

O MCP local roda offline e mantém as guias na máquina:

claude mcp add tiss -- uvx --from "tiss[mcp]" tiss mcp

Para usar o serviço remoto:

claude mcp add --transport http tiss https://tiss-api.voa.health/mcp

Agentes encontram instruções em AGENTS.md e na skill tiss.

Skill, plugins, Codex e Cursor

Ver detalhes

npx skills add Voa-Health/tiss
claude plugin marketplace add Voa-Health/tiss && claude plugin install tiss@tiss
codex plugin marketplace add Voa-Health/tiss

No Codex, adicione a ~/.codex/config.toml para o MCP local:

[mcp_servers.tiss]
command = "uvx"
args = ["--from", "tiss[mcp]", "tiss", "mcp"]

Para usar o serviço remoto:

[mcp_servers.tiss]
url = "https://tiss-api.voa.health/mcp"

No Cursor, adicione ao mcp.json para o MCP local:

{
  "mcpServers": {
    "tiss": {
      "command": "uvx",
      "args": ["--from", "tiss[mcp]", "tiss", "mcp"]
    }
  }
}

Para usar o serviço remoto:

{
  "mcpServers": {
    "tiss": {
      "url": "https://tiss-api.voa.health/mcp"
    }
  }
}

Privacidade

CLI, MCP local, Action e hook rodam na sua máquina ou runner, sem chave, registro de uso ou telemetria. As chamadas de rede do pacote são feitas apenas por ferramentas rede/D-TISS, que baixam dados públicos, e sandbox_*, que usam a operadora simulada.

CI e pre-commit

Use a Action para validar lotes no GitHub Actions:

- uses: Voa-Health/tiss@v0
  with:
    paths: lotes/

O input opcional operadora aplica as regras locais dessa operadora. Para instalar o hook, adicione ao .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Voa-Health/tiss
    rev: v0.4.0
    hooks:
      - id: tiss-validate

Sem assets opcionais

A Action e o hook instalam apenas tiss (com lxml) e validam com os XSD 4.02.00 e 4.03.00 incluídos no pacote. Não instalam pdf nem baixam dados de rede/D-TISS; fora o download do pacote, nada vai à rede. operadora aplica apenas regras incluídas no pacote. O hook seleciona arquivos .xml; limite-o com files: se o repositório tiver outros XML.

Tutoriais

API HTTP

Servidor local, chaves e telemetria

Ver detalhes

Instale o extra do servidor e inicie a API local:

pip install "tiss[server]"
tiss serve --host 127.0.0.1 --port 8000

Valide XML como JSON ou como corpo XML:

python -c 'import json, pathlib; print(json.dumps({"xml": pathlib.Path("lote.xml").read_text()}))' \
  | curl https://tiss-api.voa.health/v1/validate \
  -H 'Content-Type: application/json' \
  --data-binary @-
curl https://tiss-api.voa.health/v1/validate \
  -H 'Content-Type: application/xml' \
  --data-binary @lote.xml

Consulte o OpenAPI e o catálogo de operações.

Sem chave, só as operações do sandbox respondem. Para as demais, crie a chave sk_voa_ da organização, que vale para os produtos da Voa, no painel da organização e envie-a em Authorization: Bearer. Não há limite diário.

curl https://tiss-api.voa.health/v1/validate \
  -H "Authorization: Bearer $TISS_API_KEY" \
  -H 'Content-Type: application/xml' \
  --data-binary @lote.xml

Chave inválida ou revogada retorna 401, e a revogação vale em até 60 segundos. Chave sem o escopo da operação (tiss:validate, tiss:build, tiss:sandbox, tiss:accounts, tiss:authorization ou tiss:rules) retorna 403. Cada chamada com chave entra no uso da organização, por operação e por chave. Auto-hospedado, sem TISS_BACKEND_URL e TISS_SERVICE_SECRET, o servidor não exige chave.

O serviço não armazena nem registra payloads e não os usa para treinar modelos. Quando ativada por POSTHOG_KEY, a telemetria agregada contém operação, códigos de achados, registro ANS, versão TISS e data, sem e-mail. Envie X-Voa-Telemetry: off para desativá-la. A biblioteca local permanece offline e nunca envia telemetria. TISS_API_KEY é a variável que clientes HTTP locais podem ler para enviar uma chave de acesso.

O mapa de rejeição hospedado é uma coleta separada, opt-in e desligada por padrão. Quando habilitado no /org, envia somente agregados por prestador, código, regra e mês. O CPF é pseudonimizado com HMAC e segredo próprio da organização antes de sair do cliente; o CNPJ permanece em claro, e o código do prestador na operadora tem preferência. A retenção é de 24 meses, e a organização pode desligar a coleta e apagar tudo no /org. A telemetria anônima permanece independente e não muda com esse aceite.

Na CLI, mapa --enviar usa TISS_KEY e envia ao servidor público. TISS_MAPA_URL substitui a URL de envio (padrão: https://tiss-api.voa.health/v1/rejection-map/submit). Sem TISS_SEGREDO_PSEUDONIMO, a CLI busca o segredo antes de agregar, via GET /v1/rejection-map/config, no mesmo servidor e com Bearer sk_voa_. O envio usa POST /v1/rejection-map/submit, com o mapa agregado como corpo JSON.

Referência

Símbolos da biblioteca

Ver detalhes

Para renderizar a guia SP/SADT em PDF, instale pip install "tiss[pdf]".

tiss.rede baixa e verifica os dados na primeira consulta. Defina TISS_REDE com o caminho de um SQLite local para usar uma cópia própria. tiss.referencia consulta valores unitários de referência da ANS por TUSS, UF e semestre; o valor pago é somente o pago diretamente ao fornecedor, não o total pago pela operadora. Defina TISS_REFERENCIA para usar um SQLite local.

Campos de um achado

Ver detalhes

Mais

• Esquemas JSON · Fontes de dados · Changelog
• Contribuição · Código de conduta · Segurança
• Licença Apache-2.0