国家医保电子凭证业务标准动态库交互规范_2021-11-12.md 25 KB

国家医保电子凭证业务标准动态库交互规范

医保网络安全和信息化标准
国家医保电子凭证业务标准动态库交互规范

发布日期: 2021-11-12
实施日期: 2021-11-12
发布机构: 国家医疗保障局网络安全和信息化领导小组办公室


📑 目录

  1. 范围
  2. 业务流程
  3. 接口列表
  4. 接口规则
  5. 接口说明
  6. 字典说明
  7. 返回码说明
  8. 附录 A

📋 前言

本标准按照 GB/T 1.1-2020 给出的规则起草。

请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。

本标准由国家医疗保障局网络安全和信息化领导小组办公室提出并归口。

本标准起草单位:国家医疗保障局网络安全和信息化领导小组办公室。


1 范围

本文档主要表述了医疗机构接入医保电子凭证业务的相关流程及接口。

编写该文档的目的是为接口开发人员提供详细的说明指导。


2 业务流程

请参考《定点医药机构对接医保业务综合服务终端接口规范》、《医疗保障信息平台定点基线版医药机构接口规范》。


3 接口列表

接口类型编码 接口名称 描述
ec.query 电子凭证二维码解码接口 用于电子凭证二维码解码
cn.nhsa.qrcode.get 终端医保电子凭证码解码接口 用于定点医疗药机构通过使用医保业务综合服务终端集成的扫码设备模块获取医保电子凭证二维码码值后,通过电子凭证中台完成解码。
cn.nhsa.auth.check 刷脸授权获取医保身份接口 用于定点医药机构通过使用医保业务综合服务终端的刷脸模块,授权参保人通过刷脸进行医保身份认证。
cn.nhsa.ec.pwd 医保电子凭证密码核验接口 用于电子凭证密码核验

4 接口规则

4.1 接口规则

表 1 接口规则

规则 规则描述
调用方式 动态库
提交方式 动态库接口
数据格式 提交和返回数据都为 JSON 格式
字符编码 统一采用 GB18030 字符编码
签名算法 请求和响应均需要签名
判断逻辑 先判断协议字段返回,再判断业务返回,最后判断交易状态

4.2 安全规范

4.2.1 日期时间格式

格式: YYYYMMDDHHMMSS

4.2.2 交易金额格式约定

交易金额默认为人民币交易,接口中参数支付金额单位为【元】。对账单中的交易金额单位为【元】。

4.2.3 医疗机构业务流水号约定

医疗机构业务流水号由医疗机构自定义生成,并要求医疗机构业务流水号保持唯一性。

建议按系统时间(YYYYMMDDHHMMSS)加 3 位随机字符串加机构编号的规则来生成流水号。

4.2.4 报文公共参数

请求报文和响应报文都由报文头和报文体(data)组成;以下是通用报文头的说明;具体报文体参数(data)详见各个业务接口说明。

⚠️ 注意: 若业务接口无特殊说明,请求报文均需要组装报文头参数,若字段的可空属性出现 N/Y 的情况,则表明需要根据具体医院来定是否必传。

4.2.4.1 请求报文
参数名 参数描述 类型 长度 是否必填 备注
orgId 机构 ID 字符 40 Y 机构代码
transType 交易类型 字符 40 Y 接口交易代码
data 接口请求参数 字符 2048 Y JSON 格式字符串
extra 扩展参数 字符 2048 N JSON 格式字符串
4.2.4.2 返回报文
参数名 参数描述 类型 长度 是否必填 备注
orgId 机构 ID 字符 40 Y
code 返回码 数值 4 Y 接口返回值非 0 时,该出参为交易错误信息,详见表 7.1 返回值代码表
message 返回信息 字符 200 N code 非 0 时有效
data 接口响应参数 字符 2048 Y JSON 格式字符串
extra 扩展参数 字符 2048 N JSON 格式字符串

5 接口说明

5.1 动态库名称

调用的动态库名称:NationECCode.dll

5.2 交易接口调用函数

函数声明: char* __stdcall NationEcTrans(char* strUrl,char* InData,char* OutData)

返回类型: 返回字符串 0000 为动态库调用成功

入参说明

参数名 参数类型 参数长度 是否允许空 参数说明 备注
strUrl 字符 2048 N 业务请求地址
InData 字符 2048 N 交易请求数据 JSON 格式字符串

出参说明

