Relatório de triagem AML: hits, pontuações e JSON

Visão geral

A Análise AML cruza a identidade do titular verificado com bases globais de sanções, PEP, listas de monitoramento e mídia adversa. Cada ocorrência retorna a entidade correspondente, a base de dados ou as bases de dados que geraram a correspondência, duas pontuações (match_score, a confiança na identidade, e risk_score, o risco da entidade) e um detalhamento estruturado por fonte (pep_matches[], sanction_matches[], warning_matches[], adverse_media_matches[]). O score agregado é o maior risk_score entre as ocorrências que não estão marcadas como False Positive. A Análise AML retorna esse mesmo formato em sessões de usuário (KYC), em sessões de empresa (KYB) e na API AML independente.

Captura de tela do relatório de Análise AML da Didit com ocorrências de sanções, PEP e mídia adversa

Onde aparece nas respostas da API

No endpoint de decisão da sessão, a Análise AML é retornada como o array no plural aml_screenings[]. Cada entrada corresponde a uma execução AML no fluxo de verificação (workflow): uma verificação 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 AML independentes e de empresa retornam o mesmo formato por registro. Os campos abaixo espelham o schema canônico da página Modelos de dados.

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

O status é um veredito, e os números dos quais ele foi derivado estão no mesmo payload. Use-os ao montar sua própria classificação de risco em níveis em vez de ramificar apenas em Approved / In Review / Declined. Por exemplo, você pode combinar o risco AML com respostas de questionários, como a origem do patrimônio ou a autodeclaração de PEP:

Pontuação	Onde	Escala	Responde a
`hits[].match_score`	por ocorrência	0-100	A pessoa desta ocorrência é a mesma que foi analisada? Define o `review_status` inicial da ocorrência.
`hits[].risk_score`	por ocorrência	0-100	Quão arriscada é a entidade correspondente? Determinado pelas categorias da ocorrência (sanção, PEP, crime, …).
`score`	por análise	0-100	O maior `risk_score` entre as ocorrências não marcadas como `False Positive`. É com ele que os limiares de aprovação / revisão são comparados para gerar o `status`.

As três pontuações estão presentes em todos os lugares onde o relatório AML é entregue: GET /v3/session/{sessionId}/decision/, o objeto decision dos webhooks status.updated e data.updated em todas as versões de webhook (aml_screenings[] na V3 e o aml no singular nas versões legadas V2 / V1) e a API AML independente. Uma integração que só vê um rótulo de sinalizado / sem sinalização está lendo o status (ou o review_status de uma ocorrência) e ignorando as pontuações que vêm ao lado. O console mostra os mesmos números: o cabeçalho da seção AML traz a Risk score agregada, e cada linha da tabela de correspondências traz a Match score e a Risk score, com um detalhamento ao passar o mouse.

Schema

Consulte Análise AML na referência de modelos de dados para ver o schema canônico. Campos de nível superior:

Campo	Tipo	Observações
`status`	`Not Finished` \| `Approved` \| `Declined` \| `In Review`	Status no nível do recurso (`FeatureStatusChoices`). Orienta as regras do fluxo e a tela 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 pessoas físicas usam lógicas de correspondência diferentes.
`score`	float (0-100) \| null	Pontuação de risco AML agregada: o maior `risk_score` entre os hits não marcados como `False Positive`. `0` quando não há correspondências possíveis; `null` até a análise ser executada.
`hits`	`Hit[]`	Uma entrada por registro correspondente, incluindo os hits classificados automaticamente como `False Positive` (eles continuam listados, mas ficam fora do `score` agregado). Veja os campos por hit abaixo.
`screened_data`	object	Os valores exatos que a Didit enviou para a análise: `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` depois que você ativa o monitoramento contínuo para a sessão.
`next_ongoing_monitoring_bill_date`	string \| null	Data `YYYY-MM-DD` em que ocorre o faturamento da próxima renovação anual (`last_aml_bill_date` + 365 dias). `null` até o monitoramento ser ativado. Não é uma data de análise: veja `last_ongoing_screening_at` abaixo.
`last_ongoing_screening_at`	string (ISO 8601) \| null	Momento da última das reanálises deste registro concluídas pelo monitoramento contínuo, com ou sem mudança no resultado. `null` quando o registro nunca foi reanalisado desde que este campo foi lançado; ele nunca é preenchido retroativamente a partir da data de ativação ou de faturamento.
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601) \| null	A data de atualização mais recente dos datasets AML informada pelo provedor no momento dessa análise. `null` quando o provedor não informou datas de datasets; ela nunca é estimada.
`warnings`	`Warning[]`	Tags de aviso específicas de AML. Veja Avisos AML.
`node_id`	string \| null	Identifica o nó do grafo do fluxo que gerou esta execução AML nas respostas de sessão `/v3/`. A resposta da API AML independente o omite.

