voa-tiss

TISS sem dor de cabeça, para pessoas e agentes de IA.

Site · Playground · Documentação · Operadoras · TISS-Bench

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

Ver detalhes

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

No Codex, adicione a ~/.codex/config.toml:

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

No Cursor, adicione ao mcp.json:

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

Tutoriais

API HTTP

Servidor local, chaves e telemetria

Ver detalhes

Instale o extra do servidor e inicie a API local:

pip install "voa-tiss[server]"
python -m voa_tiss.server --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 uma chave sk_tiss_ 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 $VOA_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 VOA_TISS_BACKEND_URL e VOA_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. VOA_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 VOA_TISS_KEY e envia ao servidor público. VOA_TISS_MAPA_URL substitui a URL de envio (padrão: https://tiss-api.voa.health/v1/rejection-map/submit). Sem VOA_TISS_SEGREDO_PSEUDONIMO, a CLI busca o segredo antes de agregar, via GET /v1/rejection-map/config, no mesmo servidor e com Bearer sk_tiss_. 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 "voa-tiss[pdf]".

voa_tiss.rede baixa e verifica os dados na primeira consulta. Defina VOA_TISS_REDE com o caminho de um SQLite local para usar uma cópia própria.

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