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 abordam cada objeto de relatório por funcionalidade. O texto do título H3 é intencionalmente estável para que outros documentos possam ligar-se diretamente a ele.

Verificação de identidade

Devolvido para cada documento KYC/ID que o utilizador submete. 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	Consulte a Enumeração de estados.	`"Approved"`
`document_type`	string	Sim	Classe de 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 pelos documentos aceites nas definições de documentos do fluxo de verificação. 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/nacional extraído por OCR.	`"99999999R"`
`portrait_image`	string (URL)	Sim	URL pré-assinado do recorte facial.	`"https://<media-host>/.../portrait.jpg?..."`
`front_image`	string (URL)	Sim	URL pré-assinado da frente do documento tratada.	`"https://<media-host>/.../front.jpg?..."`
`front_video`	string (URL)	Sim	URL pré-assinado do vídeo de captura da frente (quando disponível).	`"https://<media-host>/.../front.mp4?..."`
`back_image`	string (URL)	Sim	URL pré-assinado do verso do documento tratado.	`"https://<media-host>/.../back.jpg?..."`
`back_video`	string (URL)	Sim	URL pré-assinado do vídeo de captura do verso.	`null`
`full_front_image`	string (URL)	Sim	Captura da frente sem recorte (imagem de enquadramento completo).	`"https://<media-host>/.../full_front.jpg?..."`
`full_back_image`	string (URL)	Sim	Captura do verso sem recorte (imagem de enquadramento completo).	`null`
`front_image_camera_front`	string (URL)	Sim	Imagem da câmara frontal captada ao mesmo tempo que a frente do documento.	`null`
`back_image_camera_front`	string (URL)	Sim	Imagem da câmara frontal captada 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 ao selfie captado 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 localizado do país emissor.	`"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/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 abrangidos 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`	matriz de cadeias de caracteres (URL)	Não	URLs pré-assinados de quaisquer ficheiros adicionais carregados.	`[]`
`matches`	matriz 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	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` caso contrário.	`"mitid"`
`fallback_from`	object \| null	Sim	Motivo pelo qual um método diferente de documento terminou a etapa de ID: `{ method, reason, action }`. Definido quando uma consulta ou uma autenticação com carteira falhou: na linha recusada quando a configuração do país era `decline` (`action: "decline"`), e no documento de verificação 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 que não seja documento.	`{ "method": "id_lookup", "reason": "no_match", "action": "decline" }`
`id_lookup`	object \| null	Sim	Dados da fonte, presentes apenas quando `verification_method` é `id_lookup`: `source` (a fonte exata consultada: um registo governamental na maioria dos países, um ficheiro de agência de crédito ou de registos de residência em alguns), `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`; versões anteriores podem incluir uma linha `provider` com `error`), `source_errors[]` (ambiente de pré-produção atual: diagnósticos de fonte separados; confirmar a disponibilização em produção), `registry_portrait` (URL pré-assinada, apenas para fontes que devolvem uma) e `face_match_score`.	ver abaixo
`wallet_verification`	object \| null	Sim	Dados da credencial, presentes 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é-assinada quando a carteira partilha uma) 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`), reportadas quer um aviso tenha sido acionado quer não. Cada uma inclui: `score` (0-100, quanto mais alto, mais provável que seja genuíno; o valor mais baixo, que é o valor utilizado pela decisão), `front`, `back`, `decline_threshold`, `review_threshold`, `bucket` (`approve`, `review`, `decline` ou `null`). Os limiares e a categoria são guardados no momento da avaliação; os três são `null` quando não há dados históricos de avaliação, mas as pontuações guardadas continuam visíveis. `null` quando a verificação não foi executada. Consulte 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	Consulte 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 foram apresentados à pessoa para revisão, guardado junto aos valores confirmados para que possa compará-los. `null` quando não foi pedido à pessoa que os revisse.
`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 diferente de documento. Apenas as chaves específicas do método mudam: tudo o que uma leitura de documento preenche passa a ser preenchido a partir do registo da fonte ou dos atributos da carteira, e as chaves que não se aplicam ficam 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 do chip de um documento de identidade: um chip ICAO 9303 de ePassport ou eID, ou uma leitura do Japan My Number Card através do JPKI (chip_protocol: "jpki"). Aparece como nfc_verifications[] em GET /v3/session/{sessionId}/decision/ (um por registo KYC-pai). 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	Consulte Enumeração de estados.	`"Approved"`
`portrait_image`	string (URL)	Sim	URL pré-assinada para a imagem facial extraída do chip.	`"https://<media-host>/.../nfc_portrait.jpg?..."`
`signature_image`	string (URL)	Sim	URL pré-assinada para a imagem da assinatura extraída do chip (quando está guardada no chip).	`null`
`chip_data`	object	Sim	Dados pessoais analisados dos Data Groups do chip, achatados (`kyc/utils/epassport.py:165-212`): `dgs` (Data Groups lidos), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (código MRZ do documento), `document_number`, `optional_data`, dígitos de controlo MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, `mrz_type` (`TD1`/`TD2`/`TD3`); mais `place_of_birth` e `address` (e `full_name` / `full_name_non_latin` para nomes não latinos) quando o chip contém o DG11; essas chaves estão ausentes caso contrário. `null` quando a etapa NFC foi ignorada.	`{ "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) remonta a uma CSCA válida do país emissor (e que o DSC não está revogado nem expirado); `dg_integrity` valida que os hashes de cada Data Group correspondem ao SOD. Se ambos forem `true`, o chip é genuíno e não foi adulterado.	`{ "sod_integrity": true, "dg_integrity": true }`
`certificate_summary`	objeto	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`), além de 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`	booleano	Não	`true` quando este passo NFC foi explicitamente omitido em vez de ser lido; `skip_reason` indica o motivo.	`false`
`skip_reason`	string	Sim	Motivo pelo qual o passo foi omitido, definido apenas 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 inclui também 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 ICAO 9303 de passaporte eletrónico ou de eID) ou `jpki` (Cartão My Number do Japão). Para `jpki`, `portrait_image`, `signature_image`, `chip_data`, `authenticity` e `certificate_summary` são `null`. Também definido em passos omitidos.	`"icao"`
`jpki`	objeto	Sim	O que uma leitura do Cartão My Number 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 omitidos e quando o passo foi encerrado 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, estende LivenessV2Serializer em face/serializers/face.py:216-298).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enumeração de estado.	`"Approved"`
`method`	string (enumeração)	Sim	`ACTIVE_3D`, `FLASHING` ou `PASSIVE` (`LivenessMethodChoices`, `common/config/choices.py:514-517`). A prova passiva é executada quando as sessões em computador sã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 facial de referência do utilizador.	`"https://<media-host>/.../reference.jpg?..."`
`video_url`	string (URL)	Sim	URL pré-assinado para o vídeo de prova de vida (apenas no modo ativo).	`"https://<media-host>/.../liveness.webm?..."`
`age_estimation`	float	Sim	Idade estimada (em anos) do maior rosto na imagem de referência.	`34.2`
`matches`	array 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 com modelo retido tem `vendor_user_id`, `vendor_data` e `biometric_template_id`; os seus 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 facial da prova de vida passiva (normalizada para uma percentagem).	`87.50`
`face_luminance`	float (0-100)	Sim	Pontuação de luminosidade facial da 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": []
}

