简介上海五期医保接口说明是面向HIS系统开发商及医保接口对接工程师的技术文档用于指导上海医保第五代接口的设计、开发与审核。文档从引言、业务分析到接口描述逐层展开既解释卡类型、账户标志、费用结算单元、就诊单元号等核心名词也覆盖读卡、解码、挂号请求、收费确认、明细上传、住院结算、对账退款、账户查询等高频业务场景并说明了医保支付办法等关键规则。接口描述部分给出了标准JSON返回报文格式对初始化、读卡、解码、挂号等具体方法的参数和返回字段做了说明可帮助开发人员快速完成HIS与医保中心系统的联调。资源包为单个DOCX文档体积仅34KB结构清晰、文字完整方便按章节检索阅读。目前已有1589人学习下载适合需要对接上海医保五期接口的前后台开发、测试及项目管理人员参考。1. 从“黑匣子”说起上海五期医保接口到底在干什么HIS 厂商第一次拿到上海五期医保接口说明最常见的感觉是“既简单又复杂”。说简单是因为整份设计文档把接口定义成了黑匣子前台程序只负责按约定调用方法、传参数、拿 JSON至于医保中心内部怎么算钱、怎么校验一概不需要关心。说复杂是因为对接过程真正卡人的地方不在接口本身而在对业务模型的理解——卡类型、就诊单元号、计算申请序号、医保支付办法这些词每个都对应一套医保侧的规则理解错了参数自然传不对。我个人的体感是五期接口适合两类人深度研读一类是做医院信息系统集成的研发需要在门诊挂号收费、住院登记结算这几个核心场景里把医保交易跑通另一类是接手维护存量医保接口、要排查对账差异的工程师。下文会围绕接口文档给出的方法描述把从读卡、解码到挂号请求、明细上传的完整链路拆开并给出可直接对照实现的参数表和代码片段重点分析那些文档里写了但没展开、或者展开得不够的边界问题。2. 五期接口的业务建模卡类型、就诊单元号与医保支付办法2.1 三类卡介质决定了三套调用起点上海五期医保接口的卡类型字段定义了三种完全不同的读卡路径芯片卡代码为 1指社会保障卡或 IC 卡需要插入读卡机然后调用ShYbV5_S000()获取病人基本信息。该方法返回的 JSON 中带有kh卡号、sfzh身份证号等字段后续交易入参要用。磁条卡代码为 0卡面共 28 位直接在读卡机上刷卡即可拿到卡号。文档特别强调“直接在读卡机上进行刷卡操作”意味着不需要调用读卡方法卡号是刷卡设备直接返回的程序只需接收卡号字符串。电子凭证代码为 3通过支付宝、微信或随申码渠道展示二维码先调用ShYbV5_SE01()解码拿到病人身份证信息以及ectoken令牌之后才能发起挂号、结算等操作。这个设计的实际影响是如果做的是线下窗口程序芯片卡和磁条卡是主流如果涉及线上挂号、移动支付场景电子凭证解码链路就是必选项。还需要注意ShYbV5_S000和ShYbV5_SE01的入参和返回结构完全不同前者不需要参数后者需要二维码值和渠道来源选错入口等同于整个链路走不通。2.2 账户标志、就诊单元号、计算申请序号文档里的名词解释部分有四个字段对开发调试最为关键。账户标志是医保中心系统返回的 16 位数字字符串用来描述人员类别比如职退情况、保健情况、特殊人员标识、医保办法等每一位有单独定义。它对 HIS 方主要是展示和记录意义HIS 一般不解析每一位的含义而是原样存储、原样上传。但遇到对账差异、报销比例异常时账户标志是定位人员类别是否被正确识别的重要线索。就诊单元号由挂号或住院登记交易产生代表了医疗服务过程的一次划分。后端结算、明细上传、退款等操作基本都要带着这个号相当于一次就诊流程的本地业务主键。计算申请序号是每次结算请求时医保中心返回的唯一序号HIS 方需要通过它来查询交易状态、发起确认结算。最容易被忽略的是请求和确认是两步一次完整的挂号或结算流程里jssqxh必须先由请求接口返回再作为确认接口的入参传回中间不能插入别的交易。2.3 医保支付办法结算时点才知道钱从哪出文档中有一段对医保支付办法的说明可以作为理解结算返回字段的参照。不同人员类别、不同就医类型的支付顺序差异很大门诊普通先用当年账户再用历年账户进入自负段自负累计满后按医院级别一、二、三级分别自负 10%、15%、20%其余由医保支付。门诊大病统筹支付封顶线以下个人自负 8%现金部分可用历年账户抵充封顶线以上个人自负 20%其余由医保附加段和地方附加段支付。大病项目代码覆盖化疗、放疗、血透、腹透、肾移植抗排异、同位素治疗、介入治疗、中医药治疗、精神病等。住院起付段以下个人自负起付段以上个人自负 8%统筹支付封顶线以上个人自负 20%其余由附加段支付。就医类型计算规则对应结算类型标志门诊普通当年账户→历年账户→自负段→按医院级别分段自负120门诊大病封顶线下个人8%线上个人20%32XX1~9、A住院起付段下全自负起付段上自负8%封顶线上自负20%610HIS 侧结算程序无需自行实现这些规则只需把费用总额上传医保中心返回各支付段金额。但测试用例设计必须覆盖这些场景否则无法验证返回的curaccountpay、hisaccountpay、zfdlnzhzfs等字段是否符合预期。比如一张普通门诊处方费用总额 300 元如果病人当年账户余额 200 元、历年账户余额 100 元预期返回应该是当年账户支付 200、历年账户支付 100各段的自负和统筹支付都是 0。如果实际返回出现统筹段金额不为 0就要优先排查病人的账户标志是否被正确识别。2.4 请求与确认拆分的业务含义五期接口几乎所有核心交易都是“请求 确认”两步式设计这在 HIS 对接里并不常见但逻辑上很有必要。挂号请求ShYbV5_SH01()负责向医保中心申请试算返回本次交易的计算申请序号以及各支付段的预估金额挂号确认ShYbV5_SH02()使用该序号正式登记返回就诊单元号和中心流水号。收费、结算同理。这种设计对 HIS 的交互流程有直接影响窗口操作员点击“挂号”按钮后界面先展示医保试算结果等病人确认支付后系统再调用确认接口完成记账。如果 HIS 把请求和确认做成一个事务在医保中心响应超时或网络中断时会非常被动——请求成功了但没确认下次再挂号可能会因为存在未完成的待确认交易而被医保中心拒绝。常见的做法是本地数据库记录jssqxh、请求时间、请求参数确认失败时提供“重发确认”按钮而不是让操作员重新发起挂号。3. 核心接口调用链从 Init、读卡、解码到挂号完成的完整实现3.1 初始化每个独立操作前都要调用Init()方法没有返回值细节上的复杂度只有三个入参czybm操作员编码、czyxm操作员姓名、jyqd交易渠道10 线下20 线上。文档特别提醒了一句话“本方法需要在每个独立的操作前调用。”比如挂号窗口在进行挂号请求时就需要调用医保中心系统那么挂号确认时就不需要再调用。这里有一个很实际的开发建议把Init()封装成医保服务类的内部方法在每个对外公开的业务方法执行入口处调用一次而不是由窗口程序自己决定何时调用这样可以避免漏调。public class ShanghaiYbService { private readonly string _czybm; private readonly string _czyxm; private readonly string _jyqd 10; // 10为线下, 20为线上 public ShanghaiYbService(string operatorCode, string operatorName) { _czybm operatorCode; _czyxm operatorName; } private bool Init() { // 传入操作员编码、姓名和交易渠道 // jyqd固定为10线下如果后续对接线上挂号则传20 return YbNative.Init(_czybm, _czyxm, _jyqd); } }在实际联调中Init()失败最常见的原因是操作员编码不存在或未在医保中心开通权限。日志中如果看到返回 false优先检查的是操作员编码是否对应到有效的医保结算人员。另外线上交易渠道传 20 时医保中心对操作员的校验会更严格部分医保类型甚至要求操作员绑定电子凭证渠道这点在文档中没有展开但集成时一定会遇到。3.2 读取保障卡信息ShYbV5_S000该方法无参数前提是读卡机中已插入芯片卡。返回的字段里kh是卡号9 位sfzh是身份证号xm是姓名xb是性别。一个值得注意的点是返回 JSON 中xm字段的值如果是中文需确认 HIS 程序的字符编码设置。{ kh: Z59898D78, xm: test, xb: 1, sfzh: 31000119500417017, lxdh: 13333333333, txdz: 上海市闵行区虹梅路, yzbm: , xzqh: 310000 }逻辑说明ShYbV5_S000是读卡系列方法里最基础的一个返回的数据主要是为了在 H I S 界面回显病人基本信息以及为后续交易填充carddata、cardtype等字段。kh在芯片卡场景下对应后续挂号请求的carddata但文档里又规定“芯片卡 carddata 为空”这意味着真正的卡号读取和传递发生在读卡机驱动层医保接口内部会自己从读卡设备取卡号HIS 侧传空字符串即可。这点如果不注意很容易把S000返回的kh填进carddata反而导致交易失败。3.3 电子凭证解码ShYbV5_SE01电子凭证场景下ShYbV5_SE01的入参有四个字段其中最容易出问题的是ecQrChannel和businessType。ecQrChannel只有三个合法值1支付宝、2微信、3随申码。这个值必须与病人出示二维码的渠道完全一致不一致时解码会失败或返回错误的身份信息。businessType是用码业务类型比如挂号、结算等场景需按字段表传值。officeId和officeName是医保科室编码和名称这两个字段在实际联调中经常被忽略传空也能调通但对医保中心的科室维度统计有影响建议从 H I S 科室表映射后传入。public String decodeEcToken(String qrcode, String channel, String bizType, String officeId, String officeName) { // channel: 1支付宝 2微信 3随申码 // bizType: 用码业务类型, 需与字段表一致 String result ybService.ShYbV5_SE01(qrcode, channel, bizType, officeId, officeName); // 返回json中ecToken为令牌, 后续挂号请求的carddata需填这个值 return result; }返回的ectoken令牌是后续操作的关键凭证它的有效期较短一般只在当次操作有效。这里有一个重要的技术决策HIS 不应缓存ectoken复用。如果病人挂号完成后操作员又发起收费此时应重新解码获取新的令牌而不是沿用之前的值。文档虽然没有明确写有效期但从接口设计惯例看令牌与业务场景绑定跨场景复用是典型的联调事故源。3.4 挂号请求与确认从试算到锁号挂号请求ShYbV5_SH01的入参比较多按用途可以分成三类病人身份类cardtype0 磁条卡、1 芯片卡、3 电子凭证、carddata磁条卡 28 位、电子凭证填令牌、芯片卡为空、personspectag0 普通、1 离休、2 伤残、3 干保、yllb医疗类别、persontype0 普通、1 工伤、gsrdh工伤认定号。业务归属类deptid科室编码、zlxmdm诊疗项目代码、dbtype大病项目代码、jmbz享受社区减免标志。费用类totalexpense交易费用总额、ybjsfwfyze医保结算范围总额、zhenlf诊疗费、ghf门急诊诊疗费自费、fybjsfwfyze非医保结算范围总额。其中dbtype是典型的大病场景字段只在门诊大病挂号时填写普通挂号传空即可。dbtype的取值与结算类型标志中的大病项目代码是对应关系例如化疗是 1、放疗是 2、血透是 3。personspectag的取值影响医保支付办法的判定离休、伤残、干保人员走的是特殊待遇通道如果 HIS 传错试算结果会与窗口人员预期不一致这类问题在联调中需要通过对比医保中心调试工具的结果来定位。ShYbV5_SH01的返回结构非常长包含了大量的支付段金额字段。判断一次请求是否成功的依据是返回码和jssqxh的生成情况拿到jssqxh后还需要检查curaccountpay、hisaccountpay、zfdlnzhzfs自负段历年账户支付数等字段是否符合医保支付办法的预期。比如普通门诊如果当年账户有余额curaccountpay应该是本次费用中先扣减的部分如果curaccountpay大于totalexpense说明入参可能传错了病人的账户信息。def guahao_confirm(jssqxh: str) - dict: 挂号确认传入请求阶段返回的计算申请序号 # jssqxh 在挂号请求返回的 json 中获取 resp yb.ShYbV5_SH02(jssqxh) data json.loads(resp) # 返回的 jzdyh 是就诊单元号, lsh 是中心流水号 # 这两个值在后续收费结算时都要作为入参 return {jzdyh: data.get(jzdyh), lsh: data.get(lsh)}挂号确认返回的jzdyh就诊单元号和lsh中心流水号在后续的明细上传、结算请求中都会用到。特别是jzdyh它是由医保中心生成的唯一标识HIS 侧每次收费、结算前都要先确认当前就诊是否有有效的jzdyh。一个容易出错的点是挂号确认成功后如果病人取消了挂号需要调用撤销登记方法而不是直接丢弃记录。否则医保中心侧会存在未撤销的占号记录病人下次挂号可能会报错。撤销登记方法的入参同样需要jzdyh或挂号相关凭证具体以文档字段表为准。4. 明细上传与结算闭环SN01 的正确打开方式4.1 费用明细的来源HIS 自己提供查询接口在调用明细上传方法之前文档明确要求“HIS 系统需要提供一个查询病人费用明细的接口。接口建议使用 webservice返回 json 格式字符串。”这说明明细上传的数据流是HIS 本地程序调用明细上传ShYbV5_SN01但SN01需要从某个数据源获取费用明细这个数据源就是 HIS 对外暴露的查询接口。换句话说医保接口模块不是直接查 HIS 数据库而是通过调用 HIS 提供的服务来取数。根据文档描述查询接口的入参是djh门诊传门诊号住院传住院号。返回字段非常丰富可以按层级拆解单据级xh序号、cfh处方号、deptid科室编码、deptname科室名称、cfysh处方医生号、cfysxm处方医生姓名。明细级fylb费用类别、mxxmbm明细项目编码、mxxmmc明细项目名称、mxxmdw单位、mxxmdj单价、mxxmsl数量、mxxmje金额、mxxmjyfy交易费用、mxxmybjsfwfy医保结算范围费用、mxxmgg规格、mxxmsyrq使用日期。报销与退费标志bxbz报销标志0 可报销、1 不可报销、2 定额、sftfbz收费退费标志1 收费、2 退费、jfbz减负标志。子类明细sfxfmx是否细分明细0 否、1 是以及以zl后缀标识的子类字段集合。这里需要理解“细分明细”的设计意图有些收费项目是汇总性质的比如“检查费”可能包含了多个子项目医保中心需要知道每个子项目的具体编码和金额。文档中sfxfmx1时xh字段存的是上一层明细的序号然后循环体内部填充子类明细的编码、名称、单价、数量、金额、报销标志等。实现时这个结构天然对应 Java/C# 中的主明细对象和子明细列表对象。public class FeeDetailDto { public string xh { get; set; } // 序号 public string cfh { get; set; } // 处方号 public string mxxmbm { get; set; } // 明细项目编码 public string mxxmmc { get; set; } // 明细项目名称 public decimal mxxmdj { get; set; } // 单价 public decimal mxxmsl { get; set; } // 数量 public decimal mxxmje { get; set; } // 金额 public string bxbz { get; set; } // 报销标志: 0可报销 1不可报销 2定额 public string sftfbz { get; set; } // 收费退费标志: 1收费 2退费 public string sfxfmx { get; set; } // 是否细分明细: 0否 1是 public ListSubFeeDetailDto children { get; set; } // sfxfmx1时的子类明细 }逻辑说明sfxfmx为 1 时xh字段的含义是“对应的上一层明细的序号”而不是本明细的序号。这意味着构建 json 时子类明细与主明细通过序号形成父子关系而不是通过嵌套数组的方式直接组合。常见的实现错误是把子类明细直接放在主明细的嵌套字段里导致医保中心解析不到正确的父子层级。正确做法是在明细循环中先输出主明细行如果sfxfmx1则在该行后面紧跟着输出对应zl后缀的子明细行子明细的xh引用主明细的xh。4.2 SN01结算类型标志是入参的“题眼”ShYbV5_SN01的入参只有三个但jslxbz的值必须精确匹配业务场景jslxbz含义120门诊结算220急诊结算410家床结算510急观结算610住院结算321门诊大病结算化疗322门诊大病结算放疗323门诊大病结算血透329门诊大病结算中医药治疗32A门诊大病结算精神病jslxbz的格式是三层语义拼接前两位 12 表示门诊、22 表示急诊、41 表示家床、51 表示急观、61 表示住院如果是门诊大病前两位是 32后一位是具体的大病项目代码1化疗、2放疗、3血透、4腹透、6肾移植抗排异、7同位素治疗、8介入治疗、9中医药治疗、A精神病。另一个入参djh在文档中的定义是“门诊填写门诊号住院填写住院号”这里要结合前文的费用明细查询接口来理解HIS 先拿djh查询费用明细再把查询结果连同djh一起上传。所以djh是明细数据和上传操作之间的关联键。如果 HIS 查询明细和上传明细之间有延迟而这期间病人又新增了费用就会造成明细不一致。常见做法是查询明细时对费用单据追加一个“医保上传中”的状态防止操作员在此期间新增费用。4.3 退费场景明细撤销与红冲文档业务分析中提到“明细撤销”方法对应到实际业务是病人退费时HIS 需要把已上传的明细在医保中心侧做撤销处理或者通过负向明细sftfbz2进行冲销。这里的关键是撤销操作必须携带原明细账单号该账单号在明细上传成功时由医保中心生成并返回。如果 HIS 没有保存这张账单号和费用明细的对应关系退费时就不知道要撤销哪些明细。我看到的很多联调事故都出在这一点上HIS 只保存了收费单据号和金额没保存医保返回的明细账单号退费时只能按金额找一旦金额相同就可能撤销到错误的明细。更稳妥的做法是在数据库设计时给收费明细表加两列yb_mxzdh医保明细账单号和yb_sftfbz医保收费退费标志。收费上传成功后立即回写账单号退费时根据原账单号调用撤销或冲销方法。另外明细上传和结算成功后的对账请求、交易查询也需要以这些记录为基础。5. 联调排错与验证五期接口上线前最容易被忽略的五个细节5.1 验证请求-确认完整链路是否真的闭环联调环境里最常见的“假阳性”是挂号请求返回了正常的试算结果但确认环节传参时漏传了jssqxh或者直接把请求返回的某个字段当成了确认入参。我的验证习惯是走完整链路而不是只测单接口磁条卡挂号请求 → 挂号确认 → 查询明细 → 明细上传 → 结算请求 → 结算确认 → 对账。只有完整跑通才能确认各接口返回的关键字段jssqxh、jzdyh、mxzdh能被正确保存并在下一步使用。5.2 检查金额字段的精度与单位五期接口的金额字段是数字格式但和数据库中的 decimal 或 float 的精度如何处理文档没有明确给出小数位数。一般医保接口默认保留两位小数传参时如果出现 300.001 这种精度医保中心会返回字段格式错误或长度超限。建议在统一入口处做金额格式化private String formatAmount(BigDecimal amount) { return amount.setScale(2, RoundingMode.HALF_UP).toPlainString(); }逻辑说明所有金额字段在拼装入参前统一保留两位小数四舍五入规则用HALF_UP避免浮点数计算产生的尾差导致医保侧校验失败。totalexpense、ybjsfwfyze、fybjsfwfyze三个字段的金额关系是totalexpense ybjsfwfyze fybjsfwfyze。如果 HIS 计算口径和医保中心不一致返回的支付段金额就会超出预期。5.3 观察返回码而不是只看是否返回 JSON文档中ShYbV5_SN01的回参里有fhm返回码和fhxx返回消息。很多方法没有在参数表里显式列出返回码字段但实际返回 JSON 里往往包含类似的结构。联调时最容易犯的错误是解析 JSON 拿到部分字段就认为调用成功没有校验返回码。一个可供参考的约定是返回码为 0 时代表成功非 0 时代表失败fhxx携带具体的错误描述。建议在封装的调用方法里统一增加返回码校验失败时抛出包含原始报文的异常。5.4 关注电子凭证解码后的令牌有效期电子凭证场景下从ShYbV5_SE01拿到的ecToken是一次性的后端需要把它和病人身份证信息、就诊单元号一起维护。如果病人拿在手里一段时间才支付结算时直接用旧令牌医保中心大概率会返回令牌失效。更稳妥的交互方案是在发起结算前重新调用一次解码方法获取新令牌虽然多一次网络开销但避免了令牌过期导致的交易失败。另外businessType如果传错比如挂号用了结算的用码业务类型医保侧可能会因业务类型不匹配而拒绝交易。5.5 善用交易查询与对账接口五期接口提供了交易查询和对账请求这两个方法在联调和线上问题排查里价值很大。当 HIS 收到的结算结果与医保中心不一致时先记下jssqxh或lsh然后主动发起交易查询以医保中心的记录为准来判断是提交参数问题还是返回解析问题而不是反复尝试重新提交。对账请求建议按日维度触发医保中心返回的文件或报文里包含每个结算单元的医保支付信息拿它与本地库的结算记录比对可以快速定位漏单、重复单和金额差异。如果本地没有独立的对账任务至少要保证每个结算单元在确认成功后立即把医保返回的全部字段存档到独立表里不要只保留金额。本文还有配套的精品资源点击获取