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

## 1. 接口概述

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

### 1.2 适用场景
- 门诊挂号、问诊、检查、治疗、结算
- 住院建档、入院登记、缴费
- 药店购药、下载外购处方

## 2. 函数接口定义

### 2.1 函数原型
```c
long WINAPI EcQuery(char* pInData, char* pOutData);
```

### 2.2 返回值
- `0` 表示成功
- `非0` 表示失败

### 2.3 内存分配要求
- `pInData`: 输入参数，JSON格式
- `pOutData`: 输出参数，建议分配8192字节内存

## 3. 输入参数规范 (pInData)

### 3.1 JSON格式结构
```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 标准输入示例
```json
{
  "data": {
    "orgId": "[医保定点编号]",
    "businessType": "01101",
    "operatorId": "test001",
    "operatorName": "超级管理员", 
    "officeId": "32760",
    "officeName": "消化内科"
  },
  "transType": "ec.query",
  "orgId": "[医保定点编号]"
}
```

## 4. 输出参数规范 (pOutData)

### 4.1 JSON格式结构
```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 标准输出示例
```json
{
  "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等敏感信息需要妥善保管
- 避免在日志中输出完整的患者信息
- 确保符合数据保护相关法规要求