关于 voa-tiss
voa-tiss 是面向医疗服务提供方、保险运营方及 Agent 的巴西 TISS 医疗结算工具包，支持离线处理。它结合 Python 库、HTTP API 和远程 MCP 服务，并可查询 TUSS 与 ANS 数据。
主要功能
- 01验证并修正 TISS 批次
- 02生成和解析 TISS XML
- 03读取付款明细并解释拒付
- 04核对申报金额与实付金额
- 05查询 TUSS、保险运营方和医院网络
适用场景
- 01提交前发现并修复批次错误
- 02分析拒付代码并起草申诉
- 03核对保险方付款与申报记录
MCP 相关
远程 MCP 服务 https://tiss-api.voa.health/mcp 为 Agent 提供 24 个工具和 3 个提示词，支持 TISS 操作、数据查询与对账。
配置
远程服务无需本地安装。选择你使用的客户端，复制配置或使用一键安装。
https://tiss-api.voa.health/mcpclaude mcp add --transport http health-voa-tiss https://tiss-api.voa.health/mcp{"mcpServers":{"health-voa-tiss":{"type":"http","url":"https://tiss-api.voa.health/mcp"}}}在 Cursor 中打开{"servers":{"health-voa-tiss":{"type":"http","url":"https://tiss-api.voa.health/mcp"}}}在 VS Code 中打开{"mcpServers":{"health-voa-tiss":{"type":"http","url":"https://tiss-api.voa.health/mcp"}}}{"mcpServers":{"health-voa-tiss":{"serverUrl":"https://tiss-api.voa.health/mcp"}}}命令在终端中运行；JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。
工具
详细介绍
轻松处理 TISS，为人和 AI Agent 而打造。
使用开源工具验证、修正并生成 TISS 批次，了解拒付原因并核对结算单：提供可离线运行的 Python 库、HTTP API 和远程 MCP 服务，供你的 AI Agent 使用。
提示
使用 Claude Code、Codex 或 Cursor？连接 MCP 并用葡萄牙语提出请求，例如“验证这个批次并修正可以修正的问题”。请参阅 连接 Agent。
快速开始
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]
每条发现都包含稳定的代码、位置，以及可能的现成修正方案。需要 Python 3.10+。
想在浏览器中试用？打开 playground。
适用对象
| 你的身份 | voa-tiss 可帮助你 |
|---|---|
| 医疗服务提供方（医院、诊所、实验室） | 在医疗保险机构发现错误前找出问题，并了解就诊单被拒付的原因 |
| 医疗专业人员 | 核对就诊单和 TUSS 代码，无需死记手册 |
| 医疗保险机构 | 使用自己的规则离线检查接收的批次；查看各服务提供方的拒收情况；提供应用自有规则的沙盒；验证 TISS 授权；发布带有“官方”标记的规则；并在支持 Agent 的模块中分析账单和预先授权 |
| 患者 | 用通俗易懂的语言了解拒付的含义 |
| SUS 或政府管理人员 | 查询 ANS 关于医疗保险机构、拒付和医院网络的开放数据 |
工作原理
你无需手动编写 XML TISS。整个流程始终相同：
- 验证批次：使用
check或validate。 - 使用
apply_fixes修正：修正操作是确定性的，采用 JSON Patch。 - 重新验证，直到错误清零。如果缺少数据，
needs会明确指出需要询问什么。 - 使用
build_lote生成 XML，并使用hash_epilogo计算尾部哈希。
提交后，parse_demonstrativo 会读取保险机构的返回结果，glosa 会解释 Tabela 38 中的每个代码，而 plan_reconciliation 会核对已支付和已收费的金额。若要在没有真实保险机构的情况下测试，请使用
模拟保险机构。
软件包包含的内容
- Python 库：验证、修正、生成、哈希、审计、结算单、TUSS、保险机构和医院网络。
- HTTP API：通过
https://tiss-api.voa.health提供相同的操作，并附有 OpenAPI。 - 远程 MCP 服务：为 Agent 提供 24 个工具和 3 个提示词，收录于 MCP 官方注册表。
- 模拟保险机构：提交批次并接收协议、结算单和拒付明细，无需接触生产环境。
- 计费 Agent：可根据你的工作流进行适配的完整 Agent。
- TISS-Bench：40 个合成任务，用于评估使用和不使用 MCP 的 Agent。
为何值得信赖
- **离线且确定性：**验证、修正和生成操作都在你的机器上运行，不进行遥测；相同的输入始终产生相同的输出。
- **XSD 通过哈希固定：**验证使用经哈希校验的官方 TISS 架构。
- **防提示词注入：**病历单中的自由文本仅作为数据处理，绝不作为指令。
- **你的数据不会留在我们这里：**请参阅 HTTP API 中有关负载和遥测的政策。
- **有数据衡量：**在 TISS-Bench 中，使用四种模型时，平均准确率从不使用 MCP 时的 58% 提升至使用 MCP 时的 81%。从零开始生成批次，在两种模式下的准确率仍为 16%。
连接 Agent
远程 MCP 服务位于 https://tiss-api.voa.health/mcp。Agent 可在 AGENTS.md 和
voa-tiss 技能中找到使用说明。
claude mcp add --transport http voa-tiss https://tiss-api.voa.health/mcp
技能、插件、Codex 和 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
在 Codex 中，将以下内容添加到 ~/.codex/config.toml：
[mcp_servers.voa-tiss]
url = "https://tiss-api.voa.health/mcp"
在 Cursor 中，将以下内容添加到 mcp.json：
{
"mcpServers": {
"voa-tiss": {
"url": "https://tiss-api.voa.health/mcp"
}
}
}
| 教程 | 你将学到什么 |
|---|---|
| 验证一批数据 (notebook) | 阅读发现并进行修正 |
| 对账单与核对 (notebook) | 核对运营方支付的金额 |
| TUSS 与 SP/SADT (notebook) | 搜索代码并填写申请表 |
| 生成并修正一批数据 (notebook) | 将 JSON 转换为有效的 XML |
| 按运营方设置规则 (notebook) | 根据已发布的规则进行审计 |
| 模拟运营方 (notebook) | 测试提交和拒付 |
| SP/SADT 授权 (notebook) | 申请并分析授权 |
| 拒绝原因概览 (notebook) | 按服务提供方汇总发现 |
HTTP API
本地服务器、密钥与遥测
查看详情
安装服务器扩展并启动本地 API：
pip install "voa-tiss[server]"
python -m voa_tiss.server --host 127.0.0.1 --port 8000
以 JSON 或 XML 正文形式验证 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
没有密钥时，只有沙盒操作会响应。对于其他操作，请使用 Voa 账户登录 tiss-api.voa.health/chaves，并发送收到的密钥。每日请求次数不限。
curl https://tiss-api.voa.health/v1/validate \
-H "Authorization: Bearer $VOA_TISS_API_KEY" \
-H 'Content-Type: application/xml' \
--data-binary @lote.xml
密钥有效期为 24 小时。使用登录时收到的 refresh_token 续期；密钥无效或过期时会返回 401：
curl https://tiss-api.voa.health/v1/keys/refresh \
-H 'Content-Type: application/json' \
-d '{"refresh_token": "..."}'
服务不会存储或记录负载，也不会将其用于训练模型。通过 POSTHOG_KEY 启用遥测后，汇总数据包含操作、发现代码、ANS 注册号、TISS 版本和日期；签发密钥时，还会包含组织级别和标识符，不含电子邮件。发送 X-Voa-Telemetry: off 可将其关闭。本地库始终离线，绝不会发送遥测。VOA_TISS_API_KEY 是本地 HTTP 客户端可读取并用于发送访问密钥的变量。
参考
库符号
查看详情
要将 SP/SADT 指南渲染为 PDF，请安装 pip install "voa-tiss[pdf]"。
| 符号 | 用途 |
|---|---|
validate | 验证 TISS 批次并返回报告。 |
check | 检查 JSON 批次并提出修正建议。 |
apply_fixes | 对 JSON 批次应用确定性修正。 |
build_lote | 根据已验证的批次生成 TISS XML。 |
parse_lote | 将 TISS XML 转换为 JSON 批次。 |
audit | 根据保险运营商的上下文审计批次。 |
validate_package | 验证保险运营商规则包并列出错误。 |
hash_epilogo | 计算尾注的哈希值。 |
glosa | 查询 Tabela 38 中的代码。 |
dominio.lookup / dominio.search | 查询 TISS 域表。 |
operadoras.lookup / operadoras.search | 查询 ANS 中的活跃保险运营商。 |
operadoras.perfil | 合并 ANS 登记信息和拒付指标。 |
parse_demonstrativo | 读取对账单并返回每份指南的处理决定。 |
plan_reconciliation | 提出处理决定与指南之间的对账方案。 |
sadt_missing | 列出 SP/SADT 指南中缺失的必填字段。 |
sadt_catalog | 返回 SP/SADT 目录副本。 |
render_sadt（额外项 pdf） | 生成 SP/SADT 指南的 PDF。 |
tuss.lookup | 查询 TUSS 代码。 |
tuss.search | 按文本搜索 TUSS 记录。 |
rede.* | 查询 ANS 医院网络的关联关系。 |
json_schema | 返回公开类型的 JSON 架构。 |
examples | 提供软件包的合成示例。 |
voa_tiss.rede 会在首次查询时下载并验证数据。设置
VOA_TISS_REDE 为本地 SQLite 文件的路径，以使用自有副本。
发现项字段
查看详情
| 字段 | 含义 |
|---|---|
code | 稳定代码，见 docs/codigos.md |
severity | error 或 warning |
guia | 指南标识符（如有） |
xpath | XML 中的位置（如有） |
message | 对发现项的简要描述 |
pointer | JSON 批次中的 JSON Pointer（如有） |
fix | JSON Patch 格式的修正（确定时） |
needs | 完成指南所需的字段 |
glosa | 可能对应的 Tabela 38 代码（如有） |
rule | 生成该发现项的保险运营商规则（如有） |
更多
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。