江苏医保电子凭证解码使用手册.md 16 KB

江苏医保电子凭证解码使用手册

📖 文档说明

本文档基于《医疗保障信息平台定点基线版医药机构接口规范 v0.9.9.15》中的1.14.6电子凭证解码接口实现,提供完整的使用指南和调用示例。

版本信息:

  • 接口规范版本:v0.9.9.15
  • ThCardReader版本:2025.06.27
  • 更新日期:2025年6月27日

🚀 快速开始

1. 环境要求

  • 操作系统: Windows 10/11
  • 运行环境: .NET Framework 4.8
  • 必需DLL: HeaSecReadInfo.dll
  • 服务端口: 8321 (HTTP服务)

2. 服务启动

确保ThCardReader服务已启动:

# 方式1: 直接运行exe文件
ThCardReader.exe

# 方式2: 使用启动脚本
启动服务.bat

服务启动成功后,在浏览器访问:

http://localhost:8321/api/entry?param=test

🔗 接口调用

1. 基本调用格式

http://localhost:8321/api/entry?param=jiangsu_qrcode_[业务类型]

2. 支持的业务类型

业务代码 业务名称 应用场景 科室
门诊业务
01101 门诊挂号 患者挂号登记 挂号处
01201 门诊问诊 医生问诊记录 门诊科室
01202 预约检查 检查预约登记 门诊科室
01203 检查 各类医学检查 门诊科室
01204 治疗 医疗治疗服务 门诊科室
01301 门诊结算 门诊费用结算 门诊收费处
01302 取药 药房取药服务 门诊药房
住院业务
01102 住院建档 住院患者建档 住院处
01103 入院登记 住院登记手续 住院处
01104 缴纳预缴金 住院预缴费用 住院处
药店业务
02121 药店购药 药店零售服务 药店
02122 下载外购处方 处方下载服务 药店

3. 常用调用示例

# 门诊挂号(最常用)
http://localhost:8321/api/entry?param=jiangsu_qrcode_01101

# 门诊结算
http://localhost:8321/api/entry?param=jiangsu_qrcode_01301

# 药店购药
http://localhost:8321/api/entry?param=jiangsu_qrcode_02121

# 住院建档
http://localhost:8321/api/entry?param=jiangsu_qrcode_01102

💻 前端集成

1. 基础JavaScript调用

/**
 * 调用江苏医保电子凭证解码
 * @param {string} businessType - 业务类型代码 (如: '01101')
 * @returns {Promise<Object>} - 解码结果
 */
async function callJiangsuEcDecode(businessType) {
    const url = `http://localhost:8321/api/entry?param=jiangsu_qrcode_${businessType}`;
    
    try {
        const response = await fetch(url);
        const result = await response.json();
        
        if (result.code === 200 && result.success !== false) {
            console.log('电子凭证解码成功:', result);
            return {
                success: true,
                data: result
            };
        } else {
            console.error('电子凭证解码失败:', result.message);
            return {
                success: false,
                error: result.message,
                code: result.code
            };
        }
    } catch (error) {
        console.error('调用异常:', error);
        return {
            success: false,
            error: `网络异常: ${error.message}`
        };
    }
}

// 使用示例
async function handleRegistration() {
    const result = await callJiangsuEcDecode('01101');
    if (result.success) {
        const patientData = JSON.parse(result.data.data);
        console.log('患者信息:', patientData);
        // 处理患者信息...
    } else {
        alert('读卡失败: ' + result.error);
    }
}

2. 完整的前端工具类

/**
 * 江苏医保电子凭证解码工具类
 */
class JiangsuEcReader {
    constructor(baseUrl = 'http://localhost:8321/api/entry') {
        this.baseUrl = baseUrl;
        this.businessTypes = {
            REGISTRATION: '01101',      // 门诊挂号
            CONSULTATION: '01201',      // 门诊问诊
            SETTLEMENT: '01301',        // 门诊结算
            PHARMACY: '01302',          // 取药
            INPATIENT_FILE: '01102',    // 住院建档
            INPATIENT_REGISTER: '01103', // 入院登记
            PREPAYMENT: '01104',        // 缴纳预缴金
            STORE_PHARMACY: '02121',    // 药店购药
            PRESCRIPTION: '02122'       // 下载外购处方
        };
    }
    
    /**
     * 门诊挂号
     */
    async registration() {
        return await this.callEcDecode(this.businessTypes.REGISTRATION);
    }
    
    /**
     * 门诊结算
     */
    async settlement() {
        return await this.callEcDecode(this.businessTypes.SETTLEMENT);
    }
    
    /**
     * 药店购药
     */
    async pharmacy() {
        return await this.callEcDecode(this.businessTypes.STORE_PHARMACY);
    }
    
    /**
     * 住院建档
     */
    async inpatientFile() {
        return await this.callEcDecode(this.businessTypes.INPATIENT_FILE);
    }
    
