DONSEE东信智能 - 身份证社保卡读卡智能终端应用服务商

本开发包适用以上广东东信智能科技有限公司DONSEE  EST-100R系列产品，EST-100R是一款融合了身份证、社保卡、一二维码扫码墩、磁条卡技术、接触式、非接触式智能卡技术及密码键盘于一身的多功能智能卡读写器。

各平台开发包下载地址如下：

1、PC测试软件V2.5下载

2、Windows Dll开发库和文档下载

3、C#开发包下载

4、Java开发包下载

5、谷歌火狐多浏览器Web开发包下载

6、IE浏览器OCX控件下载

7、Android开发包下载（最新）

7、Android开发包下载

8、Linux开发包下载_x86_x64

9、EST-100R-38号文接口-32位-20230517

10、EST-100R_38号文接口_X64-20230330

DONSEE  EST-100R系列

多合一读写器接口规范

广东东信智能科技有限公司

2023.05.12

一、外部方法

动态库名：SSCARDInterface.dll

依赖库：BmpToJpg.dll、Device.dll、SSE32.dll、SW100.dll、UnPack.dll和SSCARDInterface.dll放相同目录

1.1打开设备

long WINAPI iOpenPort(char* ErrMsg);

参数：ErrMsg：[OUT]返回错误信息，下同

返回值：非0表示失败

1.2关闭设备

long WINAPI iClosePort();

返回值：非0表示失败

蜂鸣器

long WINAPI iPosBeep ();

返回值：非0表示失败

1.3读取身份证/港澳台居住证信息

函数原型：

long WINAPI iReaderIDCard_CS(char* pPicFilePath, char* cardinfo, char* dsp, char* ErrMsg);

功能：读取身份证信息

参数：pPicFilePath：[IN]照片路径,例：D:\\zp.bmp

      Cardinfo：[OUT] 读卡成功时返回 "姓名|性别|民族|出生日期|地址|身份证号|发卡机关|发卡日期|卡有效期|证件类型|"。

证件类型：I:外国人  J:港澳台居住证，居民身份证为空格

dsp[OUT] 身份证照片base64数据

返回值：非0表示失败

读取身份证UID

long WINAPI iReadCertID_CS(char* cardinfo, char* ErrMsg);

功能：读取社保卡信息

参数：

      Cardinfo：[OUT] 成功返回身份证16位UID字符串。

返回值：非0表示失败

读取IC卡UID

long WINAPI iReadICUID(char* cardinfo, char* ErrMsg);

功能：读取社保卡信息

参数：

      Cardinfo：[OUT] 成功返回身份证8位UID字符串。

返回值：非0表示失败

1.4读取社保卡信息

函数原型：

long WINAPI iReadSicard_CS(int slot,char* cardinfo, char* ErrMsg);

功能：读取社保卡信息

参数：slot：[IN]PSAM卡槽，SAM1~SAM4(值：17~20)

      Cardinfo：[OUT] 成功返回："卡识别码|社保卡卡号|社会保障号码|姓名|性别|民族|出生日期|发卡日期|卡有效期|"。

返回值：非0表示失败

1.5 M1卡读写

1.5.1 M1卡读操作

1）函数原型：

long WINAPI MifareOnCardRead_CS(int addr, int keyType, char* passWord, char* OutData, char* ErrMsg)

功能：读取M1卡某一块的数据，ASCii格式

参数：

addr：[IN]块地址（0~63）

keyType：[IN]认证KeyA时传0x60,  KeyB：0x61

passWord：[IN]6字节十六进制字符串密码，例如 "ffffffffffff"

OutData：[OUT]读取的数据

返回值：非0表示失败。

2）函数原型：

long WINAPI MifareOnCardReadHEX_CS(int addr, int keyType, char* passWord, char* OutData, char* ErrMsg)

功能：读取M1卡某一块的数据，十六进制字符串格式

参数：

addr：[IN]块地址（0~63）

keyType：[IN]认证KeyA时传0x60,  KeyB：0x61

passWord：[IN]6字节十六进制字符串密码，例如 "ffffffffffff"

OutData：[OUT]读取的数据

返回值：非0表示失败。

1.5.2 M1卡写操作

1）函数原型：

long WINAPI MifareOnCardWrite_CS(int addr, int keyType, char* passWord, char* Data, char* ErrMsg)

功能：写入M1卡某一块的数据，ASCii格式

参数：

addr：[IN]块地址（0~63）

keyType：[IN]认证KeyA时传0x60,  KeyB：0x61

passWord：[IN]6字节十六进制字符串密码，例如 "ffffffffffff"

Data：[IN]待写入的数据 16个字符

返回值：非0表示失败。

2）函数原型：

long WINAPI MifareOnCardWriteHEX_CS(int addr, int keyType, char* passWord, char* Data, char* ErrMsg)

