Relatório de verificação de ID: campos e pontuações

Visão geral

O relatório de verificação de identidade reúne tudo o que a Didit extraiu e validou de um documento de identidade emitido pelo governo: passaportes, carteiras de identidade, carteiras de motorista e autorizações de residência. Ele agrupa os campos biográficos e do documento obtidos por OCR, URLs assinadas para as mídias capturadas, dados de endereço interpretados e geolocalizados, pontuações de qualidade de imagem de cada lado do documento, o conteúdo da MRZ, detalhamentos por sistema de escrita (latino / não latino) e correspondências de documentos entre sessões. O relatório é gerado depois que o usuário conclui a etapa de captura do documento em um fluxo de verificação (workflow) ou chama o endpoint de OCR independente. A Didit identifica o tipo de documento, executa o OCR, valida a MRZ, o código de barras ou o QR code, interpreta o endereço, verifica sinais de adulteração (captura de tela, cópia impressa, manipulação do retrato) e compara o documento com todos os outros documentos capturados na sua aplicação. Cada relatório tem seu próprio status, independente do status geral da sessão, que reflete como a etapa de identidade foi resolvida isoladamente:

Aprovado: documento reconhecido, todos os campos obrigatórios extraídos e nenhum aviso direcionado à recusa foi disparado.
Em Revisão: um ou mais avisos foram disparados e o seu fluxo os direciona para revisão.
Recusado: uma condição de recusa automática foi disparada (documento não suportado, documento expirado, retrato ausente, ocorrência na lista de bloqueio, falha na verificação adaptativa de idade) ou foi disparado um aviso cuja ação configurada é Decline (as condições de idade mínima/máxima usam Decline por padrão).
Expirado: a expiration_date do documento venceu após a verificação. O monitoramento contínuo de validade da Didit muda o relatório de Approved para Expired, adiciona um aviso DOCUMENT_EXPIRED e move uma sessão aprovada para o status de sessão Kyc Expired.
Não concluído: o usuário nunca concluiu a etapa de captura.

Onde ele aparece nas respostas da API

O relatório de identidade é entregue dentro do array id_verifications[], que é sempre um array JSON e nunca um objeto id_verification singular. Aparecem várias entradas quando um fluxo executa mais de uma etapa de documento (por exemplo, um documento de identidade principal mais uma verificação adicional).

API de decisão da sessão: GET /v3/session/{sessionId}/decision/ retorna id_verifications[] no nível superior. Consulte Obter a decisão da sessão.
Webhooks: os payloads de session.status.updated incluem o mesmo array id_verifications[] assim que a etapa tiver gerado dados. Consulte Webhooks.
API de OCR independente: o envio direto de documentos retorna um objeto id_verification singular com os mesmos campos. Consulte API de OCR independente.

Leia response.id_verifications[0] e percorra o array. A estrutura individual de id_verification existe apenas na API de OCR independente e não existe no endpoint de decisão v3.

Esquema

O esquema canônico, campo a campo, está na página de referência Modelos de dados. Os campos abaixo vêm diretamente de IDVerificationV3Serializer, que estende IDVerificationV2Serializer e adiciona node_id, o array matches[] de correspondências entre sessões e o array document_selfie_face_matches[] do Silent Capture.

Campos de nível superior

