Modelos de dados - Didit Docs

Visão geral

Cada relatório por funcionalidade segue a forma do serializador V3 definida em service-didit-verification. O mesmo objeto aparece em três sítios, pelo que o esquema que vê aqui é a fonte única de verdade para todos eles:

GET /v3/session/{sessionId}/decision/: cada funcionalidade é devolvida como um array no plural (id_verifications[], nfc_verifications[], liveness_checks[], face_matches[], poa_verifications[], phone_verifications[], email_verifications[], aml_screenings[], ip_analyses[], database_validations[], questionnaire_responses[], signatures[], bank_verifications[] (ver Métodos de verificação bancária), e os equivalentes KYB registry_checks[], document_verifications[], key_people_checks[]).
Payloads de webhook (status.updated, data.updated): a mesma forma dentro do envelope decision.
APIs autónomas: as respostas de objeto único (Pesquisa facial, Estimativa de idade, Autenticação biométrica) reutilizam o mesmo conjunto de campos.

A V3 introduziu fluxos multi-instância: cada objeto de funcionalidade contém um node_id que associa o relatório ao nó do grafo do fluxo que o produziu. Os endpoints V2 (no singular kyc, face, aml, etc.) continuam compatíveis com versões anteriores, mas devolvem apenas a primeira instância.

Campos comuns

Cada objeto de relatório expõe o seguinte:

Campo	Tipo	Descrição
`status`	string	Estado do ciclo de vida ao nível da funcionalidade, um dos valores da enumeração de estados. Origem: `common/config/choices.py:FeatureStatusChoices` (linhas 343-348). O `status` de nível superior da sessão principal usa a enumeração mais abrangente da sessão (`StatusChoices`, linhas 106-117).
`node_id`	string \| null	Identificador do nó do grafo do fluxo. Preenchido em fluxos multi-instância V3; `null` em sessões antigas de uma única funcionalidade.
`warnings`	array de objetos de aviso	Sinais de risco filtrados para esta funcionalidade e `node_id`. Devolvidos por `Session.get_logs(...)` (`sessions/models/session.py:1611`).

Os campos de conteúdo multimédia (portrait_image, front_image, document_file, …) são URLs pré-assinados com um período de validade limitado. Transfira-os rapidamente em vez de guardar o URL. Os exemplos mostram-nos como https://<media-host>/....

Objeto de aviso

Devolvido em cada array warnings[]. Esquema de logs/serializers/log.py:8-65 (LogV3Serializer).

Campo	Tipo	Anulável	Descrição	Exemplo
`feature`	string (enumeração)	Não	Funcionalidade que emitiu o aviso. Valores de `LogWarningChoices` (`common/config/choices.py:190-204`): `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACEMATCH`, `PROOF_OF_ADDRESS`, `PHONE`, `EMAIL`, `AML`, `LOCATION`, `DATABASE_VALIDATION`, `QUESTIONNAIRE`, `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`.	`"ID_VERIFICATION"`
`risk`	string	Não	Código de risco estável (por exemplo, `DOCUMENT_EXPIRED`, `LOW_LIVENESS_SCORE`). Valores de `logs/choices.py:RiskChoices`. Usado como chave nas tabelas de descrições.	`"DOCUMENT_EXPIRED"`
`additional_data`	objeto \| null	Sim	Contexto específico do risco (por exemplo, limiares de pontuação, campos correspondentes). A estrutura varia consoante o código de risco.	`{ "score": 42.1, "threshold": 70 }`
`log_type`	string (enumeração)	Não	Um de `error`, `warning`, `information`. De `LogTypeChoices` (`common/config/choices.py:207-210`).	`"error"`
`short_description`	string	Não	Rótulo legível do risco. De `logs/choices.py:RISK_SHORT_DESCRIPTIONS`.	`"Document expired"`
`long_description`	string	Não	Explicação mais longa e legível, adequada a interfaces voltadas para o utilizador final. De `logs/choices.py:RISK_LONG_DESCRIPTIONS`.	`"The document's expiration date has passed, rendering it no longer valid for use."`
`node_id`	string \| null	Sim	Nó do grafo do fluxo ao qual o aviso foi associado. `null` para registos V2 antigos sem `node_id`.	`"first_id_verification"`

{
  "feature": "ID_VERIFICATION",
  "risk": "DOCUMENT_EXPIRED",
  "additional_data": null,
  "log_type": "error",
  "short_description": "Document expired",
  "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
  "node_id": "first_id_verification"
}

Objetos de relatório

As restantes secções abrangem cada objeto de relatório por funcionalidade. O texto dos títulos H3 é intencionalmente estável, para que outros documentos possam criar ligações diretas para eles.

Verificação de identidade

É devolvido para cada documento de KYC/identidade submetido pelo utilizador. Aparece como id_verifications[] em GET /v3/session/{sessionId}/decision/ e dentro do campo kyc das respostas V2. Origem: kyc/serializers/kyc.py:383-414 (IDVerificationV3Serializer, que estende IDVerificationV2Serializer em kyc/serializers/kyc.py:320-380).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enumeração de estados.	`"Approved"`
`document_type`	string	Sim	Classe do documento legível por humanos (`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`). Origem: `DOC_TYPE_MAPPING` (`common/config/choices.py:1275-1289`).	`"Passport"`
`document_subtype`	string	Sim	Código do subtipo de documento do registo de documentos da Didit, filtrado pelo que as definições de documentos do fluxo aceitam. Os documentos específicos de uma região incluem a região. Lista completa de códigos: Subtipos de documento.	`"QUEENSLAND_DRIVER_LICENSE_GENERIC"`
`document_number`	string	Sim	Número do documento extraído por OCR.	`"AB1234567"`
`personal_number`	string	Sim	Identificador pessoal ou nacional extraído por OCR.	`"99999999R"`
`portrait_image`	string (URL)	Sim	URL pré-assinado para o recorte facial.	`"https://<media-host>/.../portrait.jpg?..."`
`front_image`	string (URL)	Sim	URL pré-assinado para a frente do documento já tratada.	`"https://<media-host>/.../front.jpg?..."`
`front_video`	string (URL)	Sim	URL pré-assinado para o vídeo de captura da frente (quando disponível).	`"https://<media-host>/.../front.mp4?..."`
`back_image`	string (URL)	Sim	URL pré-assinado para o verso do documento já tratado.	`"https://<media-host>/.../back.jpg?..."`
`back_video`	string (URL)	Sim	URL pré-assinado para o vídeo de captura do verso.	`null`
`full_front_image`	string (URL)	Sim	Captura da frente sem recorte (imagem completa).	`"https://<media-host>/.../full_front.jpg?..."`
`full_back_image`	string (URL)	Sim	Captura do verso sem recorte (imagem completa).	`null`
`front_image_camera_front`	string (URL)	Sim	Imagem da câmara frontal tirada ao mesmo tempo que a frente do documento.	`null`
`back_image_camera_front`	string (URL)	Sim	Imagem da câmara frontal tirada ao mesmo tempo que o verso do documento.	`null`
`front_image_camera_front_face_match_score`	float (0-100)	Sim	Semelhança entre o retrato do documento e a captura da câmara frontal.	`null`
`back_image_camera_front_face_match_score`	float (0-100)	Sim	Igual ao anterior, mas para a captura do verso.	`null`
`document_selfie_face_matches`	array	Sim	Sessões anteriores ou entradas da lista de bloqueio facial que correspondem à selfie tirada durante a captura do documento. Mesmo formato de entrada que `liveness_checks[].matches`. `null` quando a pesquisa não foi executada, `[]` quando não houve correspondências.	`null`
`front_image_quality_score`	object	Sim	Métricas de qualidade da imagem da frente: pontuações de 0 a 100 (`focus_score`, `brightness_score`, `resolution_score`, `overall_score`), além de `brightness_issue` (`ok`, `too_dark`, `too_bright`) e `is_document_fully_visible` (booleano).	`{ "focus_score": 91.0, "overall_score": 88.5 }`
`back_image_quality_score`	object	Sim	Mesma estrutura de `front_image_quality_score`.	`null`
`date_of_birth`	string (YYYY-MM-DD)	Sim	Data de nascimento extraída por OCR.	`"1990-05-12"`
`age`	integer	Sim	Idade calculada em anos no momento da extração.	`35`
`expiration_date`	string (YYYY-MM-DD)	Sim	Data de validade do documento.	`"2032-05-11"`
`date_of_issue`	string (YYYY-MM-DD)	Sim	Data de emissão do documento.	`"2022-05-11"`
`issuing_state`	string (ISO 3166-1 alpha-3)	Sim	Código do país emissor.	`"ESP"`
`issuing_state_name`	string	Sim	Nome do país emissor localizado.	`"Spain"`
`first_name`	string	Sim	Nome(s) próprio(s) extraído(s) por OCR.	`"María"`
`last_name`	string	Sim	Apelido(s) extraído(s) por OCR.	`"García López"`
`full_name`	string	Sim	Nome completo normalizado (fornecido pelo fornecedor).	`"María García López"`
`gender`	string	Sim	`M`, `F` ou outro valor fornecido pelo fornecedor.	`"F"`
`address`	string	Sim	Linha de morada extraída por OCR, sem tratamento.	`"Calle Mayor 1, 28001 Madrid"`
`formatted_address`	string	Sim	Morada geocodificada e formatada (quando é possível analisá-la).	`"Calle Mayor 1, 28001 Madrid, Spain"`
`parsed_address`	object	Sim	Morada estruturada e geocodificada: `street_1`, `street_2`, `city`, `region`, `country`, `postal_code`, `address_type`, `formatted_address`, `document_location` (`{latitude, longitude}`), `raw_results`, `is_best_match`. Origem: `kyc/utils/address.py:147-197`.	`{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }`
`place_of_birth`	string	Sim	Local de nascimento extraído por OCR.	`"Madrid"`
`marital_status`	string	Sim	Quando é possível extraí-lo.	`null`
`nationality`	string (ISO 3166-1 alpha-3)	Sim	Nacionalidade extraída por OCR.	`"ESP"`
`extra_fields`	object	Sim	Campos específicos do tipo de documento que não estão cobertos pelo esquema canónico (por exemplo, categorias da carta de condução).	`{ "DL Class": "B" }`
`mrz`	object	Sim	Campos MRZ analisados, quando presentes (`document_number`, `birth_date`, `expiry_date`, `surname`, `given_names`, …).	`{ "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" }`
`extra_files`	array de cadeias de caracteres (URL)	Não	URLs pré-assinados de quaisquer outros ficheiros carregados.	`[]`
`matches`	array de objetos	Não	Correspondências de documentos entre sessões. Cada item: `{ session_id, session_number, vendor_data, verification_date, user_details: { name, document_type, document_number }, status, is_blocklisted, api_service, front_image_url }`. `front_image_url` é pré-assinado.	`[]`
`verification_method`	string	Não	Qual o método de verificação de identidade que produziu esta linha: `document`, `id_lookup` ou `wallet`. É sempre `document` para um documento fotografado, incluindo todas as sessões criadas antes de existirem os outros métodos.	`"id_lookup"`
`assurance`	string	Não	Nível de garantia derivado de `verification_method`: `documentary`, `data_match` ou `cryptographic`.	`"data_match"`
`wallet_provider`	string \| null	Sim	ID da carteira no catálogo quando uma carteira produziu esta linha (`mitid`, `bankid_se`, `itsme`, …). `null` nos restantes casos.	`"mitid"`
`fallback_from`	object \| null	Sim	Motivo pelo qual um método não documental encerrou o passo de ID: `{ method, reason, action }`. Definido quando uma consulta ou um início de sessão com carteira falhou: na linha recusada, quando a definição do país estava em `decline` (`action: "decline"`), e na verificação de documentos com que o utilizador continua, quando estava em `fallback_to_document` (`action: "fallback_to_document"`). `null` quando não está registada nenhuma falha anterior de um método não documental.	`{ "method": "id_lookup", "reason": "no_match", "action": "decline" }`
`id_lookup`	object \| null	Sim	Evidência da fonte, presente apenas quando `verification_method` é `id_lookup`: `source` (a fonte exata consultada: na maioria dos países, um registo governamental; em alguns, um ficheiro de bureau de crédito ou de registos residenciais), `checked_at`, `attempts`, `max_attempts`, `outcome` (`match`, `partial_match`, `no_match`, `provider_error`, `format_rejected`), `comparison[]` (`{ field, label, provided, record, result }`; `field` é um de `identification_number`, `full_name`, `date_of_birth`, `address`, e `result` é `match`, `partial` ou `no_match`; as versões anteriores podem incluir uma linha `provider` com `error`), `source_errors[]` (atualmente em staging: diagnósticos de fonte separados; confirme a disponibilização em produção), `registry_portrait` (URL pré-assinado, apenas para fontes que devolvem um) e `face_match_score`.	ver abaixo
`wallet_verification`	object \| null	Sim	Evidência da credencial, presente apenas quando `verification_method` é `wallet`: `provider`, `provider_name`, `issuing_authority`, `issuing_country`, `credential_type`, `level_of_assurance` (`low`, `substantial`, `high`), `verified_at`, `signature_valid`, `attributes` (o que a carteira partilhou), `portrait` (URL pré-assinado quando a carteira partilha um) e `face_match_score`.	ver abaixo
`document_liveness`	object \| null	Sim	Pontuações de prova de vida do documento por tipo de fraude (`portrait_replace`, `printed_copy`, `screen_replay`), devolvidas quer um aviso tenha sido acionado quer não. Cada uma: `score` (0-100; quanto mais alto, maior a probabilidade de ser genuíno; o valor mais baixo, que é o valor usado na decisão), `front`, `back`, `decline_threshold`, `review_threshold`, `bucket` (`approve`, `review`, `decline`, ou `null`). Os limiares e o escalão são guardados no momento da avaliação; os três ficam a `null` quando a evidência de avaliação histórica não está disponível, mas as pontuações guardadas continuam visíveis. `null` quando a verificação não foi executada. Ver Pontuações de prova de vida do documento. Apenas V3.	`{ "portrait_replace": { "score": 96.46, "bucket": "approve" } }`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_id_verification"`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`
`region`	string	Sim	Região ou estado do país emissor, quando o documento a identifica.	`"CA"`
`extracted_data`	object	Sim	Instantâneo dos dados extraídos do documento que foi mostrado à pessoa para revisão, guardado junto dos valores confirmados para que possa compará-los. `null` quando não foi pedido à pessoa que fizesse a revisão.
`barcodes`	array de objetos	Não	Dados lidos dos códigos de barras do documento, uma entrada por código de barras com `type`, `position`, `data`, `data_raw` e `side`. `[]` quando não existem.	`[]`

