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

# Relatório de triagem AML: ocorrências, pontuações e JSON

> Analise respostas de triagem AML da Didit: sanções, PEP, notícias adversas, pontuações de risco e correspondência e monitorização contínua.

## Visão geral

A triagem AML cruza a identidade do sujeito verificado com conjuntos de dados globais de sanções, PEP, lista de vigilância e notícias adversas. Cada resultado devolve a entidade correspondente, o(s) conjunto(s) de dados que geraram a correspondência, duas pontuações — `match_score` (confiança na identidade) e `risk_score` (risco da entidade) — e uma discriminação estruturada por fonte (`pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]`). O `score` agregado é o `risk_score` mais elevado entre os resultados que não estejam marcados como `False Positive`.

A mesma estrutura é devolvida pela triagem AML em sessões de utilizador (KYC), sessões de empresas (KYB) e na API de AML autónoma.

![Captura de ecrã do relatório de triagem AML da Didit com resultados de sanções, PEP e notícias adversas](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/aml-screening-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=5b74561abdd242f108fee1b429ff5020)

## Onde surge nas respostas da API

No endpoint de decisão da sessão, a triagem AML é devolvida como o array plural **`aml_screenings[]`**. Cada entrada corresponde a uma execução de AML no fluxo (uma verificação de AML executada duas vezes gera duas entradas com valores de `node_id` diferentes).

```text theme={null}
GET /v3/session/{sessionId}/decision/
  ──▶ { "aml_screenings": [ { node_id, status, total_hits, hits, … }, … ] }
```

