ThCardReader 使用说明文档

📋 目录

功能概述
华视读身份证功能
江苏医保读社保卡功能
接口调用示例
错误处理
常见问题

🎯 功能概述

ThCardReader是一个读卡服务程序，提供HTTP接口用于读取各种证件信息。本版本支持：

华视读身份证功能：通过华视电子身份证读卡器读取身份证信息
江苏医保读社保卡功能：通过江苏医保接口读取社保卡信息

服务信息

服务地址：http://localhost:8321
协议：HTTP/1.1
数据格式：JSON
字符编码：UTF-8

🆔 华视读身份证功能

功能描述

通过华视电子身份证读卡器读取二代身份证信息，包括基本信息和照片数据。

硬件要求

华视电子身份证读卡器（USB接口）
USB连接：确保读卡器正确连接并安装驱动

API接口

1. 初始化华视读卡器

GET /readcard/entry?param=huashi_init_1001

参数说明：

1001：USB端口号（1001-1016）

返回示例：

{
  "code": 200,
  "message": "华视读卡器初始化成功",
  "device": "华视电子身份证读卡器",
  "port": 1001
}

2. 读取身份证信息

GET /readcard/entry?param=huashi_readcard

返回示例：

{
  "code": 200,
  "type": "idcard",
  "data": "张三^男^汉^19900101^北京市朝阳区某某街道^公安部门^20200101-20300101^",
  "message": "读取身份证成功。"
}

数据格式说明：

data字段用"^"分隔，包含以下信息：
[0] 姓名
[1] 性别
[2] 民族
[3] 出生日期
[4] 地址
[5] 签发机关
[6] 有效期（开始日期-结束日期）
[7] 照片Base64数据（可选）

3. 连续读卡模式

GET /readcard/entry?param=huashi_continuous

4. 获取设备状态

GET /readcard/entry?param=huashi_status

5. 关闭连接

GET /readcard/entry?param=huashi_close

专用API接口

简化调用方式

GET /readcard/huashi/simple?action=readcard&port=1001

POST方式调用

POST /readcard/huashi/readcard
Content-Type: application/json

{
  "savePath": "",
  "autoClose": true
}

🏥 江苏医保读社保卡功能

功能描述

通过江苏医保接口读取社保卡基本信息，支持自动初始化和PIN码验证。

硬件要求

江苏医保社保卡读卡器
网络连接：部分功能需要连接江苏医保平台

API接口

1. 自动初始化读社保卡（推荐）

GET /readcard/jiangsu/readcard_auto

特点：

自动检测初始化状态
如未初始化，自动执行初始化
一步完成读卡操作

返回示例：

{
  "success": true,
  "code": 200,
  "message": "社保卡读取成功",
  "device": "江苏医保社保卡读卡器",
  "interface": "江苏医保接口 v0.9.9.15",
  "interfaceType": "medical",
  "initMode": "auto",
  "autoInitSuccess": true,
  "data": {
    "cardInfo": "639900|111111198101011110|X00000019|...",
    "busiInfo": "业务信息数据",
    "name": "张三",
    "idCard": "111111198101011110",
    "cardNumber": "X00000019"
  },
  "timestamp": "2024-01-01 10:00:00"
}

2. 带PIN验证的自动读卡

GET /readcard/jiangsu/readcard_auto_pin

3. 手动初始化

GET /readcard/jiangsu/init

4. 传统读卡方式

GET /readcard/jiangsu/readcard

5. 设备状态查询

GET /readcard/jiangsu/status

6. PIN码验证

GET /readcard/jiangsu/verifypin

7. PIN码修改

GET /readcard/jiangsu/changepin

POST方式调用

带参数的读卡请求

POST /readcard/jiangsu
Content-Type: application/json

{
  "action": "readcard",
  "autoVerifyPIN": false,
  "autoInit": true
}

自定义初始化配置

POST /readcard/jiangsu
Content-Type: application/json

{
  "action": "init",
  "config": {
    "IP": "10.61.165.3",
    "PORT": 8086,
    "TIMEOUT": 30,
    "ACCESS_KEY": "your_access_key",
    "SECRETKEY": "your_secret_key",
    "ORG_ID": "H32132200561",
    "AREA_CODE": "321322"
  }
}

数据格式说明

社保卡数据格式（标准38号文）

