中华民国的健保 IC 卡必须使用兼容于 PC/SC 界面的 IC 读卡机来读取。PC/SC 的规范是由微软与其它 IC 卡厂商共同订定出来的,统一了 IC 卡的界面。因此如果要读取 IC 卡,要在环境安装好读卡机的驱动程序,并且使用 PC/SC 的函数库提供的功能来读取。不过要使用 PC/SC 函数库,并不是每个运行环境都能够做到,像是网页浏览器现阶段应该还做不到,要等 Web Smart Card API 出来才行,但还是有其它方式可以读卡。

TW NHI IC Card Service

「TW NHI IC Card Service」是笔者用 Rust 编程语言开发的中华民国健保卡读取服务,支持 Linux、macOS 和 Windows。启动服务之后就可以透过 HTTP 连接来读卡,支持 WebSocket。有了这个服务在能够进行 HTTP 连接的环境都可以读卡了。

GitHub:

运行环境

在使用 TW NHI IC Card Service 前,要先设置好环境才能正确读卡。

Windows / macOS

要先安装好读卡机的驱动程序。

Linux

需有 pcscd。基于 Debian 的 Linux 发行版可用以下指令安装并激活:

sudo apt install pcscd
sudo systemctl enable pcscd

接着安装好读卡机的驱动程序。

使用方法

直接在终端机或是命令行中运行 TW NHI IC Card Service 的可执行文件,就会启动 HTTP 服务,监听 127.0.0.1:12345。在指令加上 -i 或是 -p 参数可以分别设置要监听的网络界面和连接端口。

启动 HTTP 服务后,可以访问以下的端点:

  • GET /:读取所有读卡机的健保卡中的基本数据。回应的 Content-Type 为 application/json。JSON 格式如下:
    [
        {
            "reader_name": "读卡机名称",
            "card_no": "卡号",
            "full_name": "全名",
            "id_no": "身份证字号",
            "birth_date": "0000-00-00",
            "birth_date_timestamp": 0,
            "sex": "M:男;F:女",
            "issue_date": "0000-00-00",
            "issue_date_timestamp": 0
        },
    
        ...
    ]

    时间戳记(timestamp)的单位是毫秒,会使用本地的时区,建议将时区设置为 GMT+8。

  • GET /version:回传此服务的版本,可用来检验此服务是否正常在监听。回应的 Content-Type 为 application/json。JSON 格式如下:
    {
        "major": 0,
        "minor": 1,
        "patch": 5,
        "pre": "",
        "text": "0.1.5"
    }
  • GET /ws:WebSocket 端点。URL 查找中可以代入 interval 字段来设置服务器回传所有读卡机的健保卡中的基本数据的时间间隔,单位为秒。回传的数据格式请见 GET /。客户端也可以在连接时发送要使用的时间间隔秒数来更改回传设置。

在 JavaScript/TypeScript 上使用 TW NHI IC Card Service

笔者也提供了 JavaScript/TypeScript 套件来与 TW NHI IC Card Service 搭配使用。

GitHub:

使用方法

使用 npm 安装本套件
npm install "git+https://github.com/magiclen/tw-nhi-icc.git#semver:^0.1"
初始化
import { TWNHIICCService } from "tw-nhi-icc";

const service = new TWNHIICCService();
取得 TW NHI IC Card Service 的版本信息
const version = await service.getVersion();
取得健保卡清单
const cards = await service.getCardList();
连接 WebSocket
await service.openWebSocket();

service.onWebSocketUpdate = (cards) => {
    // ...
};

service.closeWebSocket();

在网页浏览器上使用 TW NHI IC Card Service

网页源代码

展示页面