Campo	Tipo	Descrição
`status`	`"Approved" \| "Declined" \| "In Review" \| "Expired" \| "Not Finished"`	Status da etapa de verificação de identidade.
`node_id`	string \| null	Nó do grafo do fluxo de verificação (workflow) que gerou este relatório.
`document_type`	`"Passport" \| "Identity Card" \| "Driver's License" \| "Residence Permit" \| "Health Insurance Card" \| "Tax Card" \| "Social Security Card" \| "Work Permit" \| "Visa" \| "Public Service Card" \| "Birth Certificate" \| "Firearm License" \| "Other" \| null`	Família de documento de nível superior reconhecida (em formato legível).
`document_subtype`	string \| null	Código do subtipo de documento no registro de documentos da Didit, filtrado pelo que as configurações de documento do fluxo aceitam. Documentos específicos de uma região incluem a região, por exemplo `QUEENSLAND_DRIVER_LICENSE_GENERIC`. Consulte Subtipos de documento para ver a lista completa de códigos, incluindo como diferenciar uma carteira de motorista comercial dos EUA (CDL) de uma comum.
`document_number`	string	Número do documento extraído por OCR. Para carteiras de motorista que trazem impressos tanto um número da licença quanto um número do cartão, consulte a nota abaixo da tabela.
`personal_number`	string	Número pessoal / de identificação nacional extraído por OCR, quando diferente do número do documento.
`portrait_image`, `front_image`, `front_video`, `back_image`, `back_video`, `full_front_image`, `full_back_image`	string (URL assinada)	Mídia capturada. As URLs são assinadas e têm tempo limitado: faça o download imediatamente e nunca armazene a URL.
`front_image_camera_front`, `back_image_camera_front`	string (URL assinada) \| null	Quadros capturados pela câmera frontal do usuário durante a captura do documento. Usados na verificação facial entre câmeras e comparados com a sua lista de bloqueio facial; cada um também pode ser adicionado à lista de bloqueio facial.
`front_image_camera_front_face_match_score`, `back_image_camera_front_face_match_score`	float (0–100) \| null	Pontuação de similaridade entre o quadro da câmera frontal e a foto do documento.
`document_selfie_face_matches`	array \| null	Sessões anteriores ou entradas da lista de bloqueio facial cujo rosto correspondeu à selfie tirada durante a captura do documento (Busca facial do Silent Capture). Cada entrada tem o mesmo formato de `liveness_checks[].matches`; `match_image_url` é uma URL pré-assinada que expira. `null` para sessões mais antigas ou quando a busca não foi executada, `[]` quando foi executada e não encontrou nada.
`front_image_quality_score`, `back_image_quality_score`	object \| null	Avaliação de qualidade por lado (consulte Pontuações de qualidade de imagem).
`document_liveness`	object \| null	Pontuações de prova de vida do documento por tipo de fraude, com os limiares usados na avaliação (consulte Pontuações de prova de vida do documento). Somente V3.
`date_of_birth`, `expiration_date`, `date_of_issue`	string (YYYY-MM-DD)	Datas do documento.
`age`	number	Idade do titular em anos, calculada a partir de `date_of_birth`.
`issuing_state`	string (ISO 3166-1 alpha-3)	Código do país emissor.
`issuing_state_name`	string	Nome do país localizado.
`first_name`, `last_name`, `full_name`	string	Nome do titular no sistema de escrita escolhido por `preferred_characters` (veja abaixo).
`gender`	`"M" \| "F" \| "U"`	Gênero, quando presente no documento (`U` = desconhecido).
`address`, `formatted_address`	string	Strings de endereço bruto e geocodificado/formatado.
`place_of_birth`	string	Local de nascimento extraído por OCR.
`marital_status`	`"SINGLE" \| "MARRIED" \| "DIVORCED" \| "WIDOWED" \| "UNKNOWN"`	Estado civil, quando presente no documento.
`nationality`	string (ISO 3166-1 alpha-3)	Nacionalidade do titular, quando diferente do país emissor.
`extra_fields`	object	Dados extras específicos do documento (categorias da carteira de motorista, tipo sanguíneo, nomes em sistema de escrita alternativo, `tax_number`, …).
`mrz`	object \| null	Campos chave/valor da MRZ já interpretados.
`parsed_address`	object \| null	Endereço estruturado e geocodificado (`street_1`, `street_2`, `city`, `region`, `country`, `postal_code`, `address_type`, `formatted_address`, `document_location`, `raw_results`, `is_best_match`).
`extra_files[]`	array de URLs assinadas	Imagens adicionais anexadas a este documento.
`matches[]`	array	Correspondências de documento entre sessões (consulte Correspondências entre sessões).
`warnings[]`	array	Avisos do módulo — consulte Avisos da verificação de identidade.

issuing_state é sempre de nível nacional, nunca subnacional. Para todo tipo de documento, incluindo carteiras de motorista emitidas por um estado ou província (Austrália, Estados Unidos, Canadá), issuing_state e issuing_state_name informam o país (por exemplo AUS / Australia), e não o estado. O valor subnacional, quando o documento o contém, fica disponível separadamente em parsed_address.region (com extra_fields.state como alternativa em alguns tipos de documento). A visão geral da sessão no Business Console exibe esse valor como uma linha Region abaixo de Issuing state, quando presente.

