Relatório de validação de base de dados: resposta JSON

A funcionalidade de Validação de base de dados da Didit cruza os dados de identidade de cada utilizador com a fonte oficial desse país — RENAPER (Argentina), Receita Federal (Brasil), Tribunal Electoral (Panamá, com correspondência facial biométrica), Junta Central Electoral (República Dominicana), e mais — faturada por consulta bem-sucedida, sem mínimos mensais. Cada entrada em database_validations[] é um relatório completo de Validação de base de dados — uma execução de um nó de Validação de base de dados contra um estado emissor. Os resultados por serviço de registo residem dentro do sub-array validations[] dessa entrada. Esta página documenta o formato JSON para que possa processar resultados de correspondência, dados da fonte do registo e pontuações biométricas devolvidas por cada serviço.

Relatório de validação de base de dados da Didit que mostra tipos de correspondência e campos da resposta do registo

Visão geral

É gerado um relatório de Validação de base de dados sempre que um nó de fluxo executa a funcionalidade de Validação de base de dados. Cada entrada no array database_validations[] representa uma execução do nó contra um estado emissor; se o nó executar vários serviços para esse país (por exemplo, CPF + CNH no Brasil), cada serviço aparece como um item separado dentro do sub-array validations[] da entrada. Cada relatório contém:

O status geral da funcionalidade — um valor de FeatureStatusChoices (Not Finished, Approved, Declined, In Review).
Um match_type consolidado (full_match, partial_match, no_match ou null quando nenhum serviço devolveu um resultado utilizável) agregado entre serviços através do método de correspondência.
O issuing_state (ISO 3166-1 alfa-3) e o validation_type derivado (one_by_one, two_by_two ou not_enabled — nunca null).
O bloco screened_data — os dados fornecidos pelo utilizador que foram enviados para o registo.
Um array validations[] — uma entrada por serviço que produziu um resultado, com o service_id/service_name do catálogo, o outcome_code neutro em relação ao fornecedor, um outcome_detail opcional, o mapeamento validation por campo e os source_data tratados e extraídos da resposta do registo.
Um array errors[] — erros por serviço quando uma consulta falhou ou foi ignorada; a chave é completamente omitida quando não existem erros.
Um array warnings[] — eventos de risco emitidos durante a validação (consulte avisos da Validação de base de dados).
Um node_id que identifica qual nó do grafo de fluxo produziu o relatório (apenas em sessões V3).

Onde aparece nas respostas da API

O relatório aparece como database_validations[] em GET /v3/session/{sessionId}/decision/ — sempre um array JSON, nunca um objeto individual. O array contém uma entrada por nó de Validação de base de dados no grafo de fluxo; por sua vez, o sub-array validations[] de cada entrada contém um item por serviço de registo que produziu um resultado.

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

Um valor null significa que nenhum passo de Validação de base de dados foi ainda executado.

Esquema

O esquema campo a campo canónico encontra-se na página Modelos de dados. É produzido por 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 status

O campo status utiliza o enum padrão ao nível da funcionalidade (consulte Enums de status) — consulte a Referência de enums de status. O enum também define Resub Requested, que não é produzido pela Validação de base de dados na prática.

Status	Significado
`Not Finished`	A validação ainda não produziu um resultado (estado inicial; também registado quando uma chamada autónoma falha em todos os serviços).
`Approved`	Nenhum risco foi acionado, ou os únicos riscos acionados estão configurados como `NO_ACTION` (o padrão para correspondência parcial).
`Declined`	Um resultado de não correspondência ou correspondência parcial cuja ação configurada é `DECLINE`.
`In Review`	Um resultado de não correspondência ou correspondência parcial cuja ação configurada é `REVIEW`, ou a validação não pôde ser executada de todo (`COULD_NOT_PERFORM_DATABASE_VALIDATION` — sempre em análise).

As regras de status personalizadas por nó são aplicadas sobre este status base. Consulte Avisos da Validação de base de dados para obter as ações configuráveis e os respetivos padrões.

Códigos de resultado

