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

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

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

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.

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

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 lista cada execução individualmente — incluindo aquelas que não alteraram nada. Consulte Monitorização AML contínua para ver o ciclo de vida completo.

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

{
  "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.

{
  "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 — todos os códigos de aviso que o AML pode emitir
Pontuação de risco de AML e Pontuação de correspondência de AML — como as duas pontuações são calculadas
Monitorização AML contínua — ativação e consumo de eventos de monitorização
Base de dados de listas de vigilância — conjuntos de dados abrangidos
Modelos de dados — Triagem AML — esquema canónico
Webhooks — 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

Autenticação

Verificação

Monitorização

Plataforma

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

Visão geral

Onde surge nas respostas da API

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

Esquema

Campos por hit

Monitorização contínua

Valores de estado

Exemplos

Aprovada — sem correspondências

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

Relacionado

​Visão geral

​Onde surge nas respostas da API

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

​Esquema

​Campos por hit

​Monitorização contínua

​Valores de estado

​Exemplos

​Aprovada — sem correspondências

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

​Relacionado

Visão geral

Onde surge nas respostas da API

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

Esquema

Campos por hit

Monitorização contínua

Valores de estado

Exemplos

Aprovada — sem correspondências

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

Relacionado