Carteiras de motorista com dois números (Austrália). As carteiras australianas trazem impressos tanto um número da licença, que identifica a habilitação do titular para dirigir e permanece o mesmo quando o cartão é substituído, quanto um número do cartão, que identifica o cartão físico e muda a cada nova emissão. Para essas carteiras, a Didit sempre mapeia os números da mesma forma:

personal_number — o número da licença
document_number — o número do cartão

Isso se aplica a todos os estados e territórios australianos (NSW, VIC, QLD, WA, SA, TAS, ACT, NT). Em algumas variantes, o número do cartão está impresso apenas no verso, então ele só é lido quando o verso da carteira é capturado. Quando nenhum número do cartão pode ser lido, o número da licença é informado tanto em document_number quanto em personal_number, de modo que document_number sempre contém um identificador quando a verificação é concluída. personal_number é o número da licença em ambos os casos. Em outros tipos de documento, document_number continua sendo o número principal extraído por OCR e pode ser, ele próprio, um identificador do titular.

O CUIL argentino é extra_fields.tax_number, nunca personal_number. Os documentos argentinos imprimem o CUIL (o identificador de 11 dígitos usado como chave pela AFIP, pela ANSES e pelos birôs de crédito) em um lugar diferente em cada documento, e o DNI imprime um segundo número de 11 dígitos ao lado dele:

na carteira de motorista, o CUIL é o que personal_number contém;
no DNI, personal_number contém o número de trámite, que identifica a solicitação do cartão e não é um identificador do titular. O CUIL do DNI é lido no próprio campo impresso.

Portanto, personal_number não é um CUIL confiável para a Argentina: em um DNI, ele é um número de 11 dígitos que, silenciosamente, não retornará nenhum resultado em nenhum registro. Leia extra_fields.tax_number em vez disso. A Didit só o informa quando o valor é validado como um CUIL real (prefixo de pessoa mais o dígito verificador módulo 11), em dígitos canônicos sem separadores (27111111117), qualquer que seja o documento argentino apresentado pelo titular. Quando o CUIL do cartão não pôde ser lido, a chave fica ausente em vez de ser preenchida com um número que não é um CUIL. Para atender esses usuários, capture a carteira de motorista como segundo documento ou colete o CUIL por meio de uma resposta de Questionário ou do metadata da sessão.

Pontuações de qualidade da imagem

front_image_quality_score e back_image_quality_score retornam, cada um:

Campo	Tipo	O que mede
`focus_score`	número 0–100	Nitidez: variância laplaciana local dos 10% superiores, robusta a fundos uniformes. Peso de 45%.
`brightness_score`	número 0–100	Penaliza imagens escuras demais ou superexpostas. Peso de 30%.
`brightness_issue`	`"ok" \| "too_dark" \| "too_bright"`	Direção do problema de brilho, quando `brightness_score` é baixo.
`resolution_score`	número 0–100	Baseado na contagem total de pixels da captura. Peso de 25%.
`is_document_fully_visible`	boolean \| null	`true` quando os quatro cantos do documento estão visíveis, `false` quando algum canto está cortado, `null` quando a detecção de cantos não estava disponível.
`overall_score`	número 0–100	Composto ponderado (foco 45%, brilho 30%, resolução 25%).

Use overall_score como uma verificação rápida de adequação: pontuações acima de 70 geralmente indicam uma captura boa o suficiente para uma verificação confiável.

Pontuações de prova de vida do documento

document_liveness informa o que a verificação de prova de vida do documento mediu, tenha ela gerado um aviso ou não. Um aviso só existe quando uma pontuação ficou abaixo de um dos limiares do fluxo; por isso, antes deste campo, um documento aprovado não trazia nenhuma evidência de prova de vida. É com este campo que você audita uma sessão aprovada. Ele é null quando a verificação não foi executada (por exemplo, em um método que não é de documento ou em uma indisponibilidade do modelo registrada nos logs da sessão). Ele contém um objeto por tipo de fraude (portrait_replace, printed_copy e screen_replay), cada um com:

