Informe de validación en bases de datos: respuesta JSON

La función de Validación de base de datos de Didit coteja los datos de identidad de cada usuario con la fuente oficial de cada país: RENAPER (Argentina), Receita Federal (Brasil), Tribunal Electoral (Panamá, con coincidencia facial biométrica), Junta Central Electoral (República Dominicana) y otras. Se factura por cada consulta exitosa, sin mínimos mensuales. Cada entrada de database_validations[] es un informe completo de Validación de base de datos: una ejecución de un nodo de Validación de base de datos para un país emisor. Los resultados de cada servicio de registro están dentro del array anidado validations[] de esa entrada. Esta página documenta la estructura JSON para que puedas interpretar los resultados de coincidencia, los datos de origen del registro y las puntuaciones biométricas que devuelve cada servicio.

Informe de Validación de base de datos de Didit con los tipos de coincidencia y los campos de respuesta del registro

Visión general

Se genera un informe de Validación de base de datos cada vez que un nodo de un flujo de verificación (workflow) ejecuta la función de Validación de base de datos. Cada entrada del array database_validations[] representa una ejecución de nodo para un país emisor. Si el nodo ejecuta varios servicios para ese país (por ejemplo, CPF + CNH en Brasil), cada servicio aparece como un elemento independiente dentro del subarray validations[] de la entrada. Cada informe contiene:

El status general de la función: un valor de FeatureStatusChoices (Not Finished, Approved, Declined, In Review).
Un match_type consolidado (full_match, partial_match, no_match, o null cuando ningún servicio devolvió un resultado utilizable), agregado entre servicios mediante el método de coincidencia.
El issuing_state (ISO 3166-1 alfa-3) y el validation_type derivado (one_by_one, two_by_two o not_enabled; nunca null).
El bloque screened_data: los datos proporcionados por el usuario que se enviaron al registro.
Un array validations[]: una entrada por cada servicio que produjo un resultado, con el service_id/service_name del catálogo, el outcome_code independiente del proveedor, un outcome_detail opcional, el mapa validation por campo y los source_data depurados extraídos de la respuesta del registro.
Un array errors[]: errores por servicio cuando una consulta falló o se omitió. La clave se omite por completo cuando no hay errores.
Un array warnings[]: eventos de riesgo emitidos durante la validación (consulta las advertencias de Validación de base de datos).
Un node_id que identifica qué nodo del grafo del flujo generó el informe (solo en sesiones V3).

Dónde aparece en las respuestas de la API

El informe aparece como database_validations[] en GET /v3/session/{sessionId}/decision/, siempre como un array JSON, nunca como un objeto único. El array contiene una entrada por cada nodo de Validación de base de datos del grafo del flujo y, a su vez, el subarray validations[] de cada entrada contiene un elemento por cada servicio de registro que produjo un resultado.

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

Un valor null significa que todavía no se ha ejecutado ningún paso de Validación de base de datos.

Esquema

El esquema canónico campo por campo está en la página Modelos de datos. Lo genera 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
}

Valores de estado

status usa el enum estándar a nivel de función (consulta Enums de estado); consulta la referencia del enum de estado. El enum también define Resub Requested, que en la práctica la Validación de base de datos no produce.

Estado	Significado
`Not Finished`	La validación aún no ha producido un resultado (estado inicial; también se registra cuando una llamada independiente falla en todos los servicios).
`Approved`	No se activó ningún riesgo, o los únicos riesgos activados tienen configurada la acción `NO_ACTION` (el valor predeterminado para la coincidencia parcial).
`Declined`	Un resultado sin coincidencia o con coincidencia parcial cuya acción configurada es `DECLINE`.
`In Review`	Un resultado sin coincidencia o con coincidencia parcial cuya acción configurada es `REVIEW`, o la validación no pudo ejecutarse en absoluto (`COULD_NOT_PERFORM_DATABASE_VALIDATION`, siempre a revisión).

Las reglas de estado personalizadas por nodo se aplican sobre este estado base. Consulta Advertencias de Validación de base de datos para ver las acciones configurables y sus valores predeterminados.

Códigos de resultado