As sessões de AML autónomas e de empresas devolvem a mesma estrutura por registo. Os campos abaixo refletem o esquema canónico na página [Modelos de dados](https://docs.didit.me/pt/reference/data-models.md#triagem-aml).

## Três pontuações, não um veredito

O `status` é um veredito; os números a partir dos quais foi calculado constam do mesmo payload. Leia-os quando construir a sua própria classificação de risco por níveis (por exemplo, combinando o risco de AML com respostas a questionários, tais como a origem da riqueza ou a autodeclaração de PEP), em vez de ramificar apenas com base em `Approved` / `In Review` / `Declined`:

| Pontuação | Onde | Escala | Responde a |
| - | - | - | - |
| `hits[].match_score` | por resultado | 0-100 | Este resultado corresponde à mesma pessoa que foi analisada? Determina o `review_status` inicial do resultado. |
| `hits[].risk_score` | por resultado | 0-100 | Qual é o nível de risco da entidade correspondente? Determinado pelas categorias do resultado (sanções, PEP, crime, ...). |
| `score` | por triagem | 0-100 | O `risk_score` mais elevado entre os resultados não marcados como `False Positive`. É este valor que é comparado com os limiares de aprovação / revisão para produzir o `status`. |

Todas as três estão presentes em todos os locais onde o relatório de AML é entregue: `GET /v3/session/{sessionId}/decision/`, no objeto `decision` dos webhooks `status.updated` e `data.updated` em **todas** as versões de webhook (`aml_screenings[]` na V3 e o singular legado `aml` na V2 / V1) e na API de AML autónoma. Um consumidor que veja apenas um indicador de sinalizado / sem sinalização está a ler o `status` (ou o `review_status` de um resultado) e a ignorar as pontuações ao lado. A consola mostra os mesmos números: o cabeçalho da secção de AML apresenta a **Pontuação de risco** agregada, e cada linha da tabela de correspondências inclui a **Pontuação de correspondência** e a **Pontuação de risco** com uma discriminação detalhada ao passar o cursor.

## Esquema

Consulte [Triagem AML na referência de Modelos de Dados](https://docs.didit.me/pt/reference/data-models.md#triagem-aml) para o esquema canónico. Campos de nível superior:

| Campo | Tipo | Notas |
| - | - | - |
| `status` | `Not Finished` \| `Approved` \| `Declined` \| `In Review` | Estado ao nível da funcionalidade (`FeatureStatusChoices`). Controla as regras do fluxo e o ecrã de revisão manual. |
| `total_hits` | integer | Número de entradas em `hits[]`. `0` quando não há correspondências. |
| `entity_type` | `person` \| `company` | O tipo de entidade analisada. Empresas e particulares usam lógicas de correspondência diferentes. |
| `score` | float (0-100) \| null | Pontuação de risco AML agregada — o `risk_score` mais elevado entre os hits não marcados como `False Positive`. `0` quando não há correspondências possíveis; `null` até a triagem ter sido executada. |
| `hits` | `Hit[]` | Uma entrada por registo correspondente, **incluindo** hits autoclassificados como `False Positive` (permanecem listados, mas são excluídos do `score` agregado). Consulte os campos por hit abaixo. |
| `screened_data` | object | Os valores exatos que a Didit enviou para a triagem: `full_name`, `date_of_birth`, `nationality` (ISO 3166-1 alpha-2), `document_number`. Útil para explicar um hit a um revisor ou auditar o que foi pesquisado. |
| `is_ongoing_monitoring_enabled` | boolean | `true` após ativar a monitorização contínua para a sessão. |
| `next_ongoing_monitoring_bill_date` | string \| null | `YYYY-MM-DD` da próxima renovação anual de **faturação** (`last_aml_bill_date` + 365 dias). `null` até a monitorização ser ativada. Esta não é uma data de triagem — consulte `last_ongoing_screening_at` abaixo. |
| `last_ongoing_screening_at` | string (ISO 8601) \| null | Quando a monitorização contínua **concluiu** pela última vez uma nova triagem deste registo, quer o resultado tenha mudado ou não. `null` quando o registo nunca foi submetido a nova triagem desde a disponibilização deste campo — nunca é preenchido retroativamente a partir da data de ativação ou de faturação. |
| `last_ongoing_screening_datasets_updated_at` | string (ISO 8601) \| null | A data mais recente de atualização dos conjuntos de dados de AML que o fornecedor comunicou no momento dessa triagem. `null` quando o fornecedor não comunicou datas de conjuntos de dados; nunca é estimada. |
| `warnings` | `Warning[]` | Etiquetas de aviso específicas de AML. Consulte [Avisos de AML](https://docs.didit.me/pt/core-technology/aml-screening/warnings-aml-screening.md). |
| `node_id` | string \| null | Identifica o nó do grafo do fluxo que produziu esta execução de AML nas respostas de sessão `/v3/`. A resposta da API de AML autónoma omite-o. |

### Campos por hit

Cada entrada em `hits[]` tem os seguintes campos (apresenta-se um subconjunto). Os arrays de fontes de correspondência — `pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]` — são preenchidos apenas para os conjuntos de dados aos quais o hit pertence.

| Campo | Tipo | Notas |
| - | - | - |
| `id` | string | Identificador estável do hit: `hit_` seguido de 24 carateres hexadecimais. A mesma entidade correspondente mantém o mesmo `id` quando a entidade analisada é submetida a nova triagem. Utilize-o como `hit_id` ao atualizar `review_status` através do endpoint de estado de hits de AML. |
| `caption` | string | O nome principal da entidade tal como armazenado no conjunto de dados. |
| `datasets` | string\[] | Categorias de risco nas quais a entidade está listada: `PEP` (com o respetivo nível, `PEP Level 1` a `PEP Level 4`), `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`, `SIP`, `SIE` ou `Insolvency`, e `Other Lists` quando a fonte da entidade não indicar nenhuma destas. |
| `match_score` | number (0-100) | Confiança de identidade — probabilidade de o hit ser a mesma pessoa. Hits abaixo de `aml_match_score_threshold` (predefinição `93`) começam como `False Positive`; no limiar ou acima dele começam como `Unreviewed`. Consulte [Pontuação de correspondência AML](https://docs.didit.me/pt/core-technology/aml-screening/aml-match-score.md). |
| `risk_score` | number (0-100) | Risco da entidade — o nível de risco da entidade correspondente. O `risk_score` mais elevado entre os hits que não sejam `False Positive` torna-se o `score` de nível superior. Consulte [Pontuação de risco AML](https://docs.didit.me/pt/core-technology/aml-screening/aml-risk-score.md). |
| `score` | number (0-1) | Pontuação de correspondência ponderada **descontinuada**. Em alternativa, utilize `match_score`. |
| `match` | boolean \| null | Sinalizador de correspondência exata legado. Prefira `match_score` + `review_status`. |
| `target` | boolean \| null | Se a entidade é o alvo direto da listagem. |
| `review_status` | `Unreviewed` \| `Confirmed Match` \| `False Positive` \| `Inconclusive` | O valor inicial é derivado de `match_score` em relação a `aml_match_score_threshold`. Mutável através do endpoint de estado de hits de AML; a sua atualização aciona um webhook `data.updated`, mas **não** recalcula automaticamente o `status` da funcionalidade — utilize o endpoint de estado de AML ou a revisão na consola para esse efeito. |
| `score_breakdown` | object | Como `match_score` foi calculado: pontuações de nome/data de nascimento/país, ponderações, contribuições e o efeito de "chave de ouro" do número de documento (`MATCH` sobrepõe para 100, `NEUTRAL` mantém a pontuação base, `HARD_MISMATCH` penaliza). |
| `properties` | object | Atributos em bruto do conjunto de dados (nomes, pseudónimos, datas de nascimento, cidadania, …). Útil para a análise e decisão do caso. |
| `url` | string \| null | URL de origem da entidade correspondente, quando disponível. |
| `rca_name` | string \| null | Quando o hit é um familiar ou associado próximo (RCA), o nome da pessoa relacionada através da qual houve correspondência. |
| `pep_matches[]` | object\[] | Cargos de PEP, entidades publicadoras, datas de nascimento e formação académica para o hit. |
| `sanction_matches[]` | object\[] | Nome da lista de sanções, programa, autoridade sancionadora, data de inclusão na lista e URLs de origem. |
| `warning_matches[]` | object\[] | Registos genéricos de listas de vigilância ou de ações de execução coerciva. |
| `adverse_media_matches[]` | object\[] | Notícias adversas ao nível do artigo: título, resumo, sentimento, URL de origem, data de publicação, palavras-chave. |
| `adverse_media_details` | object \| null | Sentimento agregado de notícias adversas e contagem de palavras-chave em todo o hit. |
| `risk_view` | object | Detalhe de risco ponderado por categoria, país e tipo de crime para o hit (`risk_level`, `risk_scores`, `weightage`). |
| `linked_entities[]` | object\[] | Entidades relacionadas que o conjunto de dados associa ao hit (por exemplo, familiares ou associados comerciais). |
| `first_seen` / `last_seen` | string \| null | Quando o conjunto de dados observou esta entrada pela primeira/última vez. |
| `additional_information` | object | Dados adicionais em formato livre do fornecedor do conjunto de dados. |

> [!NOTE]
>
> Os hits classificados como `False Positive` (porque `match_score` ficou abaixo do limiar da pontuação de correspondência ou porque um revisor os marcou) permanecem em `hits[]` para fins de auditoria. São excluídos apenas do cálculo do `score` agregado.

### Monitorização contínua

Quando `is_ongoing_monitoring_enabled` é `true`, a Didit volta a fazer a triagem do sujeito continuamente e volta a emitir o relatório AML sempre que uma correspondência é adicionada, removida ou alterada. As retriagens que alteram o estado de AML acionam um webhook `status.updated`; as retriagens que apenas alteram dados de correspondências acionam `data.updated`. A janela de monitorização decorre a partir de `last_aml_bill_date` durante 365 dias; `next_ongoing_monitoring_bill_date` indica quando ocorre a próxima renovação anual.

Esses sinais são todos acionados por alterações, pelo que um sujeito novamente triado durante meses sem novas correspondências não produz nenhum deles. `last_ongoing_screening_at` é o único campo que é atualizado em **cada** execução concluída, e o [endpoint de histórico de triagens](https://docs.didit.me/pt/core-technology/aml-screening/continuous-monitoring-aml-screening.md#comprovar-a-execução-da-monitorização) lista cada execução individualmente — incluindo aquelas que não alteraram nada. Consulte [Monitorização AML contínua](https://docs.didit.me/pt/core-technology/aml-screening/continuous-monitoring-aml-screening.md) para ver o ciclo de vida completo.

> [!WARNING]
>
> Três datas neste relatório significam três coisas diferentes. `next_ongoing_monitoring_bill_date` é quando será faturado a seguir. `last_ongoing_screening_at` é quando o sujeito foi efetivamente triado pela última vez. `last_ongoing_screening_datasets_updated_at` é quando as listas subjacentes a essa triagem foram atualizadas pela última vez pelo fornecedor. Apenas a segunda comprova que o controlo foi executado.

## Valores de estado

| Valor | Significado |
| - | - |
| `Not Finished` | O AML ainda não foi executado para esta sessão/nó. |
| `Approved` | A pontuação agregada é igual ou inferior ao limiar de aprovação (predefinição `80`) — incluindo quando não há correspondências ou cada correspondência é um `False Positive` (pontuação `0`). |
| `In Review` | A pontuação agregada está acima do limiar de aprovação (e igual ou inferior ao limiar de revisão), ou `COULD_NOT_PERFORM_AML_SCREENING` foi acionado. |
| `Declined` | A pontuação agregada está acima do limiar de revisão (predefinição `100`, pelo que a recusa automática só acontece se o diminuir), ou o estado foi definido manualmente. |

Os limiares são configuráveis por nó do fluxo — consulte [Pontuação de risco de AML](https://docs.didit.me/pt/core-technology/aml-screening/aml-risk-score.md). As regras de estado personalizadas combinam-se com o estado derivado através da precedência `Declined` > `In Review` > `Approved`; os revisores também podem substituir o estado de AML a partir da consola ou do endpoint de estado de AML.

## Exemplos

### Aprovada — sem correspondências

```json theme={null}
{
  "aml_screenings": [
    {
      "node_id": "aml-1",
      "status": "Approved",
      "total_hits": 0,
      "entity_type": "person",
      "score": 0,
      "hits": [],
      "screened_data": {
        "full_name": "Jane Doe",
        "nationality": "US",
        "date_of_birth": "1990-06-12",
        "document_number": "P9876543"
      },
      "is_ongoing_monitoring_enabled": false,
      "last_ongoing_screening_at": null,
      "last_ongoing_screening_datasets_updated_at": null,
      "next_ongoing_monitoring_bill_date": null,
      "warnings": []
    }
  ]
}
```

### Em análise — correspondência de PEP + notícias adversas

Todos os nomes, URLs e artigos abaixo são fictícios.

```json theme={null}
{
  "aml_screenings": [
    {
      "node_id": "aml-1",
      "status": "In Review",
      "total_hits": 1,
      "entity_type": "person",
      "score": 85,
      "hits": [
        {
          "id": "hit_7c1e9a40b2d35f86e0a4c912",
          "caption": "John Q. Exampleton",
          "datasets": ["PEP"],
          "match_score": 96,
          "risk_score": 85,
          "score": 0.97,
          "match": false,
          "target": null,
          "review_status": "Unreviewed",
          "properties": {
            "name": ["John Q. Exampleton"],
            "alias": ["Johnny Example"],
            "birthDate": ["1974"],
            "birthPlace": ["Springfield"]
          },
          "score_breakdown": {
            "name_score": 95,
            "name_weight": 60,
            "name_weight_normalized": 70.59,
            "name_contribution": 67.06,
            "dob_score": 100,
            "dob_weight": 25,
            "dob_weight_normalized": 29.41,
            "dob_contribution": 29.41,
            "country_score": 0,
            "country_weight": 15,
            "country_weight_normalized": 0,
            "country_contribution": 0,
            "document_number_match_type": "NEUTRAL",
            "document_number_effect": "No document number provided for screening",
            "total_score": 96
          },
          "pep_matches": [
            {
              "list_name": "Example PEP Registry",
              "publisher": "Example Registry",
              "matched_name": "John Q. Exampleton",
              "pep_position": "Regional council member",
              "date_of_birth": "1974-01-01",
              "place_of_birth": "Springfield",
              "source_url": "https://example.org/registry/entities/Q0000001"
            }
          ],
          "sanction_matches": [],
          "warning_matches": [],
          "adverse_media_matches": [
            {
              "country": "freedonia",
              "headline": "Court opens inquiry into council hiring irregularities",
              "summary": "John Q. Exampleton is named in a legal investigation regarding irregularities in public hiring.",
              "sentiment": "moderately negative",
              "sentiment_score": -2,
              "source_url": "https://example-news.org/articles/12345",
              "publication_date": "2025-06-09T10:19:10",
              "adverse_keywords": ["fraud", "irregularities"]
            }
          ],
          "adverse_media_details": {
            "sentiment": "Moderately Negative",
            "sentiment_score": -2,
            "entity_type": "person",
            "adverse_keywords": { "fraud": 3, "corruption": 2 }
          },
          "risk_view": {
            "categories": { "score": 100.0, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100.0 } },
            "countries":  { "score": 0.0,   "weightage": 30, "risk_level": "Low",  "risk_scores": {} },
            "crimes":     { "score": 0.0,   "weightage": 20, "risk_level": "Low",  "risk_scores": {} },
            "custom_list": {}
          },
          "linked_entities": [
            { "name": ["Mary Exampleton"], "relation": [], "details": [], "active": [], "status": [] }
          ],
          "first_seen": "2025-01-18T00:00:00",
          "last_seen": "2025-06-13T00:00:00"
        }
      ],
      "screened_data": {
        "full_name": "John Q. Exampleton",
        "nationality": "US",
        "date_of_birth": "1974-01-01",
        "document_number": null
      },
      "is_ongoing_monitoring_enabled": true,
      "next_ongoing_monitoring_bill_date": "2027-05-17",
      "warnings": [
        {
          "feature": "AML",
          "risk": "POSSIBLE_MATCH_FOUND",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Possible match found in AML screening",
          "long_description": "The Anti-Money Laundering (AML) screening process identified potential matches with watchlists or high-risk databases, requiring further review.",
          "node_id": "aml-1"
        }
      ]
    }
  ]
}
```

## Relacionado

* [Avisos de AML](https://docs.didit.me/pt/core-technology/aml-screening/warnings-aml-screening.md) — todos os códigos de aviso que o AML pode emitir
* [Pontuação de risco de AML](https://docs.didit.me/pt/core-technology/aml-screening/aml-risk-score.md) e [Pontuação de correspondência de AML](https://docs.didit.me/pt/core-technology/aml-screening/aml-match-score.md) — como as duas pontuações são calculadas
* [Monitorização AML contínua](https://docs.didit.me/pt/core-technology/aml-screening/continuous-monitoring-aml-screening.md) — ativação e consumo de eventos de monitorização
* [Base de dados de listas de vigilância](https://docs.didit.me/pt/core-technology/aml-screening/watchlist-database-aml-screening.md) — conjuntos de dados abrangidos
* [Modelos de dados — Triagem AML](https://docs.didit.me/pt/reference/data-models.md#triagem-aml) — esquema canónico
* [Webhooks](https://docs.didit.me/pt/integration/webhooks.md) — `status.updated` é acionado quando o AML altera o estado da sessão; alterações ao estado de revisão de correspondências e atualizações de dados de monitorização acionam `data.updated`


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