驗證 API
驗證流程如下:您建立驗證請求;持卡人用數位憑證皮夾(TW DIW,以下簡稱錢包)掃描,選擇憑證並同意出示;您的後端輪詢 TCS API for DIW,直到拿到結果或逾時。
圖中的 par 表示同時進行,loop 表示重複執行,alt 表示依情況走其中一條。
建立驗證請求
Section titled “建立驗證請求”POST /v1/diw/verifications每個請求都要帶 X-API-Key,也請帶 x-correlation-id,並把同一個值放進 x-request-id;POST 另外要帶 Content-Type: application/json。見 API 基礎。
Request body 只有一個欄位:
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
ref | string | 是 | 驗證情境(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_image | QR 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。
讀取 completed 結果
Section titled “讀取 completed 結果”{ "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_result | boolean | true 表示驗證通過。false 表示驗證不通過;有 result_description 時,原因寫在這個欄位。 |
result_description | string(選填) | 驗證結果的說明文字,原文照轉。可能沒有這個欄位。 |
holder_did | string(選填) | 持卡人的 DID。可能沒有這個欄位。 |
transaction_id | string | 和您查詢用的 id 相同。 |
data[] | array | 持卡人出示的憑證,一張憑證一筆。驗證情境要求多種憑證類型時會有多筆,請逐筆讀取,不要只讀第一筆。 |
data[].cid | string | 這張憑證的識別碼。 |
data[].credential_type | string | 驗證結果回報的憑證類型識別碼,原文照轉。 |
data[].claims[] | array | 持卡人出示的欄位。出現哪些欄位由驗證情境決定。 |
claims[].ename | string | 欄位英文名稱。 |
claims[].cname | string | 欄位中文名稱。 |
claims[].value | string | 欄位值,一律是字串,照持卡人出示的原文。 |
錢包一定會送出「憑證序號」,持卡人不能取消勾選這個項目。
憑證上的值可能包含全形括號(例如 汽車(普小))或民國日期(例如 110.03.15),請不要假設 value 的格式。
只有您發的憑證需要比對 cid
Section titled “只有您發的憑證需要比對 cid”- 您要確認持卡人出示的是您發的某一張憑證(例如您撤銷過其中一張):請務必比對
cid,比對方式見下方。 - 您驗證的是其他單位發的憑證(例如駕照):您手上沒有
cid可以比對。請依verify_result、credential_type和claims決定是否接受。
驗證通過(verify_result: true)只代表持卡人出示的那張憑證有效,不代表那是您預期的憑證。持卡人的錢包裡可能有兩張同一種憑證類型的憑證。您發給持卡人的那張憑證撤銷之後,持卡人仍可以出示另一張有效的憑證。這時您會收到驗證通過(verify_result: true),但 data[].cid 是另一張憑證的。
如果這張憑證是您透過發證 API 發出的,比對方式如下:
- 發證後,存下
GET /v1/diw/issuances/{id}回傳的credential_serial。 - 驗證時,
data[].cid等於您存下的credential_serial,才是您預期的那張憑證。
不要拿發證時的 cid 比對,兩者格式不同,永遠不會相等。
撤銷之後的完整行為見撤銷 API。
結果過期會回 410
Section titled “結果過期會回 410”驗證完成大約 5 分鐘後,結果會清除。之後再查詢同一個 id,回 410(error 是 Gone)。
收到 410 時,結果已經拿不回來。請建立新的驗證請求,讓持卡人重新掃描。
要避免收到 410,請在 QR code 顯示期間每 2 到 5 秒查詢一次,拿到 completed 後立刻存下您要的欄位。