Cada entrada em validations[] contém um outcome_code neutro em relação ao fornecedor — um 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. Note as distinções: NO_MATCH significa que o registo não confirmou definitivamente os dados, INCONCLUSIVE significa que o registo não conseguiu determinar num sentido ou noutro (encaminhar para análise, não recusar), e BIOMETRIC_IMAGE_UNUSABLE é um problema técnico com a selfie (repetir captura) — ao contrário do definitivo BIOMETRIC_NO_MATCH. Consulte a taxonomia completa e o tratamento recomendado na página Códigos de resultado.

Uma entrada por serviço

O array validations[] contém um item para cada serviço que produziu um payload de resultado (um mapa validation, source_data, outcome_code ou outcome_detail). Se o seu fluxo executar múltiplos serviços para o mesmo país (por exemplo, CPF do Brasil + CNH do Brasil), cada um surge separadamente com o seu próprio service_id, outcome_code e source_data. O valor consolidado de match_type agrega todos os serviços (qualquer correspondência total → full_match; caso contrário, qualquer parcial → partial_match; caso contrário, no_match), e validation_type é derivado do número de serviços distintos com correspondência total — consulte Métodos de correspondência.

URLs de imagem pré-assinados

Os campos de imagem em source_data (photo, signature) e screened_data (selfie, cnh_qr_code_image, document_image) são devolvidos como URLs pré-assinados que expiram — renove voltando a chamar o endpoint de decisão. O payload bruto de origem não é intencionalmente exposto através da API.

Exemplos

Approved — verificação de status do CPF do 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": []
}

Approved — DNI biométrico da Argentina (RENAPER)

Para a Argentina, a validação utiliza a RENAPER com uma correspondência facial biométrica. A resposta inclui um face_match_score e campos de identidade adicionais devolvidos pelo registo.

{
  "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 — o registo não pôde ser executado

Quando nenhum serviço devolve um resultado utilizável — campos obrigatórios em falta ou mal formatados, ou quando o registo não está acessível — match_type permanece null, validation_type fica not_enabled, é emitido um aviso COULD_NOT_PERFORM_DATABASE_VALIDATION e a funcionalidade passa para In Review até que os dados sejam corrigidos. Não é aplicada qualquer cobrança aos serviços ignorados.

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

Preencha o campo em falta na página de detalhes da sessão na Consola — ao guardá-lo, a verificação é acionada novamente automaticamente e limpa o aviso em caso de sucesso.

Relacionado

Visão geral da Validação de base de dados — como a API funciona de ponta a ponta e registos suportados.
Métodos de correspondência — como os resultados 1×1 / 2×2 (validation_type: one_by_one / two_by_two) são derivados.
Códigos de resultado — taxonomia completa por resultado com códigos de detalhe específicos por país.
Países e serviços suportados — todos os registos em produção, campos obrigatórios e preço por chamada.
Avisos da Validação de base de dados — o que apresentamos quando um serviço não pode ser executado.
Modelos de dados — validação de base de dados — esquema canónico campo a campo.

Autenticação

Verificação

Monitorização

Plataforma

Relatório de validação de base de dados: resposta JSON

Visão geral

Onde aparece nas respostas da API

Esquema

Valores de status

Códigos de resultado

Uma entrada por serviço

URLs de imagem pré-assinados

Exemplos

Approved — verificação de status do CPF do Brasil (Receita Federal)

Approved — DNI biométrico da Argentina (RENAPER)

In Review — o registo não pôde ser executado

Relacionado

​Visão geral

​Onde aparece nas respostas da API

​Esquema

​Valores de status

​Códigos de resultado

​Uma entrada por serviço

​URLs de imagem pré-assinados

​Exemplos

​Approved — verificação de status do CPF do Brasil (Receita Federal)

​Approved — DNI biométrico da Argentina (RENAPER)

​In Review — o registo não pôde ser executado

​Relacionado

Visão geral

Onde aparece nas respostas da API

Esquema

Valores de status

Códigos de resultado

Uma entrada por serviço

URLs de imagem pré-assinados

Exemplos

Approved — verificação de status do CPF do Brasil (Receita Federal)

Approved — DNI biométrico da Argentina (RENAPER)

In Review — o registo não pôde ser executado

Relacionado