{
  "status": "Approved",
  "document_type": "Passport",
  "document_subtype": "PASSPORT_GENERIC",
  "document_number": "AB1234567",
  "personal_number": "99999999R",
  "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
  "front_image": "https://<media-host>/.../front.jpg?signature=...",
  "front_video": null,
  "back_image": "https://<media-host>/.../back.jpg?signature=...",
  "back_video": null,
  "full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
  "full_back_image": null,
  "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": 91.0,
    "brightness_score": 88.0,
    "brightness_issue": "ok",
    "is_document_fully_visible": true,
    "resolution_score": 95.0,
    "overall_score": 88.5
  },
  "back_image_quality_score": null,
  "date_of_birth": "1990-05-12",
  "age": 35,
  "expiration_date": "2032-05-11",
  "date_of_issue": "2022-05-11",
  "issuing_state": "ESP",
  "issuing_state_name": "Spain",
  "first_name": "María",
  "last_name": "García López",
  "full_name": "María García López",
  "gender": "F",
  "address": "Calle Mayor 1, 28001 Madrid",
  "formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "parsed_address": { "street_1": "Calle Mayor 1", "street_2": null, "city": "Madrid", "region": "Madrid", "postal_code": "28001", "country": "ES", "address_type": "Calle" },
  "place_of_birth": "Madrid",
  "marital_status": null,
  "nationality": "ESP",
  "extra_fields": {},
  "mrz": {
    "document_number": "AB1234567",
    "surname": "GARCIA",
    "given_names": "MARIA",
    "birth_date": "900512",
    "expiry_date": "320511"
  },
  "extra_files": [],
  "matches": [],
  "node_id": "first_id_verification",
  "verification_method": "document",
  "assurance": "documentary",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": null,
  "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"
    }
  },
  "warnings": []
}

O mesmo objeto com um método não documental. Mudam apenas os campos específicos do método: tudo o que uma leitura do documento preenche é, em vez disso, preenchido a partir do registo oficial ou dos atributos da carteira, e os campos que não se aplicam ficam a null.