Campo	Tipo	Significado
`score`	número 0–100 \| null	Probabilidade de o documento ser genuíno para este tipo de fraude (quanto maior, mais provável que seja genuíno). É a menor pontuação entre os dois lados, que é o valor usado na decisão. `null` quando nenhum dos lados produziu uma pontuação utilizável; por exemplo, a pontuação do retrato é descartada em um lado onde nenhum retrato foi encontrado.
`front`, `back`	número 0–100 \| null	A mesma pontuação para cada lado capturado. `null` para um lado que não foi capturado ou cuja pontuação foi descartada.
`decline_threshold`, `review_threshold`	número \| null	Limiares salvos quando o nó de Verificação de identidade avaliou este documento. Edições posteriores no fluxo não os alteram. `null` quando a evidência histórica da avaliação não está disponível.
`bucket`	`"approve" \| "review" \| "decline" \| null`	Onde `score` se situa em relação a esses limiares: abaixo de `decline_threshold` → `decline`, abaixo de `review_threshold` → `review`, caso contrário `approve`. `null` quando não há pontuação utilizável, a verificação não foi aplicada ou a evidência histórica da avaliação não está disponível. O bucket descreve a verificação deste tipo de fraude, não o status geral da sessão.

"document_liveness": {
  "portrait_replace": {
    "score": 96.46,
    "front": 96.46,
    "back": 98.2,
    "decline_threshold": 35,
    "review_threshold": 70,
    "bucket": "approve"
  },
  "printed_copy": {
    "score": 91.2,
    "front": 91.2,
    "back": 93.7,
    "decline_threshold": 35,
    "review_threshold": 77,
    "bucket": "approve"
  },
  "screen_replay": {
    "score": 99.9,
    "front": 99.9,
    "back": 99.5,
    "decline_threshold": 30,
    "review_threshold": 70,
    "bucket": "approve"
  }
}

Para documentos mais antigos sem evidência de avaliação salva, as pontuações armazenadas continuam visíveis, mas ambos os limiares e bucket são null. As configurações atuais do fluxo nunca são usadas para reconstruir um resultado histórico. O mesmo se aplica a uma captura cuja avaliação do documento ainda não foi concluída. O Business Console mostra as mesmas três linhas no bloco Document liveness da seção de Verificação de identidade da sessão.

Correspondências entre sessões

matches[] lista até 5 outros documentos na sua aplicação que correspondem a este: mesma data de nascimento, mesmo país emissor e um nome completo muito semelhante. Documentos na lista de bloqueio exigem, além disso, uma correspondência exata do número do documento. Sessões que pertencem ao mesmo usuário (mesmo vendor_data) são excluídas. Cada entrada inclui session_id, session_number, vendor_data, verification_date, user_details (name, document_type, document_number), status, is_blocklisted (true quando o documento foi adicionado à sua lista de bloqueio), api_service e uma front_image_url assinada.

Valores de status

Status	Significado	Efeito posterior
`Approved`	Documento reconhecido, campos obrigatórios extraídos e todas as verificações aprovadas nos limiares configurados.	Conta como uma verificação de identidade bem-sucedida.
`In Review`	Um ou mais avisos foram disparados e o fluxo os encaminha para revisão.	A sessão também passa para `In Review` até que um revisor tome uma ação.
`Declined`	Uma condição de recusa automática foi disparada (documento não suportado, documento expirado, retrato ausente, correspondência na lista de bloqueio, falha na verificação de idade adaptativa) ou foi disparado um aviso configurado para Recusar.	A sessão é recusada, a menos que outra ramificação aprovada satisfaça o fluxo.
`Expired`	A data de validade do documento passou depois da aprovação. Definido pelo monitoramento contínuo de documentos da Didit, que é ativado por padrão (um país e tipo de documento cujo Expiration mode seja Allow expired fica isento), junto com um aviso `DOCUMENT_EXPIRED`.	Uma sessão aprovada passa para `Kyc Expired`.
`Not Finished`	O usuário abandonou a etapa de captura.	A ramificação de verificação de identidade não produziu resultado.