参数名 参数类型 参数长度 是否允许空 参数说明 备注
OutData 字符 2048 N 交易返回数据 code 为 0 时,交易成功;否则返回错误信息说明

返回值

业务含义
0000 调用成功
其他 错误信息

5.3 电子凭证二维码解码接口

5.3.1 接口描述

用于电子凭证二维码解码。

5.3.2 交易类型编码

ec.query

5.3.3 请求参数

请求报文头参数详见接口规则的通用请求报文头参数说明:请求入参

参数名 参数描述 参数类型 参数长度 是否必填 备注
orgId 机构 ID 字符 40 Y 医保定点机构代码
businessType 用码业务类型 字符 5 Y 详见 6.1 代码标识说明
operatorId 收款员编号 字符 20 Y 收款员编号
operatorName 收款员姓名 字符 30 Y 收款员姓名
officeId 医保科室编号 字符 20 Y 医保科室编号
officeName 科室名称 字符 30 Y 科室名称
deviceType 设备类型 字符 30 N 自助机该字段设为 SelfService,其它情况不用设置
photoData 人脸照片 字符 100k N 用户的人脸照片 base64 字符串,大小控制在 100k 以下(解码时的用户快照或者实人认证照片,可根据实际情况自行判定是否传入)

5.3.4 响应参数

data 出参:

参数名 参数描述 参数类型 参数长度 是否必填 备注
idNo 参保人身份证 字符 64 Y
idType 证件类型 字符 64 Y 详见 6.2 证件类型代码表
userName 参保人姓名 字符 64 Y
ecToken 令牌 字符 40 Y 用于业务处理验证
insuOrg 参保地区编码 字符 6 Y 详见 6.4 统筹区编码
ecIndexNo 电子凭证索引号 字符 32 N
gender 性别 字符 2 N
birthday 出生日期 字符 10 N
nationality 国籍 字符 32 N
email 电子邮箱 字符 32 N
extra 扩展参数 字符 N 预留字段

5.3.5 报文示例

5.3.5.1 请求参数示例(未加密)

入参报文:

{
  "data": {
    "operatorId": "008",
    "operatorName": "TEST",
    "officeId": "01",
    "officeName": "内科",
    "orgId": "1234567",
    "businessType": "01101",
    "deviceType": ""
  },
  "orgId": "1234567",
  "transType": "ec.query"
}
5.3.5.2 响应参数示例(未加密)
{
  "data": {
    "extra": "",
    "idNo": "533222199909090123",
    "idType": "01",
    "ecToken": "ADBHJRS5I01E0F3438C00000B959FA88",
    "insuOrg": "430000",
    "userName": "张三",
    "ecIndexNo": "",
    "gender": "",
    "birthday": "",
    "nationality": "",
    "email": ""
  },
  "code": 0,
  "message": "处理成功"
}

5.4 终端医保电子凭证码解码接口

5.4.1 接口描述

用于定点医疗药机构通过使用医保业务综合服务终端集成的扫码设备模块获取医保电子凭证二维码码值后,通过电子凭证中台完成解码。

5.4.2 交易类型编码

cn.nhsa.qrcode.get

5.4.3 请求入参

请求报文头参数详见接口规则的通用请求报文头参数说明:请求入参

参数名 参数描述 参数类型 参数长度 是否必填 备注
orgId 机构 ID 字符 40 Y 医保定点机构代码
outBizNo 定点医药机构本次业务流水号 字符 64 Y 不可重复,每次请求都需要唯一
businessType 用码业务类型 字符 5 Y 详见6.1代码标识说明
operatorId 收款员编号 字符 20 Y 收款员编号
operatorName 收款员姓名 字符 30 Y 收款员姓名
officeId 医保科室编号 字符 20 Y 医保科室编号
officeName 科室名称 字符 30 Y 科室名称
photoData 人脸照片 字符 100k N 用户的人脸照片 base64 字符串,大小控制在 100k 以下(解码时的用户快照或者实人认证照片,可根据实际情况自行判定是否传入)
extData 扩展参数 字符 N 预留 json 字符

5.4.4 响应出参

data 出参:

