# 在 sandbox 中测试而不消耗额度

Source: https://help.didit.me/zh/getting-started/sandbox-and-testing
Updated: 2026-10-12

通过应用名称下的切换器进入 Sandbox，创建并使用测试 API 密钥。所有检查都被模拟，不收费，你可以指定结果。

通过应用名称下的切换器进入 **Sandbox**，创建并使用测试 API 密钥。所有检查都被模拟，不收费，你可以指定结果。

Didit 的 sandbox 相当于支付服务商的测试卡：它让你可以按需复现任意核验结果，而无需调用真实的服务商、处理真实的个人数据，或动用你的余额。

## 独立的测试环境

Sandbox 是组织共享的测试应用，其数据、密钥、webhook 和列表与 Live 分开。每页顶部的横幅会提示当前环境。

![Didit 控制台的 API 密钥页面，每个密钥都归属于一个应用](https://help.didit.me/screenshots/api-keys-light.webp)

*密钥是按应用划分的，因此 sandbox 密钥永远无法访问 live 数据。*

1. **切换到 Sandbox**

   点击应用名称下的 **Sandbox**。返回 **Live** 前，检查工作流发布、Live 密钥或链接、webhook、付款和数据保留清单，然后确认切换或留在 Sandbox。

2. **创建测试密钥**

   打开**开发者 → API 密钥**，创建时选择 Sandbox。密钥决定环境；Live 密钥不会创建 Sandbox 会话。

3. **创建或复制工作流**

   Sandbox 有自己的工作流。创建要测试的流程，或从 Live 复制。

4. **像平常一样创建会话**

   使用同样的接口、同样的代码路径，唯一的区别是你发送的密钥不同。

> **Note:** 如果 **Sandbox** 是灰色的，组织尚无测试应用。请联系支持团队启用，这是账户级设置。

## sandbox 改变了什么，又没有改变什么

| | Sandbox | Live |
|---|---|---|
| 外部服务商 | 全部模拟 - 从不调用任何第三方 | 真实调用 |
| 计费 | 永不计费；跳过余额检查 | 按已完成的功能计费 |
| 会话创建上限 | 每个应用每 24 小时 500 次 | 取决于你的余额 |
| Webhook 负载 | `"environment": "sandbox"` | `"environment": "live"` |
| 提取的数据与状态 | 由你选择的场景模拟生成 | 来自真实采集的数据 |
| 采集的媒体 | **真实存储**，与 live 会话完全一样 | 存储 |

> **Warning:** sandbox 会像 live 会话一样，真实存储它所采集的媒体 - 证件、自拍、活体检测
> 视频、地址证明文件。*结果*是模拟的，但上传是真实的，因此请使用流程提供的
> 示例证件和测试数据，而不要使用真实身份证件或真实个人信息。

由于结果从不取决于图像内容本身，故意上传一张糟糕的照片并不会在 sandbox 中触发拒绝 - 结果由场景决定。

## 选择结果

创建会话时，将场景标识作为 `sandbox_scenario` 传入，或者让测试者自行选择：在托管流程中，sandbox 会话会在开始采集前，于卡片内显示一个**场景选择器**，上传组件下方还会有一排示例证件，以及一条常驻的「仅限测试数据」提示条。

| 想要测试的场景 | 场景标识 |
|---|---|
| 全部通过 | `approve` |
| 证件已过期 | `decline_document_expired` |
| 证件无法识别 | `decline_could_not_recognize_document` |
| MRZ 校验失败 | `decline_mrz_validation` |
| 未达最低年龄 | `decline_minimum_age` |
| 人脸比对分数过低 | `decline_face_match_low_similarity` |
| 活体检测遭遇仿冒攻击 | `decline_liveness_attack` |
| AML 制裁 / PEP 命中 | `decline_aml_hit` |
| IP 地址被屏蔽 | `decline_ip_blocklist` |
| 地址证明地址不匹配 | `decline_poa_address_mismatch` |
| NFC 芯片完整性校验失败 | `decline_nfc_chip_not_verified` |
| 数据库验证未找到匹配 | `decline_database_no_match` |
| 需要人工审核（AML） | `review_aml_possible_match` |
| 需要人工审核（人脸比对处于临界值） | `review_face_match_borderline` |
| 需要人工审核（地址部分匹配） | `review_poa_partial_match` |
| KYB 注册信息不匹配 | `decline_kyb_registry_mismatch` |

`review_*` 系列场景的存在，是为了让你无需构造真正会被拒绝的输入，就能完整走一遍人工审核流程 - 控制台的审核队列、`In Review` webhook，以及审核人员批准或请求重新提交的操作。

> **Tip:** 场景与魔术值的最新目录由 API 本身通过 `GET /v1/sandbox/scenarios/` 提供。
> 如果这里的某个标识看起来已经过时，请以该接口的返回结果为准。
> 完整参考：[sandbox 测试](https://docs.didit.me/integration/sandbox-testing)。

## 在你自己的代码中区分两者

每个 webhook 都带有一个 `environment` 字段 - `"sandbox"` 或 `"live"`。请基于这个字段做分支判断，而不是试图从密钥本身推断环境，这样你就永远不会把测试会话误认为真实客户。

## sandbox 不会做的事

- 不会返回真实公司的真实注册信息。sandbox 中的 KYB 使用模拟的注册信息响应。
- 不会发送真实的短信或邮件。手机验证和邮箱验证都是模拟的，因此你无法用 sandbox 预览真实的消息送达情况。
- 不会消耗你的每月套餐额度 - 这也意味着一次 sandbox 运行无法告诉你还剩多少额度。

## 如果你需要真实的测试核验

有些情况确实需要一次真实调用 - 比如确认某个国家的数据库服务已经为你开通，或者确认短信能否送达某个特定运营商。这需要在 live 应用上进行一次小额充值，而不是使用 sandbox。在花费之前请先联系支持团队，确认相关服务已经在你的账户上正式启用。