{
  "status": "Approved",
  "issuing_state": "ZAF",
  "first_name": "Thabo",
  "last_name": "Mokoena",
  "full_name": "Thabo Mokoena",
  "date_of_birth": "1991-06-15",
  "personal_number": "9106155043088",
  "node_id": "first_id_verification",
  "verification_method": "id_lookup",
  "assurance": "data_match",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": {
    "source": "Department of Home Affairs",
    "checked_at": "2026-09-04T09:12:44Z",
    "attempts": 1,
    "max_attempts": 2,
    "outcome": "match",
    "comparison": [
      { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" },
      { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" },
      { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" }
    ],
    "registry_portrait": "https://<media-host>/.../registry_portrait.jpg?signature=...",
    "face_match_score": 96.4
  },
  "wallet_verification": null,
  "warnings": []
}

{
  "status": "Approved",
  "issuing_state": "DNK",
  "first_name": "Freja",
  "last_name": "Nielsen",
  "full_name": "Freja Nielsen",
  "date_of_birth": "1988-03-02",
  "node_id": "first_id_verification",
  "verification_method": "wallet",
  "assurance": "cryptographic",
  "wallet_provider": "mitid",
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": {
    "provider": "mitid",
    "provider_name": "MitID",
    "issuing_authority": "Danish Agency for Digital Government",
    "issuing_country": "DNK",
    "credential_type": "person_identification",
    "level_of_assurance": "substantial",
    "verified_at": "2026-09-04T09:12:44Z",
    "signature_valid": true,
    "attributes": {
      "full_name": "Freja Nielsen",
      "date_of_birth": "1988-03-02",
      "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678"
    },
    "portrait": null,
    "face_match_score": null
  },
  "warnings": []
}

Verificação NFC

Devolvido para cada leitura de chip realizada com um documento de identidade: um chip de passaporte eletrónico ICAO 9303 ou de eID, ou um cartão My Number do Japão lido através do JPKI (chip_protocol: "jpki"). Aparece como nfc_verifications[] em GET /v3/session/{sessionId}/decision/ (um por registo KYC principal). Fonte: kyc/serializers/epassport.py:121-139 (NFCV3Serializer, estende NFCV2Serializer em kyc/serializers/epassport.py:83-118).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enumeração de estados.	`"Approved"`
`portrait_image`	string (URL)	Sim	URL pré-assinado da imagem facial extraída do chip.	`"https://<media-host>/.../nfc_portrait.jpg?..."`
`signature_image`	string (URL)	Sim	URL pré-assinado da imagem da assinatura extraída do chip (quando guardada no chip).	`null`
`chip_data`	object	Sim	Dados pessoais analisados a partir dos grupos de dados do chip, numa estrutura plana (`kyc/utils/epassport.py:165-212`): `dgs` (grupos de dados lidos), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (código de documento da MRZ), `document_number`, `optional_data`, dígitos de verificação da MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, `mrz_type` (`TD1`/`TD2`/`TD3`); além de `place_of_birth` e `address` (e `full_name` / `full_name_non_latin` para nomes não latinos) quando o chip contém o DG11. Caso contrário, estas chaves estão ausentes. `null` quando o passo NFC foi ignorado.	`{ "document_number": "AB1234567", "name": "MARIA" }`
`authenticity`	object	Sim	`{ sod_integrity, dg_integrity }`; `null` numa leitura JPKI. `sod_integrity` valida que a assinatura do Document Security Object (SOD) tem cadeia de confiança até uma CSCA válida do país emissor (e que a DSC não está revogada nem expirada); `dg_integrity` valida que o hash de cada grupo de dados corresponde ao SOD. Ambos `true` indicam que o chip é genuíno e não foi adulterado.	`{ "sod_integrity": true, "dg_integrity": true }`
`certificate_summary`	object	Sim	Resumo do certificado do signatário do documento (`kyc/utils/epassport.py:338-348`): `issuer`, `subject`, `serial_number` (inteiro), `not_valid_before`, `not_valid_after` (`YYYY-MM-DD HH:MM:SS`), mais um objeto `validation` `{ csca_verified, dsc_revoked, dsc_expired, csca_expired }` (`kyc/views/epassport.py:86`).	`{ "issuer": "Common Name: CSCA SPAIN, Country: ES", "not_valid_after": "2031-02-18 10:21:11" }`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_nfc"`
`is_nfc_skipped`	boolean	Não	`true` quando este passo NFC foi explicitamente ignorado em vez de lido; `skip_reason` indica o motivo.	`false`
`skip_reason`	string	Sim	Motivo pelo qual o passo foi ignorado: só é definido quando `is_nfc_skipped` é `true`. Um de `USER_SKIPPED`, `DOCUMENT_WITHOUT_CHIP`, `CHIP_CERTIFICATE_UNAVAILABLE`, `DEVICE_WITHOUT_NFC`, `INTEGRATION_WITHOUT_NFC_ACCESS`, `MRZ_KEY_UNAVAILABLE`, `JPKI_UNAVAILABLE`; ver Motivos de omissão. O payload da decisão também inclui um `nfc_skip_reason` ao nível da sessão, com a mesma taxonomia, que abrange os passos NFC ignorados antes de criar qualquer relatório.	`null`
`chip_protocol`	string	Não	Forma como o chip é lido: `icao` (chip ePassport ou eID ICAO 9303) ou `jpki` (My Number Card do Japão). Para `jpki`, `portrait_image`, `signature_image`, `chip_data`, `authenticity` e `certificate_summary` são `null`. Também é definido em passos ignorados.	`"icao"`
`jpki`	object	Sim	O que a leitura de um My Number Card comprovou: `certificate_types`, `chain_valid`, `signature_valid`, `revocation_status` (`good`, `revoked` ou `unchecked`), `ca_generation`, `certificate_expires_at`, `certificates[]`, `attributes` (nome, data de nascimento, sexo e morada do certificado de assinatura), `attributes_match_ocr` e `mismatched_attributes`. Nunca os certificados, os respetivos números de série nem as assinaturas. `null` para chips ICAO, para passos ignorados e quando o passo foi concluído sem qualquer leitura do cartão. Ver Campos JPKI.	`null`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`

{
  "status": "Approved",
  "portrait_image": "https://<media-host>/.../nfc_portrait.jpg?signature=...",
  "signature_image": null,
  "chip_data": {
    "dgs": ["DG1", "DG2", "DG11"],
    "surname": "GARCIA LOPEZ",
    "name": "MARIA",
    "country": "ESP",
    "nationality": "ESP",
    "birth_date": "1990-05-12",
    "expiry_date": "2032-05-11",
    "sex": "F",
    "document_type": "P",
    "document_number": "AB1234567",
    "optional_data": "",
    "birth_date_hash": "4",
    "expiry_date_hash": "7",
    "document_number_hash": "3",
    "optional_data_hash": "",
    "final_hash": "8",
    "mrz_string": "P<ESPGARCIA<LOPEZ<<MARIA<<<<<<<<<<<<<<<<<<<<AB1234567ESP9005124F3205117<<<<<<<<<<<<<<08",
    "mrz_type": "TD3",
    "place_of_birth": "MADRID",
    "address": "CALLE MAYOR 1, MADRID"
  },
  "authenticity": { "sod_integrity": true, "dg_integrity": true },
  "certificate_summary": {
    "issuer": "Common Name: CSCA SPAIN, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "serial_number": 118120836164494130086420187336801405660,
    "not_valid_before": "2020-11-18 10:21:11",
    "not_valid_after": "2031-02-18 10:21:11",
    "validation": {
      "csca_verified": true,
      "dsc_revoked": false,
      "dsc_expired": false,
      "csca_expired": false
    }
  },
  "node_id": "first_nfc",
  "is_nfc_skipped": false,
  "skip_reason": null,
  "chip_protocol": "icao",
  "jpki": null,
  "warnings": []
}

Verificação de prova de vida

Devolvido por sessão de prova de vida. Aparece como liveness_checks[] em GET /v3/session/{sessionId}/decision/. Origem: face/serializers/face.py:301-320 (LivenessV3Serializer, que estende LivenessV2Serializer em face/serializers/face.py:216-298).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enumeração de estados.	`"Approved"`
`method`	string (enum)	Sim	`ACTIVE_3D`, `FLASHING` ou `PASSIVE` (`LivenessMethodChoices`, `common/config/choices.py:514-517`). O modo passivo é usado quando as sessões em computador estão permitidas e o utilizador está num computador.	`"PASSIVE"`
`score`	float (0-100)	Sim	Confiança da prova de vida, arredondada a 2 casas decimais.	`92.41`
`reference_image`	string (URL)	Sim	URL pré-assinado para o recorte do rosto de referência do utilizador.	`"https://<media-host>/.../reference.jpg?..."`
`video_url`	string (URL)	Sim	URL pré-assinado para a gravação da prova de vida, quando a captura guardou uma, tanto para prova de vida ativa como passiva. `null` quando a sessão não guardou gravação.	`"https://<media-host>/.../liveness.webm?..."`
`age_estimation`	float	Sim	Idade estimada (em anos) do maior rosto na imagem de referência.	`34.2`
`matches`	matriz de objetos	Não	Correspondências faciais entre sessões. Cada item: `{ session_id, session_number, similarity_percentage, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details: { full_name, document_type, document_number }, match_image_url, status, is_blocklisted, is_allowlisted, api_service, source }`. `source` é `session`, `imported`, `list_entry` ou `retained_template`. Uma correspondência de modelo retido tem `vendor_user_id`, `vendor_data` e `biometric_template_id`; os respetivos campos de sessão, imagem, dados de identidade, estado e serviço de API são `null`.	`[]`
`face_quality`	float (0-100)	Sim	Pontuação de qualidade do rosto na prova de vida passiva (normalizada em percentagem).	`87.50`
`face_luminance`	float (0-100)	Sim	Pontuação de luminância do rosto na prova de vida passiva (normalizada de 0-255 para uma percentagem).	`54.12`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_liveness"`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`

{
  "status": "Approved",
  "method": "PASSIVE",
  "score": 92.41,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 34.2,
  "matches": [],
  "face_quality": 87.50,
  "face_luminance": 54.12,
  "node_id": "first_liveness",
  "warnings": []
}

Uma sessão PASSIVE devolve este campo quando a captura guardou uma gravação, e null quando a sessão não guardou gravação; o exemplo acima é uma sessão que não guardou nenhuma.

Correspondência facial

Devolvido por cada comparação de correspondência facial (normalmente o rosto do utilizador na prova de vida contra o retrato do documento). Aparece como face_matches[] em GET /v3/session/{sessionId}/decision/. Origem: face/serializers/face.py:367-389 (FaceMatchV3Serializer, que estende FaceMatchV2Serializer em face/serializers/face.py:323-364).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enumeração de estados.	`"Approved"`
`score`	float (0-100)	Sim	Semelhança, arredondada a 2 casas decimais. Quando o fornecedor devolve apenas um `unmatched_faces[].Confidence`, este é convertido para `100 - confidence`.	`97.83`
`source_image_session_id`	string (UUID)	Sim	A sessão cujo retrato guardado forneceu a imagem de origem (referência), definido em fluxos baseados em retrato (autenticação biométrica, ou um retrato fornecido na criação da sessão). `null` quando a referência é o retrato do documento da mesma sessão.	`null`
`source_image`	string (URL)	Sim	URL pré-assinado para a imagem de origem (referência), normalmente o retrato do documento, ou o retrato guardado nos fluxos de autenticação biométrica.	`"https://<media-host>/.../source.jpg?..."`
`target_image`	string (URL)	Sim	URL pré-assinado para a imagem alvo (rosto ao vivo) capturada durante a prova de vida.	`"https://<media-host>/.../target.jpg?..."`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_face_match"`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`
`face_coverage`	object	Sim	Indica se as regiões `eyes`, `mouth` e `face` estão cobertas na imagem capturada. Cada região tem `covered`, `calibrated` e `visibility_score`; `calibrated: false` significa que existem indícios de sombra que não acionam qualquer aviso. Devolvido apenas por `GET /v3/session/{sessionId}/decision/`, nunca em payloads de webhook.	`{ "eyes": { "covered": false, "calibrated": true, "visibility_score": 0.98 } }`

{
  "status": "Approved",
  "score": 97.83,
  "source_image_session_id": null,
  "source_image": "https://<media-host>/.../source.jpg?signature=...",
  "target_image": "https://<media-host>/.../target.jpg?signature=...",
  "node_id": "first_face_match",
  "warnings": []
}

Pesquisa facial

Devolvido pela API autónoma de Pesquisa facial (POST /v3/face-search/). A Pesquisa facial nunca aparece como array no plural em /v3/session/{sessionId}/decision/: quando é guardada com save_api_request=true, a sessão surge aí como uma entrada FACE_SEARCH em features[], mais um item liveness_checks[] que contém os matches guardados. Fontes: apis/serializers/face_search.py:8-79 (FaceSearchResponseSerializer, que envolve FaceSearchDetailsSerializer); os dicionários de correspondência são criados em face/utils/utils.py:869-884. Resposta de nível superior:

Campo	Tipo	Anulável	Descrição	Exemplo
`request_id`	string (UUID)	Não	O ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação temporário.	`"4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f"`
`face_search`	objeto	Não	O payload com os detalhes da pesquisa; ver os campos abaixo.	—
`vendor_data`	string	Sim	Eco do `vendor_data` do pedido.	`null`
`metadata`	objeto	Sim	Eco do `metadata` do pedido.	`null`
`created_at`	string (ISO 8601)	Não	Data e hora do pedido no servidor.	`"2026-06-12T01:04:42.763237+00:00"`

Objeto face_search:

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	`Declined` só quando dispara um aviso `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST`; `Approved` em todos os outros casos. As correspondências duplicadas, por si só, nunca resultam em recusa (`apis/views/face_search.py:242-248`).	`"Approved"`
`total_matches`	inteiro	Não	Número de correspondências devolvidas em `matches[]` (0 a 5).	`1`
`matches`	array de objetos de correspondência de pesquisa facial	Não	Até 5 correspondências acima do limiar mínimo de semelhança, ordenadas por semelhança decrescente (entradas na lista de bloqueio primeiro, com `search_type=blocklisted_or_approved`).	`[…]`
`user_image`	objeto	Não	Resultado da deteção da imagem enviada: `{ entities: [{ bbox, confidence }], best_angle }`, com uma entidade por cada rosto detetado.	`{ "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 }`
`warnings`	array de objetos	Não	Formato reduzido de aviso para esta API autónoma, sem `node_id`. O contrato do serializador declara `{ risk, additional_data, log_type, short_description, long_description }` (`apis/serializers/face_search.py:49-54`); o payload efetivo inclui também `feature`, que é sempre `"LIVENESS"` (`apis/views/face_search.py:332-341`).	`[]`

Objeto de correspondência de pesquisa facial

Campo	Tipo	Anulável	Descrição	Exemplo
`session_id`	string (UUID)	Sim	A sessão de verificação correspondente. É `null` quando `source` é `imported`, `list_entry` ou `retained_template`.	`"a3f2a6f1-…"`
`session_number`	inteiro	Sim	Número da sessão correspondente, legível na consola; `null` em correspondências que não são de sessão.	`1024`
`similarity_percentage`	float (0-100)	Não	Semelhança entre o rosto enviado e o rosto correspondente.	`96.42`
`source`	string (enum)	Não	Origem do rosto correspondente: `session` (sessão de verificação ou chamada autónoma guardada), `imported` (rosto carregado diretamente no perfil do utilizador), `list_entry` (rosto associado a uma lista) e `retained_template` (template biométrico sem imagem, retido depois de a sessão de origem ter sido eliminada).	`"session"`
`vendor_data`	string	Sim	O `vendor_data` da sessão correspondente ou, nas correspondências `imported` e `retained_template`, o do utilizador associado.	`"user-12345"`
`vendor_user_id`	string (UUID)	Sim	O utilizador associado. `null` nas correspondências `list_entry` e nas sessões sem utilizador.	`"2f7c1a9e-…"`
`biometric_template_id`	string (UUID)	Sim	O template retido que correspondeu. Definido apenas nas correspondências `retained_template`; use-o com `GET`/`DELETE /v3/biometric-templates/{id}/`.	`null`
`verification_date`	string (ISO 8601)	Sim	Quando o rosto correspondente foi capturado ou, no caso de um `retained_template`, quando foi retido; `null` nas correspondências `list_entry`.	`"2024-11-04T09:14:02Z"`
`user_details`	objeto	Sim	`{ full_name, document_type, document_number }`, retirado da verificação de documento da sessão correspondente; nas correspondências `imported` só `full_name` está definido; `null` quando não existem dados de identidade e sempre `null` nas correspondências `retained_template`.	`{ "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }`
`match_image_url`	string (URL)	Sim	Rosto de referência do utilizador correspondente: URL pré-assinado quando `save_api_request=true`, caminho de armazenamento em bruto caso contrário. É sempre `null` nas correspondências `retained_template`, que não guardam imagem.	`"https://<media-host>/.../matched.jpg?..."`
`status`	string	Sim	Estado de verificação da sessão correspondente (ver enum de estados); `null` nas correspondências que não são de sessão.	`"Approved"`
`is_blocklisted`	booleano	Não	Indica se o rosto correspondente está na sua lista de bloqueio facial. É sempre `false` nas correspondências `retained_template`; um rosto na lista de bloqueio é reportado à parte como uma correspondência `list_entry`.	`false`
`is_allowlisted`	booleano	Não	Indica se o rosto correspondente está numa das suas listas de permissão.	`false`
`api_service`	string (enum)	Sim	Tipo da API autónoma da sessão correspondente, em maiúsculas (por exemplo, `PASSIVE_LIVENESS`, `FACE_MATCH`); `null` nas sessões de fluxo e nas correspondências que não são de sessão.	`null`

{
  "request_id": "4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "a3f2a6f1-1c1c-4eec-8b69-1c1c2f3a2c7f",
        "session_number": 1024,
        "similarity_percentage": 96.42,
        "source": "session",
        "vendor_data": "user-12345",
        "verification_date": "2024-11-04T09:14:02Z",
        "user_details": {
          "full_name": "María García López",
          "document_type": "Passport",
          "document_number": "AB1234567"
        },
        "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

Triagem AML

Devolvido por cada entidade submetida a triagem. Aparece como aml_screenings[] em GET /v3/session/{sessionId}/decision/, tanto nas sessões KYC como nas KYB. Fonte: aml/serializers/aml.py:63-85 (AMLV3Serializer, que estende AMLV2Serializer em aml/serializers/aml.py:28-60).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver enum de estados.	`"Approved"`
`total_hits`	inteiro	Não	Número de ocorrências da triagem (está sempre presente e tem por predefinição `0`).	`2`
`entity_type`	string (enum)	Sim	`person` ou `company` (`EntityTypeChoices`, `common/config/choices.py:675-677`).	`"person"`
`hits`	array de objetos	Não	Uma entrada por ocorrência. Campos principais: `id`, `caption`, `match` (booleano), `target` (booleano \| null; indica se a entidade é o alvo direto do registo), `match_score` (float de 0 a 100, confiança de identidade), `risk_score` (float de 0 a 100, risco da entidade), `score` (float de 0 a 1, obsoleto), `datasets[]` (por exemplo, `PEP`, `PEP Level 1`-`4`, `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`), `properties` (nomes, nomes alternativos, datas de nascimento, …), `features`, `url`, `first_seen`, `last_seen`, `rca_name`, `risk_view`, `score_breakdown`, `pep_matches`, `sanction_matches`, `warning_matches`, `adverse_media_matches`, `adverse_media_details`, `linked_entities`, `additional_information` e `review_status` (`Unreviewed`, `Confirmed Match`, `False Positive`, `Inconclusive`; editável através do endpoint de atualização do estado da ocorrência AML, `AMLHitStatusChoices`).	`[…]`
`score`	float (0-100)	Sim	Pontuação global da triagem: o maior `risk_score` entre as correspondências que não estão marcadas como `False Positive` (`aml/services/aml.py:832-842`); `0` quando todas as correspondências são falsos positivos. `null` até ser calculada.	`42.7`
`screened_data`	object	Sim	Instantâneo dos dados enviados para a triagem: `full_name`, `nationality`, `date_of_birth`, `document_number`.	`{ "full_name": "María García López", "date_of_birth": "1990-05-12" }`
`is_ongoing_monitoring_enabled`	boolean	Não	Indica se a entidade está subscrita às novas triagens da monitorização contínua.	`false`
`next_ongoing_monitoring_bill_date`	string (YYYY-MM-DD)	Sim	Calculada como `last_aml_bill_date + 365 days` quando a monitorização contínua está ativada. Trata-se de uma data de faturação, não de uma data de triagem.	`null`
`last_ongoing_screening_at`	string (ISO 8601)	Sim	Momento em que a monitorização contínua concluiu a última nova triagem deste registo, tenha o resultado mudado ou não. `null` quando nunca foi sujeito a uma nova triagem; nunca é preenchido retroativamente.	`"2026-09-12T04:03:11Z"`
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601)	Sim	Data da atualização mais recente do conjunto de dados AML que o fornecedor indicou para essa triagem. `null` quando não foi indicada nenhuma data do conjunto de dados; nunca é estimada.	`null`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_aml"`
`warnings`	array	Não	Consulte o Objeto de aviso.	`[]`

{
  "status": "In Review",
  "total_hits": 1,
  "entity_type": "person",
  "hits": [
    {
      "id": "Q7XW3-aml-hit-1",
      "caption": "Maria Garcia Lopez",
      "match": true,
      "target": true,
      "match_score": 86.4,
      "risk_score": 42.7,
      "datasets": ["PEP Level 2"],
      "properties": {
        "name": ["María García López", "M. García"],
        "alias": ["Maria Garcia"],
        "birthDate": ["1990-05-12"]
      },
      "url": "https://example.org/registry/entities/Q7XW3",
      "first_seen": "2023-11-02T00:00:00Z",
      "last_seen": "2026-05-01T00:00:00Z",
      "review_status": "Unreviewed"
    }
  ],
  "score": 42.7,
  "screened_data": {
    "full_name": "María García López",
    "date_of_birth": "1990-05-12",
    "nationality": "ES",
    "document_number": "AB1234567"
  },
  "is_ongoing_monitoring_enabled": false,
  "next_ongoing_monitoring_bill_date": null,
  "last_ongoing_screening_at": null,
  "last_ongoing_screening_datasets_updated_at": null,
  "node_id": "first_aml",
  "warnings": []
}

Análise de IP

Devolvida para cada localização de rede capturada. Aparece como ip_analyses[] em GET /v3/session/{sessionId}/decision/, tanto para sessões de KYC como de KYB. Origem: kyc/serializers/location.py:196-243 (IPAnalysisSerializerV3).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Consulte a Enumeração de estados.	`"Approved"`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_ip_analysis"`
`device_brand`	string	Sim	Marca do dispositivo, obtida a partir do user agent.	`"Apple"`
`device_model`	string	Sim	Modelo do dispositivo.	`"iPhone"`
`browser_family`	string	Sim	Família do navegador.	`"Mobile Safari"`
`os_family`	string	Sim	Família do sistema operativo.	`"iOS"`
`platform`	string	Sim	Plataforma de nível superior (`mobile`, `desktop`, `tablet`).	`"mobile"`
`device_fingerprint`	string	Sim	Hash de impressão digital estável por dispositivo.	`"f2a3…"`
`ip_country`	string	Sim	Nome do país resolvido a partir do endereço.	`"Spain"`
`ip_country_code`	string (ISO 3166-1 alpha-2)	Sim	Código do país resolvido a partir do endereço.	`"ES"`
`ip_state`	string	Sim	Região / estado resolvido a partir do endereço.	`"Comunidad de Madrid"`
`ip_city`	string	Sim	Cidade resolvida a partir do endereço.	`"Madrid"`
`latitude`	float	Sim	Latitude derivada do endereço IP.	`40.4168`
`longitude`	float	Sim	Longitude derivada do endereço IP.	`-3.7038`
`ip_address`	string	Sim	O endereço capturado.	`"203.0.113.42"`
`isp`	string	Sim	Nome do ISP.	`"Telefonica de Espana"`
`organization`	string	Sim	Nome da organização (muitas vezes igual ao ISP).	`"Telefonica de Espana"`
`is_vpn_or_tor`	boolean	Sim	`true` quando o endereço IP pertence a uma VPN, a um proxy ou a um nó de saída Tor.	`false`
`is_data_center`	boolean	Sim	`true` quando o endereço IP pertence a um ASN de alojamento ou centro de dados conhecido.	`false`
`time_zone`	string	Sim	Nome do fuso horário IANA.	`"Europe/Madrid"`
`time_zone_offset`	string	Sim	Diferença em relação ao UTC.	`"+02:00"`
`ip`	object	Não	`{ location, distance_from_id_document, distance_from_poa_document }`. `location = { latitude, longitude }`. Distâncias em km; `null` quando um dos lados está em falta.	`{ "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }`
`id_document`	object	Não	`{ location, distance_from_ip, distance_from_poa_document }`. Localização do documento de identificação resolvida a partir de `issuing_state` e da morada analisada.	`{ "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }`
`poa_document`	object	Não	`{ location, distance_from_ip, distance_from_id_document }`. Morada do POA geocodificada.	`{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }`
`matches`	array of objects	Não	Correspondências de IP/dispositivo entre sessões. Cada item: `{ session_id, session_number, vendor_data, verification_date, match_type, match_source, matched_value, status, is_blocklisted, api_service, source, device_info, location_info, confidence, match_mode }`. `match_type` é `ip_address` ou `device_fingerprint`; `match_source` é `ip_address`, `persistent_id`, `legacy_fp` ou `recovered_high` (as correspondências recuperadas incluem também `recovery_similarity`, `tls_ja4_corroborated`, `recovery_gate_reason`). Limitadas a 5 correspondências de IP e 5 de dispositivo.	`[]`
`warnings`	array	Não	Consulte o Objeto de aviso.	`[]`
`browser_version`, `os_version`	string	Sim	Versões do navegador e do sistema operativo, obtidas a partir do user agent.	`"17.4"`
`user_agent`, `accept_language`	string	Sim	A cadeia do user agent e o cabeçalho `Accept-Language` enviados pelo navegador.	`"en-US,en;q=0.9"`
`session_identifier`, `session_age_ms`	string, integer	Sim	A sessão de navegação em que o passo foi executado e a sua idade em milissegundos.	`48210`
`coords_accuracy`	float	Sim	Raio de precisão, em metros, das coordenadas reportadas pelo dispositivo.	`35.0`
`raw_device_data`	object	Sim	Sinais brutos do dispositivo recolhidos para o passo.	`{}`

{
  "status": "Approved",
  "node_id": "first_ip_analysis",
  "device_brand": "Apple",
  "device_model": "iPhone",
  "browser_family": "Mobile Safari",
  "os_family": "iOS",
  "platform": "mobile",
  "device_fingerprint": "f2a3c1de8b994a3f9e4cdf3a02b1a7c9",
  "ip_country": "Spain",
  "ip_country_code": "ES",
  "ip_state": "Comunidad de Madrid",
  "ip_city": "Madrid",
  "latitude": 40.4168,
  "longitude": -3.7038,
  "ip_address": "203.0.113.42",
  "isp": "Telefonica de Espana",
  "organization": "Telefonica de Espana",
  "is_vpn_or_tor": false,
  "is_data_center": false,
  "time_zone": "Europe/Madrid",
  "time_zone_offset": "+02:00",
  "ip": {
    "location": { "latitude": 40.4168, "longitude": -3.7038 },
    "distance_from_id_document": 3.4,
    "distance_from_poa_document": 1.1
  },
  "id_document": {
    "location": { "latitude": 40.4165, "longitude": -3.7026 },
    "distance_from_ip": 3.4,
    "distance_from_poa_document": 4.0
  },
  "poa_document": {
    "location": { "latitude": 40.4170, "longitude": -3.7040 },
    "distance_from_ip": 1.1,
    "distance_from_id_document": 4.0
  },
  "matches": [],
  "warnings": []
}

Verificação de localização

Devolvido para cada passo de Verificação de localização. Aparece como geolocation_checks[] em GET /v3/session/{sessionId}/decision/: um item por passo, correspondente à sua tentativa aceite. geolocation_attempts[] lista todas as tentativas de todos os passos, da mais antiga para a mais recente. Ambos são null num fluxo sem o passo. Origem: GeolocationDecisionSerializer.

Campo	Tipo	Anulável	Descrição	Exemplo
`node_id`	string	Sim	Nó do fluxo que produziu o resultado.	`"geolocation_1"`
`status`	string	Não	Consulte a enumeração de estados.	`"Declined"`
`outcome`	string	Sim	O que aconteceu na tentativa: `verified`, `low_accuracy`, `accuracy_undetermined`, `stale`, `approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `mock_detected`, `outside_geofence`, `in_blocked_area`, `anonymizer_detected`, `skipped`, `replay_rejected` ou `unsupported_client`.	`"outside_geofence"`
`permission`	string	Sim	O que o sistema concedeu: `granted_precise`, `granted_approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `dismissed` ou `not_requested`.	`"granted_precise"`
`latitude`, `longitude`	float	Sim	Posição WGS84. `null` quando não há posição.	`48.8566`
`accuracy_m`	float	Sim	Raio de incerteza em metros.	`35.0`
`accuracy_confidence`	string	Sim	`p95`, `p68` ou `unspecified`.	`"p95"`
`measured_at`, `age_seconds`	datetime, integer	Sim	Quando o dispositivo obteve a localização e os segundos decorridos até a Didit a receber.	`2`
`source`, `platform`, `sdk_version`	string	Sim	Origem da localização, o cliente que a produziu e a sua versão do SDK.	`"browser"`
`is_mock`, `produced_by_accessory`	boolean	Sim	Indícios de spoofing que a plataforma reporta. `null` significa que a plataforma não o reporta.	`null`
`integrity`	string	Não	`attested`, `not_attested`, `failed`, `unsupported` (web) ou `not_determined`.	`"unsupported"`
`country_code`, `region_code`, `city`	string	Sim	O local a que a localização corresponde.	`"FR"`
`geofence`, `inside_geofence`, `geofence_basis`, `inside_areas`, `blocked_areas`	object, boolean, string, arrays	Sim	O resultado do país e da área.	`{ "enabled": true, "result": "outside" }`
`position_source`, `anonymizers`	string, object	Sim	De onde o passo obtém a posição, e os sinais de VPN, proxy, Tor, spoofing e emulador.	`"device_and_ip"`
`ip_distance_km`, `ip_distance_uncertainty_km`, `ip_consistent`, `document_distance_km`, `travel_excused`, `consecutive_mismatches`	number, boolean, integer	Sim	As comparações com a localização do IP e com a morada registada.	`12.4`
`attempts`	integer	Não	O número da tentativa dentro do passo.	`3`
`consent`	object	Sim	`accepted_at`, `version` e `locale` do aviso que a pessoa aceitou.
`warnings`	array de objetos de aviso	Não	Os avisos `LOCATION_*` do passo. Não estão presentes em `geolocation_attempts[]`, que acrescenta `received_at` e `created_at`.	`[]`

Todos os campos e exemplos estão no Relatório de verificação de localização.

Comprovativo de morada

Devolvido por cada documento de morada enviado. Aparece como poa_verifications[] em GET /v3/session/{sessionId}/decision/. Origem: poa/serializers/poa.py:212-227 (POAV3Serializer, que estende POAV2Serializer em poa/serializers/poa.py:173-209).

Campo	Tipo	Nulo	Descrição	Exemplo
`status`	string	Não	Consulte a enumeração de estados.	`"Approved"`
`issuing_state`	string (ISO 3166-1 alpha-3)	Sim	Código do país do emitente do documento.	`"ESP"`
`document_type`	string	Não	Tipo de alto nível de `PoaDocumentTypeChoices` (`common/config/choices.py:868-873`): `UTILITY_BILL`, `BANK_STATEMENT`, `GOVERNMENT_ISSUED_DOCUMENT`, `OTHER_POA_DOCUMENT`. Recorre a `UNKNOWN`; nunca `null`.	`"UTILITY_BILL"`
`document_subtype`	string	Não	Código de subtipo de `PoaDocumentSubtypeChoices` (por exemplo, `ELECTRICITY_BILL`, `WATER_BILL`, `ACCOUNT_STATEMENT`). Recorre a `UNKNOWN`; nunca `null`.	`"ELECTRICITY_BILL"`
`issuer`	string	Sim	Nome da entidade emissora.	`"Iberdrola"`
`issue_date`	string (YYYY-MM-DD)	Sim	Data de emissão do documento.	`"2026-04-15"`
`expiration_date`	string (YYYY-MM-DD)	Sim	Data de validade impressa no documento, quando existir.	`null`
`poa_address`	string	Sim	Morada bruta extraída por OCR.	`"Calle Mayor 1, 28001 Madrid"`
`poa_formatted_address`	string	Sim	Morada geocodificada e formatada.	`"Calle Mayor 1, 28001 Madrid, Spain"`
`poa_parsed_address`	object	Sim	Morada estruturada (`street_1`, `street_2`, `city`, `region`, `postal_code`, `country` (alpha-2), `address_type`, `document_location`, …).	`{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001" }`
`document_file`	string (URL)	Sim	URL pré-assinado para o documento carregado.	`"https://<media-host>/.../poa.pdf?..."`
`document_language`	string	Sim	Idioma detetado do documento (ISO 639-1).	`"es"`
`document_metadata`	object	Sim	Metadados filtrados: `file_size`, `content_type`, `creation_date`, `modified_date`, `creator`, `producer`, `software`, `encryption`, `is_signed`, `is_tampered`, `signature_info`, `exif_original_date`, `exif_digitized_date`, `processed_by_known_editor`, `has_different_creation_mod_date`, `overlay_manipulation`.	`{ "file_size": 184221, "content_type": "application/pdf", "is_tampered": false }`
`extra_fields`	object	Não	Campos de conta bancária (`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names`, e quaisquer chaves personalizadas guardadas no registo.	`{ "bank_iban": null, "additional_names": [] }`
`name_on_document`	string	Sim	Nome tal como aparece no comprovativo de morada.	`"María García López"`
`expected_details_address`	string	Sim	Morada que o cliente introduziu no registo (texto integral).	`"Calle Mayor 1, Madrid"`
`expected_details_formatted_address`	string	Sim	Morada esperada geocodificada.	`"Calle Mayor 1, 28001 Madrid, Spain"`
`expected_details_parsed_address`	object	Sim	Morada esperada estruturada.	`{ "city": "Madrid", "postal_code": "28001" }`
`name_match_score_expected_details`	float (0-100)	Sim	Correspondência aproximada entre `name_on_document` e o nome fornecido na criação da sessão.	`94.0`
`name_match_score_id_verification`	float (0-100)	Sim	Correspondência aproximada entre `name_on_document` e o `full_name` do documento de identidade verificado.	`100.0`
`extra_files`	array de strings (URL)	Não	URLs pré-assinadas para ficheiros adicionais carregados.	`[]`
`detected_codes`	array de objetos	Não	Códigos QR e códigos de barras detetados em todas as páginas processadas do documento: `type`, `page_number` (a partir de 1), `position` (polígono), `x`/`y`/`width`/`height` (caixa delimitadora), `page_width`/`page_height`, `raw_payload` (base64), `parsed_payload` (valor descodificado, `null` quando um código foi localizado mas não pôde ser descodificado). Array vazio quando a deteção não encontra nada.	`[{ "type": "QR_CODE", "page_number": 1, "parsed_payload": "https://issuer.example/inv/9981" }]`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_poa"`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`

{
  "status": "Approved",
  "issuing_state": "ESP",
  "document_type": "UTILITY_BILL",
  "document_subtype": "ELECTRICITY_BILL",
  "issuer": "Iberdrola",
  "issue_date": "2026-04-15",
  "expiration_date": null,
  "poa_address": "Calle Mayor 1, 28001 Madrid",
  "poa_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "poa_parsed_address": { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" },
  "document_file": "https://<media-host>/.../poa.pdf?signature=...",
  "document_language": "es",
  "document_metadata": {
    "file_size": 184221,
    "content_type": "application/pdf",
    "creation_date": "2026-04-15T08:11:32Z",
    "modified_date": "2026-04-15T08:11:32Z",
    "creator": "Iberdrola Billing",
    "producer": "Adobe PDF Library 15.0",
    "software": null,
    "encryption": null,
    "is_signed": true,
    "is_tampered": false,
    "signature_info": { "signer_name": "Iberdrola Clientes", "date": "2026-04-15T08:11:32Z" },
    "exif_original_date": null,
    "exif_digitized_date": null,
    "processed_by_known_editor": false,
    "has_different_creation_mod_date": false,
    "overlay_manipulation": null
  },
  "extra_fields": {
    "bank_account_number": null,
    "bank_iban": null,
    "bank_sort_code": null,
    "bank_routing_number": null,
    "bank_swift_bic": null,
    "bank_branch_name": null,
    "bank_branch_address": null,
    "document_phone_number": null,
    "additional_names": []
  },
  "name_on_document": "María García López",
  "expected_details_address": "Calle Mayor 1, Madrid",
  "expected_details_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "expected_details_parsed_address": { "city": "Madrid", "postal_code": "28001", "country": "ES" },
  "name_match_score_expected_details": 94.0,
  "name_match_score_id_verification": 100.0,
  "extra_files": [],
  "detected_codes": [
    {
      "type": "QR_CODE",
      "page_number": 1,
      "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
      "x": 820,
      "y": 1120,
      "width": 182,
      "height": 182,
      "page_width": 1190,
      "page_height": 1684,
      "raw_payload": "aHR0cHM6Ly9pYmVyZHJvbGEuZXMvZmFjdHVyYS85OTgx",
      "parsed_payload": "https://iberdrola.es/factura/9981"
    },
    {
      "type": "CODE_128",
      "page_number": 1,
      "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
      "x": 112,
      "y": 1480,
      "width": 448,
      "height": 60,
      "page_width": 1190,
      "page_height": 1684,
      "raw_payload": "MDA5OTgxMDAwNDI=",
      "parsed_payload": "0099810042"
    }
  ],
  "node_id": "first_poa",
  "warnings": []
}

Verificação de telefone

Devolvido por cada tentativa de verificação de telefone. Aparece como phone_verifications[] em GET /v3/session/{sessionId}/decision/ para sessões KYC e KYB. Origem: phone/serializers/phone.py:251-266 (PhoneV3Serializer, estende PhoneV2Serializer em phone/serializers/phone.py:103-248).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enum de estado.	`"Approved"`
`phone_number_prefix`	string	Não	Prefixo de país E.164 (com `+`).	`"+34"`
`phone_number`	string	Não	Número do assinante sem o prefixo.	`"612345678"`
`full_number`	string	Não	O número E.164 completo (`phone_number_prefix + phone_number`).	`"+34612345678"`
`country_code`	string (ISO 3166-1 alpha-2)	Sim	País do número.	`"ES"`
`country_name`	string	Sim	Nome do país no idioma local.	`"Spain"`
`carrier`	object	Não	`{ name, type }`, em que `type` é um valor de `LineTypeChoices` (`common/config/choices.py:648-667`): `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `voice_mail`, `unknown`, e outras classes de linha.	`{ "name": "Movistar", "type": "mobile" }`
`is_disposable`	boolean	Não	`true` quando a operadora marca o número como temporário/descartável.	`false`
`is_virtual`	boolean	Não	`true` quando `carrier.type` é um dos valores `voip`, `isp` ou `vpn`.	`false`
`verification_method`	string	Não	Canal usado para entregar o OTP (`whatsapp`, `sms`, …). Lê o `actual_channel` da última tentativa de envio (recorre ao `channel` pedido e, em último caso, a `sms`).	`"whatsapp"`
`verification_attempts`	integer	Não	Total de tentativas de envio de OTP (envio inicial mais reenvios).	`1`
`verified_at`	string (ISO 8601)	Sim	Data e hora em que o OTP foi introduzido com êxito.	`"2026-05-17T10:14:02Z"`
`lifecycle`	array de objetos	Não	Eventos por ordem cronológica: tentativas de envio, callbacks de entrega, verificações de código e o evento final de estado. Cada evento é `{ type, timestamp, details, fee }`. Os tipos de evento vêm de `PhoneEventChoices`.	`[…]`
`matches`	array de objetos	Não	Correspondências de número de telefone entre sessões. Cada item: `{ session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }`. `source` é `session` ou `list_entry`.	`[]`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_phone"`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`
`phone_intelligence`	object	Sim	Sinais de inteligência do telefone. Presente apenas quando o complemento de inteligência foi executado para o número.
`phone_social`	object	Sim	Pegada social do número. Presente apenas quando o complemento de pegada social foi executado.

{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "612345678",
  "full_number": "+34612345678",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Movistar", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:14:02Z",
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:13:51Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.02
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2026-05-17T10:13:52Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_phone",
  "warnings": []
}

Verificação de e-mail

Devolvido por cada tentativa de verificação de e-mail. Aparece como email_verifications[] em GET /v3/session/{sessionId}/decision/ para sessões KYC e KYB. Origem: email_verification/serializers/email.py:149-164 (EmailV3Serializer, estende EmailV2Serializer em email_verification/serializers/email.py:38-146).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enum de estado.	`"Approved"`
`email`	string	Não	O endereço de e-mail submetido.	`"maria.garcia@example.com"`
`is_breached`	boolean	Não	`true` quando o e-mail aparece numa fuga de dados conhecida.	`false`
`breaches`	array de objetos	Não	Detalhe por fuga de dados quando `is_breached` é `true`: `{ name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }`.	`[]`
`is_disposable`	boolean	Não	`true` quando o e-mail pertence a um fornecedor de e-mail descartável.	`false`
`is_undeliverable`	boolean	Não	`true` quando a verificação de entrega SMTP indica que a caixa de correio não aceita e-mails.	`false`
`verification_attempts`	integer	Não	Total de tentativas de verificação de OTP.	`1`
`verified_at`	string (ISO 8601)	Sim	Data e hora em que o OTP foi introduzido com êxito.	`"2026-05-17T10:15:22Z"`
`lifecycle`	array de objetos	Não	Eventos por ordem cronológica: tentativas de envio, verificações de código e o evento final de estado. Cada evento é `{ type, timestamp, details, fee }`. Os tipos de evento vêm de `EmailEventChoices`.	`[…]`
`matches`	array de objetos	Não	Correspondências de e-mail entre sessões. Cada item: `{ session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }`. `source` é `session` ou `list_entry`.	`[]`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_email"`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`
`email_intelligence`	object	Sim	Sinais de inteligência do e-mail. Presente apenas quando o complemento de inteligência foi executado para o endereço.
`email_social`	object	Sim	Pegada social do endereço. Presente apenas quando o complemento de pegada social foi executado.

{
  "status": "Approved",
  "email": "maria.garcia@example.com",
  "is_breached": false,
  "breaches": [],
  "is_disposable": false,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:15:22Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:15:11Z",
      "details": { "status": "Success", "reason": null },
      "fee": 0.02
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": { "code_tried": "739204", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_email",
  "warnings": []
}

Validação de base de dados

Devolvido por cada consulta à base de dados executada sobre os dados submetidos pelo utilizador. Aparece como database_validations[] em GET /v3/session/{sessionId}/decision/. Origem: database_validation/serializers/database_validation.py:21-142 (DatabaseValidationV3Serializer, estende DatabaseValidationV2Serializer).

Campo	Tipo	Anulável	Descrição	Exemplo
`issuing_state`	string (ISO 3166-1 alpha-3)	Sim	País cujo registo foi consultado.	`"ESP"`
`validation_type`	string (enum)	Não	Forma como o resultado foi corroborado: `one_by_one` (resultado de um único serviço), `two_by_two` (dois ou mais serviços distintos obtiveram correspondência total de forma independente para o número de identificação) ou `not_enabled` (o validador foi ignorado ou nenhum fornecedor respondeu; um `no_match` definitivo continua a devolver `one_by_one`). Nunca `null`. Origem: `DatabaseValidationChoices` (`common/config/choices.py:1097-1100`).	`"one_by_one"`
`screened_data`	object	Não	Os dados enviados para o registo. Os campos de ficheiro (`selfie`, `cnh_qr_code_image`, `document_image`) são pré-assinados no momento da leitura.	`{ "document_number": "99999999R", "date_of_birth": "1990-05-12" }`
`validations`	array de objetos	Não	Uma entrada por serviço do catálogo que produziu uma correspondência. Cada entrada pode incluir `service_id`, `service_name`, `validation` (objeto com o veredito do fornecedor), `outcome_code`, `outcome_detail` e `source_data` (perfil do cidadão normalizado: `full_name`, `gender`, `date_of_birth`, `photo` (URL pré-assinado), `signature` (URL pré-assinado), …).	`[…]`
`errors`	array de objetos	Sim	Erros por serviço quando uma consulta falhou; a chave é omitida por completo quando está vazia. Cada entrada é o objeto de erro do serviço de origem, acrescido do `service_id` que o produziu.	`[]`
`match_type`	string (enum)	Sim	Veredito de correspondência agregado entre os serviços consultados: `full_match`, `partial_match` ou `no_match` (`DatabaseValidationMatchTypeChoices`, `common/config/choices.py:1103-1106`). `null` até ser avaliado.	`"full_match"`
`status`	string	Não	Ver Enumeração de estados.	`"Approved"`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_db_validation"`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`

{
  "issuing_state": "ESP",
  "validation_type": "one_by_one",
  "screened_data": {
    "document_number": "99999999R",
    "date_of_birth": "1990-05-12",
    "first_name": "María",
    "last_name": "García López"
  },
  "validations": [
    {
      "service_id": "esp_dni",
      "service_name": "Spain - DNI/NIE verification",
      "validation": { "is_valid": true, "match_score": 100 },
      "outcome_code": "MATCH",
      "outcome_detail": "All identifiers match the registry record.",
      "source_data": {
        "full_name": "María García López",
        "gender": "F",
        "date_of_birth": "1990-05-12",
        "photo": "https://<media-host>/.../registry_photo.jpg?signature=...",
        "signature": null
      }
    }
  ],
  "match_type": "full_match",
  "status": "Approved",
  "node_id": "first_db_validation",
  "warnings": []
}

Resposta ao questionário

Devolvida por cada submissão de questionário. Aparece como questionnaire_responses[] em GET /v3/session/{sessionId}/decision/, tanto para sessões KYC como KYB. Origem: questionnaires/serializers/questionnaire.py:591-597 (QuestionnaireResponseV3Serializer, que estende QuestionnaireResponseSerializer em questionnaires/serializers/questionnaire.py:520-588).

Campo	Tipo	Anulável	Descrição	Exemplo
`questionnaire_id`	string (UUID)	Não	Identificador da versão do questionário que foi respondida.	`"6a0f1c2c-…"`
`title`	string	Não	Nome do questionário, tal como definido na Consola.	`"Customer risk profile"`
`description`	string	Sim	Descrição do questionário.	`"Short risk-profile questions."`
`languages`	array de strings	Não	Códigos de idioma em que o questionário é publicado.	`["en", "es"]`
`default_language`	string	Não	Código de idioma de reserva.	`"en"`
`is_active`	boolean	Não	Se esta versão do questionário é a ativa.	`true`
`is_simple_questionnaire`	boolean	Não	`true` quando o questionário não tem ramificações (lista linear).	`true`
`questionnaire_group_id`	string (UUID)	Não	Identificador partilhado pelas versões do mesmo questionário.	`"a7c2c2c2-…"`
`version`	integer	Não	Número da versão do modelo ativo.	`3`
`status`	string	Não	Um de `Approved`, `In Review`, `Not Finished` (uma recusa ao nível do questionário é mapeada para `In Review`).	`"Approved"`
`published_at`	string (ISO 8601)	Sim	Data em que o modelo foi publicado.	`"2026-01-12T11:00:00Z"`
`sections`	array de objetos	Não	Secções ordenadas, após aplicar o percurso do grafo e o filtro de visibilidade. Cada secção é `{ title, description, items[] }` (title e description vêm do `SECTION_HEADER` inicial, já traduzidos). Cada item é um elemento de formulário (`uuid`, `value` (id do nó), `element_type`, `is_required`, `title`, `description`, `placeholder`, `choices`, `max_files`, `required_if`, `repeatable_config`), além de um campo `answer`, que é `null` quando não há resposta e omitido nos itens de layout `HEADING`, `PARAGRAPH` e `SEPARATOR`. As respostas de ficheiros contêm `{ files: [<presigned URL>, …] }`.	`[…]`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_questionnaire"`

{
  "questionnaire_id": "6a0f1c2c-3b7d-4d2c-9eb6-fdc6c7c92ef9",
  "title": "Customer risk profile",
  "description": "Short risk-profile questions.",
  "languages": ["en", "es"],
  "default_language": "en",
  "is_active": true,
  "is_simple_questionnaire": true,
  "questionnaire_group_id": "a7c2c2c2-1111-4d2c-9eb6-fdc6c7c92ef9",
  "version": 3,
  "status": "Approved",
  "published_at": "2026-01-12T11:00:00Z",
  "sections": [
    {
      "title": "Source of funds",
      "description": null,
      "items": [
        {
          "uuid": "4f1d5e2c-aaaa-4d2c-9eb6-fdc6c7c92ef9",
          "value": "q_source_of_funds",
          "element_type": "SINGLE_CHOICE",
          "is_required": true,
          "title": "What is your main source of funds?",
          "description": null,
          "placeholder": null,
          "choices": [
            { "label": "Salary", "value": "salary" },
            { "label": "Business income", "value": "business" },
            { "label": "Investments", "value": "investments" }
          ],
          "max_files": 1,
          "required_if": null,
          "repeatable_config": null,
          "answer": { "value": "salary" }
        }
      ]
    }
  ],
  "node_id": "first_questionnaire"
}

Assinatura eletrónica

Devolvida por cada signatário de um passo de Assinatura eletrónica. Aparece como signatures[] em GET /v3/session/{sessionId}/decision/, tanto para sessões KYC como KYB, apenas quando o fluxo tem o passo. Ao contrário dos restantes objetos de relatório, o seu status é a fase de assinatura e o resultado está em verdict, e os itens de warnings[] são { code, node_id } em vez de objetos de aviso.

Campo	Tipo	Anulável	Descrição	Exemplo
`id`	string (UUID)	Não	A assinatura do signatário. Use-o como `signature_id` nas rotas de evidência e de validação.	`"0e6c2a8e-…"`
`node_id`	string	Não	Identificador do nó do fluxo.	`"feature_signature"`
`status`	string	Não	Fase da assinatura: `intro`, `review`, `code`, `signing`, `signed` ou `declined`. Só `signed` significa que os documentos estão assinados.	`"signed"`
`verdict`	string	Não	`Not Finished`, `Approved`, `In Review` ou `Declined`.	`"Approved"`
`level`	string	Não	`simple` (predefinido), `aes` ou `qes` (qualificada, um complemento).	`"aes"`
`format`	string	Não	`pdf` para uma assinatura simples, `pades` para a avançada (AES) e a qualificada (QES).	`"pades"`
`profile`	string	Sim	`PAdES-B-LT` depois de uma assinatura avançada (AES) ou qualificada (QES) estar assinada; caso contrário, null.	`"PAdES-B-LT"`
`signer`	object	Não	`{ name, capacity, company, role, roles, identity_session_id }`. `capacity` é `self` (KYC) ou `company` (KYB).	`{ "name": "Jane Doe", "capacity": "self", … }`
`identity_used`	object	Não	`{ session_id, kyc_id, verified, expected_name }`: a identidade verificada em que a assinatura se apoia. Vazio numa assinatura simples sem identidade verificada.	`{ "verified": true, … }`
`certificate`	object	Sim	`{ issuer, issued_to, serial, valid_from, valid_until }`. `null` até a assinatura estar concluída e sempre `null` numa assinatura simples.	`{ "serial": "5A3F9C21", … }`
`confirmation`	objeto	Não	`{ channel, destination, confirmed_at, attempts }`. `destination` está mascarado; `attempts` conta os códigos introduzidos, incluindo o correto. Uma assinatura simples não tem código, por isso `channel` e `destination` são `null`.	`{ "channel": "email", … }`
`timestamp`	objeto	Sim	`{ time, qualified, valid }`. `qualified` é sempre `false` para AES, em que a Didit emite o carimbo temporal; para QES, o prestador qualificado de serviços de confiança é quem o emite. `null` até à assinatura, e sempre `null` numa assinatura simples.	`{ "qualified": false, … }`
`documents`	array de objetos	Não	`{ id, uuid, title, language, source_revision, translation_id, file_name, pages, size_bytes, sha256_original, sha256_signed, status, opened_at, read_at, read_to_end, consented_at, consent, signed_file, mode, source_format, conversion, fields }`. `status` é `signed`, `declined`, `not_signed` ou `not_reached`. `mode` é `fields` ou `read_and_agree`. `source_format` é `pdf` ou `docx`; `conversion` descreve o ficheiro Word original, ou é `null` para um PDF.	`[…]`
`documents[].language`	string	Sim	Idioma da versão selecionada quando a tentativa foi iniciada, ou `null` se não estiver definido. É usada uma tradução completa e correspondente; caso contrário, o original. Depois de assinado, este é o idioma efetivamente assinado.	`"en"`
`documents[].source_revision`	string (UUID)	Não	Revisão de origem copiada para a tentativa, incluindo quando é selecionada uma tradução. Diferente do `id` do documento do signatário.	`"22222222-2222-4222-8222-222222222222"`
`documents[].translation_id`	string (UUID)	Sim	Tradução selecionada, ou `null` para o original. A cópia do documento e a seleção de idioma mantêm-se fixas depois de a tentativa ser iniciada.	`null`
`documents[].fields`	array de objetos	Não	`{ key, type, role, label, page, x, y, width, height, required, value, display_value, value_source, filled_at, image_url, value_unavailable_reason }` para cada campo do documento. `value` é uma cadeia de caracteres, um booleano para uma caixa de verificação, ou `true` para uma assinatura ou rubrica aplicada. Vazio para um documento sem campos.	`[…]`
`adopted_signature`	objeto	Sim	`{ method, font, adopted_at }`: a assinatura e as rubricas que o signatário adotou. `method` é `typed` ou `drawn`; `font` é o estilo de escrita manuscrita utilizado numa assinatura digitada. `null` até à adoção.	`{ "method": "drawn", … }`
`electronic_signature_consent_at`	string (ISO 8601)	Sim	Quando o signatário concordou em assinar os documentos eletronicamente. Definido quando algum documento tem campos.	`"2026-11-03T10:41:40Z"`
`evidence_file`	string	Sim	Caminho do PDF de evidências, depois de assinado.	`"/v3/session/…/evidence/?signature_id=…"`
`warnings`	array de objetos	Não	`{ code, node_id }`, com `code` um de `SIGNATURE_DECLINED`, `SIGNATURE_OTP_FAILED`, `SIGNATURE_NAME_MISMATCH`, `SIGNATURE_IDENTITY_NOT_VERIFIED`, `SIGNATURE_DOCUMENT_CHANGED`.	`[]`
`validation`	objeto	Sim	`{ valid, checked_at, documents[] }`: a última verificação criptográfica dos documentos assinados. `null` até à assinatura. `{ valid: null, reason: "signature_provider_outcome_unknown", checked_at }` quando não foi possível confirmar o resultado da assinatura.	`{ "valid": true, … }`
`declined_at`	string (ISO 8601)	Sim	Quando o signatário recusou.	`null`
`declined_action`	string	Não	A `signature_declined_action` do passo.	`"REVIEW"`
`signed_at`	string (ISO 8601)	Sim	Quando os documentos foram assinados.	`"2026-11-03T10:42:24Z"`
`expires_at`	string (ISO 8601)	Não	Quando a ligação de assinatura deixa de funcionar.	`"2026-11-10T10:30:00Z"`
`email_sent_at`	string (ISO 8601)	Sim	Quando foi enviada por e-mail ao signatário uma cópia assinada.	`"2026-11-03T10:42:30Z"`
`email_unavailable_reason`	string	Sim	Motivo pelo qual não foi enviada nenhuma cópia, quando foi pedida.	`null`
`ip_address`	string	Sim	O endereço IP do signatário quando pediu o seu código.	`"203.0.113.10"`
`place`	string	Sim	Não recolhido: sempre `null`.	`null`
`place_unavailable_reason`	string	Sim	`not_collected`.	`"not_collected"`

O relatório de assinatura eletrónica tem um exemplo completo e todos os campos aninhados.

Estimativa de idade

Devolvido pela API autónoma de Estimativa de idade (POST /v3/age-estimation/). A resposta contém um subconjunto da forma de Liveness check, dentro de um envelope age_estimation com status, method, score, age_estimation e warnings, além de um bloco user_image de deteção facial exclusivo da API autónoma; não inclui reference_image, video_url, matches, face_quality nem face_luminance. Em sessões de fluxo não existe um array separado: a idade estimada aparece como liveness_checks[].age_estimation em GET /v3/session/{sessionId}/decision/. Fonte: apis/serializers/age_estimation.py:50-55 (AgeEstimationResponseSerializer), envelope montado em apis/views/age_estimation.py:138-174.

Campo	Tipo	Anulável	Descrição	Exemplo
`request_id`	string (UUID)	Não	ID da sessão persistida quando `save_api_request=true` (o padrão); caso contrário, um UUID de correlação transitório.	`"3b1f1e2c-…"`
`age_estimation`	objeto	Não	Envelope do resultado: `status` (`Approved` / `Declined`), `method` (sempre `PASSIVE`), `score` (prova de vida 0-100, anulável), `age_estimation` (idade prevista, em anos, do maior rosto, anulável), `user_image` (`entities[]` com `age` por rosto, `bbox` `[x_min, y_min, x_max, y_max]`, `confidence`, `gender`; além de `best_angle`), `warnings[]`.	`{ … }`
`vendor_data`	string	Sim	Reproduzido a partir de `vendor_data` do pedido.	`null`
`metadata`	objeto	Sim	Reproduzido a partir do `metadata` incluído no pedido.	`null`
`created_at`	string (ISO 8601)	Não	Carimbo temporal do pedido no servidor.	`"2026-05-17T10:22:13.512941+00:00"`

{
  "request_id": "3b1f1e2c-7777-4d2c-9eb6-fdc6c7c92ef9",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 94.10,
    "age_estimation": 28.7,
    "user_image": {
      "entities": [
        { "age": 28.7, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-05-17T10:22:13.512941+00:00"
}

Autenticação biométrica

A autenticação biométrica executa o mesmo pipeline de Prova de vida + Correspondência facial usado na KYC padrão, mas configurado para comparar o rosto capturado com a imagem de referência de um utilizador existente, em vez de um retrato do documento recém-extraído por OCR. Não existe um serializador dedicado: GET /v3/session/{sessionId}/decision/ devolve os objetos padrão Prova de vida e Correspondência facial em liveness_checks[] e face_matches[]. O fluxo da sessão é configurado com workflow_type = "biometric_authentication" (WorkflowTypeChoices, common/config/choices.py:636).

Campo	Tipo	Pode ser nulo	Descrição	Exemplo
`liveness_checks`	array de Verificação de prova de vida	Não	Resultado da prova de vida para a tentativa de autenticação.	`[ { "status": "Approved", … } ]`
`face_matches`	array de Correspondência facial	Não	Resultado da correspondência com a referência registada. `source_image_session_id` fica definido com o `session_id` da própria sessão: a face de referência (o `portrait_image` fornecido ou a face guardada reutilizada através de `vendor_data` quando o `portrait_image` é omitido) fica registada na própria sessão de autenticação (`face/views/face.py:656-659`).	`[ { "status": "Approved", "source_image_session_id": "…", … } ]`
`status`	string	Não	Estado da sessão de nível superior (ver Enum de estado).	`"Approved"`

{
  "session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
  "status": "Approved",
  "liveness_checks": [
    {
      "status": "Approved",
      "method": "PASSIVE",
      "score": 95.10,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": null,
      "matches": [],
      "face_quality": 91.20,
      "face_luminance": 53.10,
      "node_id": "biometric_auth_liveness",
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "status": "Approved",
      "score": 98.42,
      "source_image_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
      "source_image": "https://<media-host>/.../source.jpg?signature=...",
      "target_image": "https://<media-host>/.../target.jpg?signature=...",
      "node_id": "biometric_auth_face_match",
      "warnings": []
    }
  ]
}

Registo KYB

Devolvido por cada empresa confirmada pelo registo num fluxo KYB. Aparece como registry_checks[] em GET /v3/session/{sessionId}/decision/ para sessões de empresas. Origem: kyb/serializers/kyb.py:939-964 (RegistryCheckV3Serializer).

Campo	Tipo	Pode ser nulo	Descrição	Exemplo
`status`	string	Não	Ver Enum de estado.	`"Approved"`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_registry"`
`data_resolved`	boolean	Não	`true` quando a obtenção dos dados no registo estiver concluída (ou quando `is_from_registry` for `false`, o que significa que os dados foram introduzidos manualmente).	`true`
`company`	object	Não	Payload completo da empresa: ver Objeto da empresa abaixo.	`{ … }`
`ownership_structure`	object	Sim	A tabela de capital que o registo comprovou: `shareholders[]` e `beneficial_owners[]`, em que cada proprietário tem a sua identidade no registo, a sua participação e a `shareholding` canónica.	`{ "shareholders": [...], "beneficial_owners": [] }`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`

Objeto da empresa

Proveniente de kyb/serializers/kyb.py:220-321 (KYBCompanyResponseSerializer).

Campo	Tipo	Pode ser nulo	Descrição
`uuid`	string (UUID)	Não	Identificador interno da empresa.
`node_id`	string \| null	Sim	Identificador do nó do fluxo.
`status`	string	Não	Estado da funcionalidade (`FeatureStatusChoices`).
`registry_status`	string	Sim	Estado da empresa no registo (`active`, `dissolved`, …).
`data_resolved`	boolean	Não	Mesma definição que no objeto pai.
`company_name`	string	Sim	Nome da empresa registado.
`registration_number`	string	Sim	Identificador no registo.
`country_code`	string (ISO 3166-1 alpha-2)	Sim	País de constituição.
`region`	string	Sim	Subdivisão ISO 3166-2, quando aplicável (por exemplo, `US-CA`).
`company_type`	string	Sim	Forma jurídica (`LLC`, `SL`, …).
`incorporation_date`	string (YYYY-MM-DD)	Sim	Data de constituição.
`registered_address`	string	Sim	Morada legal registada.
`tax_number`	string	Sim	Identificador fiscal ou de IVA.
`risk_level`	string	Sim	Classificação de risco fornecida pelo prestador.
`verification_status`	string	Sim	Enum interno do estado de verificação.
`is_from_registry`	boolean	Não	`true` quando provém do registo (em vez de introdução manual).
`fetch_status`	string	Sim	`pending`, `resolved`, `failed`.
`alternative_names`	string	Sim	Nomes comerciais alternativos, separados por vírgulas.
`nature_of_business`	string	Sim	Descrição em texto livre da atividade empresarial.
`registered_capital`	string	Sim	Capital social registado, como string legível por pessoas.
`registered_capital_amount`	string (decimal)	Sim	Montante do capital social registado, processado.
`registered_capital_currency`	string (ISO 4217)	Sim	Código da moeda.
`website`	string (URL)	Sim	Website da empresa.
`email`	string	Sim	Correio eletrónico público de contacto.
`phone`	string	Sim	Telefone público de contacto.
`legal_entity_identifier`	string	Sim	LEI, quando disponível.
`location_of_registration`	string	Sim	Conservatória ou região do registo.
`vat_number`	string	Sim	Número de IVA submetido para a empresa.
`vat_validation_status`	string	Não	Resultado da validação do número de IVA ou, na sua ausência, do `tax_number`: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` ou `not_applicable`. Ver Validação de IVA e número de identificação fiscal.
`vat_validated_number`	string	Sim	O número que foi verificado, tal como a fonte o conhece.
`vat_validation_source`	string	Sim	Fonte que determinou o estado: `eu_vies`, `pl_vat_white_list`, `no_brreg`, `ch_uid_register`, `br_receita_federal`, `co_rues`, `cr_hacienda`, `ec_sri`, `py_dnit` ou `format_rules`.
`vat_validated_name`	string	Sim	Nome registado na fonte (vazio quando a fonte não o divulga).
`vat_validated_address`	string	Sim	Morada registada na fonte (vazia quando não é divulgada).
`vat_checked_at`	string (ISO 8601)	Sim	Data e hora da verificação; `null` quando nenhuma verificação foi feita.
`financial_summary`	object	Sim	Síntese dos principais dados financeiros mais recentes, quando fornecido pelo registo.
`officers`	array de objetos	Não	Lista de responsáveis segura para B2C: `{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`.
`beneficial_owners`	array de objetos	Não	Lista de beneficiários efetivos segura para B2C: `{ uuid, name, first_name, last_name, entity_type, roles, ownership_min_shares, ownership_max_shares, is_active, kyc_status, kyc_session_url, effective_ownership_percent }`.
`addresses`	array de objetos	Sim	Detalhe de cada morada proveniente do registo.
`industries`	array de objetos	Sim	Classificações do tipo SIC/NAICS.
`accounts`	array de objetos	Sim	Metadados das contas apresentadas.
`registry_data`	object	Sim	Detalhe normalizado do registo pela Didit (resultado da estrutura de propriedade, correções feitas na consola, dados do registo sem campo próprio). Não é um contrato estável.
`user_provided_data`	object	Sim	Instantâneo dos campos editados pelo utilizador.
`confirmed_by_user_at`	string (ISO 8601)	Sim	Data e hora em que o utilizador confirmou os dados extraídos.
`last_console_edit_at`	string (ISO 8601)	Sim	Data e hora da última edição na consola.
`is_editable`	boolean	Não	`true` enquanto os dados obtidos do registo ainda puderem ser editados pelo utilizador final.

{
  "status": "Approved",
  "node_id": "first_registry",
  "data_resolved": true,
  "company": {
    "uuid": "b1f1e2c2-9999-4d2c-9eb6-fdc6c7c92ef9",
    "node_id": "first_registry",
    "status": "Approved",
    "registry_status": "active",
    "data_resolved": true,
    "company_name": "Sante Clinics SL",
    "registration_number": "B12345678",
    "country_code": "ES",
    "region": null,
    "company_type": "SL",
    "incorporation_date": "2018-03-22",
    "registered_address": "Calle Mayor 1, 28001 Madrid, Spain",
    "tax_number": "B12345678",
    "risk_level": "low",
    "verification_status": "verified",
    "is_from_registry": true,
    "fetch_status": "resolved",
    "alternative_names": "Sante Clinics",
    "nature_of_business": "Medical clinic operations",
    "registered_capital": "EUR 50,000",
    "registered_capital_amount": "50000.00",
    "registered_capital_currency": "EUR",
    "website": "https://santeclinics.com",
    "email": "info@santeclinics.com",
    "phone": "+34911223344",
    "legal_entity_identifier": null,
    "location_of_registration": "Registro Mercantil de Madrid",
    "vat_number": "ESB12345678",
    "vat_validation_status": "valid",
    "vat_validated_name": "SANTE CLINICS SL",
    "vat_validated_address": "CALLE MAYOR 1, 28001 MADRID",
    "vat_checked_at": "2026-05-17T10:11:05Z",
    "financial_summary": null,
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…"
      }
    ],
    "beneficial_owners": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "entity_type": "person",
        "roles": ["UBO"],
        "ownership_min_shares": "75.00",
        "ownership_max_shares": "75.00",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "effective_ownership_percent": 75.0
      }
    ],
    "addresses": [],
    "industries": [],
    "accounts": [],
    "registry_data": {},
    "user_provided_data": {},
    "confirmed_by_user_at": "2026-05-17T10:11:02Z",
    "last_console_edit_at": null,
    "is_editable": false
  },
  "ownership_structure": null,
  "warnings": []
}

Documento KYB

Devolvido por cada nó que recolhe documentos de apoio KYB. Surge como document_verifications[] em GET /v3/session/{sessionId}/decision/ para sessões de empresas: uma entrada por node_id, com items[] a listar cada documento carregado. Origem: kyb/serializers/kyb.py:1053-1068 (DocumentVerificationV3Serializer); cada item segue kyb/serializers/kyb.py:811-851 (KYBDocumentResponseSerializer).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Estado agregado dos documentos deste nó: `Approved` apenas quando todos os documentos do pipeline estão aprovados; `Declined` se algum estiver recusado; `In Review` nos restantes casos; `Not Finished` enquanto estiver pendente. Ver Enumeração de estados.	`"Approved"`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_kyb_documents"`
`items`	array de objetos de item de documento KYB	Não	Uma entrada por documento carregado ou solicitado.	`[…]`
`groups`	object	Não	Contagens por grupo de documentos: `{ <group_name>: { total, approved, pending, declined, in_review, other, missing } }`.	`{ "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }`
`required_groups`	array de strings	Não	Grupos de documentos exigidos pela configuração do fluxo.	`["incorporation_certificate", "shareholder_register"]`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`

Objeto de item de documento KYB

Campo	Tipo	Anulável	Descrição
`uuid`	string (UUID)	Não	Identificador interno do documento.
`document_type`	string	Sim	Grupo de alto nível (`incorporation_certificate`, `shareholder_register`, …).
`document_subtype`	string	Sim	Subtipo específico do fornecedor.
`document_group`	string	Sim	Espelho de `document_type` (alias mantido por clareza).
`file_url`	string (URL)	Sim	URL pré-assinado para o ficheiro limpo.
`original_filename`	string	Sim	Nome do ficheiro tal como foi carregado.
`file_size`	integer	Sim	Tamanho do ficheiro em bytes.
`status`	string	Não	Estado do documento (`FeatureStatusChoices`).
`created_at`	string (ISO 8601)	Não	Data e hora do carregamento.
`cross_check_result`	object	Sim	Veredicto da validação cruzada com o registo ou com outros documentos.
`document_metadata`	object	Sim	Mesma estrutura de metadados filtrados que o `document_metadata` de POA.
`description`	string	Sim	Descrição fornecida pelo revisor ou pelo sistema.
`is_requested`	boolean	Não	`true` quando o fluxo esperava este documento.
`ocr_data`	object	Sim	Campos extraídos por OCR, quando disponíveis.
`is_console_upload`	boolean	Não	`true` quando o documento foi carregado por um revisor da consola (excluído do veredicto agregado).
`is_confirmed`	boolean	Não	`true` quando o revisor confirmou explicitamente o documento.

{
  "status": "Approved",
  "node_id": "first_kyb_documents",
  "items": [
    {
      "uuid": "e1f1e2c2-cccc-4d2c-9eb6-fdc6c7c92ef9",
      "document_type": "incorporation_certificate",
      "document_subtype": "registro_mercantil_extract",
      "document_group": "incorporation_certificate",
      "file_url": "https://<media-host>/.../incorporation.pdf?signature=...",
      "original_filename": "incorporation_certificate.pdf",
      "file_size": 256412,
      "status": "Approved",
      "created_at": "2026-05-17T10:08:00Z",
      "cross_check_result": { "matches_registry_name": true, "matches_registration_number": true },
      "document_metadata": {
        "file_size": 256412,
        "content_type": "application/pdf",
        "is_signed": true,
        "is_tampered": false
      },
      "description": null,
      "is_requested": true,
      "ocr_data": { "company_name": "Sante Clinics SL", "registration_number": "B12345678" },
      "is_console_upload": false,
      "is_confirmed": true
    }
  ],
  "groups": {
    "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }
  },
  "required_groups": ["incorporation_certificate", "shareholder_register"],
  "warnings": []
}

Pessoa-chave KYB

Devolvido por cada nó de pessoas-chave num fluxo KYB. Surge como key_people_checks[] em GET /v3/session/{sessionId}/decision/ para sessões de empresas. Origem: kyb/serializers/kyb.py:967-1050 (KeyPeopleCheckV3Serializer).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enumeração de estados.	`"Approved"`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_key_people"`
`registry`	object	Não	`{ officers[], beneficial_owners[] }` extraídos do registo. Os dirigentes seguem `KYBPersonResponseSerializer` (`kyb/serializers/kyb.py:533-645`); os beneficiários efetivos seguem `KYBBeneficialOwnerResponseSerializer` (`kyb/serializers/kyb.py:648-788`, que acrescenta `date_of_birth`, `country_of_birth`, `email`, `company_name`, `registration_number`, `entity_type`, `roles`, `ownership_min_shares`, `ownership_max_shares`, `child_beneficial_owners`, `effective_ownership_percent`). Ambos incluem o enriquecimento AML + KYC por parte (`aml_status`, `kyc_status`, `kyc_session_url`, `kyc_session_id`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`, `kyc_document_type`, `kyc_nationality`, `kyc_liveness_passed`, `kyc_verified_at`, `kyc_aml_categories`, `kyc_notification_sent_at`).	`{ "officers": [...], "beneficial_owners": [...] }`
`submitted`	object	Não	`{ parties[] }`: entradas que a empresa confirmou ou submeteu através do fluxo de pessoas-chave (linhas `BusinessParty` com `source=USER`). Cada parte segue `BusinessPartySubmissionResponseSerializer` (`kyb/serializers/party.py:146-194`): `uuid`, `entity_type`, `source`, `name`, `first_name`, `last_name`, `company_name`, `registration_number`, `email`, `nationality`, `phone_number`, `date_of_birth`, `position`, `custom_fields`, `is_active`, `is_skipped`, `requires_verification`, `roles[]` (`{ role, ownership_percent, voting_percent }`), `kyc_session_id`, `kyc_session_status`, `kyc_session_url`, `kyc_session_deleted`, `kyb_sub_session_id`, `kyb_sub_session_status`, `kyb_sub_session_url`, `kyb_sub_session_deleted`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`. `kyc_session_deleted` e `kyb_sub_session_deleted` indicam que uma sessão filha foi eliminada: o estado fica congelado no valor que tinha, o respetivo `*_session_url` é devolvido como `null` porque a ligação deixou de resolver, e a parte deixa de bloquear a sessão principal (a verificação passa a `In Review`). Limpe-o com `PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`.	`{ "parties": [...] }`
`ubo_kyc_summary`	object	Sim	Contagens dos UBO ativos com KYC associado: `{ total, approved, flagged, pending }`. `null` quando nenhum UBO ativo tem KYC associado.	`{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`

{
  "status": "Approved",
  "node_id": "first_key_people",
  "registry": {
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "appointment_date": "2018-03-22",
        "termination_date": null,
        "is_active": true,
        "address": "Calle Mayor 1, 28001 Madrid",
        "aml_status": "Approved",
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
        "verification_workflow_type": "kyc",
        "verification_workflow_id": "11111111-1111-1111-1111-111111111111",
        "verification_workflow_label": "KYB officer KYC",
        "verification_workflow_features": [
          { "feature": "ID_VERIFICATION", "status": "Approved" },
          { "feature": "LIVENESS", "status": "Approved" },
          { "feature": "FACE_MATCH", "status": "Approved" }
        ],
        "didit_internal_id": "user-12345",
        "kyc_document_type": "Passport",
        "kyc_nationality": "ESP",
        "kyc_liveness_passed": true,
        "kyc_verified_at": "2026-05-17T10:10:11Z",
        "kyc_aml_categories": [],
        "kyc_notification_sent_at": "2026-05-15T08:00:00Z"
      }
    ],
    "beneficial_owners": []
  },
  "submitted": {
    "parties": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "entity_type": "person",
        "source": "USER",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "company_name": null,
        "registration_number": null,
        "email": "maria.garcia@example.com",
        "nationality": "ESP",
        "phone_number": null,
        "date_of_birth": "1990-05-12",
        "position": "Administrador único",
        "custom_fields": {},
        "is_active": true,
        "is_skipped": false,
        "requires_verification": true,
        "roles": [
          { "role": "UBO", "ownership_percent": 75.0, "voting_percent": null }
        ],
        "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
        "kyc_session_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "kyb_sub_session_id": null,
        "kyb_sub_session_status": null,
        "kyb_sub_session_url": null,
        "verification_workflow_type": "kyc",
        "verification_workflow_id": "11111111-1111-1111-1111-111111111111",
        "verification_workflow_label": "KYB officer KYC",
        "verification_workflow_features": [
          { "feature": "ID_VERIFICATION", "status": "Approved" },
          { "feature": "LIVENESS", "status": "Approved" }
        ],
        "didit_internal_id": "user-12345"
      }
    ]
  },
  "ubo_kyc_summary": { "total": 1, "approved": 1, "flagged": 0, "pending": 0 },
  "warnings": []
}