Documentos com múltiplos sistemas de escrita (latino / não latino)

Alguns documentos, como os do Quirguistão, Cazaquistão, Rússia, Japão, Coreia, China, países árabes, Tailândia e outros, imprimem o nome, o endereço ou o local de nascimento do titular tanto em uma transliteração latina quanto no sistema de escrita local. Você escolhe qual sistema de escrita preenche os campos de nível superior com a configuração preferred_characters do fluxo (ou da API independente):

Valor	Preenche os campos de nível superior com	O outro alfabeto vai para
`latin` (padrão)	A transliteração latina impressa no documento	`extra_fields.*_non_latin`
`non_latin`	Os valores no sistema de escrita local impressos no documento	`extra_fields.*_latin`

Os valores no sistema de escrita alternativo ficam dentro de extra_fields, em chaves com sufixo: first_name_non_latin, last_name_non_latin, middle_name_non_latin, full_name_non_latin, address_non_latin, place_of_birth_non_latin (ou as variantes _latin correspondentes).

Quando os campos de sistema de escrita alternativo aparecem

Somente quando os dois sistemas de escrita estão realmente presentes no documento. Se um campo de OCR nominalmente rotulado como “Surname-Kyrgyz (Cyrillic)” for extraído como texto em escrita latina (homóglifos ou uma transliteração latina), ele não se qualifica como alternativa não latina e essa chave é omitida.
full_name_non_latin (e full_name_latin) são sempre reconstruídos a partir dos componentes individuais de nome, nome do meio e sobrenome quando ambos os sistemas de escrita estão disponíveis. O campo bruto “Full Name” do OCR é ignorado por questão de consistência.
Quando preferred_characters=latin, mas o documento contém apenas texto não latino (de modo que os campos de nível superior acabam ficando em sistema de escrita não latino), a Didit executa uma etapa de transliteração e expõe first_name_latin, last_name_latin, middle_name_latin, full_name_latin, place_of_birth_latin e address_latin como alternativa em escrita latina.

{
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "extra_fields": {
    "first_name_non_latin": "Айна"
  }
}

last_name_non_latin está ausente porque, nesta amostra, o campo “Surname (Cyrillic)” do documento retornou em caracteres latinos: não havia um sobrenome genuinamente não latino para extrair.

Exemplos

Approved: documento de identidade espanhol sem problemas (todos os campos)

{
  "id_verifications": [
    {
      "status": "Approved",
      "document_type": "Identity Card",
      "document_subtype": "ID_CARD_GENERIC",
      "document_number": "SAMPLE-DOC-12345",
      "personal_number": "SAMPLE-PER-12345",
      "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
      "front_image": "https://<media-host>/.../front.jpg?signature=...",
      "front_video": "https://<media-host>/.../front.mp4?signature=...",
      "back_image": "https://<media-host>/.../back.jpg?signature=...",
      "back_video": "https://<media-host>/.../back.mp4?signature=...",
      "full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
      "full_back_image": "https://<media-host>/.../full_back.jpg?signature=...",
      "front_image_camera_front": null,
      "back_image_camera_front": null,
      "front_image_camera_front_face_match_score": null,
      "back_image_camera_front_face_match_score": null,
      "front_image_quality_score": {
        "focus_score": 85.3,
        "brightness_score": 92.1,
        "brightness_issue": "ok",
        "is_document_fully_visible": true,
        "resolution_score": 72.4,
        "overall_score": 84.6
      },
      "back_image_quality_score": {
        "focus_score": 79.1,
        "brightness_score": 90.5,
        "brightness_issue": "ok",
        "is_document_fully_visible": true,
        "resolution_score": 72.4,
        "overall_score": 81.5
      },
      "date_of_birth": "1990-01-01",
      "age": 35,
      "expiration_date": "2031-06-02",
      "date_of_issue": "2021-06-02",
      "issuing_state": "ESP",
      "issuing_state_name": "Spain",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "gender": "M",
      "address": "Avda de Madrid 34",
      "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
      "place_of_birth": "Madrid",
      "marital_status": "SINGLE",
      "nationality": "ESP",
      "extra_fields": {},
      "mrz": {
        "document_number": "SAMPLE-DOC-12345",
        "surname": "DOE",
        "name": "JOHN",
        "birth_date": "900101",
        "expiry_date": "310602"
      },
      "parsed_address": {
        "street_1": "Avda de Madrid 34",
        "street_2": null,
        "city": "Madrid",
        "region": "Madrid",
        "country": "ES",
        "postal_code": "28822",
        "address_type": "Avda",
        "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
        "document_location": { "latitude": 40.4168, "longitude": -3.7038 },
        "raw_results": {
          "geometry": {
            "location": { "lat": 40.4168, "lng": -3.7038 },
            "location_type": "ROOFTOP"
          }
        },
        "is_best_match": true
      },
      "extra_files": [],
      "warnings": [],
      "node_id": "id_primary",
      "matches": []
    }
  ]
}

