2. 医保支付接口协议与标准体系
医保支付接口不是一套“随便约定”的私有协议，而是由国家医保局接口规范作为顶层约束、地方医保平台在落地时做差异化扩展、再通过HTTP / WebService / 消息队列等通信方式承载、最终以统一报文格式与编码规则交换数据的分层体系。理解这四层关系，是后续做接口对接、联调和排障的前提。
先看最上层。国家医保局通过《医疗保障信息平台接口规范》等文件，统一了业务编码、交易类型、报文结构和安全要求。核心思想是“统一标准、分级部署”：国家平台定义通用交易（如人员信息查询、门诊结算、住院结算、费用明细上传、对账），地方平台在此基础上落地。因此，接口开发中真正要面对的不是“国家规范原文”，而是“某省/某市医保平台按国家规范裁剪和扩展后的接口文档”。
地方差异主要体现在五个方面：一是接入地址与网络环境，有的走医保专网，有的走政务外网或 VPN；二是鉴权机制，常见的有 AppId + Secret 签名、Token 令牌、数字证书（CA）签名；三是交易码与版本，地方可能对国家标准交易做二次编号；四是扩展字段，如地方特有的定点机构编码、参保地行政区划；五是返回码体系，除国家统一码外还有地方自定义错误码。对接前必须先拿到地方接口文档，逐项比对，不能凭国家规范“想当然”。
通信方式决定了接口的“传输形态”。HTTP/HTTPS 是目前主流，多为 RESTful 风格，用 JSON 或 XML 承载报文，适合实时性要求高的结算、查询类交易；WebService（SOAP） 在部分老平台仍在使用，报文为 XML，通过 WSDL 描述服务，优点是规范严格、跨语言，缺点是报文冗长、调试不便；消息队列（MQ） 如 Kafka、RabbitMQ、ActiveMQ，多用于费用明细批量上传、对账文件异步通知等场景，特点是解耦、削峰、可重试，但不适合要求同步返回结果的实时结算。选择哪种方式，取决于交易的实时性、数据量和平台要求。
报文格式与编码规则是接口的“语法”。常见格式有 JSON 和 XML：JSON 轻量、易读，适合 HTTP 接口；XML 结构严谨，适合 WebService 和部分医保报文。编码上，字符集统一使用 UTF-8，避免中文乱码；金额字段通常以“分”为单位的整数传输，避免浮点误差；日期时间多用 yyyy-MM-dd HH:mm:ss；布尔值用 0/1 或 Y/N，需按地方文档确认。签名方面，常见做法是将参数按字典序拼接后做 MD5 或 SHA-256，再与密钥组合，防止篡改。
把四层串起来看，一次典型的门诊结算请求是这样流动的：业务系统按国家规范组装交易码和字段，按地方文档补充扩展字段和签名，通过 HTTPS POST 把 JSON 报文发到地方医保平台地址，平台校验签名和字段后返回结算结果。如果走的是消息队列，则费用明细先入队，平台异步消费并回写对账结果，业务系统再通过查询接口确认状态。
下面给出一份可直接对照使用的接口对接前检查清单，用于在拿到地方接口文档后逐项确认，避免联调阶段才发现缺项：
| 检查项 | 确认内容 | 常见问题 |
|---|---|---|
| 接入地址 | 测试/生产 URL、网络可达性 | 测试地址与生产地址混用 |
| 鉴权方式 | AppId、Secret、Token 获取与刷新 | 签名算法与文档不一致 |
| 交易码 | 地方交易码与国家码映射 | 直接使用国家码导致报错 |
| 必填字段 | 地方扩展必填项 | 遗漏参保地、定点机构编码 |
| 报文格式 | JSON/XML、字符集、金额单位 | 金额用元导致精度错误 |
| 返回码 | 成功码、业务失败码、系统异常码 | 只判断 HTTP 200 忽略业务码 |
| 超时与重试 | 连接/读取超时、幂等策略 | 重复提交造成重复结算 |
最后强调编码规则中的两个易错点。第一，金额单位：国家规范通常要求以“分”为单位的整数传输，例如 12.50 元应传 1250，若误传 12.50 可能被平台拒绝或产生精度偏差。第二，签名顺序：签名前必须按参数名 ASCII 字典序升序拼接，且排除空值和签名字段本身，拼接后再与密钥组合计算摘要。不同地方对大小写、是否 URL 编码的要求可能不同，必须以地方文档为准。掌握这四层体系，后续对接任何地方医保平台，都能快速定位问题出在规范层、地方层、通信层还是报文层。