跳到主要内容

会话管理

创建认证会话后，只需使用生成的链接启动用户注册流程。这可以通过发送链接或直接在您的网站上使用（借助 iframe 等工具）来实现。

返回对象​

创建和获取 auth_session 的返回对象包含以下信息：

Response Body
  {
    "id": "12345678",
    "status": "pending",
    "expiration_date": "2025-12-11T11:37:15.12-03:00",
    "step_data": {
      "face_recognition": {
        "image_key": "65441d8d-015a-4a0f-97b6-b7d4fc5619b7",
        "event_date": "2025-12-11T11:37:15.12-03:00"
      },
      "personal_document": {
          "document_template": "rg",
          "ocr_keys": [
            "e13c71d0-ae0e-48e2-8c42-26f997412039",
            "3991b716-0980-409f-8e33-e3a8dd9a671c"
          ],
          "event_date": "2025-12-11T11:37:15.12-03:00"
      },
      "device_scan": {
          "session_id":  "4d450227-c77c-4487-830b-42dcd127798a",
          "event_date": "2025-12-11T11:37:15.12-03:00"
      }
    }
    "settings": {
      ...
    },
    "auth_session_hash": "1cFL1vM",
    "step": "device_scan",
    "auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
    "token": "fc0aaa39-1c21-1bc1-a5a1-39a7ca01121b",
    "token_expiration_date": "2025-12-10T11:37:15.12-03:00",
  }

此对象在会话获取端点返回：

GET https://api.caas.qitech.app/auth_session_manager/auth_session/{id}

响应字段描述：

名称类型描述
idstring会话 ID。
statusstring会话状态。
expiration_datedate会话过期日期。超过此日期后，会话将失效。
step_dataobject会话事件的返回对象。
settingsobject会话配置对象。
auth_session_hashstring会话标识哈希值。
stepstring用户当前所处步骤。
auth_session_urlstring能够收集注册信息的 URL。
tokenstring会话认证令牌。
token_expiration_datedate临时认证令牌的过期日期。默认设置为会话生成后 2 小时。

状态​

可能的状态：

  • pending
  • completed
  • expired

step_data 对象​

包含每个步骤收集数据的对象。

信息

如果步骤未列在会话的 settings 中，则该步骤不会作为 step_data 对象的字段出现

face_recognition

名称类型描述
image_keystringface_recognition 步骤的标识密钥。
event_datedate步骤完成日期。

personal_document

名称类型描述
document_templatestring用户在文件收集时选择的模板。
ocr_keyslist每个收集文件的标识密钥列表。
event_datedate步骤完成日期。

device_scan

名称类型描述
session_idstring设备扫描步骤的标识密钥。
event_datedate步骤完成日期。

网页流程认证​

为了给应用程序提供更高的安全性，我们为网页返回临时令牌。 可以通过以下端点获取令牌或生成新令牌：

POST https://api.caas.qitech.app/auth_session_manager/auth_session/{id}/token

Request Body
  {
    "token_expiration_seconds": 3600
  }

令牌对象只有一个可选字段：

名称类型描述
token_expiration_secondsinteger会话令牌的过期时间（秒）。（必须在 1 到 172800 之间，最大 48 小时。默认值为 1800）
Response Body
  {
    "id": "12345678",
    "token": "e7e99a40-0b26-4bb9-a068-9fa4886eeef3",
    "token_expiration_date": "2025-12-10T13:37:15.12-03:00",
  }

因此，如果令牌已过期，可以通过生成新令牌继续认证会话。

Webhook

会话完成将通过发送 Webhook 进行通知。为此，需要通过支持团队配置一个端点地址，我们将通过该地址通知更新，以及一个用于签名请求的 signature_key。请注意，所有 Webhook 发送均将发送到单个端点。

注意

出于安全原因，所有 Webhook 请求将仅发送到通过 HTTPS 提供服务的端点。

与网页通信​

网页可以通过名为 iframe 的工具集成，方式如下：

<iframe id="iframe" src="" href="{auth_session_url}" allow="camera; microphone" referrerPolicy="no-referrer"></iframe>

⚠️ 必要配置

为使 iframe 在生产环境（auth-session.caas.qitech.app）和沙盒环境（auth-session.sandbox.caas.qitech.app）中正常运行，需要配置以下 Permissions-Policy header：

使用特定 URL 的配置（推荐）：

{
  "key": "Permissions-Policy",
  "value": "geolocation=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), microphone=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), camera=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), fullscreen=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\")"
}

替代配置（限制较少）：

{
  "key": "Permissions-Policy",
  "value": "geolocation=*, microphone=*, camera=*, fullscreen=()"
}

此配置必须应用于托管包含 iframe 的页面的服务器，以确保授予所需权限。

如果以这种方式调用链接，网页将向请求它的页面发送回调消息。可能的回调消息为：

  • success
  • canceled
  • invalid_token
  • expired

可以通过以下方式访问：

window.addEventListener("message", (event) => {
            if (event.data === "canceled") {
              //close iframe
            }
            if (event.data === "invalid_token") {
              //close iframe
            }
            if (event.data === "success") {
              //close iframe
            }  
            if (event.data === "expired") {
              //close iframe
            }
        });

流程完成​

此服务将管理认证数据收集流程，收集的数据可在其他服务中使用。 有关如何在其他产品中使用返回密钥的更多信息，请参阅自然人注册分析示例 注册分析