数据库核验报告：JSON 响应

Didit 的数据库核验功能将每位用户的身份数据与该国家/地区的权威机构数据源（阿根廷 RENAPER、巴西 Receita Federal、巴拿马 Tribunal Electoral（包含生物识别特征人脸比对）、多米尼加共和国 Junta Central Electoral 等）进行交叉核对，按成功的查询计费，无月度最低消费。 database_validations[] 中的每个条目都是一份完整的数据库核验报告，即数据库核验节点针对一个签发国家/地区的一次运行。各个服务的登记系统核验结果位于该条目的 validations[] 子数组中。本页面介绍了其 JSON 结构，以便您解析各服务返回的匹配结果、登记系统源数据以及生物识别分数。

概述

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

整体功能 status：FeatureStatusChoices 值（Not Finished、Approved、Declined、In Review）。
汇总 match_type（full_match、partial_match、no_match，或者当没有服务返回可用结果时为 null），通过匹配方法跨服务聚合得出。
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[] 数组：核验过程中触发的风险事件（请参阅数据库核验警告）。
用于标识生成该报告的工作流图谱节点的 node_id（仅限 V3 会话）。

在 API 响应中的位置

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

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "database_validations": [
    { "node_id": "feature_db_validation_1", "status": "Approved", "...": "..." }
  ]
}

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

数据模式

权威的逐字段模式位于数据模型页面。它由 DatabaseValidationV3Serializer 生成。

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 使用标准的功能级枚举（参见状态枚举）— 参见状态枚举参考。该枚举还定义了 Resub Requested，但数据库核验在实际中不会生成该状态。

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

在此基础状态之上还会应用自定义的每个节点状态规则。有关可配置操作及其默认值，请参见数据库核验警告。

结果代码

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 不同。完整分类法及建议的处理方式请参见结果代码页面。

每个服务一个条目

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 则根据有多少个不同服务实现了完全匹配推导得出 — 参见匹配方式。

预签名图像 URL

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

示例

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

{
  "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 以及登记库返回的其他身份字段。

{
  "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。对于跳过的服务不收费。

{
  "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"
    }
  ]
}

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

身份认证

验证

监控

平台

数据库核验报告：JSON 响应

概述

在 API 响应中的位置

数据模式

状态值

结果代码

每个服务一个条目

预签名图像 URL

示例

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

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

In Review — 登记库无法运行

相关内容

​概述

​在 API 响应中的位置

​数据模式

​状态值

​结果代码

​每个服务一个条目

​预签名图像 URL

​示例

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

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

​In Review — 登记库无法运行

​相关内容

概述

在 API 响应中的位置

数据模式

状态值

结果代码

每个服务一个条目

预签名图像 URL

示例

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

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

In Review — 登记库无法运行

相关内容