一体化读卡服务Web开发技术文档

2026-09-22 技术分享开发工具

1. 概述

独立服务模式 (HTTP): 运行 一体化读卡服务.exe 并启用 HTTP 服务，允许外部应用（如网页）通过 HTTP POST 请求进行远程调用。

2. 核心调用接口

HTTP 服务接口

一体化读卡服务.exe 启用 HTTP 服务后，请求和响应的数据格式按以下标准。

请求方法: POST
请求 Body: 包含命令和参数的 JSON 字符串。
响应 Body: 包含操作结果和数据的 JSON 字符串。

3. 基本命令 JSON 结构

所有发送给 HTTP 服务的 JSON 字符串都必须包含以下核心字段：

字段名称	类型	描述
`commandType`	String	命令类型，用于区分基础硬件操作或特定医保平台的接口。
`command`	String	具体的执行操作名称。
其他参数	Mixed	根据不同的 `commandType` 或 `command` 确定，例如 `port`, `baud`, `url`, `user` 等。

响应数据结构字段：

字段名称	类型	描述
`Code`	String	状态码。 `0` 表示操作成功；非 `0` 表示操作失败或异常。
`Message`	String	状态描述信息，如“操作成功”、“设备连接失败”等。
`Data`	Object	业务数据体。包含读卡操作获取的实际数据（如姓名、卡号、身份证号等）。

注意：服务有响应为响应成功，但响应成功不等于读卡成功；判断读卡是否成功，需要看Data字段的返回数据。

发送示例：

{
    "commandType": "BasicOption",
    "command": "SSCardInfo",
    "port": 100,
    "baud": 115200
}

服务响应成功、读卡成功示例:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":0,
    "Message":"读社保卡基本信息成功",
    "Data":
    {
      "卡识别码":"442000D1560000052800000C312CCEEB",
      "卡类别":"3",
      "规范版本":"3.00",
      "初始化机构编号":"915600000244200044010056",
      "发卡日期":"20190822",
      "卡有效期":"20290822",
      "卡号":"T08244609"
    }
  }
}

服务响应成功，但读卡失败示例:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":-2,
    "Message":"社保卡复位失败",
    "Data":""
  }
}

服务响应失败，这个一般不会有返回。或返回非JSON数据。

4. 具体命令

4.1 基础硬件操作 (`commandType`: BasicOption)

这类命令用于直接操作本地连接的读卡设备。

中文描述	command	必需参数	描述
获取USB设备ID	`ReadUsbID`	无	获取已连接 USB 设备的标识符。
读设备信息	`ReadDeviceInfo`	`port`, `baud`	读取读卡设备的自身信息。
读社保卡基本信息	`SSCardInfo`	`port`, `baud`	读取社保卡（基础信息）。
读社保卡持卡人信息	`SSCardHolderInfo`	`port`, `baud`	读取社保卡（持卡人信息）。
读身份证	`IDCard`	`port`, `baud`	读取二代身份证信息。
内置扫码	`InsideQRCode`	`port`, `baud`	启用设备内置的扫码功能。
外接P30扫码	`OutsideQRCode`	`port`, `baud`	启用外接 P30 键盘进行扫码。
读磁卡	`MagCard`	`port`, `baud`	读取磁条卡信息。

业务数据体（服务返回的Data对象）基本字段说明

字段	描述
Status	返回值，操作成功返回大于等于0。
Message	操作描述。
Data	返回的数据体。

A、获取USB设备ID

这个是读取电脑的USB外设，并不对读卡器进行连接，所以不会失败，会返回所以HID USB外设的编号。

Send:

{
    "commandType": "BasicOption",
    "command": "ReadUsbID"
}

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "devices":["[VID:_HUB  PID:D808]",
    "[VID:046D  PID:C534]",
    "[VID:05E3  PID:0610]",
    "[VID:152D  PID:0583]",
    "[VID:0471  PID:7003]  T10读卡器",
    "[VID:8087  PID:0024]",
    "[VID:1FC9  PID:5AA7]",
    "[VID:05E3  PID:0626]"]
  }
}

B、读设备信息

功能：读到设备的基本信息：版本、UID等。

Send:

{
    "commandType": "BasicOption",
    "command": "ReadDeviceInfo",
    "port": 100,
    "baud": 115200
}