Correspondência facial

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

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enumeração de estado.	`"Approved"`
`score`	float (0-100)	Sim	Semelhança, arredondada a 2 casas decimais. Quando o fornecedor devolve apenas um `unmatched_faces[].Confidence`, é convertida 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`	objeto	Sim	Indica se os `eyes`, `mouth` e `face` estão cobertos 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

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

Campo	Tipo	Nulo	Descrição	Exemplo
`request_id`	cadeia de caracteres (UUID)	Não	O id da sessão guardada 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`	cadeia de caracteres	Sim	`vendor_data` do pedido, devolvido sem alterações.	`null`
`metadata`	objeto	Sim	`metadata` do pedido, devolvido sem alterações.	`null`
`created_at`	cadeia de caracteres (ISO 8601)	Não	Data e hora do pedido no servidor.	`"2026-06-12T01:04:42.763237+00:00"`

Objeto face_search:

Campo	Tipo	Nulo	Descrição	Exemplo
`status`	cadeia de caracteres	Não	`Declined` apenas quando é disparado um aviso `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST`; `Approved` nos restantes casos. 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 (as entradas da lista de bloqueio surgem primeiro, com `search_type=blocklisted_or_approved`).	`[…]`
`user_image`	objeto	Não	Resultado da deteção para a imagem enviada: `{ entities: [{ bbox, confidence }], best_angle }`, com uma entidade por face detetada.	`{ "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 em tempo de execução inclui ainda `feature`, que é sempre `"LIVENESS"` (`apis/views/face_search.py:332-341`).	`[]`

Objeto de correspondência de Pesquisa facial

Campo	Tipo	Nulo	Descrição	Exemplo
`session_id`	cadeia de caracteres (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, apresentado na consola; `null` em correspondências que não são de sessão.	`1024`
`similarity_percentage`	número decimal (0-100)	Não	Semelhança entre a face enviada e a face correspondente.	`96.42`
`source`	cadeia de caracteres (enumeração)	Não	Origem da face correspondente: `session` (sessão de verificação ou chamada autónoma guardada), `imported` (carregamento direto de uma face para o perfil do utilizador), `list_entry` (face associada a uma lista) e `retained_template` (template biométrico sem imagem, retido depois de a sessão de origem ser eliminada).	`"session"`
`vendor_data`	cadeia de caracteres	Sim	O `vendor_data` da sessão correspondente ou o do utilizador associado, nas correspondências `imported` e `retained_template`.	`"user-12345"`
`vendor_user_id`	cadeia de caracteres (UUID)	Sim	O utilizador associado. `null` nas correspondências `list_entry` e nas sessões sem utilizador.	`"2f7c1a9e-…"`
`biometric_template_id`	cadeia de caracteres (UUID)	Sim	O template retido que foi correspondido. Definido apenas nas correspondências `retained_template`; use-o com `GET`/`DELETE /v3/biometric-templates/{id}/`.	`null`
`verification_date`	cadeia de caracteres (ISO 8601)	Sim	Quando a face correspondente foi capturada ou, no caso de um `retained_template`, quando foi retida; `null` nas correspondências `list_entry`.	`"2024-11-04T09:14:02Z"`
`user_details`	objeto	Sim	`{ full_name, document_type, document_number }`, obtido da verificação do documento da sessão correspondente. Nas correspondências `imported`, apenas `full_name` está preenchido. É `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`	cadeia de caracteres (URL)	Sim	Face de referência do utilizador correspondente: URL pré-assinado quando `save_api_request=true`, caso contrário o caminho de armazenamento em bruto. É sempre `null` nas correspondências `retained_template`, pois não guardam imagem.	`"https://<media-host>/.../matched.jpg?..."`
`status`	cadeia de caracteres	Sim	Estado de verificação da sessão correspondente (ver enumeração de estados); `null` nas correspondências que não são de sessão.	`"Approved"`
`is_blocklisted`	booleano	Não	Indica se a face correspondente está na sua lista de bloqueio de faces. É sempre `false` nas correspondências `retained_template`; uma face bloqueada é reportada separadamente como uma correspondência `list_entry`.	`false`
`is_allowlisted`	booleano	Não	Indica se a face correspondente está em alguma das suas listas de permissão.	`false`
`api_service`	cadeia de caracteres (enumeração)	Sim	Tipo da API autónoma, em maiúsculas, da sessão correspondente (por exemplo, `PASSIVE_LIVENESS` ou `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

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

