> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Modelos de dados > Esquemas JSON canónicos dos relatórios da Didit: NFC, ID, prova de vida, correspondência facial, AML, IP, POA, telefone, e-mail, KYB e pessoas-chave. ## 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](https://docs.didit.me/pt/core-technology/bank-verification/verification-methods.md#ler-o-método-no-resultado)), 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. > [!NOTE] > > 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](#referência-dos-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](#objeto-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:///...`. ## 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"` | ```json theme={null} { "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](#referência-dos-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](https://docs.didit.me/pt/core-technology/id-verification/document-subtypes-id-verification.md). | `"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:///.../portrait.jpg?..."` | | `front_image` | string (URL) | Sim | URL pré-assinado da frente do documento tratada. | `"https:///.../front.jpg?..."` | | `front_video` | string (URL) | Sim | URL pré-assinado do vídeo de captura da frente (quando disponível). | `"https:///.../front.mp4?..."` | | `back_image` | string (URL) | Sim | URL pré-assinado do verso do documento tratado. | `"https:///.../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:///.../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](https://docs.didit.me/pt/core-technology/id-verification/verification-methods.md) 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](https://docs.didit.me/pt/core-technology/id-verification/report-id-verification.md#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](#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. | `[]` | ```json theme={null} { "status": "Approved", "document_type": "Passport", "document_subtype": "PASSPORT_GENERIC", "document_number": "AB1234567", "personal_number": "99999999R", "portrait_image": "https:///.../portrait.jpg?signature=...", "front_image": "https:///.../front.jpg?signature=...", "front_video": null, "back_image": "https:///.../back.jpg?signature=...", "back_video": null, "full_front_image": "https:///.../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`. ```json theme={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:///.../registry_portrait.jpg?signature=...", "face_match_score": 96.4 }, "wallet_verification": null, "warnings": [] } ``` ```json theme={null} { "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](#referência-dos-estados). | `"Approved"` | | `portrait_image` | string (URL) | Sim | URL pré-assinada para a imagem facial extraída do chip. | `"https:///.../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](https://docs.didit.me/pt/core-technology/nfc-verification/warnings-nfc-verification.md#motivos-para-ignorar). 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](https://docs.didit.me/pt/core-technology/nfc-verification/report-nfc-verification.md#campos-jpki). | `null` | | `warnings` | array | Não | Ver [Objeto de aviso](#objeto-de-aviso). | `[]` | ```json theme={null} { "status": "Approved", "portrait_image": "https:///.../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/.../reference.jpg?..."` | | `video_url` | string (URL) | Sim | URL pré-assinado para o vídeo de prova de vida (apenas no modo ativo). | `"https:///.../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](#objeto-de-aviso). | `[]` | ```json theme={null} { "status": "Approved", "method": "PASSIVE", "score": 92.41, "reference_image": "https:///.../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](#referência-dos-estados). | `"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:///.../source.jpg?..."` | | `target_image` | string (URL) | Sim | URL pré-assinado para a imagem alvo (rosto ao vivo) capturada durante a prova de vida. | `"https:///.../target.jpg?..."` | | `node_id` | string \| null | Sim | Identificador do nó do fluxo (V3). | `"first_face_match"` | | `warnings` | array | Não | Ver [Objeto de aviso](#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 } }` | ```json theme={null} { "status": "Approved", "score": 97.83, "source_image_session_id": null, "source_image": "https:///.../source.jpg?signature=...", "target_image": "https:///.../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](#objeto-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](https://docs.didit.me/pt/management-api/biometric-templates/overview.md) 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:///.../matched.jpg?..."` | | `status` | cadeia de caracteres | Sim | Estado de verificação da sessão correspondente (ver [enumeração de estados](#referência-dos-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` | ```json theme={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:///.../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](#referência-dos-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](#objeto-de-aviso). | `[]` | ```json theme={null} { "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](#referência-dos-estados). | `"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](#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. | `{}` | ```json theme={null} { "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](https://docs.didit.me/pt/core-technology/location-verification/overview.md). 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](#referência-dos-estados). | `"Declined"` | | `outcome` | string | Sim | O que aconteceu na tentativa: `verified`, `low_accuracy`, `accuracy_undetermined`, `stale`, `approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `mock_detected`, `outside_geofence`, `in_blocked_area`, `anonymizer_detected`, `skipped`, `replay_rejected` ou `unsupported_client`. | `"outside_geofence"` | | `permission` | string | Sim | O que o sistema concedeu: `granted_precise`, `granted_approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `dismissed` ou `not_requested`. | `"granted_precise"` | | `latitude`, `longitude` | float | Sim | Posição WGS84. `null` quando não há posição. | `48.8566` | | `accuracy_m` | float | Sim | Raio de incerteza, em metros. | `35.0` | | `accuracy_confidence` | string | Sim | `p95`, `p68` ou `unspecified`. | `"p95"` | | `measured_at`, `age_seconds` | datetime, integer | Sim | Quando o dispositivo obteve a 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](#objeto-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](https://docs.didit.me/pt/core-technology/location-verification/report-location-verification.md). ### 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](#referência-dos-estados). | `"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:///.../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](#objeto-de-aviso). | `[]` | ```json theme={null} { "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:///.../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](#referência-dos-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](#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. | | ```json theme={null} { "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](#referência-dos-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](#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. | | ```json theme={null} { "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](#referência-dos-estados). | `"Approved"` | | `node_id` | string \| null | Sim | Identificador do nó do fluxo (V3). | `"first_db_validation"` | | `warnings` | array | Não | Ver [Objeto de aviso](#objeto-de-aviso). | `[]` | ```json theme={null} { "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:///.../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: [, …] }`. | `[…]` | | `node_id` | string \| null | Sim | Identificador do nó do fluxo (V3). | `"first_questionnaire"` | ```json theme={null} { "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](https://docs.didit.me/pt/core-technology/electronic-signature/overview.md). 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](#objeto-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](https://docs.didit.me/pt/core-technology/electronic-signature/report-electronic-signature.md) 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`](#verificação-de-prova-de-vida), 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"` | ```json theme={null} { "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](#verificação-de-prova-de-vida) e [Correspondência facial](#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](#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](#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](#referência-dos-estados)). | `"Approved"` | ```json theme={null} { "session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "status": "Approved", "liveness_checks": [ { "status": "Approved", "method": "PASSIVE", "score": 95.10, "reference_image": "https:///.../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:///.../source.jpg?signature=...", "target_image": "https:///.../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](#referência-dos-estados). | `"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](#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-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](https://docs.didit.me/pt/business-verification/company-data.md#validação-de-iva-e-número-de-identificação-fiscal). | | `vat_validated_number` | string | Sim | O número que foi verificado, tal como a fonte o conhece. | | `vat_validation_source` | string | Sim | Fonte que 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. | ```json theme={null} { "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](#referência-dos-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](#objeto-de-item-de-documento-kyb) | Não | Uma entrada por documento carregado ou solicitado. | `[…]` | | `groups` | object | Não | Contagens por grupo de documentos: `{ : { 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-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. | ```json theme={null} { "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:///.../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](#referência-dos-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}/`](https://docs.didit.me/pt/sessions-api/update-data#ignorar-uma-parte-de-pessoas-chave). | `{ "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](#objeto-de-aviso). | `[]` | ```json theme={null} { "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](https://docs.didit.me/pt/sessions-api/retrieve-session.md#estado-rastreio-da-decisão-e-campos-de-revisã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](https://docs.didit.me/pt/getting-started/biometric-consent.md). 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: ```json theme={null} { "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: ```json theme={null} { "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). | > [!TIP] > > 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`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.