API 基礎
您的後端呼叫 TCS 提供的 REST API(以下稱 TCS API for DIW),就能在數位憑證皮夾(TW DIW,以下簡稱錢包)上發證、驗證與撤銷憑證。
本手冊使用以下兩個名詞:
- 驗證情境(VP Template):決定持卡人要出示哪些憑證與欄位。代碼是
ref。 - 憑證類型(VC Template):定義一種憑證包含哪些欄位,以及有效期間。代碼是
vc_uid。
兩種代碼都由 TCS 團隊建立後交給您。申請方式見開始使用。
正式環境網址(base URL):
https://diw.turingspace.co所有路徑都以 /v1 開頭,例如 POST https://diw.turingspace.co/v1/diw/verifications。
請求與回應的 body 都是 JSON,欄位名稱使用 snake_case。錯誤回應的 statusCode、correlationId,以及 warnings 裡的 statusRevoke、cidNotFound 例外,請照各頁列出的名稱讀取,不要自動轉換命名格式。送出 POST 請求時,請帶 Content-Type: application/json。
目前不提供測試環境。
每個請求都帶 API Key
Section titled “每個請求都帶 API Key”請將 API Key 放在請求標頭(header)X-API-Key。API Key 有問題時,API 回 401,message 會說明原因:
message | 意思 | 您要做的事 |
|---|---|---|
API Key is required | 請求沒有帶 X-API-Key | 加上 header。 |
Invalid API Key | 這把 API Key 不存在 | 檢查 API Key 是否複製完整。 |
API key has expired (grace window passed) | 這把 API Key 已經失效 | 改用 TCS 團隊核發的新 API Key;尚未取得時,請聯絡 TCS 團隊。 |
Account is not approved | 這個帳號目前不能使用 | 聯絡 TCS 團隊。 |
Authentication failed | TCS 這一端檢查 API Key 時出錯,不一定是您的 API Key 有問題 | 請稍後重送。API Key 確定無誤卻持續發生時,請帶請求時間與 x-correlation-id 聯絡 TCS 團隊。 |
API Key 請只保存在您的後端伺服器。不建議放在前端環境,例如網頁前端(web app)或行動 app(mobile app),因為這些環境的程式碼可被使用者取得,API Key 可能因此外流。
每個請求都帶 x-correlation-id 與 x-request-id
Section titled “每個請求都帶 x-correlation-id 與 x-request-id”x-correlation-id 是您自己產生的追蹤碼,例如每個請求產生一個 UUID。API 回錯誤(4xx、5xx)時,錯誤回應會在 correlationId 欄位帶回這個值。
請把同一個值也放進 x-request-id。TCS 的 log 用 x-request-id 記錄每一筆請求,包含成功的請求;回應遺失時,TCS 團隊要靠它找到這筆請求。只帶 x-correlation-id 時,成功的請求在 log 中查不到這個值。聯絡 TCS 團隊時,請一併提供請求時間與這個值。
curl -X POST https://diw.turingspace.co/v1/diw/verifications \ -H "X-API-Key: <your-api-key>" \ -H "x-correlation-id: <your-correlation-id>" \ -H "x-request-id: <your-correlation-id>" \ -H "Content-Type: application/json" \ -d '{"ref": "<ref>"}'收到 201 表示網址與 API Key 都正確。回應內容與後續輪詢方式見驗證 API;發證見發證 API。
錯誤回應的格式:
{ "statusCode": 404, "message": "verification not found", "error": "Not Found", "timestamp": "2026-10-16T03:12:45.123Z", "path": "/v1/diw/verifications/<id>", "correlationId": "<your-correlation-id>"}沒有帶 x-correlation-id 時,回應不會有 correlationId 欄位。502 的回應有時是純文字,不是這個格式,因此請在送出請求前,先把 x-correlation-id 記進您的 log。
各狀態碼的意思與處理方式見錯誤與輪詢。
id 原樣保存、原樣帶回
Section titled “id 原樣保存、原樣帶回”API 會回給您三種 id:
| id | 何時何處拿到 | 用途 |
|---|---|---|
發證請求的 id | 建立發證請求的回應(POST /v1/diw/issuances) | 查詢領取狀態 |
憑證的 cid | 查詢發證請求、狀態為 issued 時的回應(GET /v1/diw/issuances/{id}) | 撤銷這張憑證;換發時放進 cids |
驗證請求的 id | 建立驗證請求的回應(POST /v1/diw/verifications) | 查詢驗證結果 |
發證結果另外會回 credential_serial(憑證序號)。它不用帶回 API,只在驗證時用來比對 data[].cid,見驗證 API。
- 請整串保存,不要修改任何字元(包括大小寫)。每個 id 都不超過 128 個字元,資料庫欄位請依此設定長度。
- id 只能用取得它的帳號查詢或撤銷。改用其他帳號的 API Key 會回
404。 - id 格式不對時回
400;格式正確但內容被改過時回404。
把 QR code 或手機連結給持卡人
Section titled “把 QR code 或手機連結給持卡人”建立發證或驗證後,回應裡有兩個值,內容相同,用途不同。手機連結在發證回應裡叫 deep_link,在驗證回應裡叫 auth_uri。
| 欄位 | 用在哪裡 |
|---|---|
qrcode_image | 桌面網頁。值是 base64 PNG 的 data URI,可以直接放進 <img src>,讓收證者或持卡人用手機掃描。 |
deep_link(發證)/auth_uri(驗證) | 手機連結。收證者或持卡人正在用手機時,開啟這個 https 連結,手機會打開錢包 app。 |
<img src="data:image/png;base64,iVBORw0K..." alt="用錢包掃描這個 QR code" />收證者或持卡人掃描後的步驟在錢包與 TCS 之間完成,系統不會主動通知您的後端。請以 GET 輪詢(Polling)結果,查詢頻率見錯誤與輪詢。