639900|111111198101011110|X00000019|639900D15600000500BF7C7A48FB4966|张三|00814E43238697159900BF7C7A|1.00|20101001|20201001|410100813475|终端设备号|

字段说明：
[0] 发卡地区行政区划代码
[1] 社会保障号码（身份证号）
[2] 卡号
[3] 卡识别码
[4] 姓名
[5] 卡复位信息
[6] 规范版本
[7] 发卡日期
[8] 卡有效期
[9] 终端机编号
[10] 终端设备号

💻 接口调用示例

JavaScript调用示例

华视读身份证

// 读取身份证
async function readIdCard() {
    try {
        const response = await fetch('http://localhost:8321/readcard/entry?param=huashi_readcard');
        const data = await response.json();
        
        if (data.code === 200) {
            // 解析身份证数据
            const idInfo = data.data.split('^');
            console.log('姓名:', idInfo[0]);
            console.log('性别:', idInfo[1]);
            console.log('民族:', idInfo[2]);
            console.log('出生日期:', idInfo[3]);
            console.log('地址:', idInfo[4]);
        } else {
            console.error('读卡失败:', data.message);
        }
    } catch (error) {
        console.error('请求异常:', error);
    }
}

江苏医保读社保卡

// 自动初始化读社保卡
async function readSocialCard() {
    try {
        const response = await fetch('http://localhost:8321/readcard/jiangsu/readcard_auto');
        const data = await response.json();
        
        if (data.success) {
            console.log('读卡成功:', data.data);
            if (data.autoInitSuccess) {
                console.log('已自动完成初始化');
            }
        } else {
            console.error('读卡失败:', data.message);
        }
    } catch (error) {
        console.error('请求异常:', error);
    }
}

// POST方式调用
async function readSocialCardWithPost() {
    try {
        const response = await fetch('http://localhost:8321/readcard/jiangsu', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                action: 'readcard',
                autoVerifyPIN: false,
                autoInit: true
            })
        });
        
        const data = await response.json();
        console.log('读卡结果:', data);
    } catch (error) {
        console.error('请求异常:', error);
    }
}

C# 调用示例

华视读身份证

using System.Net.Http;
using Newtonsoft.Json.Linq;

// 读取身份证
private async Task<JObject> ReadIdCardAsync()
{
    using (var client = new HttpClient())
    {
        string url = "http://localhost:8321/readcard/entry?param=huashi_readcard";
        string response = await client.GetStringAsync(url);
        return JObject.Parse(response);
    }
}

// 解析身份证数据
private void ParseIdCardData(JObject result)
{
    if ((int)result["code"] == 200)
    {
        string[] idInfo = result["data"].ToString().Split('^');
        string name = idInfo[0];      // 姓名
        string gender = idInfo[1];    // 性别
        string nation = idInfo[2];    // 民族
        string birthday = idInfo[3];  // 出生日期
        string address = idInfo[4];   // 地址
    }
}

江苏医保读社保卡

// 自动初始化读社保卡
private async Task<JObject> ReadSocialCardAsync()
{
    using (var client = new HttpClient())
    {
        string url = "http://localhost:8321/readcard/jiangsu/readcard_auto";
        string response = await client.GetStringAsync(url);
        return JObject.Parse(response);
    }
}

// POST方式调用
private async Task<JObject> ReadSocialCardWithPostAsync()
{
    using (var client = new HttpClient())
    {
        var requestData = new
        {
            action = "readcard",
            autoVerifyPIN = false,
            autoInit = true
        };
        
        var json = JsonConvert.SerializeObject(requestData);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync("http://localhost:8321/readcard/jiangsu", content);
        var responseContent = await response.Content.ReadAsStringAsync();
        
        return JObject.Parse(responseContent);
    }
}

Java 调用示例

// 使用 OkHttp 库
import okhttp3.*;
import com.google.gson.Gson;

public class CardReader {
    private static final String BASE_URL = "http://localhost:8321";
    private OkHttpClient client = new OkHttpClient();
    private Gson gson = new Gson();
    
    // 华视读身份证
    public void readIdCard() throws IOException {
        Request request = new Request.Builder()
            .url(BASE_URL + "/readcard/entry?param=huashi_readcard")
            .build();
            
        try (Response response = client.newCall(request).execute()) {
            String responseBody = response.body().string();
            // 处理返回数据
            System.out.println(responseBody);
        }
    }
    
