運作方式
發證、驗證、撤銷三個流程,您的系統都只呼叫 TCS API for DIW。API 的呼叫方式見發證 API、驗證 API 與撤銷 API。
每次發證要指定一種憑證類型(VC Template)。憑證類型的欄位與卡面需事先建好,您只送出這一張憑證的欄位值。
- 向 TCS 團隊申請憑證類型(VC Template),見申請新的憑證類型與驗證情境。
- 您的系統透過 TCS API for DIW 建立一筆發證請求、送出憑證欄位,拿到 QR code 圖片(base64 編碼的 PNG)與手機連結。收證者在手機上點開手機連結,就會開啟數位憑證皮夾(TW DIW,以下簡稱錢包)。
- 您的畫面顯示 QR code 或手機連結。
- 收證者掃描 QR code 或點開手機連結,按下領取,憑證存進錢包。收證者領取後,就是這張憑證的持卡人。
- 您的後端輪詢查到這張憑證已發出,同時拿到這張憑證的
cid(憑證識別碼)與credential_serial(憑證序號)。
請在第 4 步就存好 cid 與 credential_serial。之後撤銷這張憑證要用 cid;驗證時要確認持卡人出示的是這張憑證,則用 credential_serial 比對。若未存到 cid,請用原本這筆發證的 id 再查詢一次;查詢結果仍是已發出時,會拿到同一個 cid。若 cid 未存到、原本這筆發證也已查不到,就無法透過 API 撤銷這張憑證。
收證者沒有領取時怎麼處理,見限制與注意事項。
發新憑證不會取代舊憑證,同一位持卡人可以同時持有多張同一種憑證類型的有效憑證。要每人只保留一張,見換發。

收證者掃描後,錢包顯示「已成功加入憑證」。
每次驗證要指定一個驗證情境(VP Template)。驗證情境需事先建好,寫明要持卡人出示哪些憑證類型的哪些欄位。
- 向 TCS 團隊申請驗證情境(VP Template),見申請新的憑證類型與驗證情境。
- 您的系統透過 TCS API for DIW 建立一筆驗證請求,拿到給持卡人用錢包掃描的 QR code 圖片(base64 編碼的 PNG)與手機連結。回應中的
id請存好,輪詢結果時要帶它。 - 您的畫面顯示 QR code 或手機連結。
- 持卡人用錢包掃描 QR code(或點開手機連結),選擇要出示的憑證,再同意出示。
- 您的後端主動輪詢,拿到憑證欄位與驗證結果。
結果不會推送給您。您的後端要輪詢(Polling)結果,建議每 2 到 5 秒查一次,並設定合理的逾時(建議 5 分鐘)。持卡人完成出示後,驗證結果約保留 5 分鐘,之後即清除。清除後再查不到,要重新建立一筆驗證。
錢包在出示畫面顯示「提供資料的對象:台灣圖靈鏈股份有限公司」,完成畫面顯示資料已送出至台灣圖靈鏈股份有限公司。這兩處由錢包固定顯示,您無法更改。

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

送出後,錢包顯示「資料已授權」。
您用 cid 撤銷一張憑證。撤銷後這張憑證永久失效,不能恢復。實測撤銷後約一分鐘內,持卡人的錢包就會顯示這張憑證已失效。
撤銷只影響這一張憑證。同一位持卡人的其他憑證不受影響,包括同一種憑證類型的另一張憑證。
撤銷後再驗證會看到什麼
Section titled “撤銷後再驗證會看到什麼”錢包不讓持卡人選擇已撤銷的憑證,所以這張憑證不會出現在驗證結果中。
您看到什麼,取決於持卡人的錢包裡還有哪些同一種憑證類型的憑證:
| 持卡人的錢包裡 | 您看到的結果 |
|---|---|
| 只有被撤銷的那張 | 錢包不讓持卡人選擇這張憑證,因此不會送出任何資料。您查到的狀態在您設定的逾時內都會是 pending(等待中)。 |
| 還有另一張同一種憑證類型的有效憑證 | 持卡人出示另一張。您收到驗證通過(verify_result: true),但 cid 是另一張憑證的。 |
| 憑證沒有被撤銷(正常情況) | 您收到驗證結果,依 verify_result 判斷是否通過,並且仍要比對 data[].cid。 |
您的系統要做兩件事:
- 確認出示的是哪一張憑證。如果您要確認持卡人出示的是您發出的某一張憑證(例如您撤銷過其中一張),收到結果時請比對
data[].cid與發證時存下的credential_serial,比對方法見驗證 API。驗證其他單位發出的憑證(例如駕照)時,您手上沒有cid可比對,請依驗證結果(verify_result)、憑證類型識別碼(credential_type)與欄位內容(claims)決定是否接受。 - 自己設定逾時。查詢一直停在
pending時,時間到就結束這筆驗證。建議 5 分鐘。