限制與注意事項
以下限制適用於透過 TCS 串接數位憑證皮夾(TW DIW,以下簡稱錢包)的所有組織。工程師處理這些情況的方式,見錯誤與輪詢。
目前不提供測試環境。驗收在正式環境進行,發證與撤銷都會產生實際效果。
錢包上的驗證要求方與發證方只顯示台灣圖靈鏈股份有限公司
Section titled “錢包上的驗證要求方與發證方只顯示台灣圖靈鏈股份有限公司”錢包有兩處顯示台灣圖靈鏈股份有限公司,不是您的組織:
- 驗證時,錢包同意畫面上的驗證要求方。
- 發證時,憑證上的發證方。
您能決定的是憑證卡面的名稱與圖片。卡面圖片可以放您組織的品牌,讓持卡人可從卡面辨識這是您組織的憑證(見開始使用)。但錢包同意畫面上的驗證要求方與憑證上的發證方,仍是台灣圖靈鏈股份有限公司。
如果您的服務要求這兩處顯示您的組織,透過 TCS 串接無法滿足此需求,請在決定串接前評估。您的服務條款與對持卡人的說明,請載明驗證要求方與發證方顯示為台灣圖靈鏈股份有限公司。
驗證結果只保留約 5 分鐘
Section titled “驗證結果只保留約 5 分鐘”持卡人完成出示後,驗證結果約保留 5 分鐘,之後即清除。
結果清除後無法再取得,須重新建立一筆驗證,並請持卡人掃描新的 QR code。請在持卡人完成後立即讀取結果;照建議頻率輪詢,通常能在清除前拿到結果。
結果不會主動通知,須由您的後端查詢
Section titled “結果不會主動通知,須由您的後端查詢”發證與驗證的結果都不會推送給您的系統。您的後端要在畫面顯示 QR code 的期間,建議每 2 到 5 秒查一次。
收證者或持卡人沒有掃描,或錢包不讓持卡人選擇憑證時,查到的狀態在您設定的逾時內都會是 pending(等待中)。您要自己設定逾時,建議 5 分鐘。
- 發證:逾時只結束您自己的等待畫面,不會取消這筆發證。目前沒有取消發證的功能,收證者(領取後就是持卡人)之後仍可能用原本的 QR code 領取。請依下列方式處理:
- 建立發證時,存好回應裡的
id、QR code 與手機連結。 - 收證者回來時,先用
id查詢這筆發證。已發出就存下cid,不用重新發證;仍是等待中,就再顯示原本那組 QR code 或手機連結,不要建立新的發證。 - 若必須建立新的發證,且之後兩筆都變成已發出,請用多餘那張憑證的
cid撤銷該憑證。
- 建立發證時,存好回應裡的
- 驗證:逾時後結束這筆驗證;需要時重新建立一筆驗證。
建立發證遇到錯誤時不能自動重送
Section titled “建立發證遇到錯誤時不能自動重送”建立發證時如果收到 502 或其他 5xx(TCS 這一端沒有正常完成),或完全沒有收到回應(例如逾時、連線中斷),這筆發證仍可能已經建立。如果這次發證同時要撤銷舊憑證,舊憑證要等收證者領取新憑證時才會撤銷。目前沒有方法透過 TCS API for DIW 確認這筆發證是否已經建立。
遇到這種情況,請依下列方式處理:
- 如果您使用的 HTTP client、SDK 或 API gateway 會在請求失敗時自動重送,請對建立發證這支 API 關閉這個功能,避免同一筆發證被建立兩次。
- 記下送出請求的時間與
x-correlation-id/x-request-id的值。 - 聯絡 TCS 團隊,提供請求時間與這個值,由 TCS 團隊協助確認。
驗證與撤銷沒有這個問題,收到 502 時可以重送。建立驗證重送後會產生新的 id,請改用新的 QR code;撤銷重送時回 400 且代碼是 30205,表示第一次已經撤銷成功。處理方式見撤銷 API。
目前不支援的功能
Section titled “目前不支援的功能”目前提供三項功能:發證、驗證、撤銷單張憑證。目前不提供下列功能:
- 暫時停用(suspend)一張憑證,之後再恢復(recover)。撤銷是永久的,不能恢復。
- 列出您已發出的憑證。目前沒有這個功能,請務必存下發證結果中的
cid,撤銷要用它。每筆發證的id也請存下,作為備援:沒存到cid時,可以用id再查一次取回cid,但查詢結果不保證一直保留。 - 一次撤銷多張憑證。撤銷 API 每次只能撤銷一張。只有換發時(發新憑證並同時撤銷舊憑證),可以在同一個發證請求中撤銷多張舊憑證,見發證 API。
- 取消尚未領取的發證。
- 列出或搜尋您已建立的發證請求。建立發證沒有收到
id時,無法透過 API 找回這筆發證。
需要這些功能,請聯絡 TCS 團隊。
憑證類型與驗證情境目前沒有限定帳號使用。代碼由 TCS 團隊提供,請不要公開。