参数名 参数描述 参数类型 参数长度 是否必填 备注
idNo 参保人身份证 字符 64 Y
idType 证件类型 字符 64 Y 详见 6.2 证件类型代码表
userName 参保人姓名 字符 64 Y
ecToken 令牌 字符 40 Y 用于业务处理验证
insuOrg 参保地区编码 字符 6 Y 详见 6.4 统筹区编码
ecIndexNo 电子凭证索引号 字符 32 N
gender 性别 字符 2 N
birthday 出生日期 字符 10 N
nationality 国籍 字符 32 N
email 电子邮箱 字符 32 N
extra 扩展参数 字符 N 预留字段

5.5 刷脸授权获取医保身份接口

5.5.1 接口描述

用于定点医药机构通过使用医保业务综合服务终端的刷脸模块,授权参保人通过刷脸进行医保身份认证。

5.5.2 交易类型编码

cn.nhsa.auth.check

5.5.3 请求入参

请求报文头参数详见接口规则的通用请求报文头参数说明:请求入参

参数名 参数描述 参数类型 参数长度 是否必填 备注
orgId 机构 ID 字符 40 Y 医保定点机构代码
outBizNo 定点医药机构本次业务流水号 字符 64 Y 不可重复,每次请求都需要唯一
authNo 实人认证业务流水号 字符 64 Y 医保综合服务终端返回的授权码
businessType 用码业务类型 字符 5 Y 详见 6.1代码标识说明
operatorId 收款员编号 字符 20 Y 收款员编号
operatorName 收款员姓名 字符 30 Y 收款员姓名
officeId 医保科室编号 字符 20 Y 医保科室编号
officeName 科室名称 字符 30 Y 科室名称
photoData 人脸照片 字符 100k Y 用户的人脸照片 base64 字符串,大小控制在 100k 以下(解码时的用户快照或者实人认证照片,可根据实际情况自行判定是否传入)
extData 扩展参数 字符 N 预留 json 字段

5.5.4 响应出参

data 出参:

参数名 参数描述 参数类型 参数长度 是否必填 备注
authNo 实人认证业务流水号 字符 64 Y 医保综合服务终端返回的授权码
idNo 参保人身份证 字符 64 Y
idType 证件类型 字符 64 Y 详见 6.2 证件类型代码表
userName 参保人姓名 字符 64 Y
ecToken 令牌 字符 40 Y 用于业务处理验证
insuOrg 参保地区编码 字符 6 Y 详见 6.4 统筹区编码
ecIndexNo 电子凭证索引号 字符 32 N
gender 性别 字符 2 N
birthday 出生日期 字符 10 N
nationality 国籍 字符 32 N
email 电子邮箱 字符 32 N
extra 扩展参数 字符 N 预留字段

5.6 医保电子凭证密码核验接口

5.6.1 接口描述

用于电子凭证密码核验。

5.6.2 交易类型编码

cn.nhsa.ec.pwd

5.6.3 请求入参

请求报文头参数详见接口规则的通用请求报文头参数说明:请求入参

参数名 参数描述 参数类型 参数长度 是否必填 备注
orgId 机构 ID 字符 40 Y 医保定点机构代码
idNo 人员证件号码 字符 30 Y
idType 人员证件类型 字符 3 Y
userName 人员姓名 字符 50 Y
businessType 办理业务类型 字符 6 Y 详见 6.1 代码标识说明
ecToken 身份核验令牌 字符 50 N 若是采用二维码解析用户身份,则须传递
operatorId 收款员编号 字符 20 Y 收款员编号
operatorName 收款员姓名 字符 30 Y 收款员姓名
officeId 医保科室编号 字符 20 Y 医保科室编号
officeName 科室名称 字符 30 Y 科室名称
mdtrtCertType 就诊凭证类型 字符 3 Y 详见 6.5 就诊凭证类型
deviceType 设备类型 字符 30 N 刷脸终端该字段设为 FaceTerminal,其它情况不用设置
extData 扩展参数 字符 Y 预留 json 字段

5.6.4 响应出参

data 出参:

参数名 参数描述 参数类型 参数长度 是否必填 备注
pwdFlag 密码核验结果 字符 2 Y 1-有效;0-无效
ecToken 身份核验令牌 字符 50 Y
extra 扩展参数 字符 N 预留字段

6 字典说明

规范数据项数据字典

6.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

6.2 证件类型代码表

证件代码 证件说明
01 居民身份证(户口簿)
02 中国人民解放军军官证
03 中国人民武装警察警官证
04 香港特区护照/港澳居民来往内地通行证
05 澳门特区护照/港澳居民来往内地通行证
06 台湾居民来往大陆通行证
07 外国人永久居留证
08 外国人护照
11 外国人就业证
12 外国专家证
13 外国人常驻记者证
14 台港澳人员就业证
15 回国(来华)定居专家证
16 中国护照
17 港澳台居民居住证
99 其他身份证件

