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

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

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