简介面向HIS系统开发者的上海医保五期接口说明文档用于指导医院信息系统与上海医保中心系统完成数据交互重点覆盖电子凭证解码、医保项目明细上传、挂号收费、住院结算等核心业务。资源为单个docx文件压缩包仅34KB篇幅紧凑但内容体系完整适合医保接口对接及运维人员快速查阅。文档分为引言、业务分析、接口描述三章先解释卡类型、账户标志、就诊单元号等关键名词再梳理读卡、解码、挂号确认、明细上传/撤销、住院结算、对账退款等业务流程最后给出初始化、ShYbV5_S000读卡、ShYbV5_SE01解码、ShYbV5_SH01挂号等方法说明并附标准JSON返回报文示例便于开发者直接对照接口字段进行开发调试。已有1594人学习浏览是一份实用的一手接口参考资料。1. 上海五期医保接口HIS对接医保中心的一座桥做HIS的同行应该都有这种经历拿到一份医保接口文档几十个方法、上百个字段文档里名词一个比一个绕——就诊单元号、计算申请序号、明细账单号、中心流水号分不清谁先谁后。这份上海五期医保接口说明核心就是把前台读卡、挂号收费、住院登记结算这些操作封装成一个个黑匣子方法HIS这边传参数进去拿JSON出来。它适合正在做或准备做上海医保对接的HIS开发也适合想搞懂医保结算字段流转的产品和测试人员。文档本身篇幅不大但如果你只读一遍就上手联调很容易忽略掉那些能让你对接翻车的细节。本文按业务是什么→接口怎么用→工程怎么落地→踩过哪些坑→怎么二次开发这条线拆一遍。2. 业务模型与技术边界先搞清楚医保接口在哪一层2.1 黑匣子模式HIS不用懂医保规则但要知道传什么文档里有一句很关键的话本接口程序对于主程序而言比较简单类似一个黑匣子只需按照约定调用该类中的相应方法即可。这个定位决定了整个对接的技术思路医保中心系统暴露一堆方法HIS作为调用方不参与医保政策计算只需要按方法签名传入参数、解析返回结果。但黑匣子不等于不需要懂业务。实际对接时HIS至少要理解三件事卡类型决定调用哪个读卡方法医保支付办法决定HIS怎么展示自付金额编号体系决定请求和确认之间怎么关联。这三件事理解不到位后面全是要返工的坑。从业务边界看这个接口覆盖了门诊挂号收费、住院登记结算两大主线外加明细上传、对账、退款、各类查询。文档列举了16类功能从读卡到交易查询基本涵盖了医保患者在院内发生的所有交易场景。HIS侧的调用时机很明确挂号窗口收费窗口调挂号请求确认住院处调登记撤销费用发生时调明细上传出院时调住院结算。2.2 三种卡类型的接入差异芯片卡、磁条卡、电子凭证文档在名词解释里第一个就讲了卡类型这是所有接口调用前必须判断的前提条件我拆解如下芯片卡值为1保障卡或IC卡需要插入读卡机然后调用 ShYbV5_S000 获取病人基本信息。磁条卡值为0共28位直接在读卡机上刷卡即可得到卡号不需要调用解码。电子凭证值为3通过支付宝、微信、随申码等渠道获取二维码然后调用 ShYbV5_SE01 解码拿到身份证信息和 ectoken 令牌才能继续操作。这里的差异直接影响HIS前端交互设计。芯片卡和磁条卡的读卡设备不同电子凭证则需要调起手机端或扫码枪。很多项目在联调初期翻车就是没有在HIS侧统一屏蔽这些差异导致每个收费窗口的业务逻辑里散落着各种 if 判断。合格的做法是在HIS内部做一个卡类型适配层对外暴露统一的获取病人信息接口内部判断调 S000 还是 SE01。2.3 编号体系申请序号、就诊单元号、中心流水号的关系这个接口的编号体系是新手最容易绕晕的地方我用一条链路把它串起来计算申请序号jssqxh每次结算请求时中心系统返回的唯一序号HIS用它查询交易是否成功也是后续确认时必传的参数。就诊单元号jzdyh由挂号确认或住院登记产生一个就诊单元对应一段医疗服务过程。中心流水号lsh确认结算时中心系统生成的唯一流水号。明细账单号mxzdh请求明细上传时中心系统生成一次结算对应一个明细账单。举例说明患者挂普通门诊号HIS先传挂号请求 SH01中心返回申请序号再传挂号确认 SH02带上申请序号中心返回就诊单元号和中心流水号。之后该患者产生的每笔费用HIS先通过明细上传 SN01 把费用明细推给中心中心返回明细账单号等到收费结算时HIS把这些编号都带上中心才能正确组织医保结算。2.4 医保支付办法HIS展示层必须知道的规则虽然医保计算由中心系统完成但HIS的收费界面要展示当年账户支付多少、历年账户支付多少、自负段现金多少这些字段都在挂号请求的返回报文中。文档里列举了几类典型支付办法门诊普通先用当年账户再用历年账户进入自负段自负累计满后按医院级别一、二、三级分别自负10%、15%、20%。门诊大病统筹封顶线下个人自负8%封顶线上个人自负20%。家床个人自负20%。住院起付段以下个人自负以上自负8%统筹封顶线上个人自负20%。这些规则不需要HIS计算但HIS的结算界面要展示对应字段比如 curaccountpay当年账户支付数、hisaccountpay历年账户支付数、zfdxjzfs自负段现金支付数等就是把中心返回的JSON字段渲染到界面上。理解了支付办法你才知道这些返回字段的业务含义。3. 核心接口拆解一次挂号收费从进入到返回的完整链路3.1 初始化与读卡Init 与 ShYbV5_S000 的前置关系文档明确规定初始化方法需要在每个独立的操作前调用。比如挂号窗口在进行挂号请求时调用 Init那么在挂号确认时无需再次调用。这是一个很容易被忽视的状态管理问题Init 的核心作用是给医保控件赋操作员编码、姓名、交易渠道这些固定字段。Init 方法的三个参数各有讲究czybm操作员编码和 czyxm操作员姓名理论上可以从HIS登录会话中取但要注意医保中心的操作员编码和HIS的员工号未必一致通常需要在HIS里做一个对照表jyqd交易渠道传10代表线下传20代表线上诊所和互联网医院的取值不同这个参数直接关系到医保中心对交易来源的审核。读卡方法 ShYbV5_S000 比较直观不需要参数返回的是一个包含卡号、姓名、性别、身份证号、联系电话、通讯地址、邮政编码、行政区域代码的JSON字符串。返回示例{ kh: Z59898D78, xm: test, xb: 1, sfzh: 31000119500417017, lxdh: 13333333333, txdz: 上海市某区某街道, yzbm: , xzqh: 310000 }这里的 kh卡号在后续挂号请求中会作为 carddata 参数传入当卡类型为芯片卡时carddata 不传卡号而是保持为空因为中心系统已经通过读卡机获取了卡信息。这一点逻辑容易绕芯片卡的读卡动作在S000里完成挂号请求时 carddata 反而传空。3.2 电子凭证解码ShYbV5_SE01 的参数与返回电子凭证解算是电子医保凭证场景下的前置步骤。HIS前端通过支付宝、微信或随申码获取到一个二维码字符串这就是 ecQrcode 参数。还有一个 ecQrChannel 参数标识渠道来源1代表支付宝、2代表微信、3代表随申码。businessType 是用码业务类型officeId 和 officeName 是医保科室编码和名称。这个方法返回四个关键字段username姓名、idno证件号码、idtype证件类型、ecToken令牌。ecToken 是整个电子凭证流程中的核心后续挂号请求时如果卡类型传的是3电子凭证那么 carddata 字段要传的就是这个 token而不是证件号码。常见做法是SE01 解码成功后HIS前端立即把 ecToken 保存在当前会话中并设定一个合理的失效时间。实际对接中电子凭证的 token 有时效性患者扫码后在窗口排队时间过长token 可能已经失效此时需要重新解码。3.3 挂号请求与确认SH01→SH02 的两次握手挂号请求 ShYbV5_SH01 是整个门诊流程里参数最多的方法之一我挑几个容易出错的参数重点说明cardtype这是请求前必须判断好的0/1/3分别对应磁条卡、芯片卡、电子凭证。carddata磁条卡填28位卡号芯片卡为空电子凭证填token。zlxmdm诊疗项目代码挂号时对应的诊疗项目不同医院的编码体系不同需要在HIS字典表里维护映射。personspectag特殊人员标识0普通、1离休、2伤残、3干保这个值一般不存在HIS数据库而是读卡或解码后由医保中心个性化数据决定HIS界面上要允许收费员手工修正。totalexpense交易费用总额注意是数字格式不是字符串小数位要按分处理不能出现 float 精度问题。jmbz享受社区减免标志社区医院才用的到一般医院传0。返回报文是完整的一套账目结果curaccountpay、hisaccountpay、zfdxjzfs、tcdzhzfs、tczfs、fjdzhzfs、fjzfs 分别对应历年账户、当年账户、自负段现金、统筹段账户、统筹支付、附加段账户、附加支付。HIS的收费界面就是渲染这些字段。挂号确认 ShYbV5_SH02 相对简单只传一个参数 jssqxh计算申请序号就是从请求返回的 jssqxh 字段原样传回。返回的核心是 jzdyh就诊单元号和 lsh中心流水号这两个号码要在后续的收费结算中反复使用需要持久化保存不能只存在内存里。3.4 明细上传SN01 的前置条件与循环体结构文档单独提了一个要求在调用明细上传方法之前HIS需要提供一个查询病人费用明细的接口建议使用 webservice返回JSON格式。这说明明细上传不是一个孤立动作而是依赖HIS内部先完成费用明细的聚合。SN01 方法的输入参数有三个djh门诊号或住院号、jzdyh就诊单元号、jslxbz结算类型标志。jslxbz 的取值有讲究门诊120、急诊220、家床410、急观510、住院610门诊大病则是32开头后一位表示具体大病类型1化疗、2放疗、3血透、4腹透、6肾移植抗排异、7同位素、8介入、9中医药、A精神病。这个两位数字组合容易写错尤其是大病结算不能传120。费用明细查询接口的输出参数里有一个循环体结构以 xfmx 为标记表示这条明细是否还有子明细。父级明细有 xh序号子明细通过 xh 关联到上一层明细的序号。子类字段以 zl 结尾比如 mxxmbmzl子类明细项目编码、mxxmdjzl子类明细项目单价、bxbzzl子类报销标志。这个父子结构对应医保的材料费带子项场景比如一笔手术费下面挂了多个耗材明细。3.5 请求收费与结算确认从明细账单号到最终支付文档的逻辑顺序是先上传明细拿到明细账单号mxzdh再发起收费请求。SN01 的返回里有 fhm返回码、fhxx返回消息和 mxzdh本次明细上传的明细账单号这三个字段构成一次明细上传的结果。如果 fhm 不是成功码HIS不应该继续走收费请求。收费请求之后还有确认环节这是医保接口的通用模式——请求只试算确认才真正记账。HIS侧如果中途掉线或超时请求已经成功但确认未完成患者就会看到医生已经结算了但我没付钱的诡异状态。处理这类异常的办法是保存好请求返回的申请序号用交易查询方法去中心系统查这笔请求的状态再决定继续确认还是做撤销。4. 工程落地把接口文档转成可维护的调用层4.1 一个标准的接口调用封装示例按照文档语义这些方法最终是通过一个动态库类似 ShYbV5.dll暴露给HIS调用的。但在工程落地时HIS通常不会每个方法直接裸调而是在业务层做一个封装统一处理参数组装、返回解析、异常捕获和日志记录。我习惯用C#写一个客户端封装类大致结构如下public class YbV5Client { private readonly IYbV5Native _native; // 实际调用医保中心动态库的接口 private readonly ILogger _logger; public YbV5Client(IYbV5Native native, ILogger logger) { _native native; _logger logger; } // 读卡芯片卡和磁条卡统一走这里电子凭证走 DecodeQrcode public PatientInfo ReadCard() { var json _native.ShYbV5_S000(); return JsonSerializer.DeserializePatientInfo(json); } // 电子凭证解码 public EcTokenInfo DecodeQrcode(string qrcode, string channel, string bizType) { var json _native.ShYbV5_SE01(qrcode, channel, bizType, _officeId, _officeName); return JsonSerializer.DeserializeEcTokenInfo(json); } // 挂号请求组装参数并记录日志 public RegisterRequestResult RegisterRequest(RegisterRequestData data) { var json _native.ShYbV5_SH01(data.ToRequestString()); _logger.Info($挂号请求返回: {json}); var result JsonSerializer.DeserializeRegisterRequestResult(json); if (string.IsNullOrEmpty(result.Jssqxh)) { throw new YbV5Exception(挂号请求成功但未返回计算申请序号); } return result; } }封装逻辑说明ReadCard 对应文档的 ShYbV5_S000把JSON反序列化成 PatientInfo 对象HIS业务层只认对象不认字符串RegisterRequest 在调用原生方法之后立即检查 jssqxh 是否为空为空直接抛异常避免空引用蔓延到上层所有方法统一走 _logger 记录请求报文和返回报文便于联调时回溯问题。参数说明Native 接口的 ShYbV5_S000 没有参数但实际部署时它依赖读卡机驱动和医保中心端的环境配置所以封装的构造函数里接受一个 IYbV5Native 抽象方便单元测试时用 mock 实现替换真实动态库。4.2 返回码统一处理与异常边界文档没有给出完整的返回码字典但按医保接口的通用约定返回字符串里的 fhm 字段是判断成功与否的唯一依据。实际对接时HIS要定义一套统一的状态枚举public enum YbV5Status { Success 0, // 成功 NeedRetry 1, // 可重试比如网络超时 FatalError 2 // 不可重试需要人工介入 }判断逻辑fhm 为成功码且业务字段齐全时返回 Successfhm 为系统繁忙等临时性错误码时返回 NeedRetryHIS可自动重试一次fhm 为参数错误或业务校验失败时返回 FatalError直接提示收费员并按文档排查参数。注意在结算场景重试前要先用交易查询方法确认上一笔请求是否已经生效否则可能重复结算。这个查证动作很多人会漏掉等患者发现被扣两次钱就晚了。4.3 联调环境的模拟与手工验证真实对接医保中心系统需要申请测试账号和测试卡但在开发早期可以自己写一个 mock 服务来模拟中心系统的行为。mock 服务的要点是能返回固定的JSON能模拟几种异常分支比如申请序号为空、余额不足、电子凭证token过期还能记录HIS请求的参数快照方便断言。一个简单的 mock 思路是用 ASP.NET Core 写一个 Minimal API接口路径和真实动态库的方法名对应返回写死在配置里的JSON。HIS侧通过依赖注入切换真实客户端和mock客户端接口层不用改一行代码就能在本地把整个挂号收费流程跑通。手工验证的步骤建议从读卡开始先用测试卡 S000 拿到卡号再走挂号请求确认返回的 jssqxh 非空然后拿这个 jssqxh 调挂号确认最终拿到 jzdyh 和 lsh。每一步都核对返回的JSON字段和文档中的类型、长度定义。5. 实战避坑对接上海五期接口的常见问题与排查5.1 芯片卡读卡后重复调用S000导致会话状态过期现象收费员先读了芯片卡又因为界面误操作读了一次第二次挂号请求报卡信息无效或会话超时。原因S000 读卡成功后医保中心端生成了本次读卡的会话状态挂号请求 SH01 会消费这个状态。重复调用 S000 会刷新或覆盖前一次会话导致第一次读到的卡信息失效。解决HIS前端在读卡成功后做状态标记同一患者同一就诊流程内不允许重复读卡如果确实需要重新读卡后端统一先做一次会话重置操作再走新的读卡流程。5.2 挂号请求返回的申请序号丢失导致确认失败现象挂号请求成功但确认时提示申请序号不存在或该序号已使用。原因jssqxh 是一个36位以内的长字符串某些数据库字段定义成了 int超长截断或类型转换失败更常见的是HIS前端把 jssqxh 放在页面缓存里页面刷新或收费员切换窗口后丢失。解决HIS后端在请求成功后立即持久化 jssqxh和门诊号/就诊单元号绑定存储确认时从数据库读取不依赖前端传参。从那以后我每次设计医保接口调用都把请求成功的结果必须落库作为强制约束前端只传业务主键不传中心返回的序号。5.3 明细金额出现分位精度错误现象明细上传后中心系统返回金额不一致或明细金额与结算金额不匹配。原因文档里大量字段标注为数字格式但没有明确精度。常见做法是金额以分为单位上传整数但HIS内部用 float 或 double 计算后转字符串出现浮点尾差。比如 0.1 0.2 等于 0.30000000000000004转成分就是 30 分和 30.000000000000004 分的差别。解决所有金额字段统一用 decimal 类型并且在HIS内部约定以分为单位的整数传递。上传前做一个金额汇总校验把明细合计和请求收费的 totalexpense 比对误差超过1分直接拦截不放行到中心系统。5.4 明细上传成功但收费请求报无明细账单号现象SN01 返回成功但紧接着调收费请求时报未找到明细账单。原因SN01 的返回里有 fhm、fhxx 和 mxzdh 三个字段HIS只判断了 fhm 成功就继续走流程但没有保存 mxzdh或者收费请求参数里要求传明细账单号但HIS传的是空的。解决SN01 返回后除了判断返回码还要校验 mxzdh 不为空并把这个明细账单号持久化收费请求时原样透传。如果 mxzdh 为空说明明细上传实际上没有成功需要重新上传。5.5 电子凭证 token 失效导致的挂号失败现象患者用电子凭证扫码HIS已经调 SE01 解码成功并显示了患者姓名但挂号请求报令牌无效。原因ecToken 有时效解码动作和挂号动作之间间隔太久或者中间又调了一次解码导致旧 token 被覆盖。解决SE01 解码成功后立即进入挂号请求界面上减少不必要的停留如果流程需要跨页面HIS把 token 保存在服务端会话并记录解码时间超过时限自动重新解码并友好提示患者再次扫码。6. 二次开发从一份文档到一套可维护的医保对接模块6.1 建立字段映射表而不是写死结构体文档里的JSON字段是下划线命名比如 curaccountpay而HIS内部的实体类普遍是驼峰命名CurAccountPay。最省事的做法是反序列化时直接用下划线命名建类但这样会把支付宝风格的字段名散落到整个业务代码里后续HIS内部标准字段变更时牵一发动全身。我建议在对接层维护一张字段映射表把文档中的字段映射到HIS内部统一的医保结算模型。映射表可以用配置文件维护也可以做成数据库字典表这样医保中心调整字段名时只需要改映射配置不用动业务代码。6.2 构建本地模拟器跑通全流程二次开发最痛苦的是联调环境不可用。我习惯在对接层之外写一个模拟器工程用内存数据模拟中心系统的行为S000 返回一张测试卡SH01 根据参数返回对应的支付段金额SH02 返回就诊单元号SN01 返回明细账单号。模拟器对HIS的调用方是透明的切换只需要改一个配置文件。在模拟器里额外做一件事记录每一次请求的完整参数快照和返回报文输出到本地日志。联调遇到问题时直接看快照就能定位是HIS组装参数的问题还是中心系统判断的问题不用再靠收费窗口的截图来复盘。6.3 验证方法的顺序与自动化回归每次改动对接层代码后我习惯按固定顺序走一遍回归初始化→读卡→挂号请求→挂号确认→明细上传→收费请求→收费确认→对账→撤销。这九个动作覆盖了文档里90%的接口方法把回归脚本固化下来用模拟器跑一遍能发现大部分低级错误。结合模拟器日志对比每次改版前后的报文差异重点盯三个地方卡类型与 carddata 的传递逻辑是否被破坏、jssqxh 和 mxzdh 是否在流程中被正确持久化、金额字段的精度是否保持统一。这套对接模块只要按字段映射配置化、流程状态持久化、模拟器可回归三个原则来做后续医保中心升级接口规范时你只需要改映射和个别方法签名不用重写业务逻辑。现在每换一个医保项目我都是先花半天时间搭好映射表和模拟器把黑匣子变成看得见的白盒再开始碰业务代码。希望这份拆解能帮你在对接路上少走几步弯路。本文还有配套的精品资源点击获取