DONSEE東信智能 - 身份證社保卡讀卡智能終端應用服務商

本開發包適用以上廣東東信智能科技有限公司DONSEE  EST-100R系列產品，EST-100R是一款融合了身份證、社保卡、一二維碼掃碼墩、磁條卡技術、接觸式、非接觸式智能卡技術及密碼鍵盤于一身的多功能智能卡讀寫器。

各平臺開發包下載地址如下：

1、PC測試軟件V2.5下載

2、Windows Dll開發庫和文檔下載20231115

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失敗

***********************以下為備份SDK

2、Windows Dll開發庫和文檔下載