字段说明：

字段	定义	备注
port	设备端口号，Usb填100，串口1填0，串口2填1，以此类推。	默认值：100
baud	设备波特率，9600-115200。	默认值：115200

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":0,
    "Message":"读取设备信息成功！",
    "Data":
    {
      "LibType":"DCRF32",
      "DeviceType":"T10F",
      "DeviceUID":"00010501202410001402",
      "LongVer":"QIANGSH-READER201001011234567890",
      "Ver":"T10STM32S.GZ.0101.DC4.SVN379.260714",
      "SamSN":"05.13-20240827-0041935374-0091225404"
    }
  }
}

字段说明：

字段	定义	备注
LibType	驱动库类型
DeviceType	设备类型
DeviceUID	设备唯一识别码（UID）
LongVer	设备版本信息
Ver	设备固件版本信息
SamSN	身份证安全模块编号	仅支持身份证机型特有。

C、读社保卡基本信息

功能：读到社保卡的基本信息。

Send:

{
    "commandType": "BasicOption",
    "command": "SSCardInfo",
    "port": 100,
    "baud": 115200
}

字段说明：

字段	定义	备注
port	设备端口号，Usb填100，串口1填0，串口2填1，以此类推。	默认值：100
baud	设备波特率，9600-115200。	默认值：115200

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":0,
    "Message":"读社保卡基本信息成功",
    "Data":
    {
      "卡识别码":"440100D1560000050012A78E7175895C",
      "卡类别":"3",
      "规范版本":"1.0",
      "初始化机构编号":"915600000244010044010047",
      "发卡日期":"20130207",
      "卡有效期":"20330207",
      "卡号":"205702061"
    }
  }
}

字段说明：

字段	定义	备注
Status	返回值，成功返回0
Message	操作说明
卡识别码	社保卡的卡识别码
卡类别	社保卡类型
规范版本	社保卡的规范版本号	这个可以判断是1、2、3代卡；1.x表示一代卡；2.x表示二代卡；3.x表示三代卡。
初始化机构编号	机构编码
发卡日期	社保卡发卡日期
卡有效期	社保卡到期日期
卡号	社保卡卡号	这个不是社会保障号，仅仅是卡号。

D、读社保卡持卡人信息

功能：读到社保卡的持卡人的基本信息。

Send:

{
    "commandType": "BasicOption",
    "command": "SSCardHolderInfo",
    "port": 100,
    "baud": 115200
}

字段说明：

字段	定义	备注
port	设备端口号，Usb填100，串口1填0，串口2填1，以此类推。	默认值：100
baud	设备波特率，9600-115200。	默认值：115200

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":0,
    "Message":"读社保卡持卡人信息成功",
    "Data":
    {
      "证件号码":"440106200807235016",
      "姓名":"黄东东",
      "姓名扩展":"",
      "性别":"男",
      "民族":"汉族",
      "出生地":"FFFFFF",
      "出生日期":"20080723"
    }
  }
}

字段说明：

字段	定义	备注
Status	返回值，成功返回0
Message	操作说明
证件号码	持卡人社保保障号	现在一般都用身份证号
姓名	姓名
姓名扩展	姓名的一部分	部分少数民族姓名很长的才有。
性别	性别
民族	民族
出生地	出生地行政编码
出生日期	出生日期

E、读身份证

功能：读到身份证件的信息。

Send:

{
    "commandType": "BasicOption",
    "command": "IDCard",
    "sPhotoPath": ".\\photo.bmp",
    "port": 100,
    "baud": 115200
}

字段说明：

字段	定义	备注
port	设备端口号，Usb填100，串口1填0，串口2填1，以此类推。	默认值：100
baud	设备波特率，9600-115200。	默认值：115200
sPhotoPath	保存身份证照片的路径。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":0,
    "Message":"证件读取成功！",
    "Data":
    {
      "姓名":"黄心烨",
      "性别":"女",
      "民族":"汉",
      "出生日期":"20001004",
      "住址":"广东省揭阳市榕城区东升新河村新平围",
      "公民身份号码":"445202200010048320",
      "签发机关":"揭阳市公安局榕城分局",
      "有效期限起":"20181210",
      "有效期限止":"20231210"
    }
  }
}

