> ## 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.

# Esquema de resposta KYB: referência do payload de decisão

> Esquema KYB da Didit com verificações em registos, pessoas-chave, beneficiários efetivos, documentos e triagens AML. Desde $2.00 por verificação.

Esta página documenta o payload completo devolvido por [`GET /v3/session/{id}/decision/`](https://docs.didit.me/pt/sessions-api/retrieve-session) para uma sessão de Verificação de empresas (KYB). O endpoint é unificado: quando envia um `session_id` de empresa, a resposta inclui `session_kind: "business"` e os arrays de funcionalidades específicos de empresas abaixo.

## Estrutura de nível superior

```json theme={null}
{
  "session_id": "bs_01H...",
  "session_kind": "business",
  "session_number": 89,
  "session_url": "https://verify.didit.me/...",
  "status": "Approved",
  "status_override": null,
  "workflow_id": "wf_kyb_standard",
  "features": ["KYB_REGISTRY", "AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"],
  "vendor_data": "biz-acme-001",
  "metadata": { },
  "callback": null,

  "registry_checks": [ ... ],
  "aml_screenings": [ ... ],
  "document_verifications": [ ... ],
  "key_people_checks": [ ... ],

  "phone_verifications": null,
  "email_verifications": null,
  "questionnaire_responses": null,
  "ip_analyses": null,

  "reviews": [ ],
  "decision_trace": { ... },
  "linked_records": null,
  "contact_details": { ... },
  "expected_details": null,
  "created_at": "...",
  "expires_at": "..."
}
```

Todos os arrays de funcionalidades são de múltiplas instâncias: cada item representa um nó num grafo de fluxo. Null significa que a funcionalidade não estava presente no fluxo desta sessão.

## Campos partilhados de nível superior

| Campo | Tipo | Descrição |
| - | - | - |
| `session_id` | UUID | Identificador único da sessão |
| `session_kind` | enum | Tem sempre o valor `"business"` nas sessões KYB |
| `session_number` | int | Número sequencial dentro da aplicação |
| `session_url` | URL | Ligação de verificação alojada |
| `status` | enum | Estado geral da sessão (ver [estados](https://docs.didit.me/pt/business-verification/statuses.md)) |
| `status_override` | objeto ou null | `{ overridden_at, automatic_status }` quando um revisor definiu `status` manualmente, em vez do que a plataforma teria definido (por exemplo, aprovar uma empresa enquanto uma verificação de pessoa-chave associada está recusada). `null` quando o estado é o automático. Use-o para distinguir uma aprovação manual de uma automática |
| `decision_trace` | objeto | Como a decisão foi tomada: `status`, `decided_by` (`manual`, `automatic` ou `investigator`), `decided_at`, `automatic_status`, `terminal_node_id`, `actor`, `warning_counts` e `status_warnings` (os avisos que definiram o estado) |
| `linked_records` | objeto ou null | Resumo de outros registos ligados à sessão. `null` quando não há nada a mostrar |
| `workflow_id` | UUID | Fluxo que conduziu esta sessão |
| `features` | array de strings | Identificadores das funcionalidades que o fluxo executou (por exemplo, `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`, `PHONE`, `EMAIL`) |
| `vendor_data` | string | O seu identificador da empresa |
| `metadata` | objeto | JSON de formato livre que anexou na criação da sessão |
| `callback` | URL ou null | URL de retorno opcional, para redirecionamento após a verificação |
| `contact_details` | objeto ou null | `{ email, email_lang, send_notification_emails, phone }`, definido quando o fluxo inclui notificações por e-mail ou telefone |
| `expected_details` | objeto ou null | Dados esperados da empresa que forneceu aquando da criação: `company_name`, `registry_country` (`XX` ou `XX-YY` com o estado, para registos de âmbito estadual, por exemplo `US-CA`), `registration_number` |
| `reviews` | array | Notas mais recentes do revisor sobre a sessão |
| `created_at`, `expires_at` | carimbos de data e hora ISO | — |

## `registry_checks[]`

Cada item é uma verificação de registo de empresas (normalmente uma por sessão; várias em fluxos em grafo com KYB recursivo de UBOs empresariais).

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_registry",
  "data_resolved": true,
  "company": { ...see below... },
  "ownership_structure": { },
  "warnings": []
}
```

| Campo | Descrição |
| - | - |
| `status` | Estado do ciclo de vida da funcionalidade (`Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`) |
| `node_id` | Identificador do nó do grafo para esta verificação |
| `data_resolved` | `true` quando o carregamento dos dados do registo terminou ou quando o utilizador forneceu os dados manualmente |
| `company` | Payload completo do registo: ver o **bloco `company`** abaixo |
| `ownership_structure` | A tabela de capital que o registo comprovou quando o nível de propriedade foi entregue: `shareholders[]` e `beneficial_owners[]`, cada um com a mesma identidade no registo e a mesma participação que `company.beneficial_owners[]` (`name`, `entity_type`, `roles`, `ownership_min_shares` / `ownership_max_shares`, ...) e a sua `shareholding` canónica. `null` quando o registo não comprovou nenhuma propriedade. Consulte `company.beneficial_owners` e `company.ownership` para o registo atual |
| `warnings` | Avisos estruturados ou entradas de registo associados a esta verificação do registo. Ver [Avisos de Verificação de empresas (KYB)](https://docs.didit.me/pt/business-verification/warnings.md). |

### Bloco `company`

O objeto company aninhado é a visão completa da entidade jurídica, derivada do registo (e, opcionalmente, editada pelo utilizador):

```json theme={null}
{
  "uuid": "...",
  "node_id": "feature_kyb_registry",
  "status": "Approved",
  "registry_status": "active",
  "data_resolved": true,
  "company_name": "Acme Corporation Limited",
  "registration_number": "12345678",
  "country_code": "GBR",
  "company_type": "Private Limited",
  "incorporation_date": "2010-05-14",
  "registered_address": "1 Main Street, London EC1A 1AA, United Kingdom",
  "tax_number": "SAMPLE-TAX-12345",
  "risk_level": null,
  "verification_status": "verified",
  "is_from_registry": true,
  "fetch_status": "resolved",
  "alternative_names": "Acme Ltd",
  "nature_of_business": "Software publishing",
  "registered_capital": "100000 GBP",
  "website": "https://acme.example",
  "email": "alex.sample@example.com",
  "phone": "+15550101000",
  "legal_entity_identifier": "529900XXXXXXXXXXXXX",
  "location_of_registration": "London",
  "vat_number": "GB980780684",
  "vat_validation_status": "format_valid",
  "vat_validated_number": "GB980780684",
  "vat_validation_source": "format_rules",
  "vat_validated_name": null,
  "vat_validated_address": null,
  "vat_checked_at": "2026-04-16T10:10:00Z",
  "financial_summary": { },
  "officers": [ ... ],
  "beneficial_owners": [ ... ],
  "addresses": [
    {
      "type": "registered",
      "address": "1 Main Street, London EC1A 1AA, United Kingdom",
      "street": "1 Main Street",
      "city": "London",
      "postal_code": "EC1A 1AA",
      "region": null,
      "country_code": "GB",
      "description": null
    }
  ],
  "industries": [
    { "code": "58290", "description": "Other software publishing", "scheme": "UK SIC 2007", "is_primary": true }
  ],
  "accounts": { ... },
  "ownership": {
    "status": "delivered",
    "tier_requested": "ubo",
    "tier_delivered": "ubo",
    "unavailable_reason": null,
    "direct_ownership_complete": true,
    "unresolved": []
  },
  "registry_tier": "ubo",
  "registry_tier_delivered": "ubo",
  "registry_ownership_status": "delivered",
  "registry_monitoring": null,
  "registry_data": { },
  "user_provided_data": { },
  "confirmed_by_user_at": "2026-04-16T10:10:00Z",
  "last_console_edit_at": null,
  "is_editable": false
}
```

| Campo | Descrição |
| - | - |
| `registry_status` | Estado indicado pelo fornecedor (`active`, `dissolved`, `struck_off`, `inactive`, etc.). Ver [estados](https://docs.didit.me/pt/business-verification/statuses.md#estado-do-registo-do-fornecedor) |
| `is_from_registry` | `true` quando os dados provêm de um registo oficial; `false` para introdução manual |
| `fetch_status` | `pending`, `resolved` ou `failed`: estado da consulta ao registo |
| `verification_status` | `verified`, `failed` ou `unknown` |
| `risk_level` | Valor opcional transmitido pela fonte do registo. Normalmente `null`: a Didit não calcula um nível de risco, por isso use `warnings[]` e o `status` da sessão para decidir |
| `registry_monitoring` | A monitorização de registo mais recente da empresa, ou `null` se não existir nenhuma. Preenchida apenas quando a [monitorização de registo](https://docs.didit.me/pt/business-verification/ownership.md#monitorização-de-acionistas-e-ubo) estiver disponível. Campos: `uuid`, `status`, `unavailable_reason`, `enrolled_at`, `cancelled_at`, `last_bill_date`, `next_bill_date`, `last_event_at`, `events_count`, `watched_fields` |
| `is_editable` | `true` enquanto os dados provenientes do registo ainda puderem ser editados pelo utilizador final |
| `registry_data` | O detalhe normalizado do registo da Didit: o resultado da propriedade (`ownership_error`, `section_errors`, `ubo_resolution`), as correções feitas com [update-data](https://docs.didit.me/pt/sessions-api/update-data.md) e os factos do registo que não têm campo próprio. Nunca contém o registo original da fonte. As suas chaves variam consoante a empresa e não são um contrato estável: leia, em vez disso, os campos canónicos |
| `user_provided_data` | Os campos que o utilizador final introduziu ou editou (útil para comparar com os valores do registo em auditorias) |
| `confirmed_by_user_at` | Data e hora em que o utilizador final confirmou ou editou os dados do registo |
| `vat_number` | Número de IVA tal como foi submetido, quando recolhido |
| `vat_validation_status` | Resultado da validação do número de IVA ou, se não houver número, do `tax_number`: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` ou `not_applicable`. Ver [Validação de IVA e de número de identificação 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` / `vat_validation_source` | O número que foi verificado, tal como a fonte o conhece, e a fonte que decidiu o estado (um registo oficial ou `format_rules`) |
| `vat_validated_name` / `vat_validated_address` | Nome e morada registados na fonte, quando esta os divulga |
| `vat_checked_at` | Data e hora da verificação; `null` quando não foi feita nenhuma verificação |
| `officers[]` | Dirigentes com enriquecimento KYC incorporado (ver abaixo) |
| `beneficial_owners[]` | UBOs com enriquecimento KYC incorporado (ver abaixo) |
| `addresses[]` | Todas as moradas que o registo indica, na forma canónica de morada abaixo. `null` quando não indica nenhuma |
| `industries[]` | As atividades em que o registo classifica a empresa, na forma canónica de indústria abaixo. `null` quando não indica nenhuma |
| `accounts` | Datas de entrega de documentos societários, quando reportadas: `last_annual_return_date` e `last_agm_date`. Estas descrevem registos e assembleias, não demonstrações financeiras |
| `ownership` | O resultado do nível de propriedade (acionistas / UBO), na forma canónica abaixo |
| `registry_tier` / `registry_tier_delivered` / `registry_ownership_status` | O nível encomendado, o nível entregue (e faturado) e o resultado da propriedade. Os mesmos valores estão em `ownership` |

### Um formato para todos os países e fontes de registo

A Didit consulta registos de empresas em muitos países, através de várias fontes de registo.
Cada fonte publica o seu próprio formato, mas o bloco `company` tem sempre a mesma forma: as chaves abaixo estão sempre presentes, com os mesmos tipos, independentemente do país e da fonte de onde a empresa provém.
Um facto que o registo não publica é `null`; nunca precisa de criar lógica específica para cada país nem de analisar `registry_data`.
A mesma forma é devolvida pela [decisão](https://docs.didit.me/pt/sessions-api/retrieve-session.md), pelos endpoints autónomos do [registo KYB](https://docs.didit.me/pt/standalone-apis/kyb-registry-ubo.md) e pelo fluxo de verificação alojado.

**Morada** (cada item de `addresses`)

| Campo | Descrição |
| - | - |
| `type` | Em minúsculas. `registered` para a sede social; outros tipos tal como o registo os designa (por exemplo `postal` ou `office`). `null` quando o registo não indica o tipo de morada |
| `address` | A morada completa numa única linha. Está sempre presente |
| `street`, `city`, `postal_code`, `region` | A morada em partes, quando o registo as publica |
| `country_code` | ISO 3166-1 alpha-2 |
| `description` | A designação própria do registo para a morada, quando a fornece |

**Indústria** (cada item de `industries`)

| Campo | Descrição |
| - | - |
| `code` | Código de atividade tal como o registo o imprime |
| `description` | Designação da atividade, quando o registo a publica |
| `scheme` | Sistema de classificação, com um nome por sistema, independentemente da fonte que o indicou (`UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`). Outros sistemas nacionais mantêm o nome que o registo lhes dá; `null` quando o registo não o indica |
| `is_primary` | `true` para a atividade principal. Exatamente uma entrada é a principal |

Quando o registo indica atividades mas nenhuma descrição do negócio, `nature_of_business` é preenchido a partir das designações das atividades.
Os dados de contacto e os nomes alternativos são preenchidos quando estão disponíveis, mas as alterações explícitas feitas pelo utilizador ou pelo revisor têm sempre prioridade.

**Propriedade** (`ownership`)

| Campo | Descrição |
| - | - |
| `status` | `delivered`; `not_held` quando o registo de propriedade respondeu e não lista esta empresa, pelo que não existe registo de propriedade para devolver; `unavailable` quando os dados não foram disponibilizados por qualquer outro motivo (um registo sem qualquer titular, uma secção de propriedade não devolvida ou um fornecedor que não pôde ser consultado); `pending` enquanto o registo ainda está a obter a secção de propriedade; `not_requested` no nível Basic |
| `tier_requested` / `tier_delivered` | `basic`, `shareholders` ou `ubo`. Um pedido UBO respondido apenas com acionistas diretos é disponibilizado, e faturado, como `shareholders` |
| `unavailable_reason` | Motivo pelo qual um nível de propriedade pedido não foi disponibilizado: `no_owners_on_record`, `no_natural_person_owner`, `ownership_section_unavailable`, `company_not_found`, `ambiguous_company_match`, `missing_registration_number`, `entity_type_not_covered`, `provider_unavailable` ou `other`. `null` quando a propriedade foi disponibilizada |
| `direct_ownership_complete` | `true` quando as participações declaradas dos acionistas diretos somam 100% (dentro de um ponto percentual devido ao arredondamento), `false` quando não somam, `null` quando a propriedade não foi disponibilizada ou quando uma participação não está declarada |
| `unresolved[]` | Partes da cadeia de propriedade que o registo não conseguiu resolver, como `{ reason, section }` (por exemplo, `no_group_structure_on_record` para `group_structure`: os proprietários diretos são conhecidos, mas o grupo empresarial acima deles não consta do registo) |

**Detalhe do registo** (`registry_data`)

O detalhe da própria Didit sobre a verificação no registo, nunca o registo da fonte. Cada chave é opcional e só está presente quando a empresa tem um valor para esse campo, e podem ser acrescentadas novas chaves: consulte os campos canónicos acima para tudo o que estes cobrem.

| Campo | Descrição |
| - | - |
| Dados do registo (`legal_address`, `registered_address`, `registration_date`, `dissolution_date`, `registry_status`, `verification_status`, `company_type`, e os restantes campos que [update-data](https://docs.didit.me/pt/sessions-api/update-data.md) aceita) | Cadeias de caracteres. As correções feitas com update-data e os factos que o registo indica e que não têm campo próprio (`registration_date`, `dissolution_date`) |
| `ownership_error` | Motivo pelo qual um nível de propriedade pedido não foi disponibilizado, com os mesmos códigos de `ownership.unavailable_reason` (`no_owners_on_record`, `ownership_section_unavailable`, `company_not_found`, `provider_unavailable`, `other`, ...) |
| `section_errors` | Secções que o registo não devolveu, indexadas por secção (`officers`, `shareholders`, `group_structure`), cada uma com `{ status_code }` |
| `ubo_resolution` | Como o nível UBO percorreu a cadeia: `parent_chain[]` e `subsidiaries[]` como `{ name, country_code, registration_number }`, e `unresolved[]` como `{ reason, section }` |
| `lite_enrichment` | Campos Lite em branco que outra das fontes de registo do país preencheu: `{ fields[], people_added }` |
| `registry_metadata`, `registry_sources[]`, `previous_names[]`, `parent_companies[]`, `documents_available` | Apenas em registos antigos: os campos próprios do registo, os registos oficiais consultados (`{ name, source_type }`, apenas os registos oficiais são identificados), nomes anteriores, nomes das empresas-mãe e o número de documentos apresentados disponíveis |

### Forma do item de dirigente (dentro de `company.officers`)

```json theme={null}
{
  "uuid": "...",
  "name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": null,
  "date_of_birth_year": 1983,
  "date_of_birth_month": 2,
  "address": "1 Example Street, London",
  "appointment_date": "2024-07-01",
  "termination_date": null,
  "designation": "Director",
  "role": "director",
  "nationality": "USA",
  "is_active": true,
  "kyc_status": "Approved",
  "kyc_session_url": "https://verify.didit.me/..."
}
```

`date_of_birth` só é preenchido quando o registo fornece uma data completa.
Se o registo indicar apenas o ano ou o mês e o ano, use `date_of_birth_year` e `date_of_birth_month`; o dia em falta nunca é inferido.
Os nomes, os dados de nascimento, a morada e as datas de nomeação continuam disponíveis tanto na lista de dirigentes da empresa como na lista de pessoas-chave do registo.

### Forma do item de beneficiário efetivo (dentro de `company.beneficial_owners`)

```json theme={null}
{
  "uuid": "...",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "entity_type": "person",
  "date_of_birth": null,
  "country_of_birth": null,
  "email": null,
  "company_name": null,
  "registration_number": null,
  "nationality": null,
  "designation": null,
  "appointment_date": null,
  "voting_min_shares": null,
  "voting_max_shares": null,
  "roles": ["ubo"],
  "ownership_min_shares": "40",
  "ownership_max_shares": "40",
  "is_active": true,
  "kyc_status": "Pending",
  "kyc_session_url": "https://verify.didit.me/...",
  "effective_ownership_percent": 40.0,
  "shareholding": {
    "share_class": "Ordinary",
    "number_of_shares": 40,
    "currency": "GBP",
    "nominal_value": 1,
    "total_value": null,
    "percentage": 40
  }
}
```

`kyc_status` usa uma projeção segura para B2C: `Approved`, `Declined` ou `Pending` (os estados completos da sessão passam a `Pending` até o KYC terminar).

`shareholding` indica o que o titular detém, no mesmo formato para todos os países e fontes de registo: `share_class`, `number_of_shares`, `currency`, `nominal_value`, `total_value` e `percentage` (a participação exata, com quatro casas decimais).
É `null` quando o registo não indica qualquer participação.
Um intervalo, como os 25-50% de um PSC do Reino Unido, não é uma participação: `percentage` é `null` e o intervalo fica em `ownership_min_shares` / `ownership_max_shares`.
Os acionistas e os UBO estão ambos listados em `beneficial_owners`; `roles` permite distingui-los.

## `key_people_checks[]`

Esta é a **verificação agregada** de todos os dirigentes e UBO da sessão. Expõe dois grupos, para que a consola possa apresentar lado a lado as partes «extraídas do registo» e as «submetidas pela empresa», além de um resumo de alto nível do KYC dos UBO.

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_key_people",
  "registry": {
    "officers": [ ...registry-derived officers... ],
    "beneficial_owners": [ ...registry-derived UBOs... ]
  },
  "submitted": {
    "parties": [ ...user-submitted key-people records... ]
  },
  "ubo_kyc_summary": {
    "total": 2,
    "approved": 1,
    "flagged": 0,
    "pending": 1
  },
  "warnings": []
}
```

* **`registry.officers` / `registry.beneficial_owners`**: partes extraídas da verificação no registo.
* **`submitted.parties`**: partes que o administrador da empresa acrescentou durante o fluxo Pessoas-chave (registos com `source = "USER"`).

### `registry.officers[]` / `registry.beneficial_owners[]`

Os dados do registo correspondem a `company.officers` / `company.beneficial_owners` acima. Os registos de Pessoas-chave incluem ainda o estado AML e a ligação detalhada à verificação, como `kyc_session_id` e os campos do fluxo de verificação. As listas da empresa mantêm o estado KYC simplificado e o URL de verificação já existentes.

### `submitted.parties[]`

As partes submetidas pelo utilizador transportam a respetiva ligação ao KYC ou ao KYB subordinado:

```json theme={null}
{
  "uuid": "...",
  "entity_type": "person",
  "name": "Alice Chen",
  "first_name": "John",
  "last_name": "Doe",
  "email": "alex.sample@example.com",
  "role": "ubo",
  "ownership_percent": 35.0,
  "nationality": "USA",
  "position": "CEO",
  "date_of_birth": "1990-01-01",
  "phone_number": "+34612345678",
  "source": "USER",
  "requires_verification": true,
  "is_skipped": false,
  "kyc_session_id": "sess-xyz...",
  "kyc_session_status": "Not Started",
  "kyc_session_url": "https://verify.didit.me/...",
  "kyc_session_deleted": false,
  "custom_fields": { }
}
```

As partes empresariais (`entity_type: "company"`) incluem também `company_name`, `registration_number` e `kyb_sub_session_id` / `kyb_sub_session_status` / `kyb_sub_session_deleted` quando o KYB aninhado está ativo para UBO empresariais.

`kyc_session_deleted` (e o seu equivalente empresarial `kyb_sub_session_deleted`) é `true` quando a sessão filha da parte foi eliminada. Uma sessão filha eliminada mantém o estado que tinha no momento da eliminação e nunca pode ser concluída, por isso deve ler este sinalizador e não o estado: o `*_session_url` correspondente é devolvido como `null`, porque a ligação deixou de resolver, e a verificação de Pessoas-chave passa para `In Review` em vez de ficar à espera indefinidamente. Eliminar uma sessão filha nunca conta como aprovação. Isente a parte com [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](https://docs.didit.me/pt/sessions-api/update-data#ignorar-uma-parte-de-pessoas-chave) para que o KYB possa ser concluído.

### `ubo_kyc_summary`

Progresso agregado do KYC dos UBO, útil para um único cartão do painel:

| Campo | Significado |
| - | - |
| `total` | Número de UBOs ativos com uma sessão KYC associada |
| `approved` | UBOs cujas sessões KYC estão `Approved` |
| `flagged` | UBOs cujas sessões KYC estão `Declined` ou `In Review` |
| `pending` | Todos os restantes (ainda não concluídos) |

Devolve `null` quando nenhum UBO tem sessões KYC associadas.

## `document_verifications[]`

Documentos agrupados por nó:

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_documents",
  "items": [
    {
      "uuid": "...",
      "document_type": "LEGAL_PRESENCE",
      "document_subtype": "CERTIFICATE_OF_INCORPORATION",
      "document_group": "LEGAL_PRESENCE",
      "status": "Approved",
      "file_url": "https://didit-storage.s3...",
      "document_metadata": {
        "file_size": 246810,
        "content_type": "application/pdf",
        "creation_date": "2024-05-15",
        "modified_date": "2024-05-15",
        "overlay_manipulation": null
      },
      "ocr_data": {
        "company_name": "Acme Corporation Limited",
        "registration_number": "12345678",
        "incorporation_date": "2010-05-14"
      }
    }
  ],
  "groups": {
    "LEGAL_PRESENCE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 },
    "OWNERSHIP_STRUCTURE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }
  },
  "required_groups": ["LEGAL_PRESENCE", "OWNERSHIP_STRUCTURE"],
  "warnings": []
}
```

| Campo | Descrição |
| - | - |
| `items[]` | Linhas individuais de documentos, cada uma com o seu `status`, `document_type` e `document_group` (o grupo), `document_subtype`, `file_url` (assinado), `document_metadata` e a extração OCR |
| `groups` | Contadores de progresso por grupo, indexados pelo valor do grupo (`LEGAL_PRESENCE`, `COMPANY_DETAILS`, `OWNERSHIP_STRUCTURE`, `REPRESENTATIVES_AUTHORIZATION`, além de `OTHER` para documentos não classificados). Cada grupo tem `total`, `approved`, `pending`, `declined`, `in_review`, `other` e `missing`. Consulte os [grupos de documentos KYB](https://docs.didit.me/pt/business-verification/documents.md#grupos-de-documentos) |
| `required_groups` | Grupos que o seu fluxo marcou como obrigatórios; condicionam a aprovação da sessão ao cumprimento de todos |

### Metadados de documentos societários

Para documentos societários em PDF, `items[].document_metadata.overlay_manipulation` pode incluir indícios forenses de uma possível edição de texto sobreposto. Quando está presente, inclui:

| Campo | Descrição |
| - | - |
| `analysis_incomplete` | Presente e `true` apenas quando o ficheiro não pôde ser verificado na íntegra. O que foi verificado mantém os respetivos resultados sempre que possível, e o documento gera `KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. |
| `detected` | Se foi detetada evidência de manipulação de texto sobreposto |
| `analyzed` | Se o PDF pôde ser analisado |
| `signals` | Sinais forenses que foram acionados, como `duplicate_font_subset` ou `glyph_fragmentation` |
| `manipulated_regions` | Retângulos em coordenadas da página PDF em torno do texto suspeito de ter sido editado: `page`, `x`, `y`, `width`, `height`, `page_width`, `page_height` |

O campo é `null` quando não é encontrada evidência de sobreposição, quando o documento não é um PDF ou quando o PDF não pôde ser analisado.

## `aml_screenings[]`

Triagens AML ao nível da empresa e, quando o fluxo as configura, ao nível da pessoa.

```json theme={null}
{
  "node_id": "feature_aml",
  "status": "Approved",
  "total_hits": 0,
  "score": 0,
  "entity_type": "COMPANY",
  "screened_data": {
    "company_name": "Acme Corporation Limited",
    "country_code": "GBR"
  },
  "is_ongoing_monitoring_enabled": true,
  "next_ongoing_monitoring_bill_date": "2027-04-16",
  "last_ongoing_screening_at": "2026-09-12T04:03:11Z",
  "last_ongoing_screening_datasets_updated_at": null,
  "hits": [],
  "warnings": []
}
```

Quando `total_hits > 0`, cada ocorrência inclui a pontuação de correspondência, a pontuação de risco, as fontes das listas de vigilância e um `review_status` por ocorrência, que pode atualizar através do endpoint update-aml-hit-status. Consulte o [relatório de triagem AML](https://docs.didit.me/pt/core-technology/aml-screening/report-aml-screening.md) para a estrutura das ocorrências.

## Matrizes de funcionalidades partilhadas

`phone_verifications`, `email_verifications`, `questionnaire_responses`, `ip_analyses` usam as mesmas estruturas por item que as sessões de utilizador (KYC). Têm o valor `null` quando o fluxo não os inclui. Consulte a [resposta KYC](https://docs.didit.me/pt/sessions-api/retrieve-session.md) para os esquemas dos itens.

`signatures` está presente quando o fluxo tem um passo de [Assinatura eletrónica](https://docs.didit.me/pt/core-technology/electronic-signature/overview.md). Uma sessão empresarial tem um item por cada pessoa-chave que assina em nome da empresa, com `signer.capacity: "company"`, o nome da empresa e as funções da pessoa-chave. Consulte o [relatório de assinatura eletrónica](https://docs.didit.me/pt/core-technology/electronic-signature/report-electronic-signature.md).

## Grupos de funcionalidades de avisos

Os avisos de verificação de empresas estão agrupados pela funcionalidade que os produziu:

* `KYB_REGISTRY` para indisponibilidade do registo, propriedade, atividade da empresa e restrições por país.
* `KYB_DOCUMENTS` para extração de documentos empresariais, verificação cruzada, metadados, manipulação, subtipo, idade e limites de tentativas.
* `AML` para correspondências na triagem AML da empresa ou dados de triagem em falta.
* `KYB_KEY_PEOPLE` para problemas ao nível da pessoa associados a administradores, dirigentes, UBO ou representantes.
* `PHONE` para risco do número de telefone, duplicação, lista de bloqueio e problemas relacionados com tentativas do código de verificação.
* `EMAIL` para risco do e-mail, capacidade de entrega, duplicação, lista de bloqueio e problemas relacionados com tentativas do código de verificação.
* `QUESTIONNAIRE` para regras de estado personalizadas, definidas pelas respostas ao questionário.
* `LOCATION` para Análise de dispositivo e IP, rede privada, lista de bloqueio de IP, lista de bloqueio de dispositivos e dispositivos ou IP duplicados.
* `SIGNATURE` para recusas na assinatura eletrónica, falhas na confirmação de código, incompatibilidades no nome do signatário, signatários não verificados, documentos alterados e dados de campos em falta. Consulte [avisos de assinatura eletrónica](https://docs.didit.me/pt/core-technology/electronic-signature/warnings-electronic-signature.md).

Consulte os [avisos de verificação de empresas](https://docs.didit.me/pt/business-verification/warnings.md) para a lista completa de códigos de aviso.

## Filtragem de campos com base no fluxo

Os fluxos podem limitar os campos aninhados que aparecem em cada item de funcionalidade através de `response_attributes`. Os campos sempre incluídos, independentemente disso, são `status`, `warnings` e `node_id`. Todos os outros campos são anulados quando não constam da lista de permissões. A chave mantém-se na resposta para garantir a estabilidade do esquema.

## Próximos passos

> [card] [Estados](https://docs.didit.me/pt/business-verification/statuses.md)
>
> O que significa cada valor de estado.

> [card] [Avaliação de risco](https://docs.didit.me/pt/business-verification/risk-assessment.md)
>
> O que determina o resultado de uma verificação KYB.

> [card] [Relatório AML](https://docs.didit.me/pt/core-technology/aml-screening/report-aml-screening.md)
>
> Referência completa do payload de correspondências AML.

> [card] [Pessoas-chave](https://docs.didit.me/pt/business-verification/key-people.md)
>
> Como as partes passam do registo ou da submissão pelo utilizador para os grupos `registry` / `submitted`.

> [card] [Documentos](https://docs.didit.me/pt/business-verification/documents.md)
>
> Grupos de documentos, OCR e referência cruzada.

> [card] [Obter sessão](https://docs.didit.me/pt/sessions-api/retrieve-session.md)
>
> Referência completa do endpoint, incluindo exemplos de respostas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.