mhCardReader/江苏医保电子凭证解码接口规范.md

江苏医保电子凭证解码接口规范

1. 接口概述

1.1 功能说明

电子凭证二维码解码功能，用于解析医保电子凭证二维码，获取患者身份信息和医保凭证信息。

1.2 适用场景

• 门诊挂号、问诊、检查、治疗、结算
• 住院建档、入院登记、缴费
• 药店购药、下载外购处方

2. 函数接口定义

2.1 函数原型

long WINAPI EcQuery(char* pInData, char* pOutData);

2.2 返回值

• 0 表示成功
• 非0 表示失败

2.3 内存分配要求

• pInData: 输入参数，JSON格式
• pOutData: 输出参数，建议分配8192字节内存

3. 输入参数规范 (pInData)

3.1 JSON格式结构

{
  "data": {
    "orgId": "定点编号",
    "businessType": "用码业务类型",
    "operatorId": "收款员编号", 
    "operatorName": "收款员姓名",
    "officeId": "医保科室编号",
    "officeName": "科室名称"
  },
  "transType": "ec.query",
  "orgId": "定点编号"
}

3.2 参数详细说明

序号	字段名	字段说明	类型	长度	必填	备注
1	orgId	定点编号	字符	40	是	医疗机构在医保系统中的唯一标识
2	businessType	用码业务类型	字符	-	是	见业务类型编码表，如：01101
3	operatorId	收款员编号	字符	64	是	操作员工号
4	operatorName	收款员姓名	字符	64	是	操作员姓名
5	officeId	医保科室编号	字符	20	是	科室在医保系统中的编号
6	officeName	科室名称	字符	30	是	科室名称
7	transType	交易类型编码	字符	-	是	固定值：ec.query

3.3 标准输入示例

{
  "data": {
    "orgId": "[医保定点编号]",
    "businessType": "01101",
    "operatorId": "test001",
    "operatorName": "超级管理员", 
    "officeId": "32760",
    "officeName": "消化内科"
  },
  "transType": "ec.query",
  "orgId": "[医保定点编号]"
}

4. 输出参数规范 (pOutData)

4.1 JSON格式结构

{
  "data": {
    "idNo": "身份证号",
    "userName": "姓名",
    "idType": "证件类型",
    "ecToken": "令牌",
    "insuOrg": "参保地区编码",
    "ecIndexNo": "电子凭证索引号",
    "gender": "性别",
    "birthday": "出生日期", 
    "nationality": "国籍",
    "email": "邮箱",
    "extra": "扩展参数"
  },
  "code": 0,
  "message": "处理成功"
}

4.2 参数详细说明

序号	字段名	字段说明	类型	长度	备注
1	idNo	身份证号	字符	64	患者身份证号码
2	userName	姓名	字符	64	患者姓名
3	idType	证件类型	字符	-	见证件类型编码表
4	ecToken	令牌	字符	40	电子凭证访问令牌
5	insuOrg	参保地区编码	字符	6	患者参保地区行政区划代码
6	ecIndexNo	电子凭证索引号	字符	32	电子凭证唯一索引
7	gender	性别	字符	2	患者性别
8	birthday	出生日期	字符	10	格式：YYYY-MM-DD
9	nationality	国籍	字符	32	患者国籍
10	email	邮箱	字符	100	患者邮箱地址
11	extra	扩展参数	字符	4096	预留扩展字段
12	code	响应码	数值	-	0成功，其它值失败
13	message	错误信息	字符	1024	成功或错误描述信息

4.3 标准输出示例

{
  "data": {
    "idNo": "533222199909090123",
    "userName": "张三",
    "idType": "01",
    "ecToken": "ADBHJRS5I01E0F3438C00000B959FA88",
    "insuOrg": "430000",
    "ecIndexNo": "",
    "gender": "",
    "birthday": "",
    "nationality": "",
    "email": "",
    "extra": ""
  },
  "code": 0,
  "message": "处理成功"
}

5. 业务类型编码表

5.1 医院业务类型

一级代码	一级名称	二级代码	二级名称	说明
01	医院	101	挂号	替代社保卡（预约挂号，现场挂号，取号候诊）
		102	住院建档	替代身份证、社保卡
		103	入院登记	替代社保卡
		104	缴纳预缴金	替代住院押金卡
		201	问诊	替代挂号条、社保卡
		202	预约检查	替代检查凭条、社保卡
		203	检查	替代检查凭条、社保卡
		204	治疗	替代挂号条、社保卡
		301	结算	替代社保卡（门诊结算，出院结算）
		302	取药	替代取药凭条、社保卡（门诊取药，出院带药）
		303	取报告	替代取报告凭条
		304	打印票据和清单	替代挂号条、社保卡
		305	病历材料复印	替代身份证、社保卡

5.2 药店业务类型

一级代码	一级名称	二级代码	二级名称	说明
02	药店	121	药店购药	替代社保卡
		122	下载外购处方	替代社保卡、身份证

6. 证件类型编码表

证件代码	证件说明
01	居民身份证（户口簿）
02	中国人民解放军军官证
03	中国人民武装警察警官证
04	香港特区护照/港澳居民来往内地通行证
05	澳门特区护照/港澳居民来往内地通行证
06	台湾居民来往大陆通行证
07	外国人永久居留证
08	外国人护照
17	港澳台居民居住证
99	其他身份证件

7. 错误处理

7.1 常见错误码

• code = 0: 成功
• code != 0: 失败，具体错误信息见message字段

7.2 错误处理原则

1. 检查返回的code字段判断是否成功
2. 失败时从message字段获取错误描述
3. 成功时从data字段获取患者信息

8. 技术要求

8.1 编码格式

• 动态库的输入输出参数采用GBK编码格式

8.2 内存管理

• 调用方负责分配输出参数内存，建议8192字节
• 输入参数需确保JSON格式正确

8.3 调用顺序

1. 初始化动态库 (Init函数)
2. 调用电子凭证解码 (EcQuery函数)
3. 解析返回结果进行后续业务处理

9. 使用注意事项

9.1 必要条件

• 必须先调用Init函数初始化动态库
• 确保网络连接正常，能访问医保平台
• 确保传入的定点编号等参数正确

9.2 最佳实践

• 建议对输入参数进行校验
• 建议添加超时处理机制
• 建议记录调用日志便于问题排查
• 建议对敏感信息进行脱敏处理

9.3 安全考虑

• ecToken等敏感信息需要妥善保管
• 避免在日志中输出完整的患者信息
• 确保符合数据保护相关法规要求