Campos por hit

Cada entrada em hits[] tem os campos a seguir (lista parcial). Os arrays de origem da correspondência (pep_matches[], sanction_matches[], warning_matches[], adverse_media_matches[]) são preenchidos apenas para os datasets aos quais o hit pertence.

Campo	Tipo	Observações
`id`	string	Identificador estável do hit: `hit_` seguido de 24 caracteres hexadecimais. A mesma entidade correspondente mantém o mesmo `id` quando o sujeito é analisado novamente. Use-o como `hit_id` ao atualizar `review_status` pelo endpoint de status de hit AML.
`caption`	string	O nome principal da entidade, como armazenado no dataset.
`datasets`	string[]	Categorias de risco em que a entidade está listada: `PEP` (com seu nível, de `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 indica nenhuma delas.
`match_score`	number (0-100)	Confiança na identidade: a probabilidade de o hit ser a mesma pessoa. Hits abaixo de `aml_match_score_threshold` (padrão `93`) começam como `False Positive`; no limiar ou acima dele, começam como `Unreviewed`. Veja Pontuação de correspondência AML.
`risk_score`	number (0-100)	Risco da entidade: o quanto a entidade correspondente é arriscada. O maior `risk_score` entre os hits que não são `False Positive` se torna o `score` de nível superior. Veja Pontuação de risco AML.
`score`	number (0-1)	Pontuação de correspondência ponderada obsoleta. Use `match_score` no lugar dela.
`match`	boolean \| null	Indicador legado de correspondência exata. Prefira `match_score` + `review_status`.
`target`	boolean \| null	Indica se a entidade é o alvo direto da listagem.
`review_status`	`Unreviewed` \| `Confirmed Match` \| `False Positive` \| `Inconclusive`	O valor inicial é derivado da comparação entre `match_score` e `aml_match_score_threshold`. Pode ser alterado pelo endpoint de status de hit AML; a atualização dispara um webhook `data.updated`, mas não recalcula automaticamente o `status` do recurso. Para isso, use o endpoint de status AML ou a revisão no console.
`score_breakdown`	object	Como o `match_score` foi calculado: pontuações de nome, data de nascimento e país, pesos, contribuições e o efeito “chave de ouro” do número do documento (`MATCH` sobrescreve para 100, `NEUTRAL` mantém a pontuação base, `HARD_MISMATCH` penaliza).
`properties`	object	Atributos brutos do dataset (nomes, aliases, datas de nascimento, cidadania, …). Úteis para a decisão.
`url`	string \| null	URL da fonte da entidade correspondente, quando disponível.
`rca_name`	string \| null	Quando o hit é um parente ou associado próximo (RCA), o nome da pessoa relacionada por meio da qual ocorreu a correspondência.
`pep_matches[]`	object[]	Cargos de PEP, publicadores, datas de nascimento e formação do hit.
`sanction_matches[]`	object[]	Nome da lista de sanções, programa, autoridade sancionadora, data de inclusão e URLs das fontes.
`warning_matches[]`	object[]	Registros genéricos de listas de monitoramento ou de ações de fiscalização.
`adverse_media_matches[]`	object[]	Mídia adversa por artigo: manchete, resumo, sentimento, URL da fonte, data de publicação, palavras-chave.
`adverse_media_details`	object \| null	Sentimento agregado de mídia adversa e contagens de palavras-chave do hit.
`risk_view`	object	Detalhamento do risco do hit ponderado por categoria, país e crime (`risk_level`, `risk_scores`, `weightage`).
`linked_entities[]`	object[]	Entidades relacionadas que o dataset associa ao hit (por exemplo, familiares ou associados comerciais).
`first_seen` / `last_seen`	string \| null	Quando o dataset registrou esta entrada pela primeira e pela última vez.
`additional_information`	object	Dados extras em formato livre do provedor do dataset.

Os hits classificados como False Positive (porque o match_score ficou abaixo do limiar da pontuação de correspondência ou porque um revisor os marcou assim) permanecem em hits[] para fins de auditoria. Eles ficam de fora apenas do cálculo do score agregado.

Monitoramento contínuo

Quando is_ongoing_monitoring_enabled é true, a Didit realiza triagens contínuas da entidade e reemite o relatório AML sempre que um hit é adicionado, removido ou alterado. Novas triagens que mudam o status AML disparam um webhook status.updated; novas triagens que mudam apenas os dados dos hits disparam data.updated. A janela de monitoramento vai de last_aml_bill_date até 365 dias depois; next_ongoing_monitoring_bill_date informa quando ocorre a próxima renovação anual. Todos esses sinais são acionados por mudanças, então uma entidade submetida a novas triagens por meses sem nenhum resultado novo não gera nenhum deles. last_ongoing_screening_at é o único campo que muda a cada execução concluída, e o endpoint de histórico de triagens lista cada execução individualmente, incluindo as que não mudaram nada. Consulte Monitoramento AML contínuo para ver o ciclo de vida completo.

Três datas neste relatório significam três coisas diferentes. next_ongoing_monitoring_bill_date é quando você será cobrado na próxima vez. last_ongoing_screening_at é quando a entidade foi de fato submetida à última triagem. last_ongoing_screening_datasets_updated_at é quando as listas usadas nessa triagem foram atualizadas pela última vez pelo provedor. Apenas a segunda comprova que o controle foi executado.

Valores de status

Valor	Significado
`Not Finished`	A análise AML ainda não foi executada para esta sessão ou nó.
`Approved`	A pontuação agregada é igual ou inferior ao limiar de aprovação (padrão `80`), inclusive quando não há resultados ou todos os resultados são `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 disparado.
`Declined`	A pontuação agregada está acima do limiar de revisão (padrão `100`, então a recusa automática só acontece depois que você o reduz), ou o status foi definido manualmente.

Os limiares são configuráveis por nó do fluxo de verificação (workflow); consulte Pontuação de risco AML. Regras de status personalizadas se combinam com o status derivado seguindo a precedência Declined > In Review > Approved; os revisores também podem substituir o status AML no console ou pelo endpoint de status AML.

Exemplos

Aprovado: 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 revisão: correspondência de PEP + mídia adversa

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"
        }
      ]
    }
  ]
}

