跳到內容

發證 API

發證流程如下:您送出憑證欄位;收證者用數位憑證皮夾(TW DIW,以下簡稱錢包)掃描並領取憑證;您的後端輪詢 TCS API for DIW,直到狀態變成 issued;最後存下這張憑證的 cid。憑證上的發證方顯示台灣圖靈鏈股份有限公司,不是您的組織。收證者領取後,就是這張憑證的持卡人。

API 無法指定由誰領取。請只把 QR code 和手機連結給您預期的收證者。

Rendering diagram...

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

POST /v1/diw/issuances
欄位型別必填說明
vc_uidstring是憑證類型(VC Template)的代碼。由您的組織申請,TCS 團隊建立後提供,見申請新的憑證類型與驗證情境。找不到時回 10108,已停止發行時回 11007。
fieldsarray是憑證欄位,每筆是 {ename, content}。
fields[].enamestring是欄位名稱(英),要和憑證類型定義的 ename 完全相同。
fields[].contentstring是欄位值。一律是字串,布林值也寫成文字,例如 true / false。
issuance_datestring否發行日,格式 YYYYMMDD,台灣時間。不可以是未來的日期。憑證從這天 00:00:00 開始有效。不帶就是今天。不是 8 位數字時回 400,沒有模組錯誤碼;是 8 位數字但不是存在的日期(例如 20261340)回 10109;是未來日期回 10113。
expired_datestring否到期日,格式 YYYYMMDD,台灣時間。憑證到這天 23:59:59 失效。不帶就用憑證類型設定的有效期間,從收證者掃描 QR code 時起算。不可以早於今天,也不可以早於憑證類型的建立日期。不是 8 位數字時回 400,沒有模組錯誤碼;是 8 位數字但不是存在的日期回 10109;日期太早回 10114。
cidsstring[]否這次發證時要一起撤銷的舊憑證 cid,用在換發。見下方「換發:發新憑證時撤銷舊憑證」。

fields 的規則:

  • 必填欄位都要放進 fields。少了必填欄位,或必填欄位的值是空字串,回 400,message 開頭是 issuer module 11001。選填欄位沒有值時,可以不帶,也可以帶空字串。
  • 不要帶憑證類型沒定義的欄位,否則回 400,message 開頭是 issuer module 10112。
  • 照您希望卡面顯示的順序排列。API 不會幫您重排。第一個欄位的值會印在卡面上。
  • content 要符合該欄位的規則。不符合時回 400,message 開頭是 issuer module 10110,錯誤訊息不會指出是哪個欄位。
  • 基本欄位「姓名」(name)只能用中文、英文、數字和 _。英文姓名中間有空格時,會回 10110。
{
"vc_uid": "<vc_uid>",
"fields": [
{ "ename": "name", "content": "王小明" },
{ "ename": "department", "content": "研發部" },
{ "ename": "position", "content": "工程師" },
{ "ename": "employee_id", "content": "A12345" }
],
"expired_date": "20271031"
}

成功時回 201:

{
"id": "<id>",
"qrcode_image": "data:image/png;base64,iVBORw0K...",
"deep_link": "https://frontend.wallet.gov.tw/api/moda/vcqrcode?mode=vc01&deeplink=...",
"warnings": null
}
欄位說明
id這次發證的 id。查詢領取狀態時整串帶回。
qrcode_imageQR code 圖片(base64 PNG data URI),給桌面網頁顯示。
deep_link手機連結:在手機上開啟錢包 app,內容和 QR code 相同。
warnings和 cids 有關的警告。沒帶 cids 時是 null。格式見下方「換發:發新憑證時撤銷舊憑證」。

請把 id、qrcode_image 和 deep_link 一起存下來。收證者等太久時,您可能要再顯示同一組 QR code 或手機連結。

GET /v1/diw/issuances/{id}

收證者還沒領取時回 200:

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

收證者領取後回 200:

{
"status": "issued",
"id": "<id>",
"credential": "eyJqa3UiOi...",
"cid": "<cid>",
"credential_serial": "<credential_serial>"
}

status 只有兩種值:

  • pending:收證者還沒掃描或還沒領取。2 到 5 秒後再查一次。
  • issued:收證者已經領取。
