上海五期医保接口对接实战：HIS改造与联调避坑指南

简介上海五期医保接口说明是一份面向HIS系统开发与运维人员的接口对接指导文档核心解决医院信息系统与上海医保中心系统之间的数据交互问题。文档围绕电子凭证解码、医保项目明细上传、挂号收费、住院结算、对账退款等业务展开特别解释了卡类型、账户标志、费用结算单元、中心流水号、就诊单元号等关键字段并给出门诊、住院等不同场景下的医保支付办法帮助开发者快速理解业务规则。资源为单个docx文档压缩包大小34KB内容分为引言、业务分析和接口描述三章接口部分统一采用标准JSON格式返回报文逐项说明初始化、读卡、解码、挂号请求、登记、明细上传、住院结算等方法的参数、返回字段与调用要点可直接作为开发联调和问题排查的参考手册。目前已有1593人学习下载适合正在对接上海五期医保接口或希望了解其流程的开发者、实施人员使用。1. 上海五期医保接口说明.docx为什么说它不是一次例行升级某天下午A同学从信息科转来一份《上海五期医保接口说明.docx》。他以为是例行升级医保政策调整改两个交易码、加几个校验字段。结果扫了十分钟脸色就变了——这次连报文头的签名方式都改了文档里明确标了一句“不再向前兼容旧版报文”。这意味着他维护多年的HIS对接层要动一次不小的手术而排期只有两周。这份docx的核心价值是把目录查询、费用上传、预结算、结算、退费和日对账收敛成一套统一接口模型让各家定点医疗机构按一个标准接入。适合读它的人很明确正在做HIS医保对接的开发者、集成商项目组成员、负责验收的实施人员。对这些人来说读懂它等于读懂接下来两周的工作清单读不懂联调阶段大概率要翻车。下文按我对这类项目的落地习惯把这份说明的读法、改法和坑一次讲透。2. 先读通讯和报文模型五期接口的“总纲”藏在前两章我打开这类文档有个固定习惯跳过封面和修订记录直接看通讯方式和报文结构。因为后面所有业务接口都建立在报文模型之上这两个地方出偏差后面每个交易都会出偏差。五期文档通常会把三件事放在前面通讯方式、加签规则、全局报文头字段字典。先把这三件事吃透再往下读业务章节就不慌。2.1 通讯方式与加签规则HTTP 之外还要看证书和密钥常见做法是 https POST、JSON 报文、UTF-8 编码通讯地址和端口以文档“生产环境接入参数”章节为准。真正要花时间的是加签规则。医保接口不是靠用户名密码做鉴权而是对报文体做一次数字签名接收方验签通过后才认这笔请求。五期里我见过用 RSA 和 SM2 两类算法的项目具体用哪个算法、摘要用 SHA256 还是 SM3必须看文档的算法标识不要照抄历史项目。签名有个容易被忽略的点签名原文的拼接顺序。我一般会先把业务报文按文档给定顺序做一次序列化再把时间戳、交易码加进去拼接最后做签名。拼接顺序错了签名必然验不过而且报错信息往往只写“验签失败”不告诉你哪一段拼错了排查起来很费时间。还有一点要提醒密钥文件通常是 p12 或 jks 格式联调环境拿到后先确认证书有效期很多项目临上线才发现证书已经过期。{ head: { msgId: 2024110715300012345678, timestamp: 1730970600000, appId: HIS001, txCode: 5101, sign: Base64(Signature(sha256(serializedBody timestamp txCode))) }, body: { certType: 01, certNo: 310101198001010012, visitType: 1, medicalCategory: 11 } }上面是一个简化的报文结构示例。head 里 msgId 是全链路唯一的业务流水号我习惯用「HIS 机构号 日期 序号」拼保证每次结算请求不重复timestamp 用毫秒级 Unix 时间txCode 是文档定义的四位交易码sign 字段放签名结果。body 里的 certType 是证件类型、certNo 是参保人证件号、visitType 是就诊类型、medicalCategory 是医疗类别。这些都是高频字段取值字典在文档后面会有一张表对接前要先把这张表导出来做成枚举。2.2 报文分层全局包头与业务字段的边界五期报文给我的直观感觉是分层比旧版干净。固定字段全部收进 head业务差异全部放进 body这样同一个签名函数可以复用到所有交易。对接层做通用请求封装时只需要一个入口方法传入交易码和业务参数内部自动组装 head、做签名、发请求、验响应。字段示例值说明常见口径msgId2024110715300012345678全局唯一业务流水号失败重试必须换新timestamp1730970600000毫秒时间戳与医保时间差超阈值会拒收txCode5101交易码按文档“接口清单”取值appIdHIS001调用方标识由医保中心分配sign签名串对报文整体签名算法以文档标识为准这张表是全局包头最常见的五个字段。实际对接时字段名可能叫 sysCode、reqId 或别的但语义都一样。我习惯先把它们放到一个不可变的请求头对象里不允许业务开发人员在业务代码里直接改防止有人把 msgId 复用了。读到这里还有一个章节点不能跳过文档里的“异常报文结构”。五期接口的成功响应和失败响应通常是同一套结构里面会有 code、message、data 三块。联调时最需要看的是失败响应里有没有细分错误码比如“参保人信息不存在”和“证件号格式错误”是不是两个码。错误码粒度越细定位越快如果文档只给一个“交易失败”的通用码那对接层就要靠存请求日志来排查了。3. 核心业务接口拆解费用上传到结算的调用链读完通讯和报文下一步是把业务接口盘一遍。五期接口的接口清单一般会按业务域分组文档里会给出每个接口的交易码、请求字段、响应字段、业务场景说明。我建议不要按文档顺序逐条读而是按一次完整就诊的调用链去读这样记忆成本低也容易发现缺失的接口。3.1 按业务域拆接口目录、费用、结算、退费、对账我拿到接口清单后会先画一张业务域矩阵把场景相近、字段相近的接口归到一组。以多数医保接口的通用设计为参考可以大致分成六大类业务域典型接口请求关键字段响应关键字段使用场景目录查询科室目录、诊疗项目目录、药品目录目录类型、关键字、分页目录编码、医保编码、自费标志挂号收费前同步字典费用上传费用明细上传就诊号、费用明细数组上传流水号、接收时间结算前把明细发给医保预结算费用预结算就诊号、费用流水号统筹金额、个账金额、现金支付收费窗口展示自负金额结算医保结算就诊号、预结算流水号结算流水号、医保支付结果患者确认后正式记账退费/冲正退费申请、冲正撤销原结算流水号、退费金额退费流水号、处理结果退号、退费、撤销在途交易对账日对账单下载对账日期、机构号对账文件列表每日核对医保支付明细这张表的价值是帮你建立整体感。实际文档里的交易码可能是五位、六位数字命名也会有自己的风格但业务域基本逃不出这几类。看到一个新的交易码先归到某一类里字段怎么填就大致有数了。费用上传字段值得单独说。明细数组里每个元素至少要有费用类别、项目编码、项目名称、单价、数量、金额、自费标志。这里的费用类别和医保三大目录的类别要对得上药品、诊疗、耗材、服务设施不能混。很多联调问题出在“单价×数量≠金额”这种低级偏差上医保侧一校验就会直接拒绝而且不会告诉你具体是第几条明细错了。3.2 门诊结算主链路七步走完一笔交易门诊结算流程我一般拆成七步每一步对应一到两个接口调用。之前有同事嫌步骤多跳过预结算直接调结算结果就是患者窗口已经告知要付 50 元医保侧算出来是 80 元现场非常尴尬。第一步读卡或扫码获取参保人证件信息。第二步调用参保人信息查询确认参保状态正常。第三步本地 HIS 生成费用明细调用费用明细上传拿到上传流水号。第四步调用预结算接口把上传流水号和费用总额传过去医保侧会把统筹支付、个账支付、现金支付算出来。第五步收费窗口按预结算结果向患者展示应付金额。第六步患者确认后调用正式结算接口传预结算返回的交易流水号。第七步HIS 保存结算结果更新本地费用状态完成记账和票据打印。这七步里最容易出问题的是第四步和第六步的衔接。预结算返回的流水号是有时效的常见窗口是一到两小时内有效超时后需要重新预结算。有的 HIS 把预结算结果存在内存里窗口一重启就丢了患者结算时报“预结算流水号不存在”这种问题我处理过不止一次。解决方案是把预结算结果落库关联到当前就诊号上超时检测后自动重跑预结算。3.3 退费和冲正别用混退费和冲正在业务语义上是两回事但不少新手会把它们当成同一个接口。退费是对一笔已结算成功的交易做反向操作比如患者缴费后要退号这时结算流水号已经生成医保侧已经完成记账退费后医保侧生成退费流水号。冲正则是对一笔状态未知的“在途交易”做撤销比如请求超时、没有收到明确响应但医保侧可能已经记账了这时要调冲正接口保证本地和医保侧最终一致。判断用哪个很简单如果本地已经拿到医保返回的结算流水号就用退费如果本地没拿到明确响应只是怀疑可能记账了就用冲正。冲正请求里要带原交易的 msgId而不是结算流水号因为医保侧是按照 msgId 去查原交易状态的。有的接口文档会把冲正和退费放在同一个交易码下用操作类型区分对接前要确认清楚。4. HIS 侧对接改造拿到 docx 后从哪几块下手文档读透了接下来是动手改 HIS。我一般把改造分成三块基础配置、签名封装、业务状态机。基础配置负责把环境参数集中管理签名封装负责让业务层不用理解密码学细节业务状态机负责挡住重复结算和漏对账。这三块做完对接层就稳了。4.1 盘点本地 HIS 现状先搞清楚要改什么改造前先花半天做现状盘点。我会列出四个检查项第一本地 HIS 当前的医保接口版本是什么样的报文头字段和五期差异多大第二证书和密钥现在是怎么放的是集中管理还是散落在各台前置机第三本地有没有保存医保字典表和五期要求的目录结构差距有多大第四费用明细的本地数据结构能不能满足上传接口的最小字段要求。这四项里最容易被低估的是字典表。五期接口对诊疗项目编码、药品编码的规范程度通常高于旧版本地 HIS 里如果还是自定义编码就需要做一套映射关系并写进文档。我建议在代码里做一张编码映射表医保编码为主键本地编码为值启动时加载到内存缓存医保侧返回“目录编码不存在”时能快速定位是哪条映射缺失。4.2 一个可复用的签名封装避开拼接混乱签名逻辑一定要收敛到一个类里不要在业务代码里散落多处。常见的做法是提供一个 InsuSignService业务层传入序列化后的 body、timestamp 和 txCode内部完成签名。下面是一个基于 JDK 标准库的示例不依赖第三方加密框架public class InsuSignService { private PrivateKey privateKey; private String charset UTF-8; public String sign(String body, String timestamp, String txCode) throws Exception { // 拼接顺序以接口说明文档为准这里是常见的一种body timestamp txCode String source body timestamp txCode; Signature signature Signature.getInstance(SHA256withRSA); signature.initSign(privateKey); signature.update(source.getBytes(charset)); return Base64.getEncoder().encodeToString(signature.sign()); } public void loadPrivateKey(String p12Path, String password) throws Exception { KeyStore ks KeyStore.getInstance(PKCS12); try (InputStream in Files.newInputStream(Paths.get(p12Path))) { ks.load(in, password.toCharArray()); } // 第一个私钥条目作为签名密钥机构证书前置机通常只有一个 EnumerationString aliases ks.aliases(); while (aliases.hasMoreElements()) { String alias aliases.nextElement(); if (ks.isKeyEntry(alias)) { this.privateKey (PrivateKey) ks.getKey(alias, password.toCharArray()); break; } } } }这段代码有两个关键点。一是拼接顺序body timestamp txCode必须和文档完全一致文档用timestamp body txCode你就得跟着改否则验签必败。二是Signature.getInstance的算法串要根据文档改如果是 SM2 加 SM3算法串要换成对应的比如SM3withSM2不能照抄 RSA 的写法。封装好之后业务层调用就非常简单了比如费用上传只需要构造 body、调 sign、再调统一发送方法。统一的发送方法里还要做两件事记录请求日志、处理响应码。请求日志要记录完整报文但证件号等敏感字段要做脱敏处理否则等保审计会来找你。4.3 本地交易状态机用状态位挡住重复结算接口联调中很大一类问题是重复请求。原因多是前端点了两下提交按钮或者超时后手动重试。如果本地没有状态约束同一笔费用可能被上传两次、结算两次。我习惯在本地结算记录表里加一个状态字段用状态机约束流转。CREATE TABLE settle_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, msg_id VARCHAR(64) NOT NULL COMMENT 医保流水号, local_sn VARCHAR(32) NOT NULL COMMENT 本地业务单号, status TINYINT NOT NULL COMMENT 1已上传,2已预结算,3已结算,9已退费, settle_no VARCHAR(64) COMMENT 医保结算流水号, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_msg_id (msg_id), KEY idx_local_sn (local_sn) );这张表的核心是 uk_msg_id 唯一索引同样的医保流水号永远只能插入一次。业务层在发起结算前先按 local_sn 查记录如果 status 已经是 3直接拒绝重复提交并提示“该笔费用已结算”。同时 msg_id 在重试时必须复用同一个值这样才能让医保侧通过幂等机制识别出是同一笔请求而不是一笔新交易。状态流转的规则也要写清楚已上传才能做预结算已预结算才能做结算已结算才能做退费。如果本地出现“已预结算直接跳到已退费”这种非法流转代码里要直接抛异常而不是静默覆盖。接口对接最怕本地状态和医保侧状态不一致这个状态机是最后一道防线。5. 五期接口联调避坑指南五个常见翻车点联调阶段踩坑是常态。这里整理五个我反复见过的翻车场景每一条都是现象、原因、解决三段式供你对照排查。5.1 参保人证件号校验失败现象把身份证号正常传过去了参保人信息查询一直返回“无此参保人”或“证件号不合法”换一台前置机又好了。原因常见有三种。一是证件类型字段传错比如把身份证类型码传成了护照二是身份证号末位 X 的大小写问题有的接口严格要求大写三是报文在传输过程中被 http client 做了转码比如把明文编码从 UTF-8 自动转成了 ISO-8859-1。解决先打印请求报文用十六进制方式检查证件号字节确认编码是 UTF-8再检查 certType 是否按文档字典填写最后把 X 统一转大写再传。如果还不行用医保侧提供的联调工具发一版原始报文对比差异基本能定位到问题。5.2 总金额和明细金额差一分钱现象费用上传成功预结算时医保侧返回“金额校验失败”本地反复核对也找不到哪一笔算错了。原因这是典型的金额精度问题。本地数据库用 DECIMAL(10,2) 存金额明细按“单价×数量”逐项四舍五入后再累加累加结果和直接填写的费用总额有时候会差一分钱。医保侧的校验逻辑通常是先逐项累加再和你上传的总金额比对差一分都拒绝。解决统一以“分”为单位计算明细金额先乘 100 转整数累加完再转回元或者在费用上传前本地重新用同一套规则计算总金额确保上传的总金额就是明细累加的结果。这个规则要固化到代码里不要靠人工去核对。5.3 请求超时重试出现两笔结算现象结算接口请求超时本地提示“网络异常请重试”患者又刷了一次卡结果医保侧返回两笔结算记录患者被重复扣费。原因超时后重试时代码里重新生成了 msgId医保侧把第二次请求当成一笔新交易处理。这是医保接口对接里最严重的一类事故影响的不只是一笔费用还可能引发医院和医保中心的争议。解决核心交易重试时msgId 必须复用原值直到收到明确响应。如果连续重试三次仍超时不要继续重试而是保存现场调冲正接口撤销在途交易再重新发起。配合第 4.3 节的本地状态机把“已超时待冲正”也做成一个状态防止操作员重复提交。5.4 签名验签过不去先查时钟现象本地用同样的证书和参数在测试环境签名验签都正常切到联调环境就一直报“验签失败”。看报文内容也没什么问题。原因签名时把 timestamp 放进了签名原文医保侧验签时会先检查时间偏差。本地前置机的系统时间和医保服务器时间差了超过阈值比如超过 5 分钟验签就过不去。测试环境刚好做了 NTP 同步所以正常联调环境没人管系统时钟。解决配一台 NTP 时间源所有前置机启动时自动校时报错时先对比本地时间和医保侧返回的错误报文里的时间字段确认偏差。还有一点不要在代码里用本地时间拼接 timestamp 之后再把 timestamp 值改掉签名原文和报文里的 timestamp 必须一致否则必败。5.5 诊疗项目编码在目录里查不到现象上传费用明细后医保侧返回“目录编码不存在”但项目的医保编码在本地字典里明明有。原因本地 HИС 的医保字典版本比医保侧旧某个项目在医保侧新目录里已经停用或变更了编码或者本地字典映射关系写错了把新编码映射到了旧编码上。解决启动时做一次全量目录同步把医保侧最新的目录表拉到本地写入本地字典库明细上传前先查目录缓存如果编码不存在立即返回窗口处理不要等到医保侧报错。如果是映射错误排查映射表里是否有重复映射一个医保编码映射了多个本地编码是最常见的错法。6. 稳定运行之后值得保持的三个工作习惯接口上线不是终点真正考验的是长期运行的稳定性。这里分享三个我延续至今的工作习惯都是在一次次日对账和月度结算中磨出来的。第一接口日志规范化。上线第一天就把日志格式定死每笔请求一条日志包含 msgId、交易码、本地单号、请求报文、响应报文、耗时、结果状态。报文里敏感字段脱敏后再落盘。这样做有两个好处医保侧说“这笔请求你们没发”的时候你可以三分钟之内找到原始报文本地状态和医保侧不一致的时候也可以靠日志还原现场。第二对账自动化。医保接口都有日对账机制不要等到月底靠人工拉 Excel 核对。我一般会写一个定时任务每天凌晨拉取前一日对账文件逐笔和本地结算记录比对把医保侧有而本地没有、本地有而医保侧没有的差异明细输出到一张告警表。这个任务跑起来以后问题通常当天就能发现而不是月底对数时才发现一笔两个月前的漏账。第三每个结算周期前做小额真实验证。月初或者医保政策调整前在测试环境用小额真实患者数据跑一遍完整链路费用上传、预结算、结算、退费。很多问题只在政策切换后出现比如某个费用类别的新旧字典切换。养成这个习惯后我很少再遇到“月初第一周集中报错”的情况。有一次因为切换目录版本时忘了同步门诊特殊病种映射预结算大面积报错从那以后我每逢政策调整都先跑一次冒烟场景。这行的经验很多是用踩坑换来的。你按文档把接口接通只是第一步能把对账和状态机做好才算真正接住了医保接口的复杂性。希望帮到你。本文还有配套的精品资源点击获取