    /**
     * 通用电子凭证解码方法
     * @param {string} businessType - 业务类型
     * @returns {Promise<Object>} - 标准化的结果对象
     */
    async callEcDecode(businessType) {
        const url = `${this.baseUrl}?param=jiangsu_qrcode_${businessType}`;
        
        try {
            const response = await fetch(url);
            const result = await response.json();
            
            if (result.code === 200) {
                // 解析患者信息
                const patientData = JSON.parse(result.data);
                
                return {
                    success: true,
                    patientInfo: {
                        idNo: patientData.idNo || '',                    // 身份证号
                        userName: patientData.userName || '',            // 姓名
                        idType: patientData.idType || '',               // 证件类型
                        ecToken: patientData.ecToken || '',             // 电子凭证令牌
                        insuOrg: patientData.insuOrg || '',             // 参保地区编码
                        ecIndexNo: patientData.ecIndexNo || '',         // 电子凭证索引号
                        gender: patientData.gender || '',               // 性别
                        birthday: patientData.birthday || '',           // 出生日期
                        nationality: patientData.nationality || '',     // 国籍
                        email: patientData.email || '',                 // 邮箱
                        extra: patientData.extra || ''                  // 扩展参数
                    },
                    businessType: result.businessType,
                    timestamp: result.timestamp,
                    device: result.device,
                    interfaceVersion: result.interfaceVersion,
                    originalData: result
                };
            } else {
                return {
                    success: false,
                    error: result.message || '电子凭证解码失败',
                    code: result.code,
                    suggestion: result.suggestion || '',
                    device: result.device || '江苏医保电子凭证解码器'
                };
            }
        } catch (error) {
            return {
                success: false,
                error: `网络异常: ${error.message}`,
                code: -1
            };
        }
    }
    
    /**
     * 检查服务状态
     */
    async checkStatus() {
        try {
            const response = await fetch(`${this.baseUrl}?param=jiangsu_status`);
            const result = await response.json();
            return result.success === true;
        } catch (error) {
            return false;
        }
    }
    
    /**
     * 系统初始化
     */
    async initialize() {
        try {
            const response = await fetch(`${this.baseUrl}?param=jiangsu_init`);
            const result = await response.json();
            return result;
        } catch (error) {
            return {
                success: false,
                error: `初始化失败: ${error.message}`
            };
        }
    }
}

// 使用示例
const ecReader = new JiangsuEcReader();

// 门诊挂号示例
ecReader.registration().then(result => {
    if (result.success) {
        console.log('患者姓名:', result.patientInfo.userName);
        console.log('身份证号:', result.patientInfo.idNo);
        console.log('参保地:', result.patientInfo.insuOrg);
    } else {
        console.error('读卡失败:', result.error);
        if (result.suggestion) {
            console.log('建议:', result.suggestion);
        }
    }
});

3. Vue.js 集成示例

// Vue 组件示例
export default {
    name: 'JiangsuEcReader',
    data() {
        return {
            loading: false,
            patientInfo: null,
            error: null
        };
    },
    methods: {
        async readElectronicCertificate(businessType = '01101') {
            this.loading = true;
            this.error = null;
            
            try {
                const url = `http://localhost:8321/api/entry?param=jiangsu_qrcode_${businessType}`;
                const response = await this.$http.get(url);
                
                if (response.data.code === 200) {
                    const patientData = JSON.parse(response.data.data);
                    this.patientInfo = {
                        name: patientData.userName,
                        idCard: patientData.idNo,
                        gender: patientData.gender === '1' ? '男' : '女',
                        birthday: patientData.birthday,
                        insuranceArea: patientData.insuOrg,
                        ecToken: patientData.ecToken
                    };
                    this.$message.success('电子凭证读取成功');
                } else {
                    this.error = response.data.message;
                    this.$message.error('读卡失败: ' + this.error);
                }
            } catch (error) {
                this.error = '网络异常: ' + error.message;
                this.$message.error(this.error);
            } finally {
                this.loading = false;
            }
        }
    }
};

📊 返回数据格式

1. 成功响应

{
  "code": 200,
  "message": "江苏医保电子凭证解码成功",
  "device": "江苏医保电子凭证解码器",
  "type": "qrcode",
  "originalType": "jiangsu_ec",
  "timestamp": "2025-06-27 10:30:00",
  "data": "{\"idNo\":\"320829199303301612\",\"userName\":\"张三\",\"idType\":\"01\",\"ecToken\":\"abc123456\",\"insuOrg\":\"320100\",\"ecIndexNo\":\"EC20250627001\",\"gender\":\"1\",\"birthday\":\"1993-03-30\",\"nationality\":\"156\",\"email\":\"\",\"extra\":\"{}\"}",
  "readCardResult": "{\"idNo\":\"320829199303301612\",\"userName\":\"张三\",\"idType\":\"01\",\"ecToken\":\"abc123456\",\"insuOrg\":\"320100\",\"ecIndexNo\":\"EC20250627001\",\"gender\":\"1\",\"birthday\":\"1993-03-30\",\"nationality\":\"156\",\"email\":\"\",\"extra\":\"{}\"}",
  "businessType": "01101",
  "interfaceVersion": "v0.9.9.15",
  "jiangsuOriginalData": "{\"code\":0,\"message\":\"success\",\"data\":{...}}"
}