6.3 ordStas 订单状态编码

订单状态 状态名称 备注
0 已保存
1 预结算完成
2 结算中
3 自费完成
4 医保支付完成
5 院内结算完成
6 结算完成
7 已退款
8 已医保全部退款
9 仅自费全部退款
10 仅自费部分退款
11 医保全部退自费部分退款
12 已撤销
13 医保已撤销
14 异常
15 结算失败
16 医保结算失败自费冲正失败

6.4 id_poolarea 统筹区编码

参照《国家医疗保障局医疗保障信息平台建设工程第 8 包基础信息管理子系统》发布的医保编码。

6.5 就诊凭证类型

类型代码 类型说明 备注
01A 医保电子凭证 当前指医保电子凭证二维码
02A 居民身份证
03A 社会保障卡
04A 医保刷脸

7 返回码说明

7.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 电子凭证中心 通知渠道为参保人发起密码核验认证服务失败,该渠道暂不支持医保结算业务办理

附录 A

(规范性附录)
规范数据项数据字典

A.1 调用示例

C++

// Trans 
HMODULE Handle = NULL;
char* (__stdcall * NationEcTrans)(char *strUrl,char *pindata,char *poutdata);

Handle = LoadLibrary("NationECCode.dll");
if(Handle != NULL){ //获取接口
    NationEcTrans = (char* (__stdcall * )(char*,char *,char *))GetProcAddress(Handle,"NationEcTrans");
    if(NationEcTrans!=NULL){
        Json::Value root;
        Json::Value param;
        Json::FastWriter writer;
        
        param["orgId"]="35020311234";
        param["businessType"]="01101";
        param["operatorId"]="test001";
        param["operatorName"]="管理员";
        param["officeId"]="45678";
        param["officeName"]="消化内科";
        param["deviceType"]="SelfService";
        
        root["data"] = param;
        std::string sReq = writer.write(root);
        memcpy(in_data, sReq.c_str(), sReq.size());
        
        transret = NationEcTrans(strUrl, in_data, out_data);
        string sResp(transret); 
        if(sResp == "0000")
        {
            Json::Value value;
            std::string sOut(out_data);
            if (Json::Reader().parse(sOut, value) && value.isObject())
            {
                int sFlag = value["code"].asInt();
                string sCase = value["cause"].asString();
                if (sFlag != 0){
                    return;
                }
                if (!value.isMember("data")){
                    return;
                }
                Json::Value data = value["data"];
                //Todo 处理返回数据
            }
            return;
        }
    }
}

JAVA

package com.ylzinfo;

import com.sun.jna.Library;
import com.sun.jna.Native;
import com.sun.jna.Pointer;
import com.sun.jna.Memory;

public interface EcDll extends Library {
    EcDll instance = Native.load("NationECCode", EcDll.class);
    String NationEcTrans(String strUrl, String InData, Pointer OutData);
}

public class Main {
    public static void main(String[] args) {
        //load require dll
        Native.load("libeay32", EcDll.class);
        Native.load("ssleay32", EcDll.class);
        
        Pointer rsStr = new Memory(1024 * 10);
        String rs = EcDll.instance.NationEcTrans(
            "https://****/localcfc/api/hsecfc/localQrCodeQuery",
            "{\"data\":{\"businessType\":\"01101\",\"deviceType\":\"\",\"officeId\":\"32760\",\"officeName\":\"123\",\"operatorId\":\"test001\",\"operatorName\":\"456\",\"orgId\":\"35020319001\"},\"orgId\":\"35020319001\",\"transType\":\"ec.query\"}",
            rsStr
        );
        
        String rsStrString = rsStr.getString(0, "GB18030");
        System.out.println(rsStrString);
        System.out.println(rs);
    }
}

📄 文档信息

  • 文档版本: 2021-11-12
  • 标准发布: 国家医疗保障局网络安全和信息化领导小组办公室
  • 文档性质: 国家医保电子凭证业务标准动态库交互规范
  • 字符编码: GB18030
  • 数据格式: JSON

⚠️ 重要提醒: 本文档涉及医保电子凭证核心业务,请严格按照规范要求进行开发和实施。