In Review: QR não detectado em um documento que deveria ter um

Resumido: uma resposta real sempre traz o conjunto completo de campos mostrado acima.

{
  "id_verifications": [
    {
      "status": "In Review",
      "node_id": "id_primary",
      "document_type": "Identity Card",
      "document_subtype": "ID_CARD_GENERIC",
      "document_number": "SAMPLE-DOC-12345",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "warnings": [
        {
          "feature": "ID_VERIFICATION",
          "risk": "QR_NOT_DETECTED",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "QR not detected",
          "long_description": "The system couldn't find or read the QR code on the document. This could be due to poor image quality or an unsupported document type.",
          "node_id": "id_primary"
        }
      ]
    }
  ]
}

Nota de segurança

As URLs assinadas retornadas para imagens e vídeos de documentos são temporárias: elas expiram após um período de validade limitado. Trate-as como de curta duração: baixe o que precisar imediatamente e não as armazene em cache nem as exponha publicamente. Normalmente, sua aplicação só precisa de status, de alguns campos biográficos e dos avisos. Armazene o mínimo possível para reduzir a superfície de exposição em caso de futura violação.

Relacionados

Avisos da verificação de identidade: lista completa de avisos, causas e correções.
Monitoramento de documentos: como a Didit detecta adulterações e duplicatas entre sessões.
Documentos suportados: quais tipos de documento e países são cobertos.
Subtipos de documento: lista completa de códigos document_subtype, incluindo a distinção entre carteiras de motorista comerciais e padrão dos EUA.
Webhooks: monitore session.status.updated para receber o relatório.
Modelos de dados: verificação de identidade: esquema canônico com todos os campos.

Autenticação

Verificação

Monitoramento

Plataforma

Relatório de verificação de ID: campos e pontuações

Visão geral

Onde ele aparece nas respostas da API

Esquema

Campos de nível superior

Pontuações de qualidade da imagem

Pontuações de prova de vida do documento

Correspondências entre sessões

Valores de status

Documentos com múltiplos sistemas de escrita (latino / não latino)

Quando os campos de sistema de escrita alternativo aparecem

Exemplos

Approved: documento de identidade espanhol sem problemas (todos os campos)

In Review: QR não detectado em um documento que deveria ter um

Nota de segurança

Relacionados

​Visão geral

​Onde ele aparece nas respostas da API

​Esquema

​Campos de nível superior

​Pontuações de qualidade da imagem

​Pontuações de prova de vida do documento

​Correspondências entre sessões

​Valores de status

​Documentos com múltiplos sistemas de escrita (latino / não latino)

​Quando os campos de sistema de escrita alternativo aparecem

​Exemplos

​Approved: documento de identidade espanhol sem problemas (todos os campos)

​In Review: QR não detectado em um documento que deveria ter um

​Nota de segurança

​Relacionados

Visão geral

Onde ele aparece nas respostas da API

Esquema

Campos de nível superior

Pontuações de qualidade da imagem

Pontuações de prova de vida do documento

Correspondências entre sessões

Valores de status

Documentos com múltiplos sistemas de escrita (latino / não latino)

Quando os campos de sistema de escrita alternativo aparecem

Exemplos

Approved: documento de identidade espanhol sem problemas (todos os campos)

In Review: QR não detectado em um documento que deveria ter um

Nota de segurança

Relacionados