Campo	Tipo	Nulo	Descrição	Exemplo
`status`	cadeia de caracteres	Não	Ver enumeração de estados.	`"Approved"`
`total_hits`	inteiro	Não	Número de correspondências na triagem (está sempre presente e assume `0` por defeito).	`2`
`entity_type`	cadeia de caracteres (enumeração)	Sim	`person` ou `company` (`EntityTypeChoices`, `common/config/choices.py:675-677`).	`"person"`
`hits`	array de objetos	Não	Uma entrada por correspondência. Campos principais: `id`, `caption`, `match` (booleano), `target` (booleano \| null, indica se a entidade é o alvo direto da listagem), `match_score` (número decimal de 0 a 100, confiança de identidade), `risk_score` (número decimal de 0 a 100, risco da entidade), `score` (número decimal 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, aliases, 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 para atualizar o estado da correspondência AML, `AMLHitStatusChoices`).	`[…]`
`score`	float (0-100)	Sim	Pontuação global da triagem: o `risk_score` mais alto entre as correspondências não marcadas como `False Positive` (`aml/services/aml.py:832-842`); `0` quando todas as correspondências são falsas positivas. `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. Uma data de faturação, não uma data de triagem.	`null`
`last_ongoing_screening_at`	string (ISO 8601)	Sim	Quando a monitorização contínua concluiu pela última vez uma reavaliação deste registo, tenha o resultado mudado ou não. `null` quando nunca foi reavaliado; nunca é preenchido retroativamente.	`"2026-09-12T04:03:11Z"`
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601)	Sim	Atualização mais recente das bases de dados AML indicada pelo fornecedor para essa triagem. `null` quando não foi indicada nenhuma data de base de dados; nunca é estimada.	`null`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_aml"`
`warnings`	array	Não	Ver 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 por cada localização de rede capturada. Aparece como ip_analyses[] em GET /v3/session/{sessionId}/decision/, tanto em sessões KYC como em sessões KYB. Origem: kyc/serializers/location.py:196-243 (IPAnalysisSerializerV3).

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enum de estado.	`"Approved"`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_ip_analysis"`
`device_brand`	string	Sim	Marca do dispositivo, derivada do agente do utilizador.	`"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 alto nível (`mobile`, `desktop`, `tablet`).	`"mobile"`
`device_fingerprint`	string	Sim	Hash de impressão digital do dispositivo, estável por dispositivo.	`"f2a3…"`
`ip_country`	string	Sim	Nome do país resolvido a partir do endereço IP.	`"Spain"`
`ip_country_code`	string (ISO 3166-1 alpha-2)	Sim	Código do país resolvido a partir do endereço IP.	`"ES"`
`ip_state`	string	Sim	Região / estado resolvido a partir do endereço IP.	`"Comunidad de Madrid"`
`ip_city`	string	Sim	Cidade resolvida a partir do endereço IP.	`"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 IP 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 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 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 horária 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 falta qualquer um dos dois lados.	`{ "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 identidade 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 comprovativo de morada, geocodificada.	`{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }`
`matches`	array de objetos	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 também incluem `recovery_similarity`, `tls_ja4_corroborated` e `recovery_gate_reason`). Limitado a 5 correspondências de IP e 5 de dispositivo.	`[]`
`warnings`	array	Não	Ver Objeto de aviso.	`[]`
`browser_version`, `os_version`	string	Sim	Versões do navegador e do sistema operativo, obtidas a partir do agente do utilizador.	`"17.4"`
`user_agent`, `accept_language`	string	Sim	A cadeia de agente do utilizador 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 decorreu e a respetiva 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 por 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 Enumeração de status.	`"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 leitura, e os segundos até a Didit a receber.	`2`
`source`, `platform`, `sdk_version`	string	Sim	De onde veio a leitura, o cliente que a produziu e a respetiva 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 leitura corresponde.	`"FR"`
`geofence`, `inside_geofence`, `geofence_basis`, `inside_areas`, `blocked_areas`	object, boolean, string, arrays	Sim	O resultado por país e por á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 constam do relatório de verificação de localização.

Comprovativo de morada

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

Campo	Tipo	Anulável	Descrição	Exemplo
`status`	string	Não	Consulte Enumeração de status.	`"Approved"`
`issuing_state`	string (ISO 3166-1 alpha-3)	Sim	Código do país do emissor 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` como alternativa, nunca a `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` como alternativa, nunca a `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 existe.	`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`, além de 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 (tal como foi escrita).	`"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é-assinados 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 contar 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/ tanto para sessões KYC como 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 Enumeração de estados.	`"Approved"`
`phone_number_prefix`	string	Não	Prefixo do país em E.164 (com `+`).	`"+34"`
`phone_number`	string	Não	Número do assinante sem o prefixo.	`"612345678"`
`full_number`	string	Não	Número completo em E.164 (`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 traduzido.	`"Spain"`
`carrier`	objeto	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 de `voip`, `isp`, `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 do OTP (envio inicial mais reenvios).	`1`
`verified_at`	string (ISO 8601)	Sim	Data e hora em que o OTP foi introduzido com sucesso.	`"2026-05-17T10:14:02Z"`
`lifecycle`	array de objetos	Não	Eventos cronológicos: tentativas de envio, callbacks de entrega, verificações de código e o evento de estado final. Cada evento é `{ type, timestamp, details, fee }`. Os tipos de evento vêm de `PhoneEventChoices`.	`[…]`
`matches`	array de objetos	Não	Correspondências do 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`	objeto	Sim	Sinais de inteligência do telefone. Presente apenas quando o complemento de inteligência foi executado para o número.
`phone_social`	objeto	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/ tanto para sessões KYC como 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 Enumeração de estados.	`"Approved"`
`email`	string	Não	Endereço de e-mail submetido.	`"maria.garcia@example.com"`
`is_breached`	boolean	Não	`true` quando o e-mail aparece numa violação de dados conhecida.	`false`
`breaches`	array de objetos	Não	Detalhe por violação 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 sondagem de entrega por SMTP indica que a caixa de correio não aceita e-mails.	`false`
`verification_attempts`	integer	Não	Total de tentativas de verificação do OTP.	`1`
`verified_at`	string (ISO 8601)	Sim	Data e hora em que o OTP foi introduzido com sucesso.	`"2026-05-17T10:15:22Z"`
`lifecycle`	array de objetos	Não	Eventos cronológicos: tentativas de envio, verificações de código e o evento de estado final. Cada evento é `{ type, timestamp, details, fee }`. Os tipos de evento vêm de `EmailEventChoices`.	`[…]`
`matches`	array de objetos	Não	Correspondências do 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`	objeto	Sim	Sinais de inteligência do e-mail. Presente apenas quando o complemento de inteligência foi executado para o endereço.
`email_social`	objeto	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 pesquisa na base de dados feita com 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	Como o resultado foi corroborado: `one_by_one` (resultado de um único serviço), `two_by_two` (dois ou mais serviços distintos confirmaram de forma independente, com correspondência total, 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 ao 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`	matriz de objetos	Não	Uma entrada por cada serviço do catálogo que produziu uma correspondência. Cada entrada pode incluir `service_id`, `service_name`, `validation` (objeto com o veredicto do fornecedor), `outcome_code`, `outcome_detail` e `source_data` (perfil do cidadão depurado: `full_name`, `gender`, `date_of_birth`, `photo` (URL pré-assinada), `signature` (URL pré-assinada), …).	`[…]`
`errors`	matriz 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	Veredicto agregado de correspondência nos 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 do questionário

Devolvida por cada submissão de questionário. Aparece como questionnaire_responses[] em GET /v3/session/{sessionId}/decision/ para sessões KYC e KYB. Origem: questionnaires/serializers/questionnaire.py:591-597 (QuestionnaireResponseV3Serializer, 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`	matriz de cadeias de caracteres	Não	Códigos de idioma em que o questionário é publicado.	`["en", "es"]`
`default_language`	string	Não	Código do idioma predefinido.	`"en"`
`is_active`	boolean	Não	Indica 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 simples).	`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 corresponde a `In Review`).	`"Approved"`
`published_at`	string (ISO 8601)	Sim	Data em que o modelo foi publicado.	`"2026-01-12T11:00:00Z"`
`sections`	matriz de objetos	Não	Secções ordenadas, após a aplicação da travessia do grafo e da filtragem de visibilidade. Cada secção é `{ title, description, items[] }` (title e description vêm do `SECTION_HEADER` de abertura, já pré-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`), mais um campo `answer`, que é `null` quando não há resposta e é omitido nos itens de disposição `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/ para sessões KYC e KYB, apenas quando o fluxo tem o passo. Ao contrário dos outros 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 } e não 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ências e de validação.	`"0e6c2a8e-…"`
`node_id`	string	Não	Identificador do nó do fluxo.	`"feature_signature"`
`status`	string	Não	Fase de 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) ou `aes`. `qes` é um complemento que ainda não está disponível.	`"aes"`
`format`	string	Não	`pdf` para uma assinatura simples, `pades` para avançada (AES).	`"pades"`
`profile`	string	Sim	`PAdES-B-LT` depois de uma assinatura avançada (AES) ser 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 baseia. Vazio numa assinatura simples sem identidade verificada.	`{ "verified": true, … }`
`certificate`	object	Sim	`{ issuer, issued_to, serial, valid_from, valid_until }`. `null` até à assinatura 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, pelo que `channel` e `destination` são `null`.	`{ "channel": "email", … }`
`timestamp`	objeto	Sim	`{ time, qualified, valid }`. `qualified` é sempre `false` para AES. `null` até à assinatura e sempre `null` numa assinatura simples.	`{ "qualified": false, … }`
`documents`	array de objetos	Não	`{ id, uuid, title, 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[].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 string, um booleano no caso de 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 de uma assinatura introduzida por teclado. `null` até ser adotada.	`{ "method": "drawn", … }`
`electronic_signature_consent_at`	string (ISO 8601)	Sim	Quando o signatário aceitou assinar os documentos eletronicamente. Definido quando algum documento tem campos.	`"2026-11-03T10:41:40Z"`
`evidence_file`	string	Sim	Caminho do PDF de prova, 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	O `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 uma.	`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 inclui um subconjunto da estrutura de Liveness check, dentro de um envelope age_estimation: status, method, score, age_estimation, warnings, mais um bloco autónomo user_image de deteção facial. 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/. Origem: 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 de sessão persistido quando `save_api_request=true` (o valor predefinido); caso contrário, um UUID de correlação temporário.	`"3b1f1e2c-…"`
`age_estimation`	objeto	Não	Envelope do resultado: `status` (`Approved` / `Declined`), `method` (é sempre `PASSIVE`), `score` (prova de vida de 0 a 100, anulável), `age_estimation` (idade prevista, em anos, do rosto de maiores dimensões, anulável), `user_image` (`entities[]` com, por rosto, `age`, `bbox` `[x_min, y_min, x_max, y_max]`, `confidence` e `gender`; além de `best_angle`), `warnings[]`.	`{ … }`
`vendor_data`	string	Sim	`vendor_data` ecoado do pedido.	`null`
`metadata`	objeto	Sim	`metadata` ecoado do 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 no 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 de Verificação de prova de vida e Correspondência facial em liveness_checks[] e face_matches[]. O fluxo da sessão está configurado com workflow_type = "biometric_authentication" (WorkflowTypeChoices, common/config/choices.py:636).

Campo	Tipo	Anulável	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` é definido como 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 `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 Enumeração de status).	`"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 de verificação 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	Anulável	Descrição	Exemplo
`status`	string	Não	Ver Enumeração de status.	`"Approved"`
`node_id`	string \| null	Sim	Identificador do nó do fluxo (V3).	`"first_registry"`
`data_resolved`	boolean	Não	`true` quando a consulta ao 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 capitalização comprovada pelo registo: `shareholders[]` e `beneficial_owners[]`, com cada proprietário a incluir a sua identidade no registo, a participação e o `shareholding` canónico.	`{ "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	Anulável	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	A mesma definição que a do 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 / de IVA.
`risk_level`	string	Sim	Classificação de risco fornecida pelo prestador.
`verification_status`	string	Sim	Enumeração interna do estado de verificação.
`is_from_registry`	boolean	Não	`true` quando os dados provêm do registo (em oposição à 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 da empresa.
`registered_capital`	string	Sim	Capital social registado, como texto legível.
`registered_capital_amount`	string (decimal)	Sim	Montante do capital social registado, analisado.
`registered_capital_currency`	string (ISO 4217)	Sim	Código da moeda.
`website`	string (URL)	Sim	Sítio Web 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	Serviço de registo / região.
`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 do `tax_number` quando não existe número de IVA: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` ou `not_applicable`. Ver Validação de IVA e de número 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 decidiu 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 esta 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 não foi executada nenhuma verificação.
`financial_summary`	object	Sim	Instantâneo dos principais indicadores financeiros mais recentes, quando fornecido pelo registo.
`officers`	matriz de objetos	Não	Lista de dirigentes adequada para B2C: `{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`.
`beneficial_owners`	matriz de objetos	Não	Lista de beneficiários efetivos (UBO) 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`	matriz de objetos	Sim	Detalhe de cada morada obtido no registo.
`industries`	matriz de objetos	Sim	Classificações no estilo SIC/NAICS.
`accounts`	matriz 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, factos 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 provenientes do registo puderem ainda 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. Aparece como document_verifications[] em GET /v3/session/{sessionId}/decision/ para sessões de empresas, com uma entrada por node_id, e 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 fluxo estão aprovados; `Declined` se algum estiver recusado; `In Review` nos restantes casos; `Not Finished` enquanto estiver pendente. Consulte a 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 of strings	Não	Grupos de documentos exigidos pela configuração do fluxo.	`["incorporation_certificate", "shareholder_register"]`
`warnings`	array	Não	Consulte o Objeto de aviso.	`[]`

Objeto de item de documento KYB

Campo	Tipo	Pode ser nulo	Descrição
`uuid`	string (UUID)	Não	Identificador interno do documento.
`document_type`	string	Sim	Grupo de nível superior (`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é-assinada 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 por documento (`FeatureStatusChoices`).
`created_at`	string (ISO 8601)	Não	Data e hora do carregamento.
`cross_check_result`	object	Sim	Veredito da verificação cruzada com o registo ou com outros documentos.
`document_metadata`	object	Sim	Mesma estrutura de metadados filtrados do `document_metadata` de POA.
`description`	string	Sim	Descrição fornecida pelo revisor ou pelo sistema.
`is_requested`	boolean	Não	`true` quando o fluxo previu 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 veredito 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. Aparece como key_people_checks[] em GET /v3/session/{sessionId}/decision/ para sessões de empresas. Fonte: kyb/serializers/kyb.py:967-1050 (KeyPeopleCheckV3Serializer).

Campo	Tipo	Pode ser nulo	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_key_people"`
`registry`	object	Não	`{ officers[], beneficial_owners[] }` extraído do registo. Os dirigentes seguem o `KYBPersonResponseSerializer` (`kyb/serializers/kyb.py:533-645`); os beneficiários efetivos seguem o `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 e KYC para cada 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 o `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` / `kyb_sub_session_deleted` assinalam uma sessão filha que foi eliminada: o estado fica congelado no valor que tinha, o `*_session_url` correspondente volta 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` em vez disso). Para limpar este estado, use `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	Consulte o 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.

​Visão geral

​Campos comuns

​Objeto de aviso

​Objetos de relatório

​Verificação de identidade

​Verificação NFC

​Verificação de prova de vida

​Correspondência facial

​Pesquisa facial

​Objeto de correspondência de Pesquisa facial

​Triagem AML

​Análise de IP

​Verificação de localização

​Comprovativo de morada

​Verificação de telefone

​Verificação de e-mail

​Validação de base de dados

​Resposta do questionário

​Assinatura eletrónica

​Estimativa de idade

​Autenticação biométrica

​Registo KYB

​Objeto da empresa

​Documento KYB

​Objeto de item de documento KYB

​Pessoa-chave KYB

​Campos ao nível da decisão

​Consentimento biométrico

​Referência dos estados

​Estados ao nível da funcionalidade

​Estados ao nível da sessão

Visão geral

Campos comuns

Objeto de aviso

Objetos de relatório

Verificação de identidade

Verificação NFC

Verificação de prova de vida

Correspondência facial

Pesquisa facial

Objeto de correspondência de Pesquisa facial

Triagem AML

Análise de IP

Verificação de localização

Comprovativo de morada

Verificação de telefone

Verificação de e-mail

Validação de base de dados

Resposta do questionário

Assinatura eletrónica

Estimativa de idade

Autenticação biométrica

Registo KYB

Objeto da empresa

Documento KYB

Objeto de item de documento KYB

Pessoa-chave KYB

Campos ao nível da decisão

Consentimento biométrico

Referência dos estados

Estados ao nível da funcionalidade

Estados ao nível da sessão