单一方法流

当您需要通过 API 调用动态选择验证方法而不是使用产品的静态配置时，可以使用特定于方法的端点来创建用于选择验证方法的自定义 UI。此方法使您完全控制呈现哪些验证方法以及用户如何选择它们。

Tip

对于推荐的方法，其中验证方法由您的产品配置确定，请参阅瀑布流。

在用户开始流程时再创建验证

请等用户选择开始验证（例如，在访问功能前点击用于开始验证的控件）。然后再调用 API 创建验证并获取 URL，可使用年龄验证 API 端点等端点。不要为用户可能不会进入的路径提前创建验证或获取 URL。更多说明请参阅最佳实践。

特定于方法的端点

特定于方法的端点绕过自动方法选择，直接进入所选方法的验证过程。k-ID 提供几个特定于方法的端点：

端点	验证方法
`/age-verification/perform-facial-age-estimation`	面部年龄估计扫描
`/age-verification/perform-id-verification`	ID 扫描验证
`/age-verification/perform-age-key-verification`	AgeKey
`/age-verification/perform-connect-id-verification`	ConnectID（澳大利亚）
`/age-verification/perform-credit-card-verification`	信用卡验证

有关验证方法的详细信息，包括哪些方法可用以及它们如何工作，请参阅验证方法指南。有关所有可用年龄验证端点的完整列表，请参阅 API 参考中的年龄验证端点。

创建自定义验证 UI

使用特定于方法的端点，您可以构建自定义 UI，该 UI：

向用户显示可用验证方法
让用户选择他们首选的方法
根据他们的选择调用适当的端点
如果所选方法失败，回退到其他方法

请求格式

所有年龄验证端点使用相同的请求格式：

属性	说明	必需?
`jurisdiction`	应进行年龄验证的司法管辖区	是
`criteria`	年龄验证的标准	是
`subject.email`	如果用户在任何其他上下文中使用电子邮件地址通过 k-ID 验证了其年龄，则返回原始年龄而不是要求用户再次验证	否
`subject.claimedAge`	如果用户在年龄门控中被询问其年龄，用于通知年龄估计过程	否
`subject.id`	用于跨多个验证方法报告多次失败尝试的标识符	否
`options.locale`	验证 UI 的可选 IETF BCP 47 语言标签。省略时遵循访客浏览器的语言偏好；当应用已提供用户选择的语言且希望验证与之保持一致时设置。	否
`options.redirectUrl`	验证完成后重定向到的 URL。支持 HTTP/HTTPS URL 或使用自定义协议方案的移动深度链接。仅当验证 URL 在浏览器或 Web 视图中直接打开时（未嵌入 iframe）才会发生重定向。发生重定向时，URL 包含 `verificationId` 和 `result`（PASS 或 FAIL）作为查询字符串参数。	否

请求示例

POST /api/v1/age-verification/perform-facial-age-estimation
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "criteria": {
    "ageCategory": "ADULT"
  },
  "subject": {
    "claimedAge": 23
  },
  "options": {
    "locale": "en-US",
    "redirectUrl": "https://example.com/verification-complete"
  }
}

响应格式

所有年龄验证端点返回相同的响应格式：

属性	说明
`id`	唯一验证 ID
`url`	必须在 iframe 中呈现给用户的年龄验证 URL
`shortUrl`	适用于二维码的短 URL，会重定向到完整的验证 URL

响应示例

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJhbGciOiJFUzM4NCIs...",
  "shortUrl": "https://family.k-id.com/v/7854909b-9124-4bed-9282-24b44c4a3c97?pid=42&s=qr"
}

嵌入验证小部件

一旦您收到验证 URL，请将其嵌入 iframe，就像使用标准方法一样：

<iframe 
  src="VERIFICATION_URL" 
  width="100%" 
  height="600"
  frameborder="0"
  allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
</iframe>

接收验证结果

实现应结合使用客户端和服务器端方法：客户端事件最适合控制 UI 元素，而对于数据完整性，实际结果应来自 webhook 或调用 /age-verification/get-status。

客户端（DOM 事件）

使用 DOM 事件在验证完成时进行响应式 UI 更新。有关事件结构的详细信息，请参阅 Verification.Result。

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  if (message.eventType === 'Verification.Result') {
    if (message.data.status === 'PASS') {
      // 用户通过验证 - 立即更新 UI
      console.log('Age verified:', message.data.ageCategory);
      updateUI();
    } else if (message.data.status === 'FAIL') {
      // 用户验证失败 - 立即更新 UI
      console.log('Verification failed:', message.data.failureReason);
      updateUI();
    }
  }
});

服务器端（webhooks、API 调用）

使用 webhooks 或 API 调用进行数据完整性和可靠的状态管理。对于数据完整性，始终通过 webhook 事件或调用 /age-verification/get-status 来验证结果，而不是仅依赖 DOM 事件。

Webhooks

有关 webhook 事件结构的详细信息，请参阅 Verification.Result。

配置 webhook 端点以接收 Verification.Result 事件。更多信息，请参阅 Webhooks。

API 调用

您可以使用验证 ID 通过 /age-verification/get-status 查询验证状态。如果您的 webhook 在发送结果时无法访问，这很有用。

年龄上诉

如果验证失败，您可以通过调用 /age-verification/perform-age-appeal 端点允许用户提出上诉。这为用户提供 ID 验证和可信成人证明选项（年龄估计不适用于上诉）。

可用端点

以下是常见的特定于方法的年龄验证端点：

端点	说明
`/age-verification/perform-facial-age-estimation`	仅提供面部年龄估计
`/age-verification/perform-id-verification`	仅提供 ID 文档验证
`/age-verification/perform-age-key-verification`	仅提供 AgeKey 验证
`/age-verification/perform-connect-id-verification`	仅提供 ConnectID 验证
`/age-verification/perform-credit-card-verification`	仅提供信用卡验证
`/age-verification/perform-age-appeal`	用于之前失败的验证（仅 ID 验证和可信成人证明）
`/age-verification/get-status`	查询验证的状态

有关所有可用年龄验证端点的完整和最新列表，请参阅 API 参考中的年龄验证端点。

单一方法流

On this page