Campos ao nível da decisão

Estas chaves ficam junto às matrizes de funcionalidades em GET /v3/session/{sessionId}/decision/ e dentro de decision num webhook.

Campo	Tipo	Anulável	Descrição
`status_override`	objeto	Sim	`{ overridden_at, automatic_status }` depois de um revisor ter definido `status` manualmente; `null` quando o estado é o automático.
`decision_trace`	objeto	Não	Como o estado foi alcançado: `status`, `decided_by` (`manual`, `automatic` ou `investigator`), `decided_at`, `automatic_status`, `terminal_node_id`, `actor`, `warning_counts` e `status_warnings`.
`linked_records`	objeto	Sim	Resumos de `same_face`, `earlier_verifications` e `networks`; `null` quando não há nada para mostrar.
`biometric_retention`	objeto	Não	`{ jurisdictions, deletes_at }`. `deletes_at` é a data em que são eliminados os dados biométricos captados em direto durante a sessão, e `null` quando ainda não se aplica uma data.
`database_validation_not_performed_reason`	objeto	Sim	`{ code, message }` que explica porque motivo uma validação de base de dados configurada não produziu resultado.
`assignee`, `waiting_since`, `sla_due_at`	objeto, data e hora	Sim	O revisor da Consola a quem está atribuída a sessão e o respetivo relógio de revisão; o relógio é `null` a menos que a sessão esteja `In Review`.
`shared_from_session`, `shared_from_session_number`	UUID, inteiro	Sim	A sessão de origem de uma sessão importada.
`sandbox_scenario`	cadeia de caracteres	Sim	O cenário com que foi criada uma sessão de sandbox.
`fraud_check`	objeto	Sim	O resultado da API Fraud Check; `null` para todas as outras sessões.
`full_session_video`, `full_session_video_recorded_at`	URL, data e hora	Sim	A gravação e a data e hora em que foi feita. Devolvidos apenas quando a sua organização grava vídeo da sessão completa.

