voa-tiss

English: Offline Python tools for ANS TISS documents.

Biblioteca Python para validar lotes TISS, ler demonstrativos e consultar TUSS sem rede.

Requer Python 3.10+.

Site técnico: tiss-api.voa.health.

Instalação

pip install voa-tiss
pip install "voa-tiss[pdf]"  # renderização SP/SADT

Início rápido

from voa_tiss import examples, validate

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

API

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.

Fluxo

flowchart LR
    A["Lote JSON"] --> B["check"]
    B --> C{"Há correções?"}
    C -->|sim| D["apply_fixes"]
    D --> B
    C -->|não| E["build_lote"]
    E --> F["XML TISS"]

Achados

Garantias

• Offline e determinístico.
• XSD fixado por hash.
• Texto livre da guia é dado, nunca instrução.

API e MCP

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

Conecte clientes MCP:

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

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

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

Sem chave, só as operações do sandbox respondem. Para as demais, entre com a conta Voa em tiss-api.voa.health/chaves e envie a chave recebida. 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

A chave vale 24 horas. Renove com o refresh_token recebido no login; chave inválida ou expirada retorna 401:

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

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 apenas operação, códigos de achados, registro ANS, versão TISS e data. 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.

Guias e contratos

• Validar um lote
• Demonstrativo e conciliação
• TUSS e SP/SADT
• Gerar e corrigir um lote
• Regras por operadora
• Operadora simulada
• Esquemas JSON
• Fontes de dados
• Contribuição
• Licença