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

# 数据库核验报告：JSON 响应

> 解析 Didit 数据库核验响应：包含各项服务的匹配结果、登记处源数据、生物识别面部比对分数及警告代码。按次计费，单次调用低至 $0.05。

Didit 的[数据库核验](https://docs.didit.me/zh/core-technology/database-validation/overview.md)功能将每位用户的身份数据与该国家/地区的权威机构数据源（阿根廷 RENAPER、巴西 Receita Federal、巴拿马 Tribunal Electoral（包含生物识别特征人脸比对）、多米尼加共和国 Junta Central Electoral 等）进行交叉核对，按成功的查询计费，无月度最低消费。

`database_validations[]` 中的每个条目都是一份完整的数据库核验报告，即数据库核验节点针对一个签发国家/地区的一次运行。各个服务的登记系统核验结果位于该条目的 `validations[]` 子数组中。本页面介绍了其 JSON 结构，以便您解析各服务返回的匹配结果、登记系统源数据以及生物识别分数。

![显示匹配类型和登记系统响应字段的 Didit 数据库核验报告](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/database-validation-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=56284966659e33d1c74385647537e5d9)

## 概述

每当工作流节点运行数据库核验功能时，都会生成一份数据库核验报告。`database_validations[]` 数组中的每个条目代表针对**一个签发国家/地区**的**一次节点运行**；如果该节点针对该国家/地区运行了多个服务（例如巴西的 CPF + CNH），则每个服务都会作为独立项显示在该条目的 `validations[]` 子数组中。每份报告包含：

* 整体功能 `status`：[`FeatureStatusChoices`](https://docs.didit.me/zh/reference/data-models#状态枚举参考) 值（`Not Finished`、`Approved`、`Declined`、`In Review`）。
* 汇总 `match_type`（`full_match`、`partial_match`、`no_match`，或者当没有服务返回可用结果时为 `null`），通过[匹配方法](https://docs.didit.me/zh/core-technology/database-validation/database-validation-matching-methods.md)跨服务聚合得出。
* `issuing_state`（ISO 3166-1 alpha-3）以及衍生的 `validation_type`（`one_by_one`、`two_by_two` 或 `not_enabled`，绝不为 `null`）。
* `screened_data` 区块：发送至登记系统的用户所提供数据。
* `validations[]` 数组：每个产生结果的服务对应一个条目，包含目录中的 `service_id`/`service_name`、供应商中立的 `outcome_code`、可选的 `outcome_detail`、逐字段的 `validation` 映射表以及从登记系统响应中提取的清洗后的 `source_data`。
* `errors[]` 数组：查询失败或跳过时的逐服务错误；没有错误时，该键会被**完全省略**。
* `warnings[]` 数组：核验过程中触发的风险事件（请参阅[数据库核验警告](https://docs.didit.me/zh/core-technology/database-validation/database-validation-warnings.md)）。
* 用于标识生成该报告的工作流图谱节点的 `node_id`（仅限 V3 会话）。

## 在 API 响应中的位置

该报告在 `GET /v3/session/{sessionId}/decision/` 中以 **`database_validations[]`** 形式出现，它始终是一个 JSON 数组，绝非单个对象。工作流图谱中的每个数据库核验节点都在该数组中对应一个条目；相应地，每个条目的 `validations[]` 子数组中包含产生结果的每个登记系统服务的一个条目。

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "database_validations": [
    { "node_id": "feature_db_validation_1", "status": "Approved", "...": "..." }
  ]
}
```

`null` 值表示尚未运行任何数据库核验步骤。

## 数据模式

权威的逐字段模式位于[数据模型](https://docs.didit.me/zh/reference/data-models.md#数据库核验)页面。它由 `DatabaseValidationV3Serializer` 生成。

```typescript theme={null}
interface DatabaseValidation {
  node_id: string | null;
  status: "Not Finished" | "Approved" | "Declined" | "In Review"; // FeatureStatusChoices
  issuing_state: string | null;      // ISO 3166-1 alpha-3, e.g. "ARG"
  validation_type: "one_by_one" | "two_by_two" | "not_enabled"; // derived, never null
  match_type: "full_match" | "partial_match" | "no_match" | null; // null when no service returned a usable result
  screened_data: {                   // What we sent to the registry (varies by country/service)
    tax_number?: string;
    personal_number?: string;
    document_number?: string;
    first_name?: string;
    last_name?: string;
    date_of_birth?: string;          // YYYY-MM-DD
    selfie?: string;                 // Presigned URL (biometric services)
    cnh_qr_code_image?: string;      // Presigned URL (Brazil CNH QR + face match)
    document_image?: string;         // Presigned URL (services that take a document image)
    gender?: string;                 // Biometric registry services (e.g. Argentina RENAPER)
  };
  validations: Array<{
    // Catalog metadata
    service_id?: string;             // e.g. "arg_renaper"
    service_name?: string;           // e.g. "Argentina - DNI verification (RENAPER)"
    // Per-field match outcome — keys vary by service
    // (full_name, first_name, last_name, date_of_birth, identification_number, address, …)
    validation?: Record<string, "full_match" | "partial_match" | "no_match">;
    outcome_code?: string;           // Vendor-neutral outcome, see below
    outcome_detail?: string;         // Raw upstream status detail backing the outcome code
    source_data?: {                  // Cleaned registry record
      identification_number?: string;
      first_name?: string;
      last_name?: string;
      full_name?: string;
      date_of_birth?: string;
      place_of_birth?: string;
      gender?: string;
      nationality?: string;
      issue_date?: string;
      expiration_date?: string;
      photo?: string;                // Pre-signed JPEG URL
      signature?: string;            // Pre-signed JPEG URL
      face_match_score?: number;     // Biometric services only (0-100)
    };
  }>;
  errors?: Array<{                   // Omitted entirely when empty
    service_id: string;
    code?: string;                   // e.g. "invalid_screened_data", "empty_provider_response"
    message?: string;
    missing_required_fields?: string[];
    invalid_format_fields?: string[];
    field_reasons?: Record<string, string>;
  }>;
  warnings: Warning[];               // See /reference/data-models#warning-object
}
```

### 状态值

`status` 使用标准的功能级枚举（参见[状态枚举](https://docs.didit.me/zh/reference/data-models.md#状态枚举参考)）— 参见[状态枚举参考](https://docs.didit.me/zh/reference/data-models.md#状态枚举参考)。该枚举还定义了 `Resub Requested`，但数据库核验在实际中不会生成该状态。

| 状态 | 含义 |
| - | - |
| `Not Finished` | 核验尚未生成结果（初始状态；当独立调用在所有服务中均失败时也会记录）。 |
| `Approved` | 未触发任何风险，或触发的唯一风险配置为 `NO_ACTION`（部分匹配的默认值）。 |
| `Declined` | 配置的操作为 `DECLINE` 的未匹配或部分匹配结果。 |
| `In Review` | 配置的操作为 `REVIEW` 的未匹配或部分匹配结果，或者核验完全无法运行（`COULD_NOT_PERFORM_DATABASE_VALIDATION` — 始终审核）。 |

在此基础状态之上还会应用自定义的每个节点状态规则。有关可配置操作及其默认值，请参见[数据库核验警告](https://docs.didit.me/zh/core-technology/database-validation/database-validation-warnings.md)。

### 结果代码

`validations[]` 中的每个条目都包含一个独立于供应商的 `outcome_code` — 即 `MATCH`、`PARTIAL_MATCH`、`NO_MATCH`、`DOCUMENT_NOT_FOUND`、`INVALID_DOCUMENT_FORMAT`、`INVALID_INPUT`、`MINOR_BLOCKED`、`DECEASED`、`BIOMETRIC_NO_MATCH`、`BIOMETRIC_IMAGE_UNUSABLE`、`INCONCLUSIVE`、`DOCUMENT_SUPERSEDED`、`REGISTRY_UNAVAILABLE`、`REGISTRY_ERROR` 之一。请注意其中的区别：`NO_MATCH` 表示登记库明确未能确认数据；`INCONCLUSIVE` 表示登记库无法做出确切判定（应转入审核，而非拒绝）；而 `BIOMETRIC_IMAGE_UNUSABLE` 属于技术性自拍照问题（需重新拍摄）— 与明确的 `BIOMETRIC_NO_MATCH` 不同。完整分类法及建议的处理方式请参见[结果代码](https://docs.didit.me/zh/core-technology/database-validation/database-validation-outcome-codes.md)页面。

### 每个服务一个条目

`validations[]` 数组包含**每个生成了结果 payload 的服务对应的一个条目**（一个 `validation` 映射、`source_data`、`outcome_code` 或 `outcome_detail`）。如果您的工作流针对同一个国家/地区运行多个服务（例如巴西 CPF + 巴西 CNH），每个服务都会单独显示，并带有各自的 `service_id`、`outcome_code` 和 `source_data`。汇总的 `match_type` 会聚合所有服务的结果（任何完全匹配 → `full_match`；否则任何部分匹配 → `partial_match`；否则为 `no_match`），而 `validation_type` 则根据有多少个不同服务实现了完全匹配推导得出 — 参见[匹配方式](https://docs.didit.me/zh/core-technology/database-validation/database-validation-matching-methods.md)。

### 预签名图像 URL

`source_data`（`photo`、`signature`）和 `screened_data`（`selfie`、`cnh_qr_code_image`、`document_image`）中的图像字段以会过期的**预签名 URL** 形式返回 — 可通过重新调用决策 endpoint 来刷新。原始上游 payload 故意未通过 API 暴露。

## 示例

### Approved — 巴西 CPF 状态查询 (Receita Federal)

```json theme={null}
{
  "node_id": "feature_db_validation_1",
  "status": "Approved",
  "issuing_state": "BRA",
  "validation_type": "one_by_one",
  "match_type": "full_match",
  "screened_data": {
    "tax_number": "12345678900",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1980-01-01"
  },
  "validations": [
    {
      "service_id": "bra_cpf",
      "service_name": "Brazil - CPF status check",
      "outcome_code": "MATCH",
      "outcome_detail": "200",
      "validation": {
        "full_name": "full_match",
        "date_of_birth": "full_match",
        "identification_number": "full_match"
      },
      "source_data": {
        "identification_number": "12345678900",
        "first_name": "JOHN",
        "last_name": "DOE",
        "date_of_birth": "1980-01-01",
        "lgpd_minor": false,
        "minor_under_16": false,
        "minor_under_18": false
      }
    }
  ],
  "warnings": []
}
```

### Approved — 阿根廷 DNI 生物识别 (RENAPER)

对于阿根廷，该核验使用 RENAPER，并进行生物识别人脸比对。响应中包含 `face_match_score` 以及登记库返回的其他身份字段。

```json theme={null}
{
  "node_id": "feature_db_validation_1",
  "status": "Approved",
  "issuing_state": "ARG",
  "validation_type": "one_by_one",
  "match_type": "full_match",
  "screened_data": {
    "document_number": "12345678",
    "selfie": "https://<media-host>/sessions/<session-id>/selfie.jpg?X-Amz-Signature=...",
    "gender": "M",
    "first_name": "John",
    "last_name": "Doe"
  },
  "validations": [
    {
      "service_id": "arg_renaper",
      "service_name": "Argentina - DNI verification (RENAPER)",
      "outcome_code": "MATCH",
      "validation": {
        "full_name": "full_match",
        "identification_number": "full_match"
      },
      "source_data": {
        "identification_number": "12345678",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "date_of_birth": "1990-01-01",
        "tax_id": "20000000019",
        "tax_id_type": "CUIT",
        "face_match_score": 97
      }
    }
  ],
  "warnings": []
}
```

### In Review — 登记库无法运行

当没有服务返回可用结果时 — 必填字段缺失或格式错误，或者登记库无法访问 — `match_type` 保持为 `null`，`validation_type` 为 `not_enabled`，系统会发出 `COULD_NOT_PERFORM_DATABASE_VALIDATION` 警告，且该功能在数据得到修正前会转为 `In Review`。对于跳过的服务**不收费**。

```json theme={null}
{
  "node_id": "feature_db_validation_1",
  "status": "In Review",
  "issuing_state": "PAN",
  "validation_type": "not_enabled",
  "match_type": null,
  "screened_data": {
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "selfie": "https://<media-host>/sessions/<session-id>/selfie.jpg?X-Amz-Signature=..."
  },
  "validations": [],
  "errors": [
    {
      "code": "invalid_screened_data",
      "message": "Database validation was skipped before calling the provider because the screened data has missing required fields: personal_number.",
      "missing_required_fields": ["personal_number"],
      "service_id": "pan_cedula_sib_plus"
    }
  ],
  "warnings": [
    {
      "feature": "DATABASE_VALIDATION",
      "risk": "COULD_NOT_PERFORM_DATABASE_VALIDATION",
      "additional_data": {
        "reason": "Database validation was skipped before any provider request because the screened data is incomplete or invalid.",
        "database_validation_errors": [
          {
            "code": "invalid_screened_data",
            "message": "Database validation was skipped before calling the provider because the screened data has missing required fields: personal_number.",
            "missing_required_fields": ["personal_number"],
            "service_id": "pan_cedula_sib_plus"
          }
        ],
        "missing_required_fields_by_service": { "pan_cedula_sib_plus": ["personal_number"] },
        "invalid_format_fields_by_service": {},
        "field_reasons_by_service": {}
      },
      "log_type": "warning",
      "short_description": "Could not perform database validation",
      "long_description": "The system couldn't perform the database validation, please fill the required fields for this country to automatically proceed with database validation.",
      "node_id": "feature_db_validation_1"
    }
  ]
}
```

在控制台的会话详情页面中填写缺失的字段 — 保存后会自动重新触发检查，并在成功时清除该警告。

## 相关内容

* [数据库核验概述](https://docs.didit.me/zh/core-technology/database-validation/overview.md) — API 端到端的工作方式以及支持的登记库。
* [匹配方式](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/core-technology/database-validation/database-validation-warnings.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.