Consulte Obter sessão para saber como os ler.

Consentimento biométrico

Cada decisão de Verificação de utilizadores e cada webhook de sessão inclui um único objeto biometric_consent (não um array): se a sessão exigiu consentimento biométrico explícito, o motivo e a prova da resposta. É null quando a sessão nunca foi avaliada, por exemplo num fluxo sem captura facial. Origem: BiometricConsentDecisionSerializer (sessions/serializers/biometric_consent.py). Quando o passo aparece e o que significa cada caso é explicado em Consentimento biométrico. Os campos sem valor registado são null, nunca uma string vazia.

Campo	Tipo	Descrição
`required`	booleano	Se a sessão tem de recolher consentimento biométrico explícito. Nunca volta a `false`.
`trigger`	string (enumeração) \| null	Por que motivo é exigido o consentimento, ou como foi obtido: `declared_state`, `ip_state`, `ip_unknown`, `document_issuer`, `forced` (o modo da aplicação é Always), `customer_collected` (enviou `biometric_consent` na criação da sessão). `null` enquanto não for exigido.
`status`	string (enumeração)	`not_required`, `pending` (exigido, não dado), `given`, `declined` (foi registada uma recusa; nenhum ecrã da Didit oferece atualmente uma opção de recusa).
`given_at`	string (ISO 8601) \| null	Quando o consentimento foi dado. Em `customer_collected`, o `given_at` que enviou.
`declined_at`	string (ISO 8601) \| null	Quando foi registada uma recusa.
`text_version`	string \| null	Identificador da versão do texto de consentimento a que a pessoa respondeu, ou o identificador da versão do texto que enviou.
`text_hash`	string \| null	SHA-256 (hexadecimal) do texto exato apresentado, no idioma em que foi apresentado.
`locale`	string \| null	Idioma em que o texto foi apresentado.
`policy_url`	string \| null	A política de dados biométricos à qual o passo fazia ligação.
`step`	string \| null	Passo do fluxo em que a sessão estava quando a pessoa respondeu (por exemplo `LIVENESS`).
`node_id`	string \| null	Nó do grafo do fluxo em que a sessão estava quando a pessoa respondeu.
`ip_address`	string \| null	IP de onde veio a resposta.
`ip_country_code`	string \| null	Código de país ISO 3166-1 alfa-2 do IP da resposta.
`ip_state`	string \| null	Subdivisão ISO 3166-2 do IP da resposta (por exemplo `US-IL`).
`ip_city`	string \| null	Cidade do IP da resposta.
`user_agent`	string \| null	Agente do utilizador do pedido através do qual foi dada a resposta.
`detected_ip_address`	string \| null	IP da pessoa a partir do qual o requisito foi avaliado pela última vez. Pode ser diferente de `ip_address` quando a pessoa respondeu noutro dispositivo.
`detected_country_code`	string \| null	Código de país ISO 3166-1 alfa-2 do IP detetado.
`detected_state`	string \| null	Subdivisão ISO 3166-2 do IP detetado.
`detected_city`	string \| null	Cidade do IP detetado.
`declared_state`	string \| null	Subdivisão ISO 3166-2 que declarou: `user_state`, ou o estado de uma morada nos EUA em `expected_details`.
`document_state`	string \| null	Subdivisão ISO 3166-2 que emitiu o documento de identidade, lida na captura do documento.
`jurisdictions`	array de strings	Estados dos EUA (códigos USPS, por exemplo `IL`) cuja lei biométrica abrange a pessoa. `US` quando as provas situam a pessoa nos EUA mas nenhum estado é conhecido. Vazio quando nenhuma se aplica.
`retention_months`	inteiro \| null	O limite de retenção biométrica mais curto, em meses, entre as `jurisdictions`. `null` quando nenhuma se aplica.
`reason`	string (enumeração) \| null	`BIOMETRIC_CONSENT_UNSUPPORTED_SDK`: o consentimento era exigido e um SDK nativo anterior a 4.10.0, ou um que não indicou a versão, captou uma face sem o passo; `status` fica `pending`, ou `given` se a pessoa concordou mais tarde no fluxo alojado. `BIOMETRIC_CONSENT_DECLINED`: foi registada uma recusa (substitui o motivo do SDK). `null` nos restantes casos, e sempre `null` quando a sessão não exigiu consentimento.
`decline_reason`	string \| null	`BIOMETRIC_CONSENT_DECLINED` quando uma recusa registada terminou a sessão, caso contrário `null`.
`face_data_deleted_at`	string (ISO 8601) \| null	Quando a recusa eliminou as imagens faciais, os vídeos e os modelos faciais da sessão. `null` salvo se tiver sido registada uma recusa.

