開始使用
TCS API for DIW 的開通,以及憑證類型與驗證情境的申請,都由台灣圖靈鏈股份有限公司的 TCS 團隊處理,目前沒有線上自助申請。
- 已有 TCS API Key:直接用現有的 API Key 呼叫 TCS API for DIW,不用另外開通。
- 還沒有 TCS API Key:請聯絡 TCS 團隊,說明您要發證、驗證,或兩者都要。TCS 團隊開通後,會核發 API Key 給您的組織。
費用、開通時程與請求頻率限制,請與 TCS 團隊確認。
您要用的憑證類型或驗證情境還不存在時,填寫下方的欄位申請表寄給 TCS 團隊。
申請新的憑證類型與驗證情境
Section titled “申請新的憑證類型與驗證情境”憑證類型與驗證情境由 TCS 團隊建立。請您提供內容,TCS 團隊建立後會提供代碼。您的工程師呼叫 API 時要用這個代碼。
- 憑證類型(VC Template):發證用。一種憑證類型定義憑證的欄位、卡面與有效期間。
- 驗證情境(VP Template):驗證用。一個驗證情境定義要持卡人出示哪些憑證類型的哪些欄位。
若只需驗證,不一定要申請新的憑證類型。驗證情境可以要求其他單位發的憑證,例如公路局的駕照。
憑證類型與驗證情境的代碼都由 TCS 團隊指定,開頭是 83588104_。呼叫 API 時請填入 TCS 團隊提供的完整代碼:驗證時填在 ref(例如 83588104_example_scenario),發證時填在 vc_uid(例如 83588104_example_card)。憑證類型的代碼建立後不能修改。
複製下面的表格,填好後寄給 TCS 團隊。表格的項目名稱沿用發證後台的名稱,旁邊附上英文名稱或 API 名稱。表格裡的範例是員工證,請換成您的內容。
A. 組織資料(只填一次)
Section titled “A. 組織資料(只填一次)”| 項目 | 說明 | 填寫 |
|---|---|---|
| 組織名稱 | 您組織的登記全名,中文與英文都要提供 | |
| 隱私權政策網址 | 您組織公開的隱私權政策頁面網址。有英文版時,一併提供英文版網址 |
B. 憑證類型表(每種憑證類型一份)
Section titled “B. 憑證類型表(每種憑證類型一份)”憑證類型資料
| 項目 | 說明 | 範例 |
|---|---|---|
| VC 模板名稱 | 卡面上顯示的憑證名稱。中文名稱與英文名稱都要提供。可以用中文、英文、數字。卡面最多完整顯示 18 個字,超過的字以「…」省略。 | 範例公司員工證/Example Co. Employee Card |
| 有效期間 | 數字加單位。自收證者掃描領取用的 QR code 時起算。超過有效期間或撤銷後,憑證即失效。發證時也可為單張憑證另外指定到期日,此處填寫的是預設值。 | 12 個月 |
| 卡面上傳(卡面圖片,選填) | 用卡面範本檔(SVG)設計,存成 JPG 或 PNG 後提供。不提供就用預設卡面。規格見下方「卡面圖片規格」。 | 不提供 |
| 對外顯示 | 是或否。選「是」時,其他組織也能用這種憑證類型建立驗證情境,請持卡人出示這種憑證。 | 否 |
身分保證等級(IAL)不用填。
卡面圖片規格
- 比例 1.6:1,至少 320 x 200 px,最長邊不超過 2048 px。
- 檔案 40 到 500 KB,JPG 或 PNG,RGB 色彩,72 ppi 以上。
- 文字與圖案放在安全範圍內:以 320 x 200 px 的卡面來說,是中間 288 x 168 px。
- 右上角留空。數位憑證皮夾(TW DIW,以下簡稱錢包)會在那裡顯示認證標章與憑證狀態(例如「已失效」)。
- 左下角留給第一個欄位的值,該區域內不要放圖示或文字。
- 卡面圖片可以放您組織的品牌。如果圖片已經印了您組織的名稱與憑證名稱,請告訴 TCS 團隊,卡面可以不再重複顯示發卡單位名稱與憑證名稱。
設計前請先下載卡面設計規範(數位發展部,PDF)與卡面範本檔(SVG,320 x 200 px)。
欄位
下表是範例(員工證),請換成您的欄位。
| 欄位類別 | 欄位對外名稱(中文) | 欄位對外名稱(英文) | 範例值 | 欄位名稱(英)ename | 限定資料格式 | 必填 |
|---|---|---|---|---|---|---|
| 基本欄位 | 姓名 | Full name | 王小明 | name | 不用填(基本欄位已內建規則:只能用中文、英文、數字和 _,不能有空格) | 是 |
| 自定義欄位 | 部門 | Department | 研發部 | department | 只能輸入中英文數字和_ | 是 |
| 自定義欄位 | 職稱 | Job title | 資深工程師 | position | 只能輸入中英文數字和_ | 是 |
| 自定義欄位 | 員工編號 | Employee ID | A0001 | employee_id | 只允許輸入英數 | 是 |
填表時請注意:
- 一列一個欄位。列的順序就是憑證上欄位的順序。
- 第一列必須是必填欄位。它的值會顯示在卡面左下角,最多完整顯示 18 個字,超過的字以「…」省略。
- 有合適的基本欄位時,請用基本欄位,不要另外自定義。基本欄位的名稱與規則是固定的,見基本欄位一覽。只有自定義欄位要填限定資料格式。
- 欄位名稱(英)就是 API 裡的
ename。自定義欄位的ename由您提議,TCS 團隊建立時確認。 - **每個欄位都要有中文與英文的對外名稱。**欄位對外名稱(中文、英文)可以用中文、英文、數字或
_。ename可以用英文、數字或_。 - 欄位值要符合該欄位的規則(基本欄位的內建規則,或自定義欄位選的限定資料格式)。不符合時 API 會拒絕這次發證,錯誤碼是
10110。 - 在 API 裡,每個欄位值都是字串。布林值也寫成文字,依您選的格式寫成
true、false或0、1。 - 必填欄位一定要帶值。少了必填欄位,或必填欄位的值是空字串,API 會拒絕這次發證,錯誤碼是
11001。選填欄位沒有值時,可以不帶,也可以帶空字串。
基本欄位一覽
Section titled “基本欄位一覽”| 中文 | 英文 | ename |
|---|---|---|
| 國民身分證統一編號 | National ID Number | id_number |
| 民國出生年月日 | Date of Birth (Republic of China Era / ROC) | roc_birthday |
| 姓名 | Full name | name |
| 戶籍地址 | Permanent address | registered_address |
| 護照號碼 | Passport No. | passport_no |
| 居留證統一證號 | ARC Number | residential_certificate_no |
| 外來人口統一證號 | New UI No. | UI_no |
| 性別 | Gender | gender |
| 國籍 | Nationality | nationality |
| 西元出生日期 | Date of Birth (YYYY/MM/DD) | ad_birthday |
| 汽(機)駕戶籍地址 | Registered Address (Driver) | driver_registered_address |
| 汽(機)駕戶籍區號 | Postal Code | driver_zip_no |
| 汽(機)有效日 | License Expiration Date | driver_effect_date |
基本欄位已經內建對應的規則,不用填限定資料格式。「姓名」(name)只能用中文、英文、數字和 _,英文姓名中間的空格會被拒絕,錯誤碼是 10110。自定義欄位的限定資料格式,請從下列選項挑一個(括號內是後台寫的規則):
- 只能輸入中文
- 只允許輸入英文(只允許輸入大寫或小寫英文)
- 只允許輸入英數(允許大寫字母、小寫字母以及數字)
- 只能輸入英文數字和_
- 只能輸入中英文數字和_
- 不允許輸入
~!@#$%^&*()_-+*/ - 網址格式檢查
- 電子郵件格式檢查
- 臺灣行動電話號碼規則(須以09開頭,後接8碼數字)
- 台灣身分證字號
- 護照號碼
- 居留證統一證號
- 外來人口統一證號
- 郵遞區號(只允許輸入數字且長度為3碼)
- 西元出生日期(只允許輸入數字且長度為8碼,日期格式 YYYYMMDD)
- 民國出生年月日(0991231)(只允許輸入數字且長度為7碼)
- 性別格式檢查(1:男性 2:女性)
- 國籍格式檢查(0:本國 1:外國)
- 字串
- 布林值(true, false)
- 布林值(0: false, 1: true)
上面沒有您要的規則時,請以文字描述規則,TCS 團隊將評估可否新增。
ename 的長度上限、一種憑證類型最多幾個欄位、欄位值最長多少字,TCS 團隊建立憑證類型時會跟您確認。
C. 驗證情境表(每個驗證情境一份)
Section titled “C. 驗證情境表(每個驗證情境一份)”表格的項目名稱沿用驗證後台的名稱。每個項目都要提供中文版與英文版。
| 項目 | 說明 | 範例 |
|---|---|---|
| VP 名稱 | 這個驗證情境的名稱。錢包的出示畫面以它為標題。 | 員工身分確認 |
| VP 授權目的 | 要求持卡人出示資料的目的。可以用中文、英文、數字。 | 確認來訪者是本公司員工 |
| 要求出示的憑證類型與欄位 | 可以要求其他單位發的憑證,例如公路局的駕照。上限由 TCS 團隊建立驗證情境時確認。 | 範例公司員工證:姓名、員工編號 |
| VP 授權條款 | 錢包顯示給持卡人的同意書。內容是數位發展部的同意書範本(數位憑證皮夾個人資料傳送同意書),請提供下表 9 個項目的資料,TCS 團隊依此撰寫同意書。 | 見下表 |
VP 授權條款需要的資料
| 項目 | 說明 | 範例 |
|---|---|---|
| 機構或組織名稱 | 您組織的名稱,後面加上「(委託台灣圖靈鏈股份有限公司傳送資料)」。 | 範例股份有限公司(委託台灣圖靈鏈股份有限公司傳送資料) |
| 相關服務之隱私權政策 | 您組織隱私權政策的名稱與網址。 | 範例股份有限公司隱私權政策,https://example.com/privacy |
| 蒐集主體名稱 | 同上。 | 範例股份有限公司(委託台灣圖靈鏈股份有限公司傳送資料) |
| 蒐集之目的 | 蒐集這些個人資料的目的。 | 確認來訪者是本公司員工 |
| 個人資料之類別 | 持卡人出示的資料類別。錢包一定會送出「憑證序號」,TCS 團隊會把它列入。 | 姓名、員工編號、憑證序號 |
| 個人資料利用之期間、地區、對象及方式 | 您收到資料後保存多久、在哪裡使用、誰使用、怎麼使用。 | 驗證完成後 30 天;台灣;本公司人資部門;比對員工名冊 |
| 服務名稱或蒐集主體名稱 | 持卡人行使個資權利時的聯絡對象,請填您的組織。 | 範例股份有限公司 |
| 收信地址 | 持卡人行使個資權利時的收信地址。 | 臺北市範例區範例路 1 號 |
| 收件人或部門 | 持卡人行使個資權利時的收件人或部門。 | 人資部 個資窗口 |
錢包在出示畫面顯示「提供資料的對象:台灣圖靈鏈股份有限公司」,完成畫面顯示資料已送出至台灣圖靈鏈股份有限公司。這兩處由錢包固定顯示,您無法更改。
同意書上的蒐集主體是您的組織,並註明委託台灣圖靈鏈股份有限公司傳送資料。錢包畫面上的台灣圖靈鏈股份有限公司,是受您委託傳送資料的一方。資料的用途由您決定,持卡人行使個資權利時也由您的組織受理。