跳到內容

限制與注意事項

以下限制適用於透過 TCS 串接數位憑證皮夾(TW DIW,以下簡稱錢包)的所有組織。工程師處理這些情況的方式,見錯誤與輪詢。

目前不提供測試環境。驗收在正式環境進行,發證與撤銷都會產生實際效果。

錢包上的驗證要求方與發證方只顯示台灣圖靈鏈股份有限公司

Section titled “錢包上的驗證要求方與發證方只顯示台灣圖靈鏈股份有限公司”

錢包有兩處顯示台灣圖靈鏈股份有限公司,不是您的組織:

  • 驗證時,錢包同意畫面上的驗證要求方。
  • 發證時,憑證上的發證方。

您能決定的是憑證卡面的名稱與圖片。卡面圖片可以放您組織的品牌,讓持卡人可從卡面辨識這是您組織的憑證(見開始使用)。但錢包同意畫面上的驗證要求方與憑證上的發證方,仍是台灣圖靈鏈股份有限公司。

如果您的服務要求這兩處顯示您的組織,透過 TCS 串接無法滿足此需求,請在決定串接前評估。您的服務條款與對持卡人的說明,請載明驗證要求方與發證方顯示為台灣圖靈鏈股份有限公司。

持卡人完成出示後,驗證結果約保留 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 確認這筆發證是否已經建立。

遇到這種情況,請依下列方式處理:

  1. 如果您使用的 HTTP client、SDK 或 API gateway 會在請求失敗時自動重送,請對建立發證這支 API 關閉這個功能,避免同一筆發證被建立兩次。
  2. 記下送出請求的時間與 x-correlation-id/x-request-id 的值。
  3. 聯絡 TCS 團隊,提供請求時間與這個值,由 TCS 團隊協助確認。

驗證與撤銷沒有這個問題,收到 502 時可以重送。建立驗證重送後會產生新的 id,請改用新的 QR code;撤銷重送時回 400 且代碼是 30205,表示第一次已經撤銷成功。處理方式見撤銷 API。

目前提供三項功能:發證、驗證、撤銷單張憑證。目前不提供下列功能:

  • 暫時停用(suspend)一張憑證,之後再恢復(recover)。撤銷是永久的,不能恢復。
  • 列出您已發出的憑證。目前沒有這個功能,請務必存下發證結果中的 cid,撤銷要用它。每筆發證的 id 也請存下,作為備援:沒存到 cid 時,可以用 id 再查一次取回 cid,但查詢結果不保證一直保留。
  • 一次撤銷多張憑證。撤銷 API 每次只能撤銷一張。只有換發時(發新憑證並同時撤銷舊憑證),可以在同一個發證請求中撤銷多張舊憑證,見發證 API。
  • 取消尚未領取的發證。
  • 列出或搜尋您已建立的發證請求。建立發證沒有收到 id 時,無法透過 API 找回這筆發證。

需要這些功能,請聯絡 TCS 團隊。

憑證類型與驗證情境目前沒有限定帳號使用。代碼由 TCS 團隊提供,請不要公開。