發證 API
發證流程如下:您送出憑證欄位;收證者用數位憑證皮夾(TW DIW,以下簡稱錢包)掃描並領取憑證;您的後端輪詢 TCS API for DIW,直到狀態變成 issued;最後存下這張憑證的 cid。憑證上的發證方顯示台灣圖靈鏈股份有限公司,不是您的組織。收證者領取後,就是這張憑證的持卡人。
API 無法指定由誰領取。請只把 QR code 和手機連結給您預期的收證者。
圖中的 par 表示同時進行,loop 表示重複執行,alt 表示依情況走其中一條。
POST /v1/diw/issuances| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
vc_uid | string | 是 | 憑證類型(VC Template)的代碼。由您的組織申請,TCS 團隊建立後提供,見申請新的憑證類型與驗證情境。找不到時回 10108,已停止發行時回 11007。 |
fields | array | 是 | 憑證欄位,每筆是 {ename, content}。 |
fields[].ename | string | 是 | 欄位名稱(英),要和憑證類型定義的 ename 完全相同。 |
fields[].content | string | 是 | 欄位值。一律是字串,布林值也寫成文字,例如 true / false。 |
issuance_date | string | 否 | 發行日,格式 YYYYMMDD,台灣時間。不可以是未來的日期。憑證從這天 00:00:00 開始有效。不帶就是今天。不是 8 位數字時回 400,沒有模組錯誤碼;是 8 位數字但不是存在的日期(例如 20261340)回 10109;是未來日期回 10113。 |
expired_date | string | 否 | 到期日,格式 YYYYMMDD,台灣時間。憑證到這天 23:59:59 失效。不帶就用憑證類型設定的有效期間,從收證者掃描 QR code 時起算。不可以早於今天,也不可以早於憑證類型的建立日期。不是 8 位數字時回 400,沒有模組錯誤碼;是 8 位數字但不是存在的日期回 10109;日期太早回 10114。 |
cids | string[] | 否 | 這次發證時要一起撤銷的舊憑證 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_image | QR code 圖片(base64 PNG data URI),給桌面網頁顯示。 |
deep_link | 手機連結:在手機上開啟錢包 app,內容和 QR code 相同。 |
warnings | 和 cids 有關的警告。沒帶 cids 時是 null。格式見下方「換發:發新憑證時撤銷舊憑證」。 |
請把 id、qrcode_image 和 deep_link 一起存下來。收證者等太久時,您可能要再顯示同一組 QR code 或手機連結。
輪詢領取狀態
Section titled “輪詢領取狀態”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 為止。
要替同一個人重新發證前,請這樣做:
- 保留原本發證的
id,不要丟掉。 - 用這個
id再查一次狀態。 - 如果已經是
issued,存下cid,不用重新發證。 - 如果仍是
pending,再顯示原本存下的qrcode_image或deep_link,請收證者用它領取,不要建立新的發證。如果錢包不接受原本的 QR code 或手機連結,再建立新的發證,並依第 5 步處理。 - 如果您還是必須建立新的發證,之後兩筆發證都可能變成
issued。這時用多出來那張憑證的cid撤銷它。
存下 cid 與 credential_serial
Section titled “存下 cid 與 credential_serial”拿到 issued 時,請立刻把 cid 和 credential_serial 整串存進您的資料庫,和您自己的使用者對應起來。您之後需要它們來:
- 用
cid撤銷這張憑證。 - 換發時把
cid放進cids。 - 驗證時用
credential_serial比對data[].cid,確認出示的是這張憑證。
cid 弄丟時,如果您還留著發證的 id,再查一次 GET /v1/diw/issuances/{id}。查詢結果仍是 issued 時,會拿到同一個 cid 與 credential_serial。API 目前沒有列出已發憑證的功能,所以請在第一次拿到 issued 時就存下 cid。
建立發證不能自動重送
Section titled “建立發證不能自動重送”POST /v1/diw/issuances 送兩次,會建立兩次發證(這支 API 不是 idempotent)。
下面幾種情況,發證都可能已經建立:
- 收到
502或其他5xx。 - 您的 HTTP client 等到逾時。
- 連線中斷,或回應在路上遺失,您沒有收到任何回應。
TCS 這一端處理超過 5 秒沒有完成會回 502。請把 HTTP client 的逾時設得比 5 秒長,例如 10 秒,這樣您比較會收到 502,而不是完全沒有回應。
您沒有辦法透過 API 確認,因為目前沒有列出發證紀錄的功能。遇到上面任何一種情況:
- 不要自動重送。如果您使用的 HTTP client、SDK 或 API gateway 會在請求失敗時自動重送,請對建立發證這支 API 關閉這個功能,避免同一筆發證被建立兩次。
- 記下送出請求的時間和您帶的
x-correlation-id/x-request-id的值。 - 聯絡 TCS 團隊,TCS 團隊會幫您查。
400 表示 API 拒絕了請求內容。照錯誤訊息修正後再送。常見的錯誤碼見錯誤與輪詢。
換發:發新憑證時撤銷舊憑證
Section titled “換發:發新憑證時撤銷舊憑證”發新憑證不會取代舊憑證。同一位持卡人可以同時持有多張同一種憑證類型的有效憑證。如果您要每人只保留一張(例如員工證),發新憑證時把舊憑證的 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 團隊。