跳到內容

撤銷 API

您用發證時拿到的 cid,透過 TCS API for DIW 撤銷憑證。實測撤銷後約一分鐘內,持卡人的數位憑證皮夾(TW DIW,以下簡稱錢包)就會把這張憑證顯示為「已失效」。撤銷後不能恢復。

Rendering diagram...
POST /v1/diw/credentials/{cid}/revoke

{cid} 放 GET /v1/diw/issuances/{id} 回 issued 時拿到的 cid,整串不要改。這個請求沒有 body。

每個請求都要帶 X-API-Key,也請帶 x-correlation-id,並把同一個值放進 x-request-id,見 API 基礎。

成功時回 201:

{
"cid": "<cid>",
"credential_status": "REVOKED"
}
欄位說明
cid和您撤銷時帶的 cid 相同。
credential_status撤銷後的狀態:REVOKED。

目前 API 沒有停用(suspend)和恢復(recover)的功能。

只有拿到這個 cid 的帳號能撤銷它。別的帳號送同一個 cid,回 404。

收到 502 時,TCS 無法確認這次撤銷是否已經生效。請直接重送同一個請求:

  • 回 201:撤銷完成。
  • 回 400,message 開頭是 issuer module 30205:這張憑證已經撤銷,表示第一次撤銷已經成功。
  • 回 400,message 開頭是 issuer module,但不是 30205:不能當成第一次已經成功。請帶兩次請求的時間與 x-correlation-id 聯絡 TCS 團隊。
  • 又回 502:稍後再重送。持續回 502 時,請帶每次請求的時間與 x-correlation-id 聯絡 TCS 團隊。

如果您無法確定第一次是否成功,請帶兩次請求的時間與 x-correlation-id/x-request-id 的值 聯絡 TCS 團隊。

其他錯誤見錯誤與輪詢。

撤銷之後,錢包不會讓持卡人出示這張憑證。撤銷過的憑證不會出現在驗證結果裡。

您建立驗證後,會遇到下面三種情況之一:

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

錢包出示畫面:提供資料的對象是台灣圖靈鏈股份有限公司,憑證區塊顯示「目前缺少可授權的憑證」,送出資料按鈕無法點按

表格第一種情況:錢包顯示「目前缺少可授權的憑證」,持卡人無法按「送出資料」。

只看 verify_result 不夠,您的系統還要做兩件事:

  1. 比對 cid。 確認 data[].cid 等於您存下的 credential_serial 才接受。否則可能把持卡人出示的另一張憑證,當成您撤銷的那張。

    data[].cid 要等於發證時存下的 credential_serial,見驗證 API。

  2. 自己設逾時。 驗證一直是 pending 時,時間到就結束這次驗證(建議 5 分鐘),告訴持卡人沒有收到可用的憑證。否則只剩撤銷憑證的持卡人,會一直停在等待畫面。

流程的圖解見運作方式。