    // 江苏医保读社保卡
    public void readSocialCard() throws IOException {
        Request request = new Request.Builder()
            .url(BASE_URL + "/readcard/jiangsu/readcard_auto")
            .build();
            
        try (Response response = client.newCall(request).execute()) {
            String responseBody = response.body().string();
            // 处理返回数据
            System.out.println(responseBody);
        }
    }
}

⚠️ 错误处理

常见错误码

错误码	说明	解决方案
200	成功	正常状态
1001	参数错误或设备未连接	检查参数和设备连接
1002	系统未初始化	调用初始化接口或使用auto接口
9001	系统异常	检查日志，重启服务
3000+	江苏医保DLL错误	检查DLL文件和网络连接

错误处理示例

function handleError(result) {
    switch(result.code) {
        case 200:
            console.log('操作成功');
            break;
        case 1001:
            console.error('设备错误，请检查读卡器连接');
            break;
        case 1002:
            console.error('系统未初始化，请先初始化');
            break;
        default:
            console.error('未知错误:', result.message);
    }
}

❓ 常见问题

1. 华视读卡器相关

Q: 读卡器无法识别身份证？

A: 检查以下几点：
   - USB连接是否正常
   - 驱动是否正确安装
   - 身份证是否正确放置
   - 尝试重新初始化：/readcard/entry?param=huashi_init_1001

Q: 返回错误码1001？

A: 通常是硬件问题：
   - 检查读卡器USB连接
   - 确认身份证放置正确
   - 重启读卡器驱动

2. 江苏医保相关

Q: 自动初始化失败？

A: 检查以下配置：
   - 网络连接是否正常
   - 配置参数是否正确
   - DLL文件是否完整
   - 尝试手动初始化

Q: 社保卡读取失败？

A: 可能的原因：
   - 社保卡未正确插入
   - 网络连接问题
   - 配置参数错误
   - 建议使用 /readcard/jiangsu/diagnose 诊断

3. 服务相关

Q: 无法访问HTTP接口？

A: 检查以下设置：
   - 程序是否以管理员权限运行
   - 防火墙是否允许8321端口
   - 端口是否被其他程序占用

Q: 服务启动失败？

A: 可能的解决方案：
   - 以管理员身份运行
   - 检查.NET Framework版本
   - 确保端口8321未被占用

📞 技术支持

服务信息

版本：v1.0.0
服务端口：8321
支持系统：Windows 7/8/10/11

调试信息

# 健康检查
GET /readcard/huashi/health

# 华视设备状态
GET /readcard/huashi/status

# 江苏医保状态
GET /readcard/jiangsu/status

# 江苏医保诊断
GET /readcard/jiangsu/diagnose

日志文件位置

程序目录/NEULOGS/     # 东软日志
程序目录/TSLOG/       # 终端日志
程序目录/logs/        # 江苏医保日志

重要提醒：

首次使用建议先测试设备连接
确保以管理员权限运行程序
定期检查服务状态和日志
如遇问题，优先检查硬件连接和网络状态

ThCardReader使用说明文档.md 13 KB Trvalý odkaz Historie Surový

ThCardReader 使用说明文档

📋 目录

🎯 功能概述

服务信息

🆔 华视读身份证功能

功能描述

硬件要求

API接口

1. 初始化华视读卡器

2. 读取身份证信息

3. 连续读卡模式

4. 获取设备状态

5. 关闭连接

专用API接口

简化调用方式

POST方式调用

🏥 江苏医保读社保卡功能

功能描述

硬件要求

API接口

1. 自动初始化读社保卡（推荐）

2. 带PIN验证的自动读卡

3. 手动初始化

4. 传统读卡方式

5. 设备状态查询

6. PIN码验证

7. PIN码修改

POST方式调用

带参数的读卡请求

自定义初始化配置

数据格式说明

社保卡数据格式（标准38号文）

💻 接口调用示例

JavaScript调用示例

华视读身份证

江苏医保读社保卡

C# 调用示例

华视读身份证

江苏医保读社保卡

Java 调用示例

⚠️ 错误处理

常见错误码

错误处理示例

❓ 常见问题

1. 华视读卡器相关

2. 江苏医保相关

3. 服务相关

📞 技术支持

服务信息

调试信息

日志文件位置

ThCardReader使用说明文档.md 13 KB

Trvalý odkaz Historie Surový