> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart-ID 与 Mobile-ID 集成指南

> 通过 Didit 配置 Smart-ID 和 Mobile-ID 身份验证，涵盖支持的国家/地区、对比码认证、已验证属性及降级回退机制。

Smart-ID 和 Mobile-ID 允许用户通过在手机上批准请求来验证其身份。
使用 [Smart-ID API](https://docs.didit.me/zh/api-reference/digital-id-wallets/smart-id.md) 或 [Mobile-ID API](https://docs.didit.me/zh/api-reference/digital-id-wallets/mobile-id.md) 即可直接从您自己的应用发起验证，无需通过工作流。
这两种方式也可以在 Didit 的**身份证件验证**工作流步骤中运行，并返回具有 `cryptographic` 保证级别的钱包验证结果。
对于下文介绍的托管工作流集成，请使用与其他 Didit 工作流相同的会话创建和 Webhook 集成方式。

> [!NOTE]
>
> **Smart-ID 和 Mobile-ID 现已可用。**
> Smart-ID 支持爱沙尼亚、拉脱维亚、立陶宛和比利时。
> Mobile-ID 支持爱沙尼亚和立陶宛。
> 在控制台中为您工作流接受的每个国家选择相应的钱包。
> 有关完整列表，请参阅[钱包覆盖范围和定价](https://docs.didit.me/zh/core-technology/id-verification/digital-id-wallets.md#定价)。

## 国家与前置条件

该集成涵盖爱沙尼亚（`EST`）、拉脱维亚（`LVA`）、立陶宛（`LTU`）和比利时（`BEL`）的 Smart-ID。
Mobile-ID 涵盖爱沙尼亚（`EST`）和立陶宛（`LTU`）；拉脱维亚不提供 Mobile-ID。
这些国家代码仅描述已集成的路由，并不保证您环境中的每个路由均已激活。

使用 Smart-ID 时，用户需要拥有一个处于激活状态且符合条件的 Smart-ID 身份、其个人识别码以及该应用的访问权限。
使用 Mobile-ID 时，用户需要拥有一个处于激活状态的 Mobile-ID 身份、其个人识别码以及关联的电话号码。
请以国际格式输入 Mobile-ID 电话号码：爱沙尼亚为 `+372`，立陶宛为 `+370`。
所选国家必须与所使用的身份相匹配。

这两种方法均不返回头像照片。
如果您的工作流需要自拍照，请单独配置相应的[活体检测](https://docs.didit.me/zh/core-technology/liveness/overview.md)和[人脸比对](https://docs.didit.me/zh/core-technology/face-match/overview.md)步骤。

## 用户看到的内容

1. 用户选择自己的国家，并从您工作流接受的钱包中选择 **Smart-ID** 或 **Mobile-ID**。
2. 验证会话要求输入个人识别码；Mobile-ID 还会要求输入关联的电话号码。
3. 在身份验证请求发送到手机的过程中，页面会显示一个比对码。
4. 用户检查手机上的比对码是否与验证页面上的比对码一致，然后在手机上输入 PIN 码予以批准。
5. Didit 验证已签名的身份结果并继续执行验证工作流。

身份表单和比对码屏幕采用与其他验证方式相同的布局。
启用白标自定义后，它们会继承该会话的配色、字体和排版、按钮样式和客户徽标，并继续使用该会话的域名。
刷新页面会恢复当前有效的比对码，而不会发起新的批准请求。

用户绝不会在验证页面上输入其钱包 PIN 码。
如果验证码不一致或用户并未发起该请求，则应将其取消。
比对码流程适用于桌面或手机浏览器，不需要二维码。
页面会自动等待结果并提供取消选项。
手机端的批准仍必须通过身份和签名检查，Didit 才会将钱包验证视为成功。

## 配置工作流

在控制台中，打开您工作流的**身份证件验证**节点，选择**国家**，然后打开您想要配置的国家。
在**接受的钱包**下方，选择可用的钱包并选择失败行为。
在创建新会话之前，请保存并发布该工作流。
有关完整的控制台路径，请参阅[控制台中的身份证件验证方式](https://docs.didit.me/zh/console/id-verification-methods.md#启用-smart-id-或-mobile-id)。

> [!WARNING]
>
> 以下内容为 `methods` 配置片段，并非完整的工作流请求。
> 仅当您环境中爱沙尼亚的 `smart_id` 和 `mobile_id` **均**标记为 `available` 时方可使用。
> 不可用的钱包会导致整个工作流保存失败。

```json theme={null}
{
  "EST": {
    "document": { "enabled": true },
    "wallet": {
      "enabled": true,
      "providers": ["smart_id", "mobile_id"],
      "on_failure": "fallback_to_document"
    }
  }
}
```

`providers` 数组为一个允许列表：用户可在其中的钱包之间进行选择，数组顺序并不设定首选钱包。
对于立陶宛，当两者均可用时，使用 `LTU`，并采用相同的钱包标识符。
对于拉脱维亚或比利时，仅使用带有 `smart_id` 的 `LVA` 或 `BEL`，且须经过同样的可用性检查。
省略的国家将保留其现有的默认证件采集行为。
完整的配置规范请参阅[工作流功能配置](https://docs.didit.me/zh/management-api/workflows/feature-configs.md#ocr-/-身份证件验证)。

## 读取验证结果

通过[会话决策 API](https://docs.didit.me/zh/sessions-api/retrieve-session.md) 或您的 [Webhook 集成](https://docs.didit.me/zh/integration/webhooks.md)读取已完成的会话。
成功的钱包核验会记录 `verification_method: "wallet"`、`assurance: "cryptographic"` 以及 `wallet_provider: "smart_id"` 或 `"mobile_id"`。
`wallet_verification` 对象标明了钱包、签发国家/地区、验证时间、保证等级和签名结论。
身份证件验证结果会提供标准化的 `full_name` 和 `date_of_birth` 字段。
对于这两个钱包，`wallet_verification.attributes` 会携带来自已验证身份的 `given_name`、`family_name`、`birthdate` 和 `personal_code`。
签发国家/地区仅标明身份路由，并不确认该个人的国籍。
Didit 返回的是签名结论，而非底层的已签名断言。
不会返回头像照片或钱包 PIN 码。

在控制台中，会话的**凭据**卡片会显示该钱包及其已验证的证据。
成功的钱包核验将完成身份证件验证步骤；您工作流中后续的核验仍将决定该会话的最终决策。
有关字段类型以及单项核验结果与整个会话决策之间的区别，请参阅[身份证件验证数据模型](https://docs.didit.me/zh/reference/data-models.md#身份证件验证)。

## 处理取消和失败

如果用户取消、超时或无法完成认证，Didit 会应用该国家/地区的 `wallet.on_failure` 设置。
当该国家/地区启用了 `fallback_to_document` 时，它会启动证件采集。
`decline` 会将身份证件验证步骤标记为已拒绝。
如果证件采集已被禁用，则没有可用的证件回退方案。

只有已完成且核验通过的钱包核验才会产生钱包验证费用。
已取消、已过期和失败的钱包尝试均不计费。
完成的证件回退属于单独的核验，按[证件验证定价](https://docs.didit.me/zh/getting-started/pricing.md)计费。
有关已公布的费率，请查阅[钱包费率表](https://docs.didit.me/zh/core-technology/id-verification/digital-id-wallets.md#定价)；未公布费率的方式不应视为免费。

## 生产前测试

在启用相应钱包和国家/地区的环境中，测试您计划提供的每个钱包和国家/地区。
确认显示了正确的钱包、比对码清晰可见、通过核准后工作流能够继续进行，并且会话结果包含预期的钱包证明材料。
此外还要检查取消、过期以及您所选择的回退行为。

沙盒模拟和预发布环境测试与生产环境认证有所不同。
模拟核准有助于检查您的集成，但并不能证明真实身份可以在生产环境中完成认证。
在全面上线前，请在控制台中确认生产环境可用性，并为您打算使用的路由完成一次经授权的真机验证。

## 其他数字身份钱包

Didit 的[数字身份钱包目录](https://docs.didit.me/zh/core-technology/id-verification/digital-id-wallets.md)包含生产环境可用性以及即将推出的钱包，包括当前可用的 Finnish Trust Network 以及即将推出的 BankID 和 EUDI Wallet 集成。
列表中列出的钱包、已公布的价格或填妥的入驻表单本身并不代表已启用生产环境认证。
请通过该目录以及您所在环境的控制台，确认您当前可以启用的功能。

另请参阅[适用于芬兰的 Finnish Trust Network](https://docs.didit.me/zh/core-technology/id-verification/finnish-trust-network.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.