功能：写入M1卡某一块的数据，十六进制字符串格式

参数：

addr：[IN]块地址（0~63）

keyType：[IN]认证KeyA时传0x60,  KeyB：0x61

passWord：[IN]6字节十六进制字符串密码，例如 "ffffffffffff"

Data：[IN]待写入的数据 32个字符

返回值：非0表示失败。

1.6读取磁条卡信息

函数原型：

long WINAPI iReadMagCard(int timeOut, int nTrack,  char* trackData, char* ErrMsg);

功能：读取磁条卡信息

参数：timeOut：[IN]刷卡超时值，单位为秒

      nTrack：[IN] 磁道值1-3

      Cardinfo：[OUT] 成功返回磁道信息。

返回值：小于等于0表示失败，大于0表示成功

1.7扫码二维码信息

函数原型：

long WINAPI ScanQRcode(int nTimeOut, char* pCodeInfo, char* ErrMsg);

功能：扫码信息

参数：nTimeOut：[IN]扫码超时值，单位为毫秒

      pCodeInfo：[OUT] 成功返回扫码信息。

返回值：非0表示失败，等于0表示成功

相关函数：

设置主动扫码：

long WINAPI SetAutoQRcode(char* ErrMsg);

关闭主动扫码：

long WINAPI CloseAutoQRcode(char* ErrMsg);

1.8 读银行卡号

函数原型：

int iReadBankNo_CS(int iType,  char*cardInfo,  char* errMsg);

参数：

iType:1=插卡，2=非接，3=自动

cardInfo：银行卡号

errMsg：错误信息

社保卡加密机相关函数说明

1.1 SI_ReadCardBas “读基本信息”

1.1.1函数定义

读基本信息接口函数定义见表1。在进行任何社保卡操作前，应先调用此函数。

表1读基本信息接口函数定义

函数名称读基本信息

语法long SI_ReadCardBas (int iType, char* pOutInfo)

功能描述选择社保卡社会保障系统环境后，通过PSAM卡对社保卡进行内部认证，通过后将卡内的基本信息读出返回。

参数说明序号参数输入/输出类型长度（十进制）含义

1iTypeIN整数4操作卡的类型

2pOutInfoOUT字符串1024读出数据或返回错误信息

返回值0表示成功；非0表示失败。

1.1.2参数说明

（1）输入参数iType

表示执行本函数时操作卡的类型，定义如下：1-接触式操作卡；2-非接触式操作卡；3-自动寻卡，接触式操作卡优先；4-自动寻卡，非接触式操作卡优先。

（2）输出参数pOutInfo

当函数执行成功时，该输出参数为读出的社保卡基本信息各数据项，依次为：发卡地区行政区划代码（卡识别码前6位）、社会保障号码、卡号、卡识别码、姓名、卡复位信息（仅取历史字节）、规范版本、发卡日期、卡有效期、终端机编号、终端设备号。各数据项之间以“|”分割，且最后一个数据项以“|”结尾。例如：639900|111111198101011110|X00000019|639900D15600000500BF7C7A48FB4966|张三|00814E43238697159900BF7C7A|1.00|20101001|20201001|410100813475|终端设备号|。

当函数执行失败时，该输出参数为错误信息描述。

注：当没有终端设备号时，终端设备号返回空字符串。

1.2 SI_ReadCardHSM_Step1 “基于加密机的读基本信息（步骤一）”

1.2.1函数定义

基于加密机的读基本信息（步骤一）接口函数定义见表2。

表2基于加密机的读基本信息（步骤一）接口函数定义

函数名称基于加密机的读基本信息（步骤一）

语法long SI_ReadCardHSM_Step1 (int iType, char* pOutInfo)

功能描述选择社会保障系统环境后，返回内部认证和外部认证所需信息。

参数说明序号参数输入/输出类型长度（十进制）含义

1iTypeIN整数4操作卡的类型

2pOutInfoOUT字符串1024返回认证信息或错误信息

返回值0表示成功；非0表示失败。

1.2.2参数说明

（1）输入参数iType

定义同1.1.2（1）。

（2）输出参数pOutInfo

当函数执行成功时，该输出参数为读出的社保卡内部认证和外部认证的计算数据，依次为：发卡地区行政区划代码（卡识别码前6位）、卡复位信息（仅取历史字节）、算法标识、卡识别码、内部认证过程因子、内部认证鉴别所需的原始信息、外部认证过程因子、外部认证鉴别所需的原始信息，其中外部认证相关数据项全部不为空或全部为空。各数据项之间以“|”分割，且最后一个数据项以“|”结尾。

当函数执行失败时，该输出参数为错误信息描述。

注：当外部认证相关数据项为空时，表示不做外部认证。

