跳到內容

驗證 API

驗證流程如下:您建立驗證請求;持卡人用數位憑證皮夾(TW DIW,以下簡稱錢包)掃描,選擇憑證並同意出示;您的後端輪詢 TCS API for DIW,直到拿到結果或逾時。

Rendering diagram...

圖中的 par 表示同時進行,loop 表示重複執行,alt 表示依情況走其中一條。

POST /v1/diw/verifications

每個請求都要帶 X-API-Key,也請帶 x-correlation-id,並把同一個值放進 x-request-id;POST 另外要帶 Content-Type: application/json。見 API 基礎。

Request body 只有一個欄位:

欄位型別必填說明
refstring是驗證情境(VP Template)的代碼。由您的組織申請,TCS 團隊建立後提供,見申請新的憑證類型與驗證情境。它決定持卡人要出示哪些憑證、哪些欄位。
{
"ref": "<ref>"
}

ref 必須是非空字串。缺少、空字串或不是字串,回 400。body 裡多帶其他欄位,也回 400。

找不到這個驗證情境時,回 400,錯誤碼是 10102。其他狀態碼與處理方式見錯誤與輪詢。

成功時回 201:

{
"id": "<id>",
"qrcode_image": "data:image/png;base64,iVBORw0K...",
"auth_uri": "https://frontend.wallet.gov.tw/api/moda/vpqrcode?mode=vp01&deeplink=..."
}
欄位說明
id這次驗證的 id。查詢結果時整串帶回。
qrcode_imageQR code 圖片(base64 PNG data URI),給桌面網頁顯示。
auth_uri手機連結。持卡人正在用手機時,開啟這個 https 連結就會打開錢包 app。內容和 QR code 相同。

id、QR code 與手機連結的用法見 API 基礎。

GET /v1/diw/verifications/{id}

{id} 放建立時拿到的 id,整串不要改。持卡人還沒完成時回 200:

{
"status": "pending",
"id": "<id>"
}

status 只有兩種值:pending 和 completed。

  • pending:持卡人還沒完成。2 到 5 秒後再查一次。
  • completed:有結果了。讀法見下一節。

持卡人沒有掃描,或錢包不讓持卡人選擇憑證時,在您設定的逾時內都會是 pending(等待中)。請自己設逾時,建議 5 分鐘。時間到就停止查詢,請持卡人重新開始。

只有建立這筆驗證請求的帳號能查詢結果。用其他帳號的 API Key 查詢同一個 id,會回 404。

{
"status": "completed",
"verify_result": true,
"result_description": "success",
"holder_did": "did:key:z...",
"transaction_id": "<transaction_id>",
"data": [
{
"cid": "<cid>",
"credential_type": "2-16-886-101-20003-20008-20082_driverlicense_car_1211",
"claims": [
{ "ename": "name", "cname": "姓名", "value": "<姓名>" },
{ "ename": "license_type", "cname": "駕照種類", "value": "汽車(普小)" },
{ "ename": "issued_date", "cname": "發照日期", "value": "110.03.15" }
]
}
]
}
欄位型別說明
verify_resultbooleantrue 表示驗證通過。false 表示驗證不通過;有 result_description 時,原因寫在這個欄位。
result_descriptionstring(選填)驗證結果的說明文字,原文照轉。可能沒有這個欄位。
holder_didstring(選填)持卡人的 DID。可能沒有這個欄位。
transaction_idstring和您查詢用的 id 相同。
data[]array持卡人出示的憑證,一張憑證一筆。驗證情境要求多種憑證類型時會有多筆,請逐筆讀取,不要只讀第一筆。
data[].cidstring這張憑證的識別碼。
data[].credential_typestring驗證結果回報的憑證類型識別碼,原文照轉。
data[].claims[]array持卡人出示的欄位。出現哪些欄位由驗證情境決定。
claims[].enamestring欄位英文名稱。
claims[].cnamestring欄位中文名稱。
claims[].valuestring欄位值,一律是字串,照持卡人出示的原文。

錢包一定會送出「憑證序號」,持卡人不能取消勾選這個項目。

憑證上的值可能包含全形括號(例如 汽車(普小))或民國日期(例如 110.03.15),請不要假設 value 的格式。

  • 您要確認持卡人出示的是您發的某一張憑證(例如您撤銷過其中一張):請務必比對 cid,比對方式見下方。
  • 您驗證的是其他單位發的憑證(例如駕照):您手上沒有 cid 可以比對。請依 verify_result、credential_type 和 claims 決定是否接受。

驗證通過(verify_result: true)只代表持卡人出示的那張憑證有效,不代表那是您預期的憑證。持卡人的錢包裡可能有兩張同一種憑證類型的憑證。您發給持卡人的那張憑證撤銷之後,持卡人仍可以出示另一張有效的憑證。這時您會收到驗證通過(verify_result: true),但 data[].cid 是另一張憑證的。

如果這張憑證是您透過發證 API 發出的,比對方式如下:

  1. 發證後,存下 GET /v1/diw/issuances/{id} 回傳的 credential_serial。
  2. 驗證時,data[].cid 等於您存下的 credential_serial,才是您預期的那張憑證。

不要拿發證時的 cid 比對,兩者格式不同,永遠不會相等。

撤銷之後的完整行為見撤銷 API。

驗證完成大約 5 分鐘後,結果會清除。之後再查詢同一個 id,回 410(error 是 Gone)。

收到 410 時,結果已經拿不回來。請建立新的驗證請求,讓持卡人重新掃描。

要避免收到 410,請在 QR code 顯示期間每 2 到 5 秒查詢一次,拿到 completed 後立刻存下您要的欄位。