Cada entrada de validations[] incluye un outcome_code independiente del proveedor, que es uno de 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. Ten en cuenta las diferencias: NO_MATCH significa que el registro definitivamente no confirmó los datos, INCONCLUSIVE significa que el registro no pudo determinar ni una cosa ni la otra (envíalo a revisión, no lo rechaces) y BIOMETRIC_IMAGE_UNUSABLE es un problema técnico de la selfie (hay que repetirla), a diferencia del resultado definitivo BIOMETRIC_NO_MATCH. Consulta la taxonomía completa y el tratamiento recomendado en la página Códigos de resultado.

Una entrada por servicio

El array validations[] contiene un elemento por cada servicio que produjo un payload de resultado (un mapa validation, source_data, outcome_code u outcome_detail). Si tu flujo ejecuta varios servicios para el mismo país (por ejemplo, Brasil CPF + Brasil CNH), cada uno aparece por separado con su propio service_id, outcome_code y source_data. El match_type agregado combina todos los servicios (cualquier coincidencia total → full_match; si no, cualquier coincidencia parcial → partial_match; si no, no_match), y validation_type se deriva de cuántos servicios distintos obtuvieron una coincidencia total; consulta Métodos de coincidencia.

URL de imágenes prefirmadas

Los campos de imagen de source_data (photo, signature) y screened_data (selfie, cnh_qr_code_image, document_image) se devuelven como URL prefirmadas que caducan; para renovarlas, vuelve a llamar al endpoint de decisión. El payload original del proveedor no se expone a través de la API de forma intencionada.

Ejemplos

Aprobado: comprobación del estado del CPF de Brasil (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": []
}

Aprobado: DNI biométrico de Argentina (RENAPER)

En Argentina, la validación usa RENAPER con una coincidencia facial biométrica. La respuesta incluye un face_match_score y campos de identidad adicionales que devuelve el registro.

{
  "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ón: no se pudo consultar el registro

Cuando ningún servicio devuelve un resultado utilizable (faltan campos obligatorios o tienen un formato incorrecto, o no se puede acceder al registro), match_type se mantiene en null, validation_type es not_enabled, se emite una advertencia COULD_NOT_PERFORM_DATABASE_VALIDATION y la función pasa a In Review hasta que se corrijan los datos. No se cobra por los servicios omitidos.

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

Completa el campo que falta desde la página de detalle de la sesión en la Console: al guardarlo, la comprobación se vuelve a ejecutar automáticamente y, si tiene éxito, la advertencia desaparece.

Relacionado

Visión general de la Validación de base de datos: cómo funciona la API de principio a fin y qué registros admite.
Métodos de coincidencia: cómo se derivan los resultados 1×1 / 2×2 (validation_type: one_by_one / two_by_two).
Códigos de resultado: taxonomía completa por resultado con códigos de detalle específicos de cada país.
Países y servicios admitidos: todos los registros activos, los campos obligatorios y el precio por llamada.
Advertencias de Validación de base de datos: qué mostramos cuando un servicio no puede ejecutarse.
Modelos de datos: validación de base de datos: esquema canónico campo por campo.

Autenticación

Verificación

Monitorización

Plataforma

Informe de validación en bases de datos: respuesta JSON

Visión general

Dónde aparece en las respuestas de la API

Esquema

Valores de estado

Códigos de resultado

Una entrada por servicio

URL de imágenes prefirmadas

Ejemplos

Aprobado: comprobación del estado del CPF de Brasil (Receita Federal)

Aprobado: DNI biométrico de Argentina (RENAPER)

En revisión: no se pudo consultar el registro

Relacionado

​Visión general

​Dónde aparece en las respuestas de la API

​Esquema

​Valores de estado

​Códigos de resultado

​Una entrada por servicio

​URL de imágenes prefirmadas

​Ejemplos

​Aprobado: comprobación del estado del CPF de Brasil (Receita Federal)

​Aprobado: DNI biométrico de Argentina (RENAPER)

​En revisión: no se pudo consultar el registro

​Relacionado

Visión general

Dónde aparece en las respuestas de la API

Esquema

Valores de estado

Códigos de resultado

Una entrada por servicio

URL de imágenes prefirmadas

Ejemplos

Aprobado: comprobación del estado del CPF de Brasil (Receita Federal)

Aprobado: DNI biométrico de Argentina (RENAPER)

En revisión: no se pudo consultar el registro

Relacionado