2. 患者信息字段说明

字段名 类型 说明 示例值
idNo string 身份证号 "320829199303301612"
userName string 姓名 "张三"
idType string 证件类型 "01"(身份证)
ecToken string 电子凭证令牌 "abc123456"
insuOrg string 参保地区编码 "320100"
ecIndexNo string 电子凭证索引号 "EC20250627001"
gender string 性别 "1"(男)/"2"(女)
birthday string 出生日期 "1993-03-30"
nationality string 国籍 "156"(中国)
email string 邮箱 ""
extra string 扩展参数 "{}"

3. 失败响应

{
  "success": false,
  "code": 1001,
  "message": "江苏医保电子凭证业务类型【99999】无效!支持的业务类型:01101(门诊挂号)、01301(门诊结算)、02121(药店购药)等",
  "type": "qrcode",
  "device": "江苏医保电子凭证解码器"
}

4. 错误码说明

错误码范围 说明 处理建议
1xxx 系统级错误 检查初始化、配置、DLL文件
2xxx 江苏医保接口错误 检查网络、认证、参数格式
3xxx DLL调用错误 检查DLL文件、设备连接

🔧 系统管理

1. 服务状态检查

// 检查江苏医保服务状态
async function checkJiangsuStatus() {
    const response = await fetch('http://localhost:8321/api/entry?param=jiangsu_status');
    const result = await response.json();
    return result.success;
}

2. 系统初始化

// 手动初始化江苏医保系统
async function initializeJiangsu() {
    const response = await fetch('http://localhost:8321/api/entry?param=jiangsu_init');
    const result = await response.json();
    return result;
}

3. DLL文件检查

// 检查DLL文件是否存在
async function checkDllFiles() {
    const response = await fetch('http://localhost:8321/api/entry?param=jiangsu_checkdll');
    const result = await response.json();
    return result;
}

⚠️ 注意事项

1. 环境要求

  • 服务启动: 确保ThCardReader.exe已启动并运行在8321端口
  • DLL文件: 确保HeaSecReadInfo.dll文件存在于程序目录
  • 网络连接: 确保能够访问江苏医保服务器
  • 防火墙: 确保8321端口未被防火墙阻止

2. 配置要求

在实际使用前,需要正确配置以下参数:

  • ORG_ID: 医疗机构的定点编号
  • ACCESS_KEY: 江苏医保分配的访问密钥
  • SECRET_KEY: 江苏医保分配的密钥
  • 服务器地址: 江苏医保服务器IP和端口

3. 业务规范

  • 业务类型: 只能使用江苏医保规范定义的业务类型代码
  • 操作员信息: 建议根据实际情况设置操作员ID和姓名
  • 科室信息: 系统会根据业务类型自动匹配科室名称

4. 错误处理

// 推荐的错误处理方式
async function handleEcDecode(businessType) {
    try {
        const result = await callJiangsuEcDecode(businessType);
        
        if (result.success) {
            // 成功处理
            return result.data;
        } else {
            // 错误处理
            switch (result.code) {
                case 1002:
                    console.log('系统未初始化,尝试自动初始化');
                    break;
                case 1001:
                    console.log('业务类型无效:', businessType);
                    break;
                default:
                    console.log('未知错误:', result.error);
            }
            return null;
        }
    } catch (error) {
        console.error('调用异常:', error);
        return null;
    }
}

🧪 测试验证

1. 使用测试页面

# 打开测试页面
test_jiangsu_ec_decode.html

2. 浏览器测试

# 直接在浏览器访问
http://localhost:8321/api/entry?param=jiangsu_qrcode_01101

3. 命令行测试

# 使用curl测试
curl "http://localhost:8321/api/entry?param=jiangsu_qrcode_01101"

📞 技术支持

1. 常见问题

Q: 调用返回"系统未初始化"错误? A: 系统会自动初始化,如果仍有问题,请检查DLL文件和网络连接。

Q: 返回"业务类型无效"错误? A: 请使用规范定义的业务类型代码,参考本文档的业务类型表。

Q: 网络连接失败? A: 请检查江苏医保服务器地址和网络连接状态。

2. 日志查看

日志文件位置:

logs/江苏医保读卡日志_YYYYMMDD.log

3. 联系方式

如遇技术问题,请参考:

  • 接口规范文档:《医疗保障信息平台定点基线版医药机构接口规范 v0.9.9.15》
  • 实现说明文档:江苏医保电子凭证解码功能实现说明.md

文档版本: v1.0
最后更新: 2025年6月27日
适用版本: ThCardReader v2025.06.27