API 參考
身份驗證 API 參考。
你可以呼叫嘅每個端點、你會見到返嚟嘅每個欄位，以及 webhook 送達後該點處理。如需準確嘅欄位類型，請以你自己 API 來源 /docs 上嘅實時 OpenAPI 文件為準——本頁係白話版本。
基礎 URL 同環境
一個基礎 URL，兩個環境。
所有請求都送到同一個主機。你處於邊個環境，完全取決於你傳送嘅 API 金鑰。
| 基礎 URL（本文件） | https://api.shieldid.ca — illustrative; your production API origin is published together with your API keys. |
|---|---|
| 驗證標頭 | X-Api-Key: <your key>，除咗下面註明嘅兩個公開端點外，每個請求都要帶上。 |
| Sandbox 金鑰前綴 | vk_sand_… — 用呢個金鑰建立嘅 session 會標記為 environment: "sandbox"，而且永不收費。 |
| 正式環境金鑰前綴 | vk_live_… — 相同嘅請求，按你嘅方案收費。 |
| 內容類型 | 每個請求內容同回應都使用 application/json。 |
端點
完整嘅 v1 介面。
六個 JSON 端點，另加一個託管頁面同一個公開嘅憑證查核，兩者都唔係 JSON，只需要連結過去。
| Endpoint | Auth | What it does |
|---|---|---|
| POST /v1/sessions | X-Api-Key | 建立驗證 session。需要 return_url 同 webhook_url。會返回 session_id、verification_url 同 status: "PENDING"。 |
| GET /v1/sessions/{id} | X-Api-Key | 單一 session 嘅狀態同頂層欄位：status、confidence、environment。 |
| GET /v1/sessions/{id}/result | X-Api-Key | session 達到 VERIFIED 或 FAILED 後嘅完整結果：person、逐項查核結果、confidence、verified_until。 |
| DELETE /v1/sessions/{id} | X-Api-Key | 取消仍處於 PENDING 或 IN_PROGRESS 狀態嘅會話。已處於 VERIFIED、FAILED 或 EXPIRED 嘅會話無法取消。 |
| GET /v1/credentials/{token} | None — public | 查核已驗證嘅憑證目前是否有效。無需 API 金鑰，所以可以喺瀏覽器入面呼叫。注意：目前嘅回應除咗有效／無效標記之外，亦會包含已驗證人士嘅姓名同證件類型／國家，請勿將此連結交俾你唔想佢睇到呢啲資料嘅第三方。 |
| GET /v1/pricing/{country} | X-Api-Key | 按兩個字母嘅 ISO 3166-1 國家代碼查詢各國定價。 |
| /v/{session_id} | 託管驗證頁面 — 即係 session 返回嘅 verification_url。桌面版會顯示 QR code；掃描後，申請人嘅手機會開啟同一條連結，用嚟拍攝證件同自拍。 |
|---|---|
| /c/{session_id} | 針對單一已驗證 session 嘅公開、免驗證憑證查核頁面。注意：目前嘅回應除咗有效／無效標記之外，亦會包含已驗證人士嘅姓名同證件類型／國家，請勿將此連結交俾你唔想佢睇到呢啲資料嘅第三方。 |
| /docs | 針對你帳戶 API 來源嘅即時互動式 OpenAPI 參考文件。 |
建立 session
POST /v1/sessions,完整流程。
請求內容,以及確切嘅回應。
bash
curl -X POST https://api.shieldid.ca/v1/sessions \
-H "X-Api-Key: vk_sand_your_key" \
-H "Content-Type: application/json" \
-d '{
"return_url": "https://yourapp.example/verified",
"webhook_url": "https://yourapp.example/hooks/shieldid",
"expected_name": "Jordan Smith",
"locale": "en",
"metadata": { "application_id": "app_9182" }
}'| return_url | string，必填 — 申請人完成後被導返去嘅位置。必須係 http 或 https。 |
|---|---|
| webhook_url | string，必填 — 已簽署結果嘅送達位置。請參閱下面嘅 Webhooks。 |
| expected_name | string，必填 — 你預期證件上出現嘅姓名，用嚟交叉核對身份證件實際顯示嘅內容。 |
| expected_dob / expected_address | string，選填 — 如有提供，會同證件交叉核對；進行驗證時並非必填。 |
| locale | string，選填 — "en" 或 "fr"。設定申請人所見託管頁面嘅語言。 |
| metadata | object，選填 — 你自己嘅參考資料 — 例如申請編號、租戶編號，任何你想喺結果同 webhook 入面原樣返回嘅內容。 |
結果
GET /v1/sessions/{id}/result — 回應結構。
Webhook payload 會送出相同嘅結構，所以你好少需要輪詢呢個端點。
| session_id | 你建立嘅 id。 |
|---|---|
| status | PENDING、IN_PROGRESS、VERIFIED、FAILED 或 EXPIRED。 |
| environment | "sandbox" 或 "production"，同建立 session 嘅金鑰相符。 |
| person | 從文件讀取嘅欄位：姓名、出生日期、文件類型、文件國家同司法管轄區、地址。 |
| checks | 每項檢查各有一個結論——見下文。絕不會只有一個不透明嘅分數。 |
| confidence | 驗證嘅單一整體數值。個別檢查（包括人臉配對）仍會根據固定決策線獨立報告——呢個欄位唔會取代佢哋。 |
| verified_until | 喺 VERIFIED 工作階段上，結果被視為有效嘅時長。 |
| failure_reason | 喺 FAILED 工作階段上設定——例如 FACE_MATCH_BELOW_THRESHOLD 或 CANCELLED_BY_API。否則為 null。 |
| metadata | 你建立工作階段時傳送嘅內容，原封不動。 |
json
{
"session_id": "ses_9f2c1a",
"status": "VERIFIED",
"environment": "sandbox",
"person": {
"name": "Jordan Smith",
"dob": "1994-03-11",
"document_type": "drivers_licence",
"document_country": "CA",
"document_jurisdiction": "ON"
},
"checks": {
"document": "PASS",
"liveness": "PASS",
"antispoof": "PASS",
"face_match": "PASS"
},
"confidence": 88,
"verified_until": "2027-03-11T00:00:00Z",
"failure_reason": null,
"metadata": { "application_id": "app_9182" }
}Add-onchecks.document、checks.liveness、checks.antispoof 同 checks.face_match 各自會得出 PASS、FAIL 或 SKIPPED。監控名單篩查（checks.sanctions —— CLEAR、MATCH 或 SKIPPED）係附加功能，只會喺啟用咗該功能嘅帳戶出現。
工作階段生命週期
五個狀態，一條路徑。
工作階段會自行向前推進；你唔使驅動狀態機，只需讀取就得。
| PENDING | 已建立。仍未有人開啟 verification_url。 |
|---|---|
| IN_PROGRESS | 申請人已開啟連結，正處於擷取流程中。 |
| VERIFIED | 所有檢查已執行，結果已備妥。終止狀態——請呼叫結果端點或讀取 webhook。 |
| FAILED | 至少有一項檢查未通過。failure_reason 會說明原因。即將推出：可將工作階段重設為 PENDING 嘅重試功能——在此之前，請將 FAILED 視為終止狀態，如果申請人想再試，請建立新工作階段。 |
| EXPIRED | 冇人及時完成。工作階段會喺預設時限（30 分鐘）後自動過期；請建立新工作階段再試。 |
DELETE /v1/sessions/{id} 可提早取消處於 PENDING 或 IN_PROGRESS 狀態嘅會話。已達 VERIFIED、FAILED 或 EXPIRED 嘅會話無法取消——因為已經完成。
錯誤
需要預先規劃嘅事項。
以下係現時值得針對性編寫程式碼嘅精選清單。完整、最新嘅錯誤碼同 payload 記載於 /docs 嘅實時 OpenAPI。
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | 缺少 X-Api-Key 標頭。 |
| 401 | INVALID_KEY_FORMAT | 金鑰並非以 vk_sand_ 或 vk_live_ 開頭，或者同帳戶上任何金鑰都唔吻合。 |
| 403 | FORBIDDEN | 金鑰有效，但無權存取你所要求嘅工作階段或資源。 |
| 404 | NOT_FOUND | 冇任何工作階段、憑證或資源擁有該 id。 |
| 409 | CONFLICT | 會話所處嘅狀態不容許執行該操作,例如取消一個已經 VERIFIED 嘅會話。 |
| 422 | VALIDATION_ERROR | 缺少必要欄位或欄位格式錯誤——例如 return_url 並非有效嘅 http 或 https URL。 |
Webhooks
簽署、送達、重試。
當工作階段達到 VERIFIED 或 FAILED，ShieldID 會將上述結構 POST 到你嘅 webhook_url。
- 以 POST 送達，JSON 主體符合上述結果結構。
- 以 HMAC-SHA256 對原始請求主體簽署，並透過 X-Bio-Signature 標頭傳送。信任 payload 之前，請先用你嘅 webhook 密鑰驗證。
- 如果你嘅端點冇回覆 2xx 狀態，最多會以線性退避方式重試三次。
- 即將推出：FAILED 工作階段重試，解決後會送出第二個 webhook。現時請以每個工作階段一個 webhook 為準。
- 呢度嘅欄位名稱同本參考一致。如果實際收到嘅內容唔同，請以實時 payload 為準並通知我哋——欄位清單係跟隨 API 保持同步，而唔係相反。
驗證簽署
javascript
import crypto from "node:crypto";
function isValidShieldIdSignature(rawBody, signatureHeader, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const provided = signatureHeader || "";
const a = Buffer.from(expected, "hex");
const b = Buffer.from(provided, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// rawBody must be the exact, unparsed request body
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
const ok = isValidShieldIdSignature(req.body, req.headers["x-bio-signature"], process.env.SHIELDID_WEBHOOK_SECRET);
if (!ok) return res.status(401).send("invalid signature");
const result = JSON.parse(req.body);
// result.session_id, result.status, result.checks, …
res.status(200).send("ok");
});冪等性同重試
寫出可以安全執行兩次嘅處理程式。
暫時未有專用嘅冪等性金鑰，無論係建立工作階段定係 webhook 送達都未有。
- 重試嘅 webhook 送達可能會就同一個工作階段多次到達。請以 session_id + status 作為處理程式嘅鍵，並令寫入結果嘅操作具備冪等性。
- 唔好喺逾時後盲目重試 POST /v1/sessions——先檢查工作階段是否已建立，否則同一位申請人可能最終有兩個工作階段。
- 已計劃為建立工作階段提供專用嘅 Idempotency-Key 標頭。
即將推出建立工作階段時支援 Idempotency-Key
問題