Uma sessão em Illinois processada por um SDK nativo anterior a 4.10.0, que captou a selfie sem o passo:

{
  "required": true,
  "trigger": "ip_state",
  "status": "pending",
  "given_at": null,
  "declined_at": null,
  "text_version": null,
  "text_hash": null,
  "locale": null,
  "policy_url": null,
  "step": null,
  "node_id": null,
  "ip_address": null,
  "ip_country_code": null,
  "ip_state": null,
  "ip_city": null,
  "user_agent": null,
  "detected_ip_address": "203.0.113.42",
  "detected_country_code": "US",
  "detected_state": "US-IL",
  "detected_city": "Chicago",
  "declared_state": null,
  "document_state": null,
  "jurisdictions": ["IL"],
  "retention_months": 36,
  "reason": "BIOMETRIC_CONSENT_UNSUPPORTED_SDK",
  "decline_reason": null,
  "face_data_deleted_at": null
}

Uma pessoa numa VPN com saída fora dos EUA, que concordou no fluxo alojado:

{
  "required": true,
  "trigger": "declared_state",
  "status": "given",
  "given_at": "2026-10-13T18:31:07.412000Z",
  "declined_at": null,
  "text_version": "bio-consent-2026-10-12",
  "text_hash": "9b2f0c5e4d8a7f61c3e2b4a5d6f7081923a4b5c6d7e8f90a1b2c3d4e5f6a7b8c",
  "locale": "en",
  "policy_url": "https://didit.me/legal/biometric-data-policy",
  "step": "LIVENESS",
  "node_id": "feature_liveness_1",
  "ip_address": "198.51.100.23",
  "ip_country_code": "ES",
  "ip_state": "ES-M",
  "ip_city": "Madrid",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1",
  "detected_ip_address": "198.51.100.23",
  "detected_country_code": "ES",
  "detected_state": "ES-M",
  "detected_city": "Madrid",
  "declared_state": null,
  "document_state": null,
  "jurisdictions": ["IL"],
  "retention_months": 36,
  "reason": null,
  "decline_reason": null,
  "face_data_deleted_at": null
}

