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

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

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

📑 目录

范围
业务流程
接口列表
接口规则
- 4.1 接口规则
- 4.2 安全规范
接口说明
- 5.1 动态库名称
- 5.2 交易接口调用函数
- 5.3 电子凭证二维码解码接口
- 5.4 终端医保电子凭证码解码接口
- 5.5 刷脸授权获取医保身份接口
- 5.6 医保电子凭证密码核验接口
字典说明
返回码说明
附录 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

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

国家医保电子凭证业务标准动态库交互规范_2021-11-12.md 25 KB 永久連結 文件歷史 原始文件

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

📑 目录

📋 前言

1 范围

2 业务流程

3 接口列表

4 接口规则

4.1 接口规则

4.2 安全规范

4.2.1 日期时间格式

4.2.2 交易金额格式约定

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

4.2.4 报文公共参数

4.2.4.1 请求报文

4.2.4.2 返回报文

5 接口说明

5.1 动态库名称

5.2 交易接口调用函数

入参说明

出参说明

返回值

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

5.3.1 接口描述

5.3.2 交易类型编码

5.3.3 请求参数

5.3.4 响应参数

5.3.5 报文示例

5.3.5.1 请求参数示例（未加密）

5.3.5.2 响应参数示例（未加密）

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

5.4.1 接口描述

5.4.2 交易类型编码

5.4.3 请求入参

5.4.4 响应出参

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

5.5.1 接口描述

5.5.2 交易类型编码

5.5.3 请求入参

5.5.4 响应出参

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

5.6.1 接口描述

5.6.2 交易类型编码

5.6.3 请求入参

5.6.4 响应出参

6 字典说明

6.1 代码标识说明

6.2 证件类型代码表

6.3 ordStas 订单状态编码

6.4 id_poolarea 统筹区编码

6.5 就诊凭证类型

7 返回码说明

7.1 返回值代码表

附录 A

A.1 调用示例

C++

JAVA

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

永久連結文件歷史原始文件