> ## 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.

# 数据库核验警告与跳过代码

> Didit 数据库核验警告参考指南：涵盖 COULD_NOT_PERFORM_DATABASE_VALIDATION、部分或无匹配、登记机构无法访问及字段缺失等警告代码。

Didit 的[数据库核验](https://docs.didit.me/zh/core-technology/database-validation/overview.md)功能依据权威民政登记机构（阿根廷 RENAPER、巴西 Receita Federal、巴拿马 Tribunal Electoral（生物识别）、多米尼加共和国 Junta Central Electoral 等）核验身份数据，按成功的查询计费，无最低月度消费要求。

当没有服务可以运行（缺少必填字段或格式有误、登记机构不可用）、证件本身无法核查（未包含所配置服务所需的标识符，例如没有国民身份证号的护照），或者聚合结果无法确定（部分匹配、无匹配）时，该功能会在会话上发出一条**警告**。如果签发国家/地区在工作流中根本未启用，则该步骤会被静默跳过，不产生警告且不收费。本页面记录了每个警告代码、其触发条件以及如何配置工作流响应。

## 概述

工作流会话以及独立 API（`POST /v3/database-validation/`）均会生成警告。所有五种风险均带有功能标识 `DATABASE_VALIDATION`，显示在报告中的 `database_validations[].warnings[]` 下，并遵循标准[警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象)结构（`feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`）。

数据库核验没有硬性的自动拒绝触发器。两种匹配结果风险、证件已被取代风险以及不适用风险均映射到一个**可配置操作**（`DECLINE`、`REVIEW` 或 `NO_ACTION`）；`COULD_NOT_PERFORM_DATABASE_VALIDATION` 是唯一的固定行为：它始终将该功能路由至**审核中**。

## 可配置风险

| 设置 | 风险代码 | 行为 |
| - | - | - |
| 无匹配操作 | `DATABASE_VALIDATION_NO_MATCH` | `REVIEW`（工作流默认值）将该功能设置为**审核中**；`DECLINE` 执行拒绝；`NO_ACTION` 记录警告而不影响状态。独立 API 的 `no_match_action` 参数默认值为 `DECLINE`。 |
| 部分匹配操作 | `DATABASE_VALIDATION_PARTIAL_MATCH` | `NO_ACTION`（默认值）记录警告而不影响状态；`REVIEW` 将该功能设置为**审核中**；`DECLINE` 执行拒绝。 |
| 无匹配操作 | `DATABASE_VALIDATION_DOCUMENT_SUPERSEDED` | 共用**无匹配操作**设置：没有单独的控制项。登记机构的数据与提交的数据相抵触，因此在无匹配时选择拒绝的组织，对已被替代的凭证也会选择拒绝。 |
| 不适用操作 | `DATABASE_VALIDATION_NOT_APPLICABLE` | `NO_ACTION`（默认值）记录警告而不影响状态；`REVIEW` 将该功能设置为**审核中**；`DECLINE` 执行拒绝。当证件完全无法核查时触发：证件未包含所配置服务查询所需的标识符（例如没有国民身份证号的护照）。 |

配置的操作还会决定警告的 `log_type`：`DECLINE` → `error`，`REVIEW` → `warning`，`NO_ACTION` → `information`。

匹配结果本身由各服务的 `validation` 条目聚合而成（任何完全匹配 → `full_match`；否则任何部分匹配 → `partial_match`；否则 `no_match`）。有关推导 1×1 / 2×2 结果的完整决策逻辑，请参阅[匹配方法](https://docs.didit.me/zh/core-technology/database-validation/database-validation-matching-methods.md)。

## 生成的警告

| 标签 | 简短描述 | 描述 |
| - | - | - |
| `COULD_NOT_PERFORM_DATABASE_VALIDATION` | 无法执行数据库核验 | 没有服务返回可用结果（`match_type` 保持为 `null`），通常是因为缺少必填字段或字段格式错误，或者登记系统返回了错误。`additional_data` 包含每个服务的跳过摘要（`reason`、`database_validation_errors`、`missing_required_fields_by_service`、`invalid_format_fields_by_service`、`field_reasons_by_service`）；独立 API 则使用 `{ "validation_errors": [...] }`。触发此警告时**不向您收费**；在数据更正之前，该功能将进入**审核中**状态。 |
| `DATABASE_VALIDATION_NOT_APPLICABLE` | 数据库核验不适用于此证件 | 提供的证件未包含所配置的数据库服务所需的标识符（`match_type` 保持为 `null`），例如，巴西护照不包含 CPF，因此无法查询 CPF 登记系统。对于该证件类型，这属于预期情况，并不表示证件有问题。`additional_data` 包含每个服务的跳过摘要。触发此警告时**不向您收费**。操作可配置（默认 `NO_ACTION`）。 |
| `DATABASE_VALIDATION_PARTIAL_MATCH` | 数据库核验部分匹配 | 聚合 `match_type` 为 `partial_match`：部分筛查字段与登记系统匹配，但并非全部匹配。操作可配置（默认 `NO_ACTION`）。 |
| `DATABASE_VALIDATION_NO_MATCH` | 数据库核验不匹配 | 聚合 `match_type` 为 `no_match`：登记系统无法确认被筛查的身份。操作可配置（在工作流中默认 `REVIEW`，在独立 API 上默认 `DECLINE`）。 |
| `DATABASE_VALIDATION_DOCUMENT_SUPERSEDED` | 已作废的证件版本 | 某个服务返回了 `DOCUMENT_SUPERSEDED`：登记系统确认了该人员，但出示的证件版本不是存档的版本，此后已签发了更新的版本。此警告独立于 `match_type` 产生，后者保持为 `full_match`，因为每个个人字段都完全匹配，否则该问题将不会显现。`additional_data` 列出了报告该情况的服务。遵循 **No Match Action** 设置。 |

> [!NOTE]
>
> `COULD_NOT_PERFORM_DATABASE_VALIDATION` 涵盖两种不同的情况，警告的 `long_description`（以及针对单个服务失败的 `database_validation_errors[].message`）现在会指明具体适用于哪一种情况，而不是显示单一的通用句子：在能够查询任何服务之前，筛查数据缺失或格式错误；或者已查询服务但未返回可用结果。在第二种情况下，当登记系统报告了该次尝试的自身诊断详情时，该详情将包含在消息中，因此您无需联系支持团队即可了解原因。响应中绝不会显示上游服务的名称。

> [!NOTE]
>
> 当在工作流会话中触发 `COULD_NOT_PERFORM_DATABASE_VALIDATION` 或 `DATABASE_VALIDATION_NOT_APPLICABLE` 时，一旦在控制台的会话详情页面上补齐缺失数据，就会自动重新触发检查：保存字段将重新运行核验，并在成功时移除警告。当“不适用”操作拒绝了会话时，此机制同样有效，因此被拒绝的会话可以通过更正数据来进行补救。对于 `DATABASE_VALIDATION_NOT_APPLICABLE`，当证件本可以包含该标识符但未被读取时（例如，未提取出身份证号的居留卡），重新运行会有所帮助；对于绝不会包含该标识符的证件类型（例如，没有身份证号的护照），则将保留该警告。跳过的服务**不收费**；您只需在服务返回可计费结果时付费。

## 示例

```json theme={null}
{
  "warnings": [
    {
      "feature": "DATABASE_VALIDATION",
      "risk": "DATABASE_VALIDATION_NO_MATCH",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Database validation no match",
      "long_description": "The system identified a no match in the database validation, requiring further investigation.",
      "node_id": "feature_db_validation_1"
    }
  ]
}
```

## 警告类型

根据您的应用配置，每个风险都会被分配一个严重程度。严重程度分为三类：

## 相关内容

* [数据库核验概览](https://docs.didit.me/zh/core-technology/database-validation/overview.md) — 该功能的端到端工作原理及受支持的登记系统。
* [数据库核验报告](https://docs.didit.me/zh/core-technology/database-validation/database-validation-report.md) — 完整的响应格式，包含每个服务的 `validations[]`。
* [匹配方法](https://docs.didit.me/zh/core-technology/database-validation/database-validation-matching-methods.md) — 1×1 / 2×2 结果（`validation_type: one_by_one` / `two_by_two`）如何从每个服务的匹配中得出。
* [结果代码](https://docs.didit.me/zh/core-technology/database-validation/database-validation-outcome-codes.md) — 包含特定国家/地区详细代码的完整逐项结果分类法。
* [受支持的国家/地区与服务](https://docs.didit.me/zh/core-technology/database-validation/database-validation-supported-countries.md) — 每个线上登记系统、必填字段以及每次调用价格。
* [数据模型 — 数据库核验](https://docs.didit.me/zh/reference/data-models.md#数据库核验) — 规范的逐字段模式。


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