Referência dos estados

Dois conjuntos de valores relacionados partilham o nome de campo status. Todos os objetos de relatório por funcionalidade desta página usam o enum de nível de funcionalidade. O status de nível superior da sessão principal usa o enum de sessão, mais abrangente.

Estados ao nível da funcionalidade

Usados pelo campo status de todos os objetos de relatório. Origem: common/config/choices.py:343-348 (FeatureStatusChoices).

Valor	Significado
`Not Finished`	A funcionalidade foi provisionada, mas o utilizador ainda não a concluiu.
`Approved`	A funcionalidade passou em todas as verificações.
`Declined`	A funcionalidade falhou pelo menos uma verificação crítica (ver `warnings[]` com `log_type: "error"`).
`In Review`	A funcionalidade acionou sinais de falha não crítica e aguarda revisão manual (ver `warnings[]` com `log_type: "warning"`).
`Resub Requested`	Um revisor pediu ao utilizador que voltasse a submeter esta funcionalidade.

A verificação de telefone, de e-mail e de identidade pode também apresentar Expired quando o respetivo passo excede o tempo limite (PhoneStatusChoices em common/config/choices.py:377-382, EmailStatusChoices em common/config/choices.py:434-439).

Estados ao nível da sessão

Usados pelo status de nível superior da sessão principal. Origem: common/config/choices.py:106-117 (StatusChoices).

Valor	Significado
`Not Started`	A sessão foi criada, mas o utilizador ainda não a iniciou.
`In Progress`	O utilizador iniciou o fluxo; o resultado ainda não foi determinado.
`Approved`	A sessão passou em todas as verificações.
`Declined`	A sessão falhou pelo menos uma verificação crítica.
`In Review`	A sessão aguarda revisão manual.
`Expired`	A sessão expirou antes de ser concluída.
`Abandoned`	O utilizador abandonou o fluxo sem o concluir.
`Kyc Expired`	A janela de validade do KYC expirou (usado em fluxos de reverificação).
`Resubmitted`	O utilizador voltou a submeter após uma recusa anterior; esta sessão é substituída por uma mais recente.
`Awaiting User`	O sistema aguarda uma ação por parte do utilizador (por exemplo, a introdução de um OTP).

Os valores terminais da sessão são Approved, Declined, In Review, Expired, Kyc Expired e Abandoned. Uma sessão pode atingir a sua decisão global enquanto uma funcionalidade individual permanece In Review.