跳至主要內容
ShieldID

快速入門

身分驗證快速入門。

依序從 sandbox 金鑰到第一個已簽署的 webhook。每個步驟都有可運作的範例，複製後換成您自己的金鑰與 URL 即可執行。

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

逐步說明

七個步驟，一個下午即可完成。

  1. 取得 sandbox 金鑰

    在自助註冊功能開發完成之前，Sandbox 金鑰（前綴 vk_sand_）須經申請核發。請透過聯絡表單提出，多數申請會在同一個工作日內處理完畢。Sandbox 工作階段不會計費，因此無需等待，可以立即開始。

  2. 建立您的第一個工作階段

    只需一次呼叫。傳入 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 酬載已包含您所需的一切資訊。如果您想自行取得結果（例如在重新導向之後），可以直接呼叫結果端點。

    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 的工作階段會附帶 failure_reason。請向申請人顯示有用的資訊。即將推出：重試 FAILED 的工作階段，將其重設為 PENDING。目前請將 FAILED 視為最終狀態，若申請人想再試一次，請建立新的工作階段。

在正式啟用之前

上線至正式環境。

sandbox 與正式環境之間的請求格式完全相同，只有金鑰不同。在讓真實申請人進入 vk_live_ 工作階段之前，請先確認以下事項。

  • 將 vk_sand_ 金鑰換成 vk_live_ 金鑰。請求的其他部分都不需更動。
  • 將 webhook_url 指向一個真實、持續運作且會驗證簽章的端點，而不是 request bin 或您的筆電。
  • 在您的應用程式中處理全部三種最終狀態：VERIFIED、FAILED 與 EXPIRED，而不是只處理順利的情況。
  • 確認您的 return_url 會讀取 ShieldID 在重新導向時附加的 session_id 與 status 查詢參數。
  • 請透過 GET /v1/pricing/{country} 或價格頁面確認目前的定價，以免正式環境的費用讓您措手不及。
  • 請勿讓 sandbox 金鑰出現在真實申請人可能接觸到的任何地方，sandbox 工作階段之所以免費，是因為它不是真實的。

常見問題

快速入門常見問題。

開始使用

現在就執行第一步。

申請 sandbox 金鑰，將第一個 cURL 指令貼到終端機執行，您就已經領先大多數的整合了。

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