欄位說明
credential簽好的憑證(SD-JWT 格式),TCS 照原樣轉給您。這個字串裡沒有欄位值。
cid這張憑證的識別碼。撤銷與換發時要用。
credential_serial這張憑證的序號,錢包上顯示為「憑證序號」。驗證時拿它和 data[].cid 比對,見驗證 API。

只有建立這筆發證請求的帳號能查詢結果。用其他帳號的 API Key 查詢同一個 id,會回 404。其他會回 400/404 的情況見錯誤與輪詢。

收證者沒有掃描或還沒領取時,在您設定的逾時內都會是 pending(等待中)。請自己設逾時,建議 5 分鐘。這個逾時只結束您的等待畫面,不會取消發證。收證者之後仍可能掃描原本的 QR code 領取憑證。

等待畫面關閉後,請把還沒有結果的發證留在待處理清單,之後再查詢,直到狀態變成 issued 為止。

要替同一個人重新發證前,請這樣做:

  1. 保留原本發證的 id,不要丟掉。
  2. 用這個 id 再查一次狀態。
  3. 如果已經是 issued,存下 cid,不用重新發證。
  4. 如果仍是 pending,再顯示原本存下的 qrcode_image 或 deep_link,請收證者用它領取,不要建立新的發證。如果錢包不接受原本的 QR code 或手機連結,再建立新的發證,並依第 5 步處理。
  5. 如果您還是必須建立新的發證,之後兩筆發證都可能變成 issued。這時用多出來那張憑證的 cid 撤銷它。

拿到 issued 時,請立刻把 cid 和 credential_serial 整串存進您的資料庫,和您自己的使用者對應起來。您之後需要它們來:

cid 弄丟時,如果您還留著發證的 id,再查一次 GET /v1/diw/issuances/{id}。查詢結果仍是 issued 時,會拿到同一個 cid 與 credential_serial。API 目前沒有列出已發憑證的功能,所以請在第一次拿到 issued 時就存下 cid。

POST /v1/diw/issuances 送兩次,會建立兩次發證(這支 API 不是 idempotent)。

下面幾種情況,發證都可能已經建立:

  • 收到 502 或其他 5xx。
  • 您的 HTTP client 等到逾時。
  • 連線中斷,或回應在路上遺失,您沒有收到任何回應。

TCS 這一端處理超過 5 秒沒有完成會回 502。請把 HTTP client 的逾時設得比 5 秒長,例如 10 秒,這樣您比較會收到 502,而不是完全沒有回應。

您沒有辦法透過 API 確認,因為目前沒有列出發證紀錄的功能。遇到上面任何一種情況:

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

400 表示 API 拒絕了請求內容。照錯誤訊息修正後再送。常見的錯誤碼見錯誤與輪詢。

發新憑證不會取代舊憑證。同一位持卡人可以同時持有多張同一種憑證類型的有效憑證。如果您要每人只保留一張(例如員工證),發新憑證時把舊憑證的 cid 放進 cids;如果可以同時持有多張(例如每次活動的參加證明),就不要帶 cids。

在 cids 放入舊憑證的 cid。收證者領取新憑證時,那些舊憑證會一起撤銷;收證者沒有領取,舊憑證就維持有效。cids 的規則:

  • 要放發證時拿到的整串 cid,不要截掉任何部分。格式不對,回 400。
  • 不是您的帳號發出的 cid,回 404。
  • 只要有一筆不對,API 就不會發證,也不會撤銷任何舊憑證。

舊憑證已經撤銷過,或系統找不到這張憑證時,請求仍然成功,warnings 會列出這些憑證。warnings 是一個物件,有兩個欄位,各是一個陣列;沒有對應的憑證時,該欄位是 null:

欄位內容
warnings.statusRevoke已經撤銷過的舊憑證
warnings.cidNotFound系統找不到的舊憑證

warnings 列出的是憑證序號,不是 cid。請用發證時存下的 credential_serial 找出對應的舊憑證。

帶 cids 的請求收到 502 或其他 5xx,或沒有收到回應時,新的發證可能已經建立。舊憑證要等收證者領取新憑證時才會撤銷。處理方式和上一節相同:不要自動重送,聯絡 TCS 團隊。