1.3 SI_ReadCardHSM_Step2 “基于加密机的读基本信息（步骤二）”

1.3.1函数定义

基于加密机的读基本信息（步骤二）接口函数定义见表3。

表3基于加密机的读基本信息（步骤二）接口函数定义

函数名称基于加密机的读基本信息（步骤二）

语法long SI_ReadCardHSM_Step2 (char *pKey, char* pOutInfo)

功能描述根据加密机返回的内部认证和外部认证结果数据对社保卡进行内部认证和外部认证，通过后将卡内的基本信息读出返回。

参数说明序号参数输入/输出类型长度（十进制）含义

1pKeyIN字符串128加密机返回的内部认证和外部认证结果数据

2pOutInfoOUT字符串1024读出数据或返回错误信息

返回值0表示成功；非0表示失败。

1.3.2参数说明

（1）输入参数pKey

加密机返回的内部认证和外部认证结果数据，依次为：内部认证结果数据（即内部认证鉴别数据（16位）和内部认证鉴别所需的原始信息（16位）拼接组成）、外部认证结果数据（即外部认证鉴别数据（16位）和外部认证鉴别所需的原始信息（16位）拼接组成）。各数据项之间以“|”分割，且最后一个数据项以“|”结尾。

注：如果不做外部认证，则后面一个参数都为空字符串。

（2）输出参数pOutInfo

定义同1.1.2（2）。

注：当没有PSAM卡时，终端机编号返回12个0，即6个0x00对应的字符。

当没有终端设备号时，终端设备号返回空字符串。

2 读社保基本信息流程

读基本信息流程如图C.1所示。

图C.1读基本信息流程

具体流程如下：

（1）调用SI_ReadCardBas函数，判断函数执行结果，若执行成功，则返回基本信息，调用持卡库的卡鉴权服务接口，完成卡鉴权操作；若执行失败，返回错误代码并进行判断，当判断到五种情况的错误代码（详见10.5）后，则调用基于加密机的SI_ReadCardBas_HSM_Step1函数，否则报错退出；

（2）若SI_ReadCardBas_HSM_Step1函数执行成功，则分析返回数据内容，组织持卡库报文，调用持卡库的卡内部认证服务接口，否则报错退出；

（3）若卡内部认证服务接口调用成功，则调用基于加密机的SI_ReadCardBas_HSM_Step2函数，否则报错退出；

（4）若SI_ReadCardBas_HSM_Step2函数执行成功，则返回基本信息，调用持卡库的卡鉴权服务接口，完成卡鉴权操作，否则报错退出。

3、社保卡状态码

社保卡状态码

返回值错误信息描述

-1卡类型不对

-2无卡

-3有卡未上电

-4卡无应答

-5加载动态库错

-11读卡器连接错

-12未建立连接

-13（动态库）不支持该命令

-14（发给动态库的）命令参数错

-15信息校验和出错

-20卡识别码格式错

-21内部认证失败（用户卡不合法）

-22传入数据与卡内不符

-23传入数据不合法

-24PSAM卡密钥级别不够

-31用户取消密码输入

-32密码输入操作超时

-33输入密码长度错

-34两次输入密码不一致

-35（预留）初始密码不能交易

-36（预留）不能改为初始密码

-41运算数据含非法字符

-42运算数据长度错

-51PIN校验失败，剩余次数N次（根据卡返回信息）

-52PIN锁定

-2201无PSAM卡

-2202PSAM卡算法不支持（即PSAM卡内没有SSF33算法或SM4算法）

-2203PSAM卡内没有RKSSSE密钥（3.0卡读个人基本信息需要RKSSSE密钥外部认证）

-2204不需要加密机认证

-25536、-25537、-25538、-25539、-25540、-25541外部认证失败，剩余可尝试次数0~5次

-26368Lc/Le不正确

-26881命令不接受（无效状态）

-27009命令与文件结构不相符、当前文件非所需文件

-27010不满足安全条件

-27011密钥锁定（算法锁定）鉴别方法锁定

-27012引用数据无效、随机数无效

-27013不满足使用条件、应用被锁定、应用未选择、余额上溢

-27016安全报文数据项不正确、MAC不正确

-27264数据域参数不正确

-27265不支持该功能、卡中无MF、卡被锁定、应用锁定

-27266未找到文件、文件标识相重、SFI不正确

-27267未找到记录

-27272未找到引用数据、未找到密钥

-37634MAC无效

-37635应用已被永久锁定、卡片锁定

-37891PSAM卡不支持消费交易

-37894所需MAC（或/和TAC）不可用

其他未知错误

附录

错误代码描述

0执行成功

-1设备连接失败

-2上电失败

-3选环境失败

-4卡通信失败

-5读磁条失败

-6卡鉴权失败

-7读身份证失败

-8无卡

-9异常错误

-10加载dll失败