跳到內容

運作方式

發證、驗證、撤銷三個流程,您的系統都只呼叫 TCS API for DIW。API 的呼叫方式見發證 API、驗證 API 與撤銷 API。

每次發證要指定一種憑證類型(VC Template)。憑證類型的欄位與卡面需事先建好,您只送出這一張憑證的欄位值。

  1. 向 TCS 團隊申請憑證類型(VC Template),見申請新的憑證類型與驗證情境。
  2. 您的系統透過 TCS API for DIW 建立一筆發證請求、送出憑證欄位,拿到 QR code 圖片(base64 編碼的 PNG)與手機連結。收證者在手機上點開手機連結,就會開啟數位憑證皮夾(TW DIW,以下簡稱錢包)。
  3. 您的畫面顯示 QR code 或手機連結。
  4. 收證者掃描 QR code 或點開手機連結,按下領取,憑證存進錢包。收證者領取後,就是這張憑證的持卡人。
  5. 您的後端輪詢查到這張憑證已發出,同時拿到這張憑證的 cid(憑證識別碼)與 credential_serial(憑證序號)。

請在第 4 步就存好 cid 與 credential_serial。之後撤銷這張憑證要用 cid;驗證時要確認持卡人出示的是這張憑證,則用 credential_serial 比對。若未存到 cid,請用原本這筆發證的 id 再查詢一次;查詢結果仍是已發出時,會拿到同一個 cid。若 cid 未存到、原本這筆發證也已查不到,就無法透過 API 撤銷這張憑證。

收證者沒有領取時怎麼處理,見限制與注意事項。

發新憑證不會取代舊憑證,同一位持卡人可以同時持有多張同一種憑證類型的有效憑證。要每人只保留一張,見換發。

發證流程:您送出憑證欄位、拿到 QR code 或手機連結、收證者掃描或點開連結並領取、您查到已發出並存下 cid

錢包畫面「已成功加入憑證」:卡面左上角是發證方台灣圖靈鏈股份有限公司與憑證名稱範例公司員工證,左下角是第一個欄位的值王小明,下方是確認按鈕

收證者掃描後,錢包顯示「已成功加入憑證」。

每次驗證要指定一個驗證情境(VP Template)。驗證情境需事先建好,寫明要持卡人出示哪些憑證類型的哪些欄位。

  1. 向 TCS 團隊申請驗證情境(VP Template),見申請新的憑證類型與驗證情境。
  2. 您的系統透過 TCS API for DIW 建立一筆驗證請求,拿到給持卡人用錢包掃描的 QR code 圖片(base64 編碼的 PNG)與手機連結。回應中的 id 請存好,輪詢結果時要帶它。
  3. 您的畫面顯示 QR code 或手機連結。
  4. 持卡人用錢包掃描 QR code(或點開手機連結),選擇要出示的憑證,再同意出示。
  5. 您的後端主動輪詢,拿到憑證欄位與驗證結果。

結果不會推送給您。您的後端要輪詢(Polling)結果,建議每 2 到 5 秒查一次,並設定合理的逾時(建議 5 分鐘)。持卡人完成出示後,驗證結果約保留 5 分鐘,之後即清除。清除後再查不到,要重新建立一筆驗證。

驗證流程:您建立驗證、畫面顯示 QR code 或手機連結、持卡人掃描、選擇憑證並同意出示、您的後端查詢結果;完成後約 5 分鐘結果清除,要重新建立驗證

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

錢包出示畫面:標題是驗證情境名稱員工身分確認,提供資料的對象是台灣圖靈鏈股份有限公司,下方列出要出示的憑證範例公司員工證與欄位憑證序號、姓名、員工編號,以及送出資料按鈕

持卡人在這個畫面確認要出示的欄位,再按「送出資料」。

錢包完成畫面「資料已授權」:您已將資料授權送出至台灣圖靈鏈股份有限公司,下方列出送出的憑證與欄位

送出後,錢包顯示「資料已授權」。

您用 cid 撤銷一張憑證。撤銷後這張憑證永久失效,不能恢復。實測撤銷後約一分鐘內,持卡人的錢包就會顯示這張憑證已失效。

撤銷只影響這一張憑證。同一位持卡人的其他憑證不受影響,包括同一種憑證類型的另一張憑證。

錢包不讓持卡人選擇已撤銷的憑證,所以這張憑證不會出現在驗證結果中。

您看到什麼,取決於持卡人的錢包裡還有哪些同一種憑證類型的憑證:

持卡人的錢包裡您看到的結果
只有被撤銷的那張錢包不讓持卡人選擇這張憑證,因此不會送出任何資料。您查到的狀態在您設定的逾時內都會是 pending(等待中)。
還有另一張同一種憑證類型的有效憑證持卡人出示另一張。您收到驗證通過(verify_result: true),但 cid 是另一張憑證的。
憑證沒有被撤銷(正常情況)您收到驗證結果,依 verify_result 判斷是否通過,並且仍要比對 data[].cid。

您的系統要做兩件事:

  • 確認出示的是哪一張憑證。如果您要確認持卡人出示的是您發出的某一張憑證(例如您撤銷過其中一張),收到結果時請比對 data[].cid 與發證時存下的 credential_serial,比對方法見驗證 API。驗證其他單位發出的憑證(例如駕照)時,您手上沒有 cid 可比對,請依驗證結果(verify_result)、憑證類型識別碼(credential_type)與欄位內容(claims)決定是否接受。
  • 自己設定逾時。查詢一直停在 pending 時,時間到就結束這筆驗證。建議 5 分鐘。

撤銷後再驗證的三種結果:只有被撤銷的憑證時,在您設定的逾時內都是 pending;還有另一張同一種憑證類型的有效憑證時收到驗證通過但 cid 是另一張;憑證沒被撤銷時收到驗證結果,依 verify_result 判斷是否通過,並且仍要比對 data[].cid 與 credential_serial