voa-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.

_{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.}

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 voa-tiss

from voa_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.

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 remoto fica em https://tiss-api.voa.health/mcp. Agentes encontram as instruções de uso no AGENTS.md e na skill voa-tiss.

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

Skill, plugins, Codex e Cursor

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

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

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

Tutoriais

API HTTP

Servidor local, chaves e telemetria

pip install "voa-tiss[server]"
python -m voa_tiss.server --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 $VOA_TISS_API_KEY" \
  -H 'Content-Type: application/xml' \
  --data-binary @lote.xml

curl https://tiss-api.voa.health/v1/keys/refresh \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token": "..."}'

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