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

# Informe de validació en bases de dades: resposta JSON

> Interpreta respostes de Didit: resultats de coincidència, dades de registres, puntuacions biomètriques i advertències. Pagament per crida des de $0.05.

La funcionalitat de [Validació en bases de dades](https://docs.didit.me/ca/core-technology/database-validation/overview.md) de Didit confronta les dades d'identitat de cada usuari amb la font autoritzada de referència d'aquell país — RENAPER (Argentina), Receita Federal (Brasil), Tribunal Electoral (Panamà, amb coincidència facial biomètrica), Junta Central Electoral (República Dominicana) i més —, facturada per consulta satisfactòria sense mínims mensuals.

Cada entrada de `database_validations[]` és un informe complet de Validació en bases de dades — una execució d'un node de Validació en bases de dades contra un estat emissor. Els resultats del registre per servei es troben dins de l'array `validations[]` d'aquesta entrada. Aquesta pàgina documenta l'estructura JSON perquè puguis analitzar els resultats de coincidència, les dades d'origen del registre i les puntuacions biomètriques retornades per cada servei.

![Informe de validació en bases de dades de Didit que mostra els tipus de coincidència i els camps de resposta del registre](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)

## Visió general

Es genera un informe de Validació en bases de dades cada vegada que un node del flux de treball executa la funcionalitat de Validació en bases de dades. Cada entrada del vector `database_validations[]` representa **l'execució d'un node** contra **un estat emissor**; si el node executa diversos serveis per a aquest país (per exemple CPF + CNH al Brasil), cada servei apareix com un element separat dins de l'array `validations[]` de l'entrada. Cada informe conté:

* L'`status` global de la funcionalitat — un valor de [`FeatureStatusChoices`](https://docs.didit.me/ca/reference/data-models#referència-d’enumeració-d’estats) (`Not Finished`, `Approved`, `Declined`, `In Review`).
* Un `match_type` agregat (`full_match`, `partial_match`, `no_match`, o `null` quan cap servei ha retornat un resultat utilitzable) consolidat entre serveis mitjançant el [mètode de coincidència](https://docs.didit.me/ca/core-technology/database-validation/database-validation-matching-methods.md).
* L'`issuing_state` (ISO 3166-1 alfa-3) i el `validation_type` derivat (`one_by_one`, `two_by_two`, o `not_enabled` — mai `null`).
* El bloc `screened_data` — les dades proporcionades per l'usuari que s'han enviat al registre.
* Un vector `validations[]` — una entrada per servei que hagi generat un resultat, amb el `service_id`/`service_name` del catàleg, l'`outcome_code` independent del proveïdor, un `outcome_detail` opcional, el mapa `validation` per camp i el `source_data` net extret de la resposta del registre.
* Un vector `errors[]` — errors per servei quan una consulta ha fallat o s'ha omès; la clau s'**omet completament** quan no hi ha errors.
* Un vector `warnings[]` — esdeveniments de risc emesos durant la validació (consulta [Advertències de Validació en bases de dades](https://docs.didit.me/ca/core-technology/database-validation/database-validation-warnings.md)).
* Un `node_id` que identifica quin node del graf del flux de treball ha generat l'informe (només per a sessions V3).

## On apareix a les respostes de l'API

L'informe apareix com a **`database_validations[]`** a `GET /v3/session/{sessionId}/decision/` — sempre com a array JSON, mai com a objecte singular. El vector conté una entrada per node de Validació en bases de dades al graf del flux de treball; al seu torn, l'array `validations[]` de cada entrada conté un element per servei de registre que hagi generat un resultat.

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

Un valor `null` significa que encara no s'ha executat cap pas de Validació en bases de dades.

## Schema

L'esquema canònic camp per camp es troba a la pàgina [Models de dades](https://docs.didit.me/ca/reference/data-models.md#validació-en-bases-de-dades). El genera `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
}
```

### Valors d'estat

`status` utilitza l'enum estàndard a nivell de funcionalitat (consulta [Enums d'estat](https://docs.didit.me/ca/reference/data-models.md#referència-d’enumeració-d’estats)) — consulta la [Referència d'enums d'estat](https://docs.didit.me/ca/reference/data-models.md#referència-d’enumeració-d’estats). L'enum també defineix `Resub Requested`, que a la pràctica no el genera Validació en bases de dades.

| Estat | Significat |
| - | - |
| `Not Finished` | La validació encara no ha generat cap resultat (estat inicial; també es registra quan una crida independent falla en tots els serveis). |
| `Approved` | No s'ha activat cap risc, o els únics riscs activats estan configurats com a `NO_ACTION` (el valor per defecte de coincidència parcial). |
| `Declined` | Un resultat de no coincidència o de coincidència parcial l'acció configurada del qual és `DECLINE`. |
| `In Review` | Un resultat de no coincidència o de coincidència parcial l'acció configurada del qual és `REVIEW`, o la validació no s'ha pogut executar en absolut (`COULD_NOT_PERFORM_DATABASE_VALIDATION` — sempre en revisió). |

S'apliquen regles d'estat personalitzades per node a sobre d'aquest estat base. Consulta [Advertències de Validació en bases de dades](https://docs.didit.me/ca/core-technology/database-validation/database-validation-warnings.md) per a les accions configurables i els seus valors per defecte.

### Codis de resultat

Cada entrada de `validations[]` inclou un `outcome_code` neutral respecte al proveïdor — un d'entre `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`. Tingues en compte les distincions: `NO_MATCH` significa que el registre no ha confirmat les dades de manera definitiva, `INCONCLUSIVE` significa que el registre no ha pogut determinar ni una cosa ni l'altra (deriva a revisió, no a rebuig), i `BIOMETRIC_IMAGE_UNUSABLE` és un problema tècnic de la selfie (cal tornar-la a fer) — a diferència del definitiu `BIOMETRIC_NO_MATCH`. Consulta la taxonomia completa i la gestió recomanada a la pàgina [Codis de resultat](https://docs.didit.me/ca/core-technology/database-validation/database-validation-outcome-codes.md).

### Una entrada per servei

La llista `validations[]` conté **un element per a cada servei que hagi generat un payload de resultats** (un mapa de `validation`, `source_data`, `outcome_code` o `outcome_detail`). Si el teu flux de treball executa diversos serveis per al mateix país (per exemple, CPF del Brasil + CNH del Brasil), cadascun apareix per separat amb el seu propi `service_id`, `outcome_code` i `source_data`. El `match_type` consolidat agrega els resultats de tots els serveis (qualsevol coincidència total → `full_match`; si no, qualsevol parcial → `partial_match`; si no, `no_match`), i `validation_type` es deriva de quants serveis diferents han tingut una coincidència total — consulta [Mètodes de coincidència](https://docs.didit.me/ca/core-technology/database-validation/database-validation-matching-methods.md).

### URL d'imatges signades prèviament

Els camps d'imatge a `source_data` (`photo`, `signature`) i `screened_data` (`selfie`, `cnh_qr_code_image`, `document_image`) es retornen com a **URL signades prèviament** que caduquen — actualitza-les tornant a cridar l'endpoint de decisió. El payload en brut del proveïdor no s'exposa intencionadament a través de l'API.

## Exemples

### Aprovada — comprovació d'estat del CPF del Brasil (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": []
}
```

### Aprovada — biometria del DNI de l'Argentina (RENAPER)

Per a l'Argentina, la validació utilitza RENAPER amb coincidència facial biomètrica. La resposta inclou un `face_match_score` i camps d'identitat addicionals retornats pel registre.

```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": []
}
```

### En revisió — el registre no s'ha pogut executar

Quan cap servei no retorna un resultat utilitzable — camps obligatoris absents o amb format incorrecte, o el registre no està disponible —, `match_type` es manté com a `null`, `validation_type` és `not_enabled`, s'emet una advertència `COULD_NOT_PERFORM_DATABASE_VALIDATION` i la funcionalitat passa a `In Review` fins que es corregeixin les dades. **No s'aplica cap càrrec** als serveis omesos.

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

Omple el camp que falta des de la pàgina de detall de la sessió a la Console — desar-lo torna a activar la comprovació automàticament i elimina l'advertència si és satisfactori.

## Relacionat

* [Visió general de Validació en bases de dades](https://docs.didit.me/ca/core-technology/database-validation/overview.md) — com funciona l'API d'extrem a extrem i registres admesos.
* [Mètodes de coincidència](https://docs.didit.me/ca/core-technology/database-validation/database-validation-matching-methods.md) — com es deriven els resultats 1×1 / 2×2 (`validation_type: one_by_one` / `two_by_two`).
* [Codis de resultat](https://docs.didit.me/ca/core-technology/database-validation/database-validation-outcome-codes.md) — taxonomia completa per resultat amb codis de detall específics per país.
* [Països i serveis admesos](https://docs.didit.me/ca/core-technology/database-validation/database-validation-supported-countries.md) — tots els registres en producció, camps obligatoris i preu per crida.
* [Advertències de Validació en bases de dades](https://docs.didit.me/ca/core-technology/database-validation/database-validation-warnings.md) — què mostrem quan un servei no es pot executar.
* [Models de dades — validació en bases de dades](https://docs.didit.me/ca/reference/data-models.md#validació-en-bases-de-dades) — esquema canònic camp per camp.


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