国家医保电子凭证刷脸授权获取医保身份接口规范.md 15 KB
国家医保电子凭证刷脸授权获取医保身份接口规范
医保网络安全和信息化标准
国家医保电子凭证业务标准动态库交互规范
发布日期： 2021-11-12
实施日期： 2021-11-12
发布机构： 国家医疗保障局网络安全和信息化领导小组办公室
📑 目录
📋 前言
本标准按照 GB/T 1.1-2020 给出的规则起草。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。
本标准由国家医疗保障局网络安全和信息化领导小组办公室提出并归口。
本标准起草单位：国家医疗保障局网络安全和信息化领导小组办公室。
1 接口概述
1.1 范围
本文档主要表述了医疗机构接入医保电子凭证业务中的刷脸授权获取医保身份接口的相关流程及接口规范。
编写该文档的目的是为接口开发人员提供详细的说明指导。
1.2 业务流程
请参考《定点医药机构对接医保业务综合服务终端接口规范》、《医疗保障信息平台定点基线版医药机构接口规范》。
1.3 接口说明
| 接口类型编码 | 接口名称 | 描述 |
|---|---|---|
cn.nhsa.auth.check |
刷脸授权获取医保身份接口 | 用于定点医药机构通过使用医保业务综合服务终端的刷脸模块，授权参保人通过刷脸进行医保身份认证。 |
2 接口规则
2.1 接口规则
表 1 接口规则
| 规则 | 规则描述 |
|---|---|
| 调用方式 | 动态库 |
| 提交方式 | 动态库接口 |
| 数据格式 | 提交和返回数据都为 JSON 格式 |
| 字符编码 | 统一采用 GB18030 字符编码 |
| 签名算法 | 请求和响应均需要签名 |
| 判断逻辑 | 先判断协议字段返回，再判断业务返回，最后判断交易状态 |
2.2 安全规范
2.2.1 日期时间格式
格式: YYYYMMDDHHMMSS
2.2.2 交易金额格式约定
交易金额默认为人民币交易，接口中参数支付金额单位为【元】。对账单中的交易金额单位为【元】。
2.2.3 医疗机构业务流水号约定
医疗机构业务流水号由医疗机构自定义生成，并要求医疗机构业务流水号保持唯一性。
建议按系统时间（YYYYMMDDHHMMSS）加 3 位随机字符串加机构编号的规则来生成流水号。
2.2.4 报文公共参数
请求报文和响应报文都由报文头和报文体(data)组成；以下是通用报文头的说明；具体报文体参数(data)详见各个业务接口说明。
⚠️ 注意： 若业务接口无特殊说明，请求报文均需要组装报文头参数，若字段的可空属性出现 N/Y 的情况，则表明需要根据具体医院来定是否必传。
2.2.4.1 请求报文
| 参数名 | 参数描述 | 类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| orgId | 机构 ID | 字符 | 40 | Y | 机构代码 |
| transType | 交易类型 | 字符 | 40 | Y | 接口交易代码 |
| data | 接口请求参数 | 字符 | 2048 | Y | JSON 格式字符串 |
| extra | 扩展参数 | 字符 | 2048 | N | JSON 格式字符串 |
2.2.4.2 返回报文
| 参数名 | 参数描述 | 类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| orgId | 机构 ID | 字符 | 40 | Y | |
| code | 返回码 | 数值 | 4 | Y | 接口返回值非 0 时，该出参为交易错误信息，详见表 6.1 返回值代码表 |
| message | 返回信息 | 字符 | 200 | N | code 非 0 时有效 |
| data | 接口响应参数 | 字符 | 2048 | Y | JSON 格式字符串 |
| extra | 扩展参数 | 字符 | 2048 | N | JSON 格式字符串 |
3 动态库说明
3.1 动态库名称
调用的动态库名称：NationECCode.dll
3.2 交易接口调用函数
函数声明： char* __stdcall NationEcTrans(char* strUrl,char* InData,char* OutData)
返回类型： 返回字符串 0000 为动态库调用成功
入参说明
| 参数名 | 参数类型 | 参数长度 | 是否允许空 | 参数说明 | 备注 |
|---|---|---|---|---|---|
| strUrl | 字符 | 2048 | N | 业务请求地址 | |
| InData | 字符 | 2048 | N | 交易请求数据 | JSON 格式字符串 |
出参说明
| 参数名 | 参数类型 | 参数长度 | 是否允许空 | 参数说明 | 备注 |
|---|---|---|---|---|---|
| OutData | 字符 | 2048 | N | 交易返回数据 | code 为 0 时，交易成功；否则返回错误信息说明 |
返回值
| 值 | 业务含义 |
|---|---|
| 0000 | 调用成功 |
| 其他 | 错误信息 |
4 刷脸授权获取医保身份接口
4.1 接口描述
用于定点医药机构通过使用医保业务综合服务终端的刷脸模块，授权参保人通过刷脸进行医保身份认证。
4.2 交易类型编码
cn.nhsa.auth.check
4.3 请求入参
请求报文头参数详见接口规则的通用请求报文头参数说明：请求入参
| 参数名 | 参数描述 | 参数类型 | 参数长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| orgId | 机构 ID | 字符 | 40 | Y | 医保定点机构代码 |
| outBizNo | 定点医药机构本次业务流水号 | 字符 | 64 | Y | 不可重复，每次请求都需要唯一 |
| authNo | 实人认证业务流水号 | 字符 | 64 | Y | 医保综合服务终端返回的授权码 |
| businessType | 用码业务类型 | 字符 | 5 | Y | 详见 5.1代码标识说明 |
| operatorId | 收款员编号 | 字符 | 20 | Y | 收款员编号 |
| operatorName | 收款员姓名 | 字符 | 30 | Y | 收款员姓名 |
| officeId | 医保科室编号 | 字符 | 20 | Y | 医保科室编号 |
| officeName | 科室名称 | 字符 | 30 | Y | 科室名称 |
| photoData | 人脸照片 | 字符 | 100k | Y | 用户的人脸照片 base64 字符串，大小控制在 100k 以下（解码时的用户快照或者实人认证照片，可根据实际情况自行判定是否传入） |
| extData | 扩展参数 | 字符 | N | 预留 json 字段 |
4.4 响应出参
data 出参：
| 参数名 | 参数描述 | 参数类型 | 参数长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| authNo | 实人认证业务流水号 | 字符 | 64 | Y | 医保综合服务终端返回的授权码 |
| idNo | 参保人身份证 | 字符 | 64 | Y | |
| idType | 证件类型 | 字符 | 64 | Y | 详见 5.2 证件类型代码表 |
| userName | 参保人姓名 | 字符 | 64 | Y | |
| ecToken | 令牌 | 字符 | 40 | Y | 用于业务处理验证 |
| insuOrg | 参保地区编码 | 字符 | 6 | Y | 详见 5.4 统筹区编码 |
| ecIndexNo | 电子凭证索引号 | 字符 | 32 | N | |
| gender | 性别 | 字符 | 2 | N | |
| birthday | 出生日期 | 字符 | 10 | N | |
| nationality | 国籍 | 字符 | 32 | N | |
| 电子邮箱 | 字符 | 32 | N | ||
| extra | 扩展参数 | 字符 | N | 预留字段 |
5 字典说明
规范数据项数据字典
5.1 代码标识说明
表 A.1 电子凭证用码业务类型表
| 第一级编码 | 第一级名称 | 第二级编码 | 第二级名称 | 第二级说明 |
|---|---|---|---|---|
| 01 | 医院 | 101 | 挂号 | 替代社保卡（预约挂号，现场挂号，取号候诊） |
| 01 | 医院 | 102 | 住院建档 | 替代身份证、社保卡 |
| 01 | 医院 | 103 | 入院登记 | 替代社保卡 |
| 01 | 医院 | 104 | 缴纳预缴金 | 替代住院押金卡 |
| 01 | 医院 | 201 | 问诊 | 替代挂号条、社保卡 |
| 01 | 医院 | 202 | 预约检查 | 替代检查凭条、社保卡 |
| 01 | 医院 | 203 | 检查 | 替代检查凭条、社保卡 |
| 01 | 医院 | 204 | 治疗 | 替代挂号条、社保卡 |
| 01 | 医院 | 301 | 结算 | 替代社保卡（门诊结算，出院结算） |
| 01 | 医院 | 302 | 取药 | 替代取药凭条、社保卡（门诊取药，出院带药） |
| 01 | 医院 | 303 | 取报告 | 替代取报告凭条 |
| 01 | 医院 | 304 | 打印票据和清单 | 替代挂号条、社保卡（打印收费清单，票据清单，结算单，异地就医结算单） |
| 01 | 医院 | 305 | 病历材料复印 | 替代身份证、社保卡（门诊和住院各类材料复印） |
| 01 | 医院 | 306 | 诊间核验身份 | 替代身份证、社保卡 |
| 02 | 药店 | 121 | 药店购药 | 替代社保卡 |
| 02 | 药店 | 122 | 下载外购处方 | 替代社保卡、身份证 |
| 02 | 药店 | 123 | 特殊门诊 | 替代社保卡 |
| 02 | 药店 | 124 | 药师审核处方 | 替代社保卡、身份证 |
| 03 | 医疗类APP | 131 | 医疗类APP线上身份认证 | 替代社保卡，目前地方医保APP都是绑定社保卡 |
| 03 | 医疗类APP | 132 | 医疗类APP线上结算 | 替代社保卡，目前地方医保APP都是绑定社保卡 |
| 05 | 柜台 | 101 | 线下修改密码 | 线下经办柜台修改/重置医保电子凭证密码 |
| 05 | 柜台 | 151 | 医保业务办理 | 线下经办柜台办理医保业务 |
💡 例如： 在医院挂号，业务类型编码为：01101
5.2 证件类型代码表
| 证件代码 | 证件说明 |
|---|---|
| 01 | 居民身份证（户口簿） |
| 02 | 中国人民解放军军官证 |
| 03 | 中国人民武装警察警官证 |
| 04 | 香港特区护照/港澳居民来往内地通行证 |
| 05 | 澳门特区护照/港澳居民来往内地通行证 |
| 06 | 台湾居民来往大陆通行证 |
| 07 | 外国人永久居留证 |
| 08 | 外国人护照 |
| 11 | 外国人就业证 |
| 12 | 外国专家证 |
| 13 | 外国人常驻记者证 |
| 14 | 台港澳人员就业证 |
| 15 | 回国（来华）定居专家证 |
| 16 | 中国护照 |
| 17 | 港澳台居民居住证 |
| 99 | 其他身份证件 |
5.3 ordStas 订单状态编码
| 订单状态 | 状态名称 | 备注 |
|---|---|---|
| 0 | 已保存 | |
| 1 | 预结算完成 | |
| 2 | 结算中 | |
| 3 | 自费完成 | |
| 4 | 医保支付完成 | |
| 5 | 院内结算完成 | |
| 6 | 结算完成 | |
| 7 | 已退款 | |
| 8 | 已医保全部退款 | |
| 9 | 仅自费全部退款 | |
| 10 | 仅自费部分退款 | |
| 11 | 医保全部退自费部分退款 | |
| 12 | 已撤销 | |
| 13 | 医保已撤销 | |
| 14 | 异常 | |
| 15 | 结算失败 | |
| 16 | 医保结算失败自费冲正失败 |
5.4 id_poolarea 统筹区编码
参照《国家医疗保障局医疗保障信息平台建设工程第 8 包基础信息管理子系统》发布的医保编码。
5.5 就诊凭证类型
| 类型代码 | 类型说明 | 备注 |
|---|---|---|
| 01A | 医保电子凭证 | 当前指医保电子凭证二维码 |
| 02A | 居民身份证 | |
| 03A | 社会保障卡 | |
| 04A | 医保刷脸 |
6 返回码说明
6.1 返回值代码表
| 错误码 | 使用范围 | 说明 |
|---|---|---|
| 0 | 系统级 | 成功 |
| -1 | 系统级 | 未知异常 |
| -2 | 系统级 | 请求参数异常 |
| -3 | 系统级 | 服务端请求超时 |
| -4 | 系统级 | 权限校验异常 |
| -5 | 系统级 | 无效的请求地址 |
| -6 | 系统级 | 触发限流 |
| 501001 | 电子凭证中心 | 二维码 Token 失效 |
| 500001 | 电子凭证中心 | 该电子凭证不存在 |
| 500002 | 电子凭证中心 | 更新电子凭证出现异常 |
| 500003 | 电子凭证中心 | 该电子凭证应用渠道未授权 |
| 500004 | 电子凭证中心 | 电子凭证密码错误 |
| 500005 | 电子凭证中心 | 展码 id 失效或已过期 |
| 500006 | 电子凭证中心 | 该电子凭证应用渠道授权记录不存在 |
| 500007 | 电子凭证中心 | 该应用渠道未授权 |
| 500008 | 电子凭证中心 | 非法授权码 |
| 500009 | 电子凭证中心 | 该授权记录已存在 |
| 500012 | 电子凭证中心 | 该应用渠道不存在 |
| 500013 | 电子凭证中心 | 该应用渠道未通过审核 |
| 500014 | 电子凭证中心 | 非法经办流水号 |
| 500015 | 电子凭证中心 | 短信验证码错误 |
| 500021 | 电子凭证中心 | 未知交易 |
| 500022 | 电子凭证中心 | 用户未授权或已过期，请重新进入 |
| 500023 | 电子凭证中心 | 缓存已过期，请重新进入 |
| 500024 | 电子凭证中心 | 需要生成的链接类型为空或不存在 |
| 500027 | 电子凭证中心 | 获取手机号出错 |
| 500028 | 电子凭证中心 | 获取实名信息出错 |
| 500030 | 电子凭证中心 | 验证码已过期，请重新获取 |
| 500032 | 电子凭证中心 | 请求缺少关键性配置 |
| 500033 | 电子凭证中心 | 请求国家电子凭证出错 |
| 500036 | 电子凭证中心 | 签名出错 |
| 500037 | 电子凭证中心 | 非法实人认证流水号 |
| 500040 | 电子凭证中心 | 该电子凭证应用渠道授权记录不存在 |
| 500041 | 电子凭证中心 | 保存电子凭证数据失败 |
| 500042 | 电子凭证中心 | 电子凭证密码未设置 |
| 500049 | 电子凭证中心 | 电子凭证二维码无效 |
| 500050 | 电子凭证中心 | 用户身份信息为空，查询人员基础 Id 失败 |
| 500051 | 电子凭证中心 | 业务流水已过期，请重新进行业务办理 |
| 500053 | 电子凭证中心 | 缺少请求地方服务配置 |
| 500054 | 电子凭证中心 | 参保地为空 |
| 500056 | 电子凭证中心 | 解除应用渠道失败 |
| 500057 | 电子凭证中心 | 接入机构不存在 |
| 500058 | 电子凭证中心 | 接入机构审核未通过 |
| 500059 | 电子凭证中心 | 经办流水号对应授权渠道不一致 |
| 500062 | 电子凭证中心 | code 不存在或已失效 |
| 500079 | 电子凭证中心 | 输入密码错误次数已达 5 次，账户已锁定，24 小时后将自动解锁或前往重置密码后手动解锁 |
| 500142 | 电子凭证中心 | 用码业务类型传输错误，请调整 |
| 500159 | 电子凭证中心 | 请使用医保电子凭证二维码 |
| 500169 | 电子凭证中心 | 医保定点机构代码不允许为空 |
| 500228 | 电子凭证中心 | 医保定点机构代码不符合标准规范，请调整 |
| 500316 | 电子凭证中心 | 医保定点机构代码传输错误，请调整 |
| 500319 | 电子凭证中心 | 通知渠道为参保人发起密码核验认证服务失败，请重试或采用线下密码核验认证 |
| 500320 | 电子凭证中心 | 该笔结算业务无需参保人输入密码，可直接办理 |
| 500321 | 电子凭证中心 | 通知渠道为参保人发起密码核验认证服务失败，该渠道暂不支持医保结算业务办理 |
📄 文档信息
- 文档版本： 2021-11-12
- 标准发布： 国家医疗保障局网络安全和信息化领导小组办公室
- 文档性质： 国家医保电子凭证刷脸授权获取医保身份接口规范
- 字符编码： GB18030
- 数据格式： JSON
⚠️ 重要提醒： 本文档涉及医保电子凭证核心业务，请严格按照规范要求进行开发和实施。