跳至主要內容
ShieldID

快速入門

身份驗證快速入門。

由 sandbox 金鑰到第一個已簽署 webhook，依次進行。每一步都有可運作嘅範例 — 複製後換上你自己嘅金鑰同 URL，就可以執行。

申請 sandbox 金鑰完整 API 參考文件

逐步說明

七個步驟,一個下午。

  1. 取得 sandbox 金鑰

    Sandbox 金鑰（前綴 vk_sand_）而家按要求發出，自助註冊功能仍在開發中。請透過聯絡表格申請 — 大部分申請都會喺同一個工作日內處理。Sandbox session 永不收費，所以無需等待，可以即刻開始。

  2. 建立你嘅第一個 session

    只需一次呼叫。傳入 return_url（申請人完成後會去到嘅頁面）同 webhook_url（簽署咗嘅結果會送去嘅地方）。你會取回 session_id 同 verification_url。

    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" }
  }'

  3. 將連結交畀申請人

    開啟 verification_url 就會見到託管頁面。喺桌面瀏覽器會顯示 QR code——掃描後會將同一條連結傳送到手機，實際嘅證件拍攝、活體檢測挑戰同自拍都係喺手機上進行。即刻用你自己部手機試下。

  4. 架設 webhook 端點

    將 webhook_url 指向一個接受 POST、讀取原始請求內容（你需要未經解析嘅內容先可以驗證簽署），並且回傳 2xx 狀態碼嘅路由。如果唔係，ShieldID 最多會重試傳送三次。

    javascript
    import express from "express";
const app = express();

app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  // Verify the signature before you trust this body — see the next step.
  console.log("Received a webhook:", req.body.toString());
  res.status(200).send("ok");
});

app.listen(3000);

  5. 驗證簽署

    喺確認 webhook 內容確實來自 ShieldID 之前，唔好根據佢採取任何行動。用你嘅 webhook 密鑰對原始內容計算 HMAC-SHA256，再同 X-Bio-Signature 標頭比對。

    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");
});

  6. 讀取結果

    webhook payload 已經包含你需要嘅一切。如果你想自己攞結果——例如喺重新導向之後——可以直接呼叫結果端點。

    bash
    curl https://api.shieldid.ca/v1/sessions/ses_9f2c1a/result \
  -H "X-Api-Key: vk_sand_your_key"

# → { "session_id": "ses_9f2c1a", "status": "VERIFIED", "checks": { "document": "PASS", … }, … }

  7. 處理 FAILED 同重試

    去到 FAILED 嘅 session 會帶有 failure_reason。向申請人顯示有用嘅資訊。即將推出：重試 FAILED session，將佢重設為 PENDING。目前請將 FAILED 視為最終狀態，如果申請人想再試，就建立新 session。

正式啟用前

轉用正式環境。

請求格式喺 sandbox 同正式環境之間完全一樣——只有金鑰唔同。喺你讓真實申請人使用 vk_live_ session 之前，請先確認以下事項。

  • 將 vk_sand_ 換成 vk_live_ 金鑰。請求嘅其他部分完全唔使改。
  • 將 webhook_url 指向一個真正、長期運行並會驗證簽署嘅端點——而唔係 request-bin 或者手提電腦。
  • 喺你嘅應用程式處理全部三個最終狀態：VERIFIED、FAILED 同 EXPIRED，唔好只顧理想情況。
  • 確認你嘅 return_url 會讀取 ShieldID 喺重新導向時附加嘅 session_id 同 status 查詢參數。
  • 用 GET /v1/pricing/{country} 或者價格頁面查閱最新定價，免得正式環境嘅收費令你意外。
  • 唔好將 sandbox 金鑰放喺真實申請人可以接觸到嘅任何地方——sandbox session 免費，係因為佢並唔真實。

問題

快速入門常見問題。

立即開始

即刻行第一步。

申請一個 sandbox 金鑰，將第一條 cURL 指令貼入終端機，你已經領先大部分整合方案。

申請 sandbox 金鑰完整 API 參考文件