Relacionados

Avisos AML: todos os códigos de aviso que a análise AML pode emitir
Pontuação de risco AML e pontuação de correspondência AML: como as duas pontuações são calculadas
Monitoramento AML contínuo: como ativar e consumir eventos de monitoramento
Banco de dados de listas de monitoramento: conjuntos de dados cobertos
Modelos de dados: análise AML: schema canônico
Webhooks: status.updated é disparado quando a análise AML altera o status da sessão; mudanças no status de revisão dos resultados e atualizações dos dados de monitoramento disparam data.updated

Autenticação

Verificação

Monitoramento

Plataforma

Relatório de triagem AML: hits, pontuações e JSON

Visão geral

Onde aparece nas respostas da API

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

Schema

Campos por hit

Monitoramento contínuo

Valores de status

Exemplos

Aprovado: sem correspondências

Em revisão: correspondência de PEP + mídia adversa

Relacionados

​Visão geral

​Onde aparece nas respostas da API

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

​Schema

​Campos por hit

​Monitoramento contínuo

​Valores de status

​Exemplos

​Aprovado: sem correspondências

​Em revisão: correspondência de PEP + mídia adversa

​Relacionados

Visão geral

Onde aparece nas respostas da API

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

Schema

Campos por hit

Monitoramento contínuo

Valores de status

Exemplos

Aprovado: sem correspondências

Em revisão: correspondência de PEP + mídia adversa

Relacionados