字段说明：

字段	定义	备注
Status	返回值，成功返回0
Message	操作说明
姓名	姓名
性别	性别
民族	民族
出生日期	出生日期
住址	身份证上的地址
公民身份号码	身份证号码
签发机关	发证机关
有效期限起	发证日期
有效期限止	有效日期

F、内置扫码

功能：调用设备内置扫码器扫条码、二维码。

Send:

{
    "commandType": "BasicOption",
    "command": "InsideQRCode",
    "iTimeOut": 30,
    "port": 100,
    "baud": 115200
}

字段说明：

字段	定义	备注
port	设备端口号，Usb填100，串口1填0，串口2填1，以此类推。	默认值：100
baud	设备波特率，9600-115200。	默认值：115200

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":0,
    "Message":"扫码成功！",
    "Data":
    {
      "条码长度":28,
      "条码数据":"4244002415156691097602440000"
    }
  }
}

字段说明：

字段	定义	备注
Status	返回值，成功返回0
Message	操作说明
条码长度	扫到条码数据的长度。
条码数据	扫码条码数据的空容。

G、外接P30扫码

功能：调用读卡器外接P30扫码键盘扫条码、二维码。

Send:

{
    "commandType": "BasicOption",
    "command": "OutsideQRCode",
    "iTimeOut": 30,
    "port": 100,
    "baud": 115200
}

字段说明：

字段	定义	备注
port	设备端口号，Usb填100，串口1填0，串口2填1，以此类推。	默认值：100
baud	设备波特率，9600-115200。	默认值：115200

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":0,
    "Message":"扫码成功！",
    "Data":
    {
      "条码长度":28,
      "条码数据":"4244002415156691097602440000"
    }
  }
}

字段说明：

字段	定义	备注
Status	返回值，成功返回0
Message	操作说明
条码长度	扫到条码数据的长度。
条码数据	扫码条码数据的空容。

H、读磁卡

功能：读到磁条卡，注意，这个是同步操作，超时结束前会造成阻塞。

读磁卡要先调用，然后再刷磁卡，刷卡要水平、匀速。

Send:

{
    "commandType": "BasicOption",
    "command": "MagCard",
    "iTimeOut": 30,
    "port": 100,
    "baud": 115200
}

字段说明：

字段	定义	备注
port	设备端口号，Usb填100，串口1填0，串口2填1，以此类推。	默认值：100
baud	设备波特率，9600-115200。	默认值：115200
iTimeOut	读磁卡超时时间，单位：秒。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Status":0,
    "Message":"读磁卡成功！",
    "Data":
    {
      "第一轨长度":0,
      "第一轨数据":"",
      "第二轨长度":39,
      "第二轨数据":";6217921001521726=24052200000070400000?",
      "第三轨长度":106,
      "第三轨数据":";996217921001521726=15615600000000000008800000002404040000000000000000000=000000000000=000000000000000000?"
    }
  }
}

字段说明：

字段	定义	备注
Status	返回值，成功返回0
Message	操作说明
第一轨长度	第一磁轨的数据长度。
第一轨数据	第一磁轨的数据内容。
第二轨长度	第二磁轨的数据长度。
第二轨数据	第二磁轨的数据内容。
第三轨长度	第三磁轨的数据长度。
第三轨数据	第三磁轨的数据内容。

4.2 广州市医保库接口 (`commandType`: GZSSCard)

这类命令调用广州市医保相关的在线接口，调用的前提是医保网通畅。

中文描述	command	必需参数	示例参数值
读社保卡	`ReadCardBasGZ`	`url`, `user`	`"user": "H44010400081"`
读身份证	`ReadIDCardGZ`	`url`, `user`	`"url": "<http://igb.hsa.gdgov.cn/gdyb_api/prd/api/card/initDll>"`
内置扫码	`GetTwoBarCodes`	`url`, `user`	同上
外接键盘扫码	`GetTwoBarCodesByExtP30`	`url`, `user`	同上
读磁条医保卡	`ReadMedicalCardGZ`	`url`, `user`	同上

A、读社保卡

功能：医保库读社保卡。第一次读卡时，服务会自动调用Init。

Send:

{
    "commandType": "GZSSCard",
    "command": "ReadCardBasGZ",
    "url": "http://igb.hsa.gdgov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GZSSCard\\SSCard.dll",
	  "Api":"ReadCardBasGZ",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

B、读身份证

功能：医保库读身份证卡。第一次读卡时，服务会自动调用Init。

Send:

{
    "commandType": "GZSSCard",
    "command": "ReadIDCardGZ",
    "url": "http://igb.hsa.gdgov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GZSSCard\\SSCard.dll",
	  "Api":"ReadIDCardGZ",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

C、内置扫码

功能：医保库扫码。第一次调用时，服务会自动调用Init。

Send:

{
    "commandType": "GZSSCard",
    "command": "GetTwoBarCodes",
    "url": "http://igb.hsa.gdgov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GZSSCard\\SSCard.dll",
	  "Api":"GetTwoBarCodes",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

D、外接键盘扫码

功能：医保库扫码。第一次调用时，服务会自动调用Init。

Send:

{
    "commandType": "GZSSCard",
    "command": "GetTwoBarCodesByExtP30",
    "url": "http://igb.hsa.gdgov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GZSSCard\\SSCard.dll",
	  "Api":"GetTwoBarCodes",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

E、读磁条医保卡

功能：医保库读磁条医保卡。第一次调用时，服务会自动调用Init。

Send:

{
    "commandType": "GZSSCard",
    "command": "ReadMedicalCardGZ",
    "url": "http://igb.hsa.gdgov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GZSSCard\\SSCard.dll",
	  "Api":"ReadMedicalCardGZ",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

4.3 广东省医保库接口 (`commandType`: GDSSCard)

这类命令调用广东省医保相关的在线接口。

中文描述	command	必需参数	示例参数值
读社保卡	`ReadCardBas`	`url`, `user`	`"user": "H440001"`
读身份证	`ReadSFZ`	`url`, `user`	`"url": "<http://hosp.gd.hsip.gov.cn/gdyb_api/prd/api/card/initDll>"`
内置扫码	`GetQRBase`	`url`, `user`	同上
外接键盘扫码	`GetQRBaseByExtP30`	`url`, `user`	同上

A、读社保卡

功能：医保库读社保卡。第一次读卡时，服务会自动调用Init。

Send:

{
    "commandType": "GDSSCard",
    "command": "ReadCardBas",
    "url": "http://hosp.gd.hsip.gov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GDSSCard\\SSCard.dll",
	  "Api":"ReadCardBas",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

B、读身份证

功能：医保库读身份证卡。第一次读卡时，服务会自动调用Init。

Send:

{
    "commandType": "GDSSCard",
    "command": "ReadSFZ",
    "url": "http://hosp.gd.hsip.gov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GDSSCard\\SSCard.dll",
	  "Api":"ReadSFZ",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

C、内置扫码

功能：医保库扫码。第一次调用时，服务会自动调用Init。

Send:

{
    "commandType": "GDSSCard",
    "command": "GetQRBase",
    "url": "http://hosp.gd.hsip.gov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GDSSCard\\SSCard.dll",
	  "Api":"GetQRBase",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

D、外接键盘扫码

功能：医保库扫码。第一次调用时，服务会自动调用Init。

Send:

{
    "commandType": "GDSSCard",
    "command": "GetQRBaseByExtP30",
    "url": "http://hosp.gd.hsip.gov.cn/gdyb_api/prd/api/card/initDll",
    "user": "H44012345678"
}

字段说明：

字段	定义	备注
url	医保读卡URL，以当地医保给的为准。
user	医院、药店的医疗机构编号。

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
	{
	  "Lib":".\\GDSSCard\\SSCard.dll",
	  "Api":"GetQRBase",
	  "InDataLength":10240,
	  "InSignDataLength":10240,
	  "Result":-300000,
	  "OutData":"需要先调用初始化函数",
	  "OutDataLength":10,
	  "OutSignData":"",
	  "OutSignDataLength":0,
	  "ErrorInfo":""
	}
}

字段说明：

字段	定义	备注
Lib	医保动态库的地址
Api	调用医保库的API名称。
InDataLength	数据长度入参（预分配内存用）
InSignDataLength	签名数据长度入参（预分配内存用）
Result	返回值，0表示成功，其它为失败。
OutData	Result=0时，读出卡片的原始数据 Result不为0时，会返回医保库报错。	医保结算用。
OutDataLength	卡片原始数据长度
OutSignData	数据签名	医保结算用。
OutSignDataLength	数据签名长度
ErrorInfo	错误信息	这个是服务程序返回的错误信息。

4.4 国家医保电子凭证动态库接口 (`commandType`: NationEcTrans)

这个是调用国家医保电子凭证动态库的接口。只有一个通道入口，具体操作如扫码、刷脸，是通过入参指定的。

通道接口 Send:

{
    "commandType": "NationEcTrans",
    "command": "NationEcTrans",
    "sUrl": "https://igb.hsa.gdgov.cn/prd_nation_eccode/prd_eccode/localcfc/api/hsecfc/localQrCodeQuery",
    "sInData": {
        "data": {
            "businessType": "01101",
            "deviceType": "",
            "officeId": "32760",
            "officeName": "消化内科",
            "operatorId": "test001",
            "operatorName": "超级管理员",
            "orgId": "H44010400081"
        },
        "orgId": "H44010400081",
        "transType": "ec.query"
    }
}

字段	定义	备注
sUrl	扫码网络URL，一般是医保给的。
sInData	发给动态库的JSON报文。按《国家医保电子凭证业务标准动态库交互规范.pdf》标准

Get:

{
  "Status":200,
  "Message":"ok",
  "Data":
  {
    "Lib":"NationECCode.dll",
    "Api":"NationEcTrans",
    "Url":"https://igb.hsa.gdgov.cn/prd_nation_eccode/prd_eccode/localcfc/api/hsecfc/localQrCodeQuery",
    "InData":
    {
      "data":
      {
        "businessType":"01101",
        "deviceType":"",
        "officeId":"32760",
        "officeName":"消化内科",
        "operatorId":"test001",
        "operatorName":"超级管理员",
        "orgId":"H44010400081"
      },
      "orgId":"H44010400081",
      "transType":"ec.query"
    },
    "Result":"0000",
    "OutData":
    {
      "code":-2,
      "message":"医保电子凭证编码错误,
      请重新扫码",
      "orgId":"H44010400081"
    },
    "ErrorInfo":""
  }
}

字段	定义	备注
Lib	国家库的文件名称
Api	国家库的接口名称
Url	调用时的URL入参内空
InData	调用时的INDATA入参内容
Result	调用动态库的返回值，0000表示成功。
OutData	调用后读出的出参内容。内按文档里德解析

附文档：

📎 附件2：国家医保电子凭证业务标准动态库交互规范.pdf

4.5 社保库接口（38号文相关，`commandType`:SSCardDriver)

4.6 身份证阅读器接口（`commandType`:SDTApi）

tel/wx: +8613924026262

一体化读卡服务Web开发技术文档

1. 概述

2. 核心调用接口

HTTP 服务接口

3. 基本命令 JSON 结构

发送示例：

服务响应成功、读卡成功示例:

服务响应成功，但读卡失败示例:

4. 具体命令

4.1 基础硬件操作 (commandType: BasicOption)

A、获取USB设备ID

B、读设备信息

C、读社保卡基本信息

D、读社保卡持卡人信息

E、读身份证

F、内置扫码

G、外接P30扫码

H、读磁卡

4.2 广州市医保库接口 (commandType: GZSSCard)

A、读社保卡

B、读身份证

C、内置扫码

D、外接键盘扫码

E、读磁条医保卡

4.3 广东省医保库接口 (commandType: GDSSCard)

A、读社保卡

B、读身份证

C、内置扫码

D、外接键盘扫码

4.4 国家医保电子凭证动态库接口 (commandType: NationEcTrans)

4.5 社保库接口（38号文相关，commandType:SSCardDriver)

4.6 身份证阅读器接口（commandType:SDTApi）

4.1 基础硬件操作 (`commandType`: BasicOption)

4.2 广州市医保库接口 (`commandType`: GZSSCard)

4.3 广东省医保库接口 (`commandType`: GDSSCard)

4.4 国家医保电子凭证动态库接口 (`commandType`: NationEcTrans)

4.5 社保库接口（38号文相关，`commandType`:SSCardDriver)

4.6 身份证阅读器接口（`commandType`:SDTApi）