跳到主要内容
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,您会看到托管页面。在桌面浏览器上，页面会显示二维码——扫描后会将完全相同的链接传到手机上，而实际的证件拍照、活体检测挑战和自拍都在手机上完成。现在就用您自己的手机试一试。

  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 参考