tiss 0.4.0

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.

_{O agente faturista usando só o MCP público: corrige dois erros do lote, envia à operadora simulada, lê as glosas e rascunha um recurso por guia, sem inventar evidência.}

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 e rede hospitalar.
• API HTTP: as mesmas operações em https://tiss-api.voa.health, com OpenAPI.
• MCP remoto: 24 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

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

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

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

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

{
  "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

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

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

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

Referência

Símbolos da biblioteca

Campos de um achado

Mais

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