跳到內容

開始使用

TCS API for DIW 的開通,以及憑證類型與驗證情境的申請,都由台灣圖靈鏈股份有限公司的 TCS 團隊處理,目前沒有線上自助申請。

  • 已有 TCS API Key:直接用現有的 API Key 呼叫 TCS API for DIW,不用另外開通。
  • 還沒有 TCS API Key:請聯絡 TCS 團隊,說明您要發證、驗證,或兩者都要。TCS 團隊開通後,會核發 API Key 給您的組織。

費用、開通時程與請求頻率限制,請與 TCS 團隊確認。

您要用的憑證類型或驗證情境還不存在時,填寫下方的欄位申請表寄給 TCS 團隊。

憑證類型與驗證情境由 TCS 團隊建立。請您提供內容,TCS 團隊建立後會提供代碼。您的工程師呼叫 API 時要用這個代碼。

  • 憑證類型(VC Template):發證用。一種憑證類型定義憑證的欄位、卡面與有效期間。
  • 驗證情境(VP Template):驗證用。一個驗證情境定義要持卡人出示哪些憑證類型的哪些欄位。

若只需驗證,不一定要申請新的憑證類型。驗證情境可以要求其他單位發的憑證,例如公路局的駕照。

憑證類型與驗證情境的代碼都由 TCS 團隊指定,開頭是 83588104_。呼叫 API 時請填入 TCS 團隊提供的完整代碼:驗證時填在 ref(例如 83588104_example_scenario),發證時填在 vc_uid(例如 83588104_example_card)。憑證類型的代碼建立後不能修改。

複製下面的表格,填好後寄給 TCS 團隊。表格的項目名稱沿用發證後台的名稱,旁邊附上英文名稱或 API 名稱。表格裡的範例是員工證,請換成您的內容。

項目說明填寫
組織名稱您組織的登記全名,中文與英文都要提供
隱私權政策網址您組織公開的隱私權政策頁面網址。有英文版時,一併提供英文版網址

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 IDA0001employee_id只允許輸入英數是

填表時請注意:

  • 一列一個欄位。列的順序就是憑證上欄位的順序。
  • 第一列必須是必填欄位。它的值會顯示在卡面左下角,最多完整顯示 18 個字,超過的字以「…」省略。
  • 有合適的基本欄位時,請用基本欄位,不要另外自定義。基本欄位的名稱與規則是固定的,見基本欄位一覽。只有自定義欄位要填限定資料格式。
  • 欄位名稱(英)就是 API 裡的 ename。自定義欄位的 ename 由您提議,TCS 團隊建立時確認。
  • **每個欄位都要有中文與英文的對外名稱。**欄位對外名稱(中文、英文)可以用中文、英文、數字或 _。ename 可以用英文、數字或 _。
  • 欄位值要符合該欄位的規則(基本欄位的內建規則,或自定義欄位選的限定資料格式)。不符合時 API 會拒絕這次發證,錯誤碼是 10110。
  • 在 API 裡,每個欄位值都是字串。布林值也寫成文字,依您選的格式寫成 true、false 或 0、1。
  • 必填欄位一定要帶值。少了必填欄位,或必填欄位的值是空字串,API 會拒絕這次發證,錯誤碼是 11001。選填欄位沒有值時,可以不帶,也可以帶空字串。
中文英文ename
國民身分證統一編號National ID Numberid_number
民國出生年月日Date of Birth (Republic of China Era / ROC)roc_birthday
姓名Full namename
戶籍地址Permanent addressregistered_address
護照號碼Passport No.passport_no
居留證統一證號ARC Numberresidential_certificate_no
外來人口統一證號New UI No.UI_no
性別Gendergender
國籍Nationalitynationality
西元出生日期Date of Birth (YYYY/MM/DD)ad_birthday
汽(機)駕戶籍地址Registered Address (Driver)driver_registered_address
汽(機)駕戶籍區號Postal Codedriver_zip_no
汽(機)有效日License Expiration Datedriver_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 號
收件人或部門持卡人行使個資權利時的收件人或部門。人資部 個資窗口

錢包在出示畫面顯示「提供資料的對象:台灣圖靈鏈股份有限公司」,完成畫面顯示資料已送出至台灣圖靈鏈股份有限公司。這兩處由錢包固定顯示,您無法更改。

同意書上的蒐集主體是您的組織,並註明委託台灣圖靈鏈股份有限公司傳送資料。錢包畫面上的台灣圖靈鏈股份有限公司,是受您委託傳送資料的一方。資料的用途由您決定,持卡人行使個資權利時也由您的組織受理。