4. 医保支付核心业务接口梳理
医保支付接口集成不是把若干 HTTP 地址拼在一起，而是把医院业务系统的动作翻译成医保平台能识别的交易。要理解这一层，先要抓住一个基本事实：医保侧接口大多以“交易码 + 入参 + 出参 + 状态”的方式组织，医院侧则围绕患者、就诊、费用、结算、票据这些对象组织数据。集成的核心工作，就是在两者之间建立稳定的映射关系，并保证调用顺序符合医保业务规则。
从功能上看，这些接口可以分成三类。第一类是基础数据类，包括目录下载和人员信息查询。目录下载负责把医保药品、诊疗、耗材三大目录及对应编码、自付比例、限定支付范围同步到本地，通常按版本号或增量时间拉取，医院侧要落库并保留版本，避免结算时用错目录。人员信息查询则用于挂号或结算前确认参保身份、险种类型、待遇状态，返回字段一般包含人员编号、参保地、险种、人员类别、账户余额、是否封锁等。第二类是交易结算类，包括挂号、门诊结算、住院结算和退费。第三类是核对类，主要是对账，用于日终把医院侧交易流水与医保侧结算记录逐笔比对。
挂号接口常被误解为“只是登记”。实际上它承担了医保侧的就诊登记职责：把患者本次就诊与医保人员信息绑定，生成医保就诊号，并校验该人员当前是否允许挂号。典型入参包括人员编号、就诊类型（普通门诊/急诊/门诊慢特病）、科室、医生、挂号费；出参返回医保就诊号、挂号交易流水号、基金支付与个人支付金额。挂号成功后，医院 HIS 必须把医保就诊号与院内就诊号做一对一关联，后续门诊结算、退费都依赖这个关联。
门诊结算接口是调用最频繁、也最容易出问题的一类。它接收本次就诊的处方明细，按目录逐条计算医保基金支付、个人账户支付和现金支付，返回结算编号、各支付渠道金额和医保结算信息。调用前通常要先做费用明细上传或预结算，确认无误后再正式结算。这里的关键是明细的“三对应”：院内收费项目编码对应医保目录编码、数量金额对应、科室医生对应。任何一条明细对不上，结算就可能被拒或产生基金支付偏差。
住院结算比门诊复杂，因为它跨越入院登记、费用上传、出院结算三个阶段。入院时调用住院登记接口建立医保住院号；住院期间按日或按批次上传费用明细；出院时调用住院结算接口，一次性计算起付线、分段自付、封顶线、大病保险等。住院结算的入参通常包含住院号、出院时间、费用总额、医保内费用、自费费用等，出参返回统筹支付、大病支付、救助支付、个人支付等分项。医院侧必须保证费用上传与结算的明细一致，否则会出现“结算金额与上传明细不符”的报错。
退费接口用于冲销已结算交易。它一般要求传入原结算编号或原交易流水号，并说明退费原因和退费金额。医保侧会校验原交易状态、是否已对账、是否超过退费时限。退费成功后，医院侧要同步冲销院内收费记录和票据。需要特别注意的是，退费不是简单地把钱退回去，而是产生一笔反向交易，因此对账时要把正交易和负交易配对核对。
对账接口通常在日终或次日凌晨调用。医院侧把当日所有医保交易按交易类型、结算编号、金额汇总后上传，医保侧返回对账结果，包括总笔数、总金额、平账标志和差异明细。对账不平的常见原因有：医院侧已结算但医保侧未落账、退费未同步、金额精度差异、交易重复上传。处理方式是先按结算编号逐笔比对，定位差异交易，再决定补传、冲正或人工调整。
下面这张图把上述接口按一次完整就诊的时间顺序串起来，重点表现“基础数据准备—身份确认—挂号—门诊/住院结算—退费—对账”的调用链路，以及各接口之间的依赖关系。
把这张图落到工程实现上，有几个容易踩坑的地方。第一，目录下载必须做版本管理。医保目录会随政策调整，如果医院侧不记录版本号，结算时可能用旧目录计算自付比例，导致基金支付偏差。建议在本地建一张目录版本表，记录每次下载的版本、时间和生效日期。第二，挂号与结算的就诊号必须一致。很多集成故障源于挂号返回的医保就诊号没有正确回写到 HIS 就诊记录，结算时传了院内号，医保侧查不到对应登记，直接报“无有效就诊信息”。第三，退费要判断原交易状态。如果原结算已经对账，退费可能被拒绝，需要走冲正或人工调整流程。第四，对账差异要能定位到笔。只返回“不平”没有意义，必须能按结算编号列出差异交易，才能决定补传还是冲正。
在实际项目中，建议把每个接口的入参、出参、错误码和调用前置条件整理成一张接口契约表，至少包含：接口名称、交易码、请求方式、关键入参、关键出参、前置依赖、常见错误码、重试策略。这样在联调时，遇到报错可以快速判断是参数问题、状态问题还是时序问题。例如，结算报“明细不存在”，先查费用上传是否成功；挂号报“人员封锁”，先查人员信息查询返回的待遇状态；对账报“金额不平”，先按结算编号逐笔比对正负交易。
最后要强调，医保接口的调用时序本质上反映的是医保业务规则。医院侧不能只做“转发”，而要在本地维护好就诊号映射、目录版本、费用明细和交易流水这四类数据。只有本地数据与医保侧数据保持一致，挂号、结算、退费、对账才能稳定跑通。接口集成的质量，最终体现在每一笔交易都能对上、每一笔退费都能冲掉、每一天的对账都能平掉。