简介面向HIS系统开发与医保对接技术人员的上海医保五期接口说明文档源于上海五期医保接口开发设计的指导性文件。文档系统梳理了前台程序调用医保中心系统的数据交互流程覆盖电子凭证解码、挂号收费请求与确认、登记与撤销、明细上传、住院结算、对账退款、账户及登记查询等核心业务场景并给出标准json返回报文格式及方法描述。资源为单个docx文档大小约34KB体量紧凑便于快速查阅。文档对卡类型、账户标志、计算申请序号、费用结算单元、中心流水号、就诊单元号、明细账单号等专业名词作了通俗解释同时详细说明初始化、读卡、解码、挂号、收费等方法的参数与返回字段可作为医保五期接口开发、联调、评审的参考底稿。已有1592人学习下载适合医院信息科、HIS厂商研发及医保接口实施人员参考使用。1. 上海五期医保接口一份 docx 背后是整个医院对账流程的重构做医院信息化的工程师对「医保接口」这四个字应该都不陌生。每年医保政策调整、目录更新、结算规则变化信息系统就得跟着改一轮接口。上海五期医保接口指的是上海市医保中心推出的第五代医保结算接口规范那份「上海五期医保接口说明.docx」就是医院信息科和 HIS 厂商拿到的对接依据。不少人以为它只是一份接口文档翻一翻、照着调几个字段就行实际落地时才发现它牵动的是一条完整的业务链从门诊挂号、收费结算、住院登记到每日对账、月度申报、退费冲正每个环节都要跟着改。这份文档解决的核心问题是让医院内部 HIS 系统与上海医保中心的后台系统在同一套规则下对话。五期相比之前的版本最大的变化在于接口交互方式更严格、返回码体系更细、对账粒度更精确。适合谁来读如果你是 HIS 开发、医院信息科运维、或者负责医保接口对接的第三方实施工程师这篇文章会把这份 docx 里的技术要点拆开讲清楚怎么落地、参数怎么调、哪些坑最容易踩。2. 先读懂 docx 里的接口骨架前置机、报文格式与两类接口2.1 前置机部署为什么不是 HIS 直连医保中心上海医保五期接口的部署模式和全国很多省份类似采用「医院前置机 医保专网」的架构。前置机是一台独立的服务器放在医院内网区通过医保专网与医保中心通信。HIS 系统不直接访问医保中心而是先访问前置机上的医保客户端程序再由客户端程序完成与医保中心的报文交换。这种设计有三个直接好处。第一是安全隔离医保网络是独立专网医院内网如果直接接入网络边界会很难管控。第二是接口稳定性医保中心侧如果变更地址或协议医院只需要升级前置机上的客户端HIS 侧改动最小。第三是事务一致性前置机上的客户端负责保存请求和响应日志医院在排查结算失败时可以拿到完整链路。前置机的硬件要求不算高常见的配置是 4 核 CPU、8G 内存、千兆网卡操作系统通常是 Windows Server 2016 以上或 Linux。需要注意的是前置机上必须安装医保中心下发的根证书和签名工具这是后续报文签名验签的基础。HIS 与前置机之间走局域网 HTTP 或 WebService前置机与医保中心之间走专网两段网络的超时阈值要分开配置。2.2 报文格式解析XML 与 JSON 并存版本号别填错上海五期接口说明里报文格式是 XML 与 JSON 并存的。交易类接口以 XML 为主目录查询类接口部分支持 JSON具体要看那份 docx 里的接口清单。以最常用的门诊结算接口为例请求报文的根节点通常是 内部包含 、 、 、 等区块。这里有一个容易搞错的点TradeCode 不是随便写的。五期接口沿用医保中心的统一交易码例如门诊结算可能是 1001住院结算可能是 1002冲正可能是 2005具体数值以 docx 里的接口定义为准。开发时不要凭经验猜必须对照文档逐项核对。另外报文头里的 Version 字段五期要求填 5.0如果沿用四期的 4.0前置机客户端会在验签阶段直接拒绝返回的错误码通常是签名验证失败或版本不匹配。Request Head Version5.0 TradeCode1001 HospitalId3101XXXXXXX / Body UserInfo IdCardNo310101194912310000 Name张三 / MedicalInfo TotalAmt285.50 SelfPayAmt85.50 / /Body /Request这段示例表示版本 5.0门诊结算交易医院编号和患者身份信息放在 Body 的 UserInfo 区。实际开发时Head 里一般还要带交易流水号 OrganMsgId用于后续对账这个字段是五期新增的必填项。注意 Version 是字符串不要写成数字 5.0前置机验签逻辑做的是精确字符串匹配。2.3 一类是交易接口一类是目录接口别混在一个服务里部署五期接口说明里明确把接口分为两类交易类接口和目录类接口。交易类接口包括门诊结算、住院结算、冲正、撤销、下载对账文件等特点是高频、实时、对响应时间敏感。目录类接口包括药品目录下载、诊疗项目目录下载、异地人员信息查询等特点是低频、数据量大、通常在夜间批量执行。这两类接口的部署要求不一样。交易类接口必须保持长连接或短连接但高频可用超时时间要短一般 5 到 10 秒内必须有响应否则收费窗口会卡住。目录类接口则建议做成批量任务比如每天晚上 10 点后自动拉取增量目录避开业务高峰。同时两类接口的事务性要求也不同。交易接口必须支持冲正和撤销因为门诊收费场景下收费员录错项目或者患者要求退费必须通过冲正交易把医保结算记录作废。目录接口一般是查询性质不涉及事务回滚只需要记录拉取时间和版本号确保本地目录与医保中心一致即可。3. 实现一个医保结算请求签名生成、超时识别与批次对账3.1 签名生成是第一个硬门槛MD5 还是 RSA以 docx 附录为准上海医保五期接口的报文签名常见方案是医疗机构用私钥对报文关键字段做签名医保中心用对应的公钥验签。签名算法一般是 RSA 或 MD5具体以 docx 附录的「签名算法说明」为准。开发时最容易出错的是签名字段的拼接顺序文档里会逐个字段列出参与签名的字段名顺序是固定的。比如一个门诊结算请求参与签名的字段可能是 HospitalId、OrganMsgId、TradeCode、TotalAmt、IdCardNo按文档给定的顺序拼接后用私钥签名得到一段 Base64 字符串放进报文的 Sign 字段。很多团队第一次联调被退回就是因为字段顺序和文档不一致或者拼接时多了空格、换了换行符。import hashlib import base64 def md5_sign(data_string: str) - str: md5 hashlib.md5() md5.update(data_string.encode(utf-8)) return base64.b64encode(md5.digest()).decode(utf-8) # 参与签名的字段顺序必须和 docx 附录一致 raw f{hospital_id}|{organ_msg_id}|{trade_code}|{total_amt}|{id_card_no} sign md5_sign(raw)这段代码演示的是 MD5 签名方式用竖线分隔字段。逻辑上就是先按文档给的顺序拼接字符串再对整个字符串做 MD5 摘要最后 Base64 编码。参数说明hospital_id 是医院编号organ_msg_id 是本次交易的流水号trade_code 是交易码total_amt 是总金额id_card_no 是患者身份证号。实际项目里RSA 签名则是用私钥对拼接字符串做 SHA256withRSA生成 256 字节签名最终同样 Base64 编码。两种方式实现思路一样差别只在摘要算法和密钥管理。3.2 POST 到前置机用 HTTP 客户端还是 WebServiceHIS 调用前置机的方式一般有两种HTTP POST 或 WebService。五期接口说明中对前置机的调用地址有明确约定通常是 http://前置机IP:端口/接口路径报文以 application/x-www-form-urlencoded 或 text/xml 方式提交。开发时注意HTTP 头里的 Content-Type 要和前置机的端口约定一致有些前置机程序对 Content-Type 是严格校验的。curl -X POST http://192.168.10.10:8080/medicare/trade \ -H Content-Type: application/x-www-form-urlencoded \ -d tradeCode1001reqXmlRequest%3CHead%20Version%3D%225.0%22%2F%3E%3C%2FRequest%3Esignxxxx这是用 curl 模拟的一次交易请求reqXml 是转义后的 XML 报文sign 是签名串。前置机返回的也是 XML里面包含交易状态码、医保结算明细和统筹支付金额。这里有一个实用经验联调时先用 curl 手动发一包确认前置机能正常响应再写业务代码能省很多排查时间。3.3 批次对账医险对账文件的下载与核对五期接口强调日清日结每天的医保结算数据必须在当日业务结束后完成对账。具体做法是晚上 10 点后调用对账文件下载接口从医保中心拉取当天的结算明细文件然后和 HIS 本地记录逐笔核对。# 下载对账文件示例为模拟命令 curl -X POST http://192.168.10.10:8080/medicare/download \ -d tradeCode7001date2025-01-15hospitalId3101XXXXXXX对账文件通常是文本文件或 XML 文件每行是一条结算记录包含交易流水号、交易时间、总金额、统筹支付金额、个人账户支付金额等字段。HIS 侧需要做的就是逐行比对某笔交易医保中心有记录但 HIS 没有说明上传时丢失HIS 有记录但医保中心没有说明重复退费或冲正未同步。比对完成后生成差异报告由医院医保办确认后再做平衡调整。对账这步没有捷径一定不能只比对总金额要按流水号比对明细。很多对账不平的问题都是因为同日多笔退费串联导致总量吻合但明细不匹配。4. 五期接口必调的四个参数超时窗口、重试次数、批量大小与签名缓存4.1 交易接口超时窗口门诊收费场景 5 秒是红线门诊收费窗口的医保结算请求从 HIS 发出到拿到医保中心返回用户可接受的等待时间在 5 秒以内。这个时间不是医保中心接口的响应时间而是从「HIS 发起请求」到「HIS 收到完整响应」的端到端耗时。其中包含局域网传输、前置机处理、专网传输、医保中心业务处理四个环节。因此在配置超时阈值时我一般建议 HIS 侧 HTTP 客户端连接超时设为 3 秒读超时设为 10 秒。连接超时超过 3 秒说明局域网或前置机端口可能异常读超时超过 10 秒通常是医保中心业务繁忙或前置机排宕。这两个参数如果调反了会出现一种很奇怪的现场连接迟迟不建立以为服务不可用其实只是连接超时太短。4.2 重试次数与幂等性冲正请求不能因为超时就重发交易接口的重试是个危险操作。如果一笔门诊结算请求因网络原因超时HIS 没有收到响应此时你不能盲目重发——医保中心可能已经结算成功重复发送会产生两笔医保记账记录。五期接口解决这个问题的机制是交易流水号OrganMsgId的幂等性医保中心侧对相同流水号的重复请求会直接返回已处理状态。但前提是重试时必须携带同一笔流水号。设计重试方案时HIS 生成的交易流水号要落库在重试时从库中读取原流水号而不是重新生成。我见过不止一次现场翻车就是因为开发偷懒把重试请求当作新交易生成了新流水号结果患者医保账户被重复记账退费流程非常繁琐。重试次数一般不超过 3 次每次间隔 1 秒、2 秒、4 秒递增。如果连续 3 次都超时应当转入人工处理流程收费员可以引导患者先自费后续凭发票做医保报销。不建议无限重试因为在一个持续阻塞的下午无限重试只会把前置机拖垮。4.3 目录下载的批量大小全量目录不能一次拉完上海医保的药品目录和诊疗项目目录全量数据量在几十万条级别。如果一次性调用目录下载接口报文会非常大前置机和医保中心都可能因内存溢出拒绝响应。五期接口通常支持分页或增量下载常见做法是按更新时间拉取增量首次上线时全量拉取。全量拉取时分页大小建议设为 1000 条每页。太大会导致单次响应报文超过前置机的接收上限太大会增加请求次数拉一个完整目录要几个小时。增量更新则是记录上次拉取到的时间戳每天只拉取该时间之后的变更数据。医院 HIS 的本地药品字典就靠这个机制保持和医保中心一致。目录存储建议直接落库不要用文本文件保存后每次启动重新加载。用数据库表存储目录版本号拉取前先查本地版本号拉取后更新版本号这样即使前置机重启目录也能快速恢复。4.4 签名缓存私钥读文件还是读数据库前置机上的私钥文件如果是首次部署通常会以加密文件的形式下发。程序读取私钥时如果每次都从磁盘文件加载在高频交易场景下会有性能损耗。常见优化是启动时把私钥加载进内存缓存后续签名直接使用缓存值。但这个缓存存在一个运维坑医保中心如果做密钥轮换会下发新的私钥文件程序如果一直用缓存中的旧私钥签名验证会持续失败。这就要求程序在检测到密钥文件变更时间或哈希变化时自动重新加载。更稳妥的做法是把密钥文件的读取封装成一个带失效时间的方法每 5 分钟检查一次文件指纹指纹变化就重新加载。import os import hashlib key_cache {fingerprint: None, private_key: None} def get_private_key(key_path: str): with open(key_path, rb) as f: content f.read() fp hashlib.md5(content).hexdigest() if key_cache[fingerprint] ! fp: key_cache[fingerprint] fp key_cache[private_key] content return key_cache[private_key]这段代码的逻辑是每次取私钥前先计算文件指纹发现指纹变化就重新读文件否则用缓存。参数说明key_path 是私钥文件路径content 是文件原始字节fp 是内容指纹。这样做的好处是兼顾性能和密钥轮换避免重启服务才生效的尴尬。5. 避坑指南上海五期医保接口常见的五个障碍与解决办法5.1 现象联调时返回「签名验证失败」但本地签名逻辑看着没问题原因签名字段顺序与 docx 附录不一致或者拼接时使用了空格、制表符与文档要求的竖线分隔符不匹配。还有一种隐蔽原因是前置机的时钟偏差超过 5 分钟导致时间戳字段验签失败。解决先把参与签名的字段逐一列出对照 docx 里的签名规则原文用肉眼核对拼接顺序。然后检查前置机的系统时间与医保中心标准时间做一次同步。最后用医保中心联调平台提供的「签名自测工具」验证签名串是否正确这个工具通常会返回详细的错误信息指出是字段值不对还是摘要算法不匹配。5.2 现象门诊结算偶发超时前置机日志显示请求已发送但医保中心未返回原因这是典型的网络半开状态前置机到医保中心的专网链路可能在某个时点发生闪断TCP 连接未断开但数据已无法送达。HIS 端表现为读超时前置机端日志显示报文已发出但没有响应。解决前置机上配置 TCP KeepAlive 参数每 30 秒发送一个心跳包确保链路异常能在 90 秒内被系统感知。HIS 端重试逻辑按前一章策略执行不要无限重试。同时在收费窗口提示「医保网络异常请稍后重试」避免患者在窗口长时间等待。5.3 现象对账时 HIS 有记录医保中心文件里查不到这笔交易原因HIS 在请求发出后收到了医保中心的成功响应但前置机向医保中心发送时报文在传输链路上被丢弃或者医保中心返回成功响应后响应报文在前置机回传 HIS 时丢失。两种情况都会导致 HIS 记录成功但医保中心没有记录。解决把前置机日志中该交易流水号的发送记录调出来如果发送记录显示已发出但没有收到响应说明报文可能在链路中丢失。处理方式是下一批次时补传这笔交易或者走冲正重发流程。关键是 HIS 侧要把每笔交易的完整报文和响应报文落库以便核验时定位是在哪个环节丢失的。5.4 现象目录下载到一半进程被杀死重启后又要重新拉全量原因没有记录分页游标或增量时间戳重启后从第一页开始拉。如果目录有 50 万条每页 1000 条拉到第 300 页时程序宕机重新启动又从第 1 页开始每次都在做无用功。解决目录下载设计成断点续传每成功处理完一页就把当前页数和最后一条记录的更新时间写入数据库。重启后先查数据库中的游标位置再续传剩余部分。此外目录数据入库要加唯一索引比如以药品编码为唯一键重复拉取时做幂等更新避免产生重复数据。5.5 现象五期上线后四期时代的旧结算记录无法查询原因五期接口调整了交易表结构旧数据如果没做迁移映射HIS 的历史结算记录会因字段不一致而无法展示。常见的坑是五期用 OrganMsgId 作为交易唯一键四期的流水号是自增整数两套体系没有关联。解决上线前先做历史数据迁移把四期的交易流水号写入五期表的扩展字段同时在五期交易表里保留 legacy_trans_id 字段。查询时优先按五期流水号查不到时用旧流水号映射查询。这样能保证医保办在月报时可以看到连续完整的交易链。6. 把 docx 变成运维手册接口日志规范、自测用例与切换演练做到这一步接口的主流程已经能跑通了但离「稳定运行」还有一段距离。我习惯的做法是把那份 docx 里所有的接口定义提炼成一张接口清单表包含交易码、接口名称、方向、超时时间、是否必填、报文示例。然后为每个接口准备一套联调用例包括正常用例、边界用例和异常用例每次前置机升级或医保中心调整参数后先跑一遍用例集再放量。接口日志规范是另一个容易被忽视的环节。每笔交易必须记录请求时间、响应时间、交易码、流水号、返回码、耗时、原始报文。日志文件按天切割保留至少 30 天。这样遇到医保办来问「上周三某笔结算为什么被拒」可以直接查日志还原现场而不是让收费员回忆。日志格式建议用 JSON 单行方便导入日志分析平台。切换演练值得认真做一次。找一个周末业务低峰时段将 HIS 的医保接口地址从前置机 A 切到前置机 B验证门诊挂号、收费、住院登记、出院结算几个核心流程能正常走通。演练时故意拔掉 A 的网线看 HIS 能否自动或手动切换到 B这个动作能暴露出前置机配置里的很多隐藏问题。实际项目中我见过一次切换演练把收费处的所有结算请求都打到一台未配置医保目录的备用机上结果目录下载任务把所有带宽占满门诊业务卡了二十分钟。那次之后我们规定备用机每晚必须跑一次目录增量同步并且演练当日先停掉批处理任务。五期接口给医院带来的不只是技术升级更是一次对账流程和运维习惯的重建。全文里提到的签名、超时、重试、对账、切换都是我在真实项目里用时间换来的血泪经验。每个医院的前置机环境、HIS 版本、科室流程都不一样照搬别人的配置不一定适用但排查思路是可复用的先看日志确认是传输层还是业务层的问题再按本文的边界参数去配置超时和重试策略。希望这份拆解能帮你在对接上海五期医保接口时少走一些弯路顺利走完从拿到 docx 到上线稳定运行的全过程。本文还有配套的精品资源点击获取