> ## 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 のデータベース検証レスポンスを解析する方法。サービスごとの照合結果、公的登録機関のソースデータ、生体認証による顔照合スコア、警告コードを確認できます。従量課金で1回$0.05から。

Diditの[データベース検証](https://docs.didit.me/ja/core-technology/database-validation/overview.md)機能は、各ユーザーの本人情報をその国の公的機関のデータソースと照合します。データソースにはRENAPER(アルゼンチン)、Receita Federal(ブラジル)、Tribunal Electoral(パナマ、生体認証による顔照合付き)、Junta Central Electoral(ドミニカ共和国)などがあります。料金は照会が成功した分だけ請求され、月額の最低利用料金はありません。

`database_validations[]`の各エントリーは、1件の完全なデータベース検証レポートです。これは、1つの発行国に対してデータベース検証ノードを1回実行した結果にあたります。サービスごとの登録機関の照合結果は、そのエントリー内の`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[]`配列の各エントリーは、**1つの発行国**に対する**1回のノード実行**を表します。ノードがその国で複数のサービスを実行する場合(例: ブラジルのCPFとCNH)、各サービスはエントリーの`validations[]`サブ配列内の個別の項目として表示されます。各レポートには次の情報が含まれます。

* 機能全体の`status`。[`FeatureStatusChoices`](https://docs.didit.me/ja/reference/data-models#ステータス列挙値リファレンス)の値(`Not Finished`、`Approved`、`Declined`、`In Review`)です。
* 集約された`match_type`(`full_match`、`partial_match`、`no_match`、または利用可能な結果を返したサービスがない場合は`null`)。[照合方式](https://docs.didit.me/ja/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[]`配列。結果を返したサービスごとに1件のエントリーがあり、カタログの`service_id`/`service_name`、ベンダーに依存しない`outcome_code`、任意の`outcome_detail`、フィールドごとの`validation`マップ、登録機関のレスポンスから抽出して整形した`source_data`を含みます。
* `errors[]`配列。照会が失敗した場合やスキップされた場合の、サービスごとのエラーです。エラーがない場合、このキーは**完全に省略**されます。
* `warnings[]`配列。検証中に発生したリスクイベントです([データベース検証の警告](https://docs.didit.me/ja/core-technology/database-validation/database-validation-warnings.md)を参照)。
* `node_id`。レポートを生成したワークフローのグラフノードを識別します(V3セッションのみ)。

## APIレスポンスでの表示位置

このレポートは、`GET /v3/session/{sessionId}/decision/`の**`database_validations[]`**として表示されます。常にJSON配列であり、単一のオブジェクトになることはありません。配列には、ワークフローのグラフ内にあるデータベース検証ノードごとに1件のエントリーが含まれます。さらに、各エントリーの`validations[]`サブ配列には、結果を返したレジストリサービスごとに1件の項目が含まれます。

```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/ja/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/ja/reference/data-models.md#ステータス列挙値リファレンス)を参照)。詳しくは[ステータス列挙型リファレンス](https://docs.didit.me/ja/reference/data-models.md#ステータス列挙値リファレンス)を参照してください。この列挙型には`Resub Requested`も定義されていますが、実際にはデータベース検証で生成されることはありません。

| ステータス | 意味 |
| - | - |
| `Not Finished` | 検証の結果がまだ出ていない状態です(初期状態。単独の呼び出しがすべてのサービスで失敗した場合にも記録されます)。 |
| `Approved` | リスクが1つも発生していないか、発生したリスクがすべて`NO_ACTION`に設定されている状態です(部分一致のデフォルト)。 |
| `Declined` | 不一致または部分一致の結果で、設定されたアクションが`DECLINE`の場合です。 |
| `In Review` | 不一致または部分一致の結果で、設定されたアクションが`REVIEW`の場合、または検証をまったく実行できなかった場合です(`COULD_NOT_PERFORM_DATABASE_VALIDATION`は常にレビュー)。 |

ノードごとのカスタムステータスルールは、この基本ステータスに上乗せして適用されます。設定可能なアクションとそのデフォルトについては、[データベース検証の警告](https://docs.didit.me/ja/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/ja/core-technology/database-validation/database-validation-outcome-codes.md)ページを参照してください。

### サービスごとに1エントリ

`validations[]`配列には、**結果ペイロードを生成したサービスごとに1つの項目**(`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/ja/core-technology/database-validation/database-validation-matching-methods.md)を参照してください。

### 署名付き画像URL

`source_data`(`photo`、`signature`)および`screened_data`(`selfie`、`cnh_qr_code_image`、`document_image`)の画像フィールドは、有効期限のある**署名付きURL**として返されます。更新するには判定エンドポイントを再度呼び出してください。上流から受け取った生のペイロードは、意図的にAPI経由では公開していません。

## 例

### 承認済み: ブラジル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": []
}
```

### 承認済み: アルゼンチン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": []
}
```

### レビュー中: 登録機関による検証を実行できなかった場合

どのサービスからも有効な結果が返されない場合(必須フィールドの欠落や形式不正、または登録機関に到達できない場合)、`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/ja/core-technology/database-validation/overview.md): APIのエンドツーエンドの仕組みと対応する登録機関。
* [照合方式](https://docs.didit.me/ja/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/ja/core-technology/database-validation/database-validation-outcome-codes.md): 国別の詳細コードを含む、結果ごとの分類の全体像。
* [対応国とサービス](https://docs.didit.me/ja/core-technology/database-validation/database-validation-supported-countries.md): 稼働中のすべての登録機関、必須フィールド、呼び出しごとの料金。
* [データベース検証の警告](https://docs.didit.me/ja/core-technology/database-validation/database-validation-warnings.md): サービスを実行できない場合に表示される内容。
* [データモデル: データベース検証](https://docs.didit.me/ja/reference/data-models.md#データベース検証): フィールドごとの正式なスキーマ。


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