mhCardReader/江苏电子凭证接口调用说明.md

江苏医保电子凭证接口调用说明

📋 快速开始

1. 必需文件

• 江苏电子凭证解码接口调用方法.cs - 核心接口代码
• HeaSecReadInfo.dll - 江苏医保DLL文件
• Newtonsoft.Json.dll - JSON处理库

2. 基本调用方式

// 方式1：简单调用（使用默认配置）
var result = JiangSuEcDecoder.DecodeElectronicCertificate("01101");

// 方式2：完整参数调用
var result = JiangSuEcDecoder.DecodeElectronicCertificate(
    businessType: "01101",      // 业务类型：门诊挂号
    operatorId: "OP001",        // 操作员编号
    operatorName: "张医生",      // 操作员姓名
    officeId: "32760",          // 科室编号
    officeName: "内科"          // 科室名称
);

3. 自定义配置

// 创建配置
var config = new JiangSuEcDecoder.JiangSuConfig
{
    IP = "192.168.1.100",                    // 医院内网IP
    ORG_ID = "H32132200561",                // 医保定点编号
    ACCESS_KEY = "your_access_key_here",     // 访问密钥
    SECRETKEY = "your_secret_key_here",      // 秘钥
    EC_URL = "http://your.server.com:10086/localcfc/api/hsecfc/localQrCodeQuery"
};

// 初始化
var initResult = JiangSuEcDecoder.Initialize(config);

// 解码
var decodeResult = JiangSuEcDecoder.DecodeElectronicCertificate("01101");

🌐 Web API集成

1. 添加控制器

将 JiangSuEcController 类添加到您的Web API项目中。

2. 接口地址

• 初始化: POST /api/jiangsuec/init
• 解码: POST /api/jiangsuec/decode

3. 前端调用示例

// 解码电子凭证
$.ajax({
    url: "http://localhost:8321/api/jiangsuec/decode",
    type: "POST",
    contentType: "application/json",
    data: JSON.stringify({
        businessType: "01101",          // 门诊挂号
        operatorId: "OP001",           // 操作员编号
        operatorName: "张医生",         // 操作员姓名
        officeId: "32760",             // 科室编号
        officeName: "内科"             // 科室名称
    }),
    success: function(result) {
        if (result.success) {
            console.log("解码成功:", result.data);
            alert("患者: " + result.data.userName + ", 身份证: " + result.data.idNo);
        } else {
            alert("解码失败: " + result.message);
        }
    }
});

📊 返回数据格式

成功返回

{
  "success": true,
  "code": 200,
  "message": "江苏医保电子凭证解码成功",
  "device": "江苏医保电子凭证解码器",
  "data": {
    "idNo": "320123199001010001",        // 身份证号
    "userName": "张三",                   // 姓名
    "idType": "01",                      // 证件类型
    "ecToken": "ADBHJRS5I01E0F3438C",    // 令牌
    "insuOrg": "320000",                 // 参保地区编码
    "gender": "1",                       // 性别
    "birthday": "1990-01-01",            // 出生日期
    "ecIndexNo": "EC123456789"           // 电子凭证索引号
  }
}

失败返回

{
  "success": false,
  "code": 1002,
  "message": "江苏医保系统未初始化，电子凭证解码失败",
  "device": "江苏医保电子凭证解码器"
}

🏷️ 业务类型编码

编码	说明	适用场景
01101	门诊挂号	预约挂号、现场挂号、取号候诊
01102	住院建档	住院登记建档
01103	入院登记	住院入院手续
01201	问诊	医生诊疗过程
01301	门诊结算	门诊费用结算
01302	取药	门诊取药、出院带药
02121	药店购药	药店零售购药

⚙️ 配置参数说明

参数	说明	示例值
IP	医保服务器IP	10.61.165.3
PORT	服务器端口	8086
ORG_ID	医保定点编号	H32132200561
ACCESS_KEY	访问密钥	向医保局申请
SECRETKEY	秘钥	向医保局申请
EC_URL	电子凭证解码URL	医保局提供

🔧 集成步骤

1. 复制文件: 将 江苏电子凭证解码接口调用方法.cs 添加到项目中
2. 引用DLL: 确保 HeaSecReadInfo.dll 在输出目录
3. 安装NuGet: Install-Package Newtonsoft.Json
4. 配置参数: 修改 JiangSuConfig 类中的默认配置
5. 调用接口: 使用 DecodeElectronicCertificate 方法

📝 注意事项

• ✅ 需要江苏医保局申请的正式密钥
• ✅ 确保网络能访问医保服务器
• ✅ DLL文件版本要与医保系统匹配
• ✅ 建议在正式环境前先测试初始化
• ✅ 异常处理要完善，记录详细日志

🆘 常见问题

错误码	说明	解决方案
1002	系统未初始化	调用Initialize方法
1003	配置信息为空	检查配置参数
2xxx	医保接口错误	检查业务参数和网络
3xxx	DLL调用错误	检查DLL文件和版本

📞 技术支持

• 接口问题：查看详细错误信息和建议
• 配置问题：联系医保局技术支持
• DLL问题：确认版本匹配性