简介面向医院HIS系统开发与运维人员的上海医保五期接口说明文档聚焦医保中心与HIS之间的数据交互系统讲解电子凭证解码、医保项目明细上传、挂号收费、住院结算、对账退款等核心接口的调用方式。文档共三章引言部分梳理目的、背景及卡类型、账户标志、费用结算单元等关键名词并说明医保支付办法与门诊、住院场景的结算规则业务分析覆盖读卡、解码、登记、撤销、明细上传、干保查询等十五类业务场景接口描述给出标准JSON返回报文格式并逐个说明Init、ShYbV5_S000、ShYbV5_SE01、ShYbV5_SH01等方法的参数与返回值还涉及电子凭证二维码渠道支付宝、微信、随申码的处理可作为对接开发与问题排查的直接参考。资源为单个docx文档共1个文件压缩包大小34KB内容紧凑、目录清晰。目前已有1594人学习使用适合医疗信息化工程师、医保接口对接人员快速上手与排错。1. 上海五期医保接口HIS侧对接前先搞清楚这几个概念做HIS开发的都知道医保接口是医院信息化里最玄学的环节。挂号、收费、住院结算每一笔交易背后都要跟医保中心系统来回确认任何一个字段对不上窗口就直接卡住。这份《上海五期医保接口说明》是上海医保五期开发设计的指导性文件核心思路是让HIS把医保接口当成一个“黑匣子”——HIS负责调用方法、传参医保中心系统负责算钱、记账。它覆盖了读卡、电子凭证解码、挂号请求与确认、收费请求与确认、住院登记、明细上传、结算、对账、退款等16个交易类型适合两类人读一类是HIS开发商要接上海医保五期的接口开发人员另一类是做医保对接维护、需要排查交易问题的工程师。读完你能弄明白五期接口的交易链路、核心方法怎么调、参数怎么传以及文档里没写透的边界条件。2. 业务分析先行先看懂交易边界和数据流2.1 功能清单医保接口不是结算系统是交易通道这份文档把接口定位得很清楚对于主程序而言它类似一个黑匣子只需按照约定调用相应方法即可。换句话说医保五期接口不负责你的业务流程它只负责把HIS需要的医保数据送出去、把中心系统算好的结果带回来。从第二章的功能分析看接口总共有16个能力划分成几类读卡与解码读取保障卡信息、解码电子凭证二维码挂号类挂号请求和确认区分普通、大病、工伤收费类收费请求和确认覆盖普通、大病、家床、工伤登记类住院、急观、家床、保健急观、保健入院撤销类住院、急观、家床、保健急观、保健的撤销登记结算类明细上传、明细撤销、住院结算普通、工伤查询类账户查询、登记查询、干保查询、工伤认定号查询、交易查询其他对账请求、退款请求注意这里有个设计细节挂号、收费都拆成了“请求”和“确认”两个步骤这是医保五期的典型防重复交易设计——请求阶段中心系统返回“计算申请序号”确认阶段HIS拿这个序号再去确认中心系统靠它保证同一笔交易只被确认一次。2.2 六个绕不开的名词对接前必须统一认识文档第一章花了大量篇幅解释名词这一步很多人会跳过但恰恰是联调翻车的重灾区。挑几个关键的卡类型。三个取值0为磁条卡1为芯片卡保障卡或IC卡3为电子凭证。芯片卡需要插入读卡机之后调用ShYbV5_S000获取病人基本信息磁条卡共28位直接在读卡机上刷卡就能取卡号电子凭证需要通过支付宝、微信、随申码等渠道获取二维码再调用ShYbV5_SE01解码拿到身份证信息和ectoken令牌。卡类型是很多方法的前置参数选错了后面全是错。账户标志。中心系统用16位账户标志描述人员类别比如职退情况、保健情况、特殊人员标识、医保办法等每一位都有定义。HIS侧基本不用解析它原样传给后续交易即可但联调时看返回报文要知道它的含义。计算申请序号。HIS每次向中心系统发送结算请求时中心系统返回的唯一申请序号HIS可以通过它查询交易是否成功。这个序号在挂号确认、收费确认、结算时都要原样带回属于必须持久化的关键字段。费用结算单元与中心流水号。HIS每次与中心系统进行确认结算时产生一个费用结算单元中心系统生成唯一流水号。通俗理解一次结算交易 一个费用结算单元 一个中心流水号。就诊单元号。医疗服务过程按照特定参数划分成相同部分每个部分为一个就诊单元由挂号或住院登记产生。后续的明细上传、结算都挂在这个单元下。明细账单号与费用明细单体序号。一次结算交易包含的具体费用明细称为明细账单编号为明细账单号由请求明细上传发起、中心系统生成且唯一。费用明细单体序号则是每个明细账单中的明细项编号从1开始、正整数、账单内保持唯一。2.3 数据流骨架从挂号到结算的完整链路把16个方法串起来看一次完整的门诊医保流程大概是这样的挂号窗口读卡或解码 → 调用挂号请求传总费用 → 中心系统计算各支付段金额并返回计算申请序号 → 调用挂号确认拿到就诊单元号 → 医生开单收费时先查费用明细 → 调用明细上传把明细账单发给中心 → 中心返回明细账单号 → 收费请求带上明细账单号 → 中心返回各支付段金额和新的计算申请序号 → 收费确认完成交易。住院场景多了登记与撤销登记结算时则走住院结算。这套链路里HIS自己的业务系统管门诊、住院流程医保接口只负责跟中心系统做数据交换。理解这个边界很重要明细数据从哪来、怎么保证和HIS内部数据一致是HIS侧自己的事接口文档不管。3. 核心方法拆解读卡、解码与挂号请求的完整链路3.1 初始化Init每个独立操作前的必要步骤文档里第一个方法是初始化签名如下public bool Init()参数有三个参数说明类型最大长度czybm操作员工号字符串20czyxm操作员姓名字符串100jyqd交易渠道10为线下20为线上字符串2返回true表示初始化成功false失败。这里有句话值得圈出来本方法需要在每个独立的操作前调用。比如挂号窗口在进行挂号请求的时候调用医保中心系统ShYbV5.dll那么在挂号确认时无需调用。也就是说不是每个方法调用前都要Init而是每个独立的业务操作前要Init——一次操作内部的多次交易共享一次初始化。实际开发中我一般把Init放在挂号、收费子系统的入口处窗口操作员登录后做一次而不是每次交易都初始化否则读卡器会反复建连慢且容易出问题。3.2 读卡与解码芯片、磁条、电子凭证三种入口读保障卡信息的方法public string ShYbV5_S000()无参数返回标准JSON格式字符串{ kh: Z59898D78, xm: test, xb: 1, sfzh: 31000119500417017, lxdh: 13333333333, txdz: 地址示例字段, yzbm: , xzqh: 310000 }kh是卡号、xm姓名、xb性别、sfzh身份证号、lxdh联系电话、txdz通讯地址、yzbm邮编、xzqh行政区域代码。注意这个方法只能用于芯片卡磁条卡不需要调它刷卡直接拿28位卡号。解码方法public string ShYbV5_SE01()参数参数说明类型最大长度ecQrcode电子凭证二维码值字符串80ecQrChannel获取二维码渠道1支付宝、2微信、3随申码字符串1businessType用码业务类型字符串10officeId医保科室编码字符串50officeName医保科室名称字符串50返回字段主要是username姓名、idno证件号码、idtype证件类型、ecToken令牌。这个ecToken就是后续挂号请求、收费请求里carddata要用的令牌。实际对接中要注意电子凭证二维码有有效期解码后拿到的ecToken也有使用时效HIS应该在解码后尽快发起后续交易不能把令牌存到数据库里等下班再用否则必然过期。3.3 挂号请求与确认一笔交易的完整闭环挂号请求方法public string ShYbV5_SH01()这个方法支持普通挂号、大病挂号、工伤挂号。核心入参如下cardtype卡类型0磁条卡、1芯片卡、3电子凭证carddata卡号磁条卡填28位卡号芯片卡为空电子凭证填令牌deptid科室编码zlxmdm诊疗项目代码personspectag特殊人员标识0普通、1离休、2伤残、3干保yllb医疗类别dbtype大病项目代码大病挂号填写其他可空persontype病人类型0普通、1工伤gsrdh工伤认定号工伤挂号填写totalexpense交易费用总额ybjsfwfyze医保结算范围总额zhenlf诊疗费ghf门急诊诊疗费自费fybjsfwfyze非医保结算范围总额jmbz享受社区减免标志0不享受、1享受返回报文包含大量支付段字段这是最核心的部分{ cardtype: 1, cardid: Z59898D78, personname: test, personspectag: 0, accountattr: 0101010101010101, totalexpense: 120.00, curaccountpay: 50.00, hisaccountpay: 30.00, zfdxjzfs: 20.00, curaccountamt: 300.00, hisaccountamt: 500.00, jssqxh: 20250101123456789012345678901234, jlc: 记录测号, jfje: 15.00 }curaccountpay是当年账户支付数hisaccountpay是历年账户支付数zfdxjzfs是自负段现金支付数tcdzhzfs是统筹段账户支付数、tczfs是统筹支付数jssqxh是计算申请序号jfje是减负金额。这些支付段字段直接决定窗口要向病人收多少钱HIS必须原样展示不能自己重算。挂号确认public string ShYbV5_SH02()入参只有一个jssqxh即挂号请求返回的计算申请序号。返回两个关键字段jzdyh就诊单元号和lsh中心流水号。到这里一次挂号交易才算真正落地。挂号请求时中心系统已经把支付段算好了确认只是锁定结果、生成就诊单元。如果在请求之后、确认之前窗口撤单了这笔交易就自然作废不会产生费用。但如果确认成功、拿到了就诊单元号后续的所有明细上传都挂在这个单元号下。4. 结算链路明细上传、预结算与对账4.1 明细上传的基础HIS要先提供一个费用明细查询接口文档在“明细上传”章节里有一个容易被忽略的要求在调用明细上传方法之前HIS系统需要提供一个查询病人费用明细的接口接口建议使用webservice返回json格式字符串。这个设计是有道理的。医保五期的明细上传不是HIS自己拼明细报文传给中心而是中心系统需要明细数据时主动向HIS查。所以我一般把这一步理解成“中心向HIS要明细”而不是“HIS向中心推明细”。实际操作中HIS先查自己的费用表把明细数据按文档要求的字段组织好再传给ShYbV5_SN01。明细查询接口的输出参数很长挑核心字段列一下djh门诊填写门诊号住院填写住院号xh序号cfh处方号deptid、deptname科室编码和名称cfysh、cfysxm处方医生号和姓名fylb费用类别mxxmbm、mxxmmc明细项目编码和名称mxxmdj、mxxmsl、mxxmje单价、数量、金额mxxmjyfy明细项目交易费用mxxmybjsfwfy明细项目医保结算范围费用bxbz报销标志0可报销、1不可报销、2定额sftfbz收费退费标志1收费、2退费sfxfmx是否细分明细0否、1是这里还有一个循环体设计当sfxfmx1时每个明细项目下可以挂子类明细字段以zl结尾比如mxxmbmzl、mxxmmczl、mxxmslzl、bxbzzl等。典型场景是药品拆零、材料费下挂多个部件“细分明细”就是把一条费用拆成多条子项向医保展示。4.2 明细上传与结算类型标志明细上传方法public string ShYbV5_SN01()入参就三个参数说明类型最大长度djh门诊填门诊号住院填住院号字符串34jzdyh就诊单元号字符串20jslxbz结算类型标志字符串3jslxbz是这个地方最容易写错的参数它是一个三位编码编码含义120门诊结算220急诊结算410家床结算510急观结算610住院结算32X门诊大病结算最后一位区分病种1化疗、2放疗、3血透、4腹透、6肾移植抗排异、7同位素治疗、8介入治疗、9中医药治疗、A精神病注意门诊大病是“32”开头加一位病种代码所以是三位。我见过有人把门诊大病写成320结果中心系统不认报“结算类型不合法”。文档里写了“门诊大病前两位32门诊大病结算后一位病种代码”注意后一位是字符A代表精神病不是数字。明细上传的返回值有三个fhm返回码、fhxx返回消息、mxzdh本次明细上传的明细账单号。fhm为0或空时表示成功mxzdh要保存起来后续收费请求要用。文档里有一句描述比较模糊原话是“输出参数”下面列了fhm、fhxx、mxzdh但没有明确fhm的取值字典。实际对接经验是fhm非0即为失败fhxx是失败原因。我一般会在HIS侧把fhm返回码、fhxx返回消息两个字段完整记到日志表里排查问题时直接查日志不用让窗口再复述一次报错文案。4.3 结算、撤销、对账HIS侧的收尾动作结算确认是门诊收费、住院结算的最后一步入参通常是计算申请序号加就诊单元号或者再加明细账单号中心系统返回最终的支付段金额和中心流水号。这部分文档的描述比较概括只出现在方法列表里但它其实是整个交易链路里事务性最强的一步。关于撤销明细撤销、撤销登记都是跟结算配套的。比如收费请求已经发起但发现明细传错了先做明细撤销再修正后重新上传最后再走结算。撤销的入参通常是jssqxh和/或明细账单号中心系统根据序号定位到原始交易做冲正。对账请求的作用是拉取HIS与中心系统在一段时间内的交易清单用于比对双方账单是否一致。我在项目里一般把对账做成日终任务每天晚上自动拉取当天所有医保交易跟本地T_BILLING表逐笔比对状态不一致的进入人工处理队列。文档没写对账接口的响应结构但按五期接口惯例返回的是符合条件的所有交易汇总或明细清单同样以JSON格式返回。5. 踩坑与排查文档里没写透的边界条件5.1 电子凭证令牌过期明明解码成功了挂号却报“令牌无效”现象门诊窗口用随申码扫码ShYbV5_SE01解码正常返回了username和ecToken但紧接着调ShYbV5_SH01挂号请求时中心系统返回“令牌无效”或“交易已过期”。原因ecToken不是永久有效的凭证中心系统对解码后的令牌设置了有效期。文档只写了“获取病人身份信息以及ectoken令牌后才能进行后续操作”没有明确有效时长实际联调几次后发现这个令牌按分钟级过期且一次解码对应一次交易。解决解码和挂号请求必须在同一操作流程内连续完成中间不要穿插其他业务动作。我当时的做法是窗口扫码后立即调SE01拿到ecToken不落库直接作为carddata传给SH01全程控制在几秒内。如果中间因为网络或业务弹窗卡住了宁可让病人重新扫码也不要拿着旧令牌重试。5.2 计算申请序号没保存确认交易时找不到原始请求现象挂号请求成功返回了jssqxh但没有持久化等收费确认时要用却找不到了只能让病人重新挂号窗口怨声载道。原因jssqxh是后续确认、查询交易是否成功的唯一凭证文档里写得很清楚但实际排错时发现很多HIS开发者把它当临时字段只在内存里传递进程一重启就丢了。解决把所有医保接口返回的关键字段——jssqxh、jzdyh、lsh、mxzdh——统一存到一张交易流水表里每条流水有一个本地唯一键与医保返回字段做关联。我一般给这张表加唯一索引djh jssqxh并单独记录请求报文和返回报文全文方便日终对账和异常排查。从那以后凡是从医保接口拿到的序号类字段我都默认先落库再走业务流程。5.3 支付段字段没展示窗口不知道该收病人多少钱现象挂号请求返回了一大串支付段金额HIS只取了totalexpense和jssqxh把curaccountpay、zfdxjzfs这些字段丢了导致结算时窗口跟病人对不上账。原因很多第一次接医保的开发者只关心交易通没通没意识到医保五期的返回值本身就是“中心系统算好了的账单”各支付段金额加总才是病人该付的钱。HIS如果自己重新算一遍必然跟中心对不上。解决把挂号请求、收费请求、结算返回的支付段字段原样透传到前端展示窗口界面上病人自付金额直接用医保返回的“自负段现金支付数 现金自费部分”之和不要自己做加减法。同时把所有支付段字段存入结算记录表日终对账时直接比对明细。5.4 返回报文JSON中的字段截断姓名和地址超长被切现象ShYbV5_S000返回的报文里xm字段变成了一串截断的字符串数据库中姓名字段被切了一半窗口调用建档接口时报错。原因接口间的字段长度约定不一致。医保文档规定的xm最长50位但HIS内部病人主索引表可能只留了30位直接把医保返回的字符串塞进去就截断了。txdz通讯地址80位也是同理。解决对接层做一次字段适配按HIS内部表的实际字段长度截断或做校验而不是直接把医保值塞进去。我一般会在接口封装类里加一个sanitize方法对所有字符串字段按目标表字段长度做trim和cut并记录截断日志——一旦发现截断说明HIS主数据模型可能本身就有问题该改模型而不是掩盖问题。5.5 磁条卡和芯片卡的调用顺序搞反现象用芯片卡挂号时窗口先刷了卡、然后调ShYbV5_SH01结果中心系统返回“卡信息不存在”但是换成磁条卡就正常。原因芯片卡必须先用ShYbV5_S000读卡获取病人基本信息再拿返回报文中的kh卡号去发起挂号请求。有的HIS把磁条卡和芯片卡当成同一种处理误以为直接刷卡就能获得卡号但保障卡的芯片读到的不是简单卡号还需要中心系统侧的一次验证。解决按文档的卡类型分支处理——芯片卡先S000读卡磁条卡直接取28位卡号电子凭证先SE01解码拿令牌。三种卡走三套前置流程之后才统一进入挂号请求。这个分支逻辑应该在读卡器驱动层就处理干净不要让上层业务感知卡类型的差异。6. 二次开发把这份文档落成HIS里的一个服务最后聊聊怎么基于这份文档做二次开发。我的建议是不要直接在主业务代码里到处调ShYbV5的dll方法而是做一个独立的医保接口服务层把16个方法封装成HIS内部的领域服务。核心是设计一个网关类把dll调用统一收口public class YbV5Gateway { private YbV5Api api; // 医保中心提供的dll封装 public YbTradeResult guahaoRequest(YbGuahaoReq req) { String resp api.ShYbV5_SH01(buildParams(req)); YbTradeResult result parse(resp); saveTradeLog(req, resp); // 全量落库便于排查 return result; } }所有返回报文统一走JSON解析并把fhm返回码翻译成HIS内部的业务异常。业务层只跟YbTradeResult打交道不直接接触dll方法名。另外联调阶段我强烈建议写一个模拟器。中心系统的测试环境不是随时可用的而且有些异常场景很难触发。做一个Stub实现入参和返回完全照文档的参数表来支持在配置里指定返回“令牌过期”“返回码非0”等异常就能在HIS内部先把全链路跑通。我第一次接这类接口时没有先搭桩结果联调时才发现有一堆边界条件没有处理返工成本很高。从那以后我每次接医保接口都强制先把桩搭好、把交易链路走一遍再做真环境联调。希望帮到你。本文还有配套的精品资源点击获取