跳到主要内容

单一方法流

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

提示

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

特定于方法的端点​

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

端点验证方法
/age-verification/perform-facial-age-estimation面部年龄估计扫描
/age-verification/perform-id-verificationID 扫描验证
/age-verification/perform-age-key-verificationAgeKey
/age-verification/perform-connect-id-verificationConnectID（澳大利亚）
/age-verification/perform-inference电子邮件地址年龄估计

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

创建自定义验证 UI​

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

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

请求格式​

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

属性说明必需?
jurisdiction应进行年龄验证的司法管辖区是
criteria年龄验证的标准是
subject.email如果用户在任何其他上下文中使用电子邮件地址通过 k-ID 验证了其年龄，则返回原始年龄而不是要求用户再次验证否
subject.claimedAge如果用户在年龄门控中被询问其年龄，用于通知年龄估计过程否
subject.id用于跨多个验证方法报告多次失败尝试的标识符否

请求示例​

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

响应格式​

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

属性说明
id唯一验证 ID
url必须在 iframe 中呈现给用户的年龄验证 URL

响应示例​

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJhbGciOiJFUzM4NCIs..."
}

嵌入验证小部件​

一旦您收到验证 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-inference仅提供电子邮件年龄估计
/age-verification/perform-age-appeal用于之前失败的验证（仅 ID 验证和可信成人证明）
/age-verification/get-status查询验证的状态

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