Regras e pontuação de KYT: velocidade e condições

Cada transação enviada à Didit é avaliada em relação a todas as regras ativas da sua aplicação. As regras definem condições, verificações de frequência e ações que determinam o status final e a pontuação da transação. Este capítulo da aula da Didit Academy sobre o motor de regras de fraude retoma a partir da criação de uma regra. A aula da Academy sobre o motor de regras mostra, em vídeo, a criação de uma regra aos 7:54: gatilho, condições, ações e pontuação e, em seguida, o backtesting antes da implantação.

​

Pacotes de regras integrados

A Didit oferece uma biblioteca de regras pré-configuradas que cobre as tipologias regulatórias mais comuns. Instale as predefinições (ou pacotes inteiros) que quiser a partir da biblioteca, no console, pela API de instalação ou com as ferramentas do MCP, e controle o modo de cada predefinição instalada. Para o catálogo completo de todas as regras predefinidas, com limiares e ações, consulte a Biblioteca de regras.

​

Origens das regras

Toda regra tem um source que indica quem a gerencia:

​

Anatomia de uma regra

Cada regra é composta por:

​

Ações

Quando uma regra corresponde a uma transação, uma ou mais ações são executadas. Cada regra pode ter várias ações, e todas são aplicadas em conjunto: A maioria das regras predefinidas combina Adicionar pontuação com Alterar status. Por exemplo, uma regra de contraparte sancionada adiciona 90 pontos à pontuação e recusa a transação imediatamente.

​

Exigir verificação do usuário (AWAITING_USER)

Uma ação Alterar status → AWAITING_USER faz mais do que definir um status: a Didit cria automaticamente uma sessão de verificação hospedada para o titular da transação (mesmo vendor_data) no momento em que a regra é acionada. A sessão é retornada no bloco action_required da transação (e no objeto remediation) na resposta de criação e em todas as leituras posteriores, além de nos dois webhooks de transação. Assim, você pode redirecionar o usuário imediatamente; veja ações exigidas do usuário. Regras personalizadas devem indicar o fluxo na própria ação (workflow_id): tanto o construtor de regras do console quanto a API de regras exigem isso. As regras da biblioteca integrada não trazem um fluxo; para elas, o fluxo da sessão é definido nesta ordem:

1. O fluxo de remediação configurado nas suas configurações de transações.
2. O fluxo de Autenticação biométrica da sua aplicação, quando o titular já tem um rosto de referência armazenado de uma verificação aprovada.
3. O fluxo padrão da sua aplicação.

Isso significa que as regras da biblioteca com AWAITING_USER sempre geram uma sessão acionável sem configuração adicional: uma autenticação biométrica adicional para usuários que você já verificou e uma verificação completa nos demais casos. As transações de Travel Rule ficam fora desse fallback automático: nelas, a espera em AWAITING_USER é pela comprovação de propriedade da carteira, que tem seu próprio fluxo. A opção mais robusta para transações de alto risco é um fluxo de Autenticação biométrica: como o titular é o usuário que você já verificou no KYC, a Didit reutiliza o rosto de referência verificado no onboarding dele (a selfie de prova de vida aprovada, a foto do chip do passaporte ou o retrato do documento). O usuário só tira uma selfie ao vivo, e a Didit executa a prova de vida e uma correspondência facial 1:1 com a identidade que abriu a conta. Credenciais roubadas, OTPs obtidos por phishing e trocas de SIM (SIM swap) não passam por essa barreira. Passo a passo completo: autenticação biométrica adicional para um saque de alto valor. Quando a sessão chega a uma decisão, a transação segue essa decisão automaticamente e um webhook transaction.status.updated é disparado: uma sessão aprovada aprova a transação (decision_reason_code: user_action_approved), uma sessão recusada a recusa (user_action_declined) e uma sessão que termina em revisão envia a transação para IN_REVIEW (user_action_in_review). Uma sessão expirada ou abandonada mantém a transação em AWAITING_USER.

​

Pontuação

Quando uma transação corresponde a uma ou mais regras, as pontuações são combinadas:

1. Cada correspondência de regra contribui para a pontuação de risco geral da transação por meio da ação add_score
2. A pontuação final determina o status da transação com base nos limiares de pontuação da sua aplicação
3. Se alguma regra tiver uma ação change_status, esse status é aplicado diretamente; DECLINED sempre tem prioridade

Limiares de pontuação padrão (configuráveis no console):

​

Criação de regras personalizadas

As regras personalizadas podem ser criadas no Business Console ou pela Management API (também acessível pelo Didit MCP e por qualquer assistente de IA conectado via MCP). As regras no modo Active entram em vigor imediatamente para todas as novas transações. Os títulos são únicos por aplicação.

​

Backtesting

Antes de ativar uma regra, você pode validá-la com dados históricos:

• Coloque a regra no modo Test — a regra é avaliada em cada nova transação, mas os resultados não afetam o status nem a pontuação da transação. As estatísticas de execução (número de correspondências, entidades afetadas) se acumulam para que você possa avaliar o impacto antes de colocá-la em produção.
• Use o recurso de backtest - no console ou via POST /v3/transactions/rules/backtest/ - para avaliar retroativamente as condições e a agregação de uma regra em transações de um período especificado. O backtest retorna o número de transações avaliadas, de transações que atenderam às condições e das entidades afetadas - sem modificar nenhum dado histórico. Envie os mesmos conditions, aggregation, evaluation_mode e scope da regra que você pretende ativar: omitir o escopo significa nenhuma restrição, então o backtest contaria transações que a regra salva ignora.

​

Janelas de velocidade (agregação)

As regras de velocidade agregam dados históricos de transações ao longo de um período para detectar padrões que verificações de uma única transação não identificariam: Cada agregação especifica:

• Uma janela de tempo: <N>m (minutos), <N>h (horas) ou <N>d (dias) - por exemplo, 30m, 6h, 7d, 30d. Atenção: m significa minutos, não meses.
• Filtros para restringir quais transações históricas são incluídas. As chaves são caminhos de campo do catálogo de campos; o valor especial "__current__" corresponde ao valor do mesmo campo na transação que está sendo avaliada (por exemplo, "subject_vendor_data": "__current__" restringe a janela ao mesmo titular), e um valor de lista indica que o campo deve corresponder a um dos valores da lista. Os filtros comparam apenas por igualdade ou pertencimento - não existe filtro lt/gte, então um intervalo como transações abaixo de 10,000 não pode ser expresso por um filtro. Coloque o intervalo na métrica (max abaixo de 10,000, min acima de 1,000) e lembre-se de que uma condição restringe a transação que está sendo avaliada, nunca a janela.
• Um operador e limiar (eq, ne, gt, gte, lt, lte em relação a value, por exemplo, count >= 20)

​

Padrões de exemplo

​

Catálogo de campos

Condições e filtros de agregação referenciam os campos da transação pelo caminho:

​

Operadores de condição

As regras aceitam os seguintes operadores de comparação nas condições: Todos os demais operadores exigem um value não vazio, e a API responde com 400 quando ele não é informado. contains, not_contains e regex recebem uma única string, não uma lista nem um objeto; contains_any recebe uma lista de strings.

​

Tipos de valor de condição

Um value_type opcional em uma condição muda a forma como value é interpretado:

​

Condições agrupadas

Uma lista simples de condições é combinada de acordo com o evaluation_mode da regra (ALL/ANY). Para lógica mista, atribua às condições um group_index: as condições que compartilham o mesmo índice formam um grupo, group_logic (AND/OR, padrão AND) combina as condições dentro de um grupo, e groups_logic na primeira condição (AND/OR, padrão OR) combina os resultados dos grupos. Quando qualquer condição tem um group_index, a avaliação agrupada substitui o evaluation_mode.

​

Referência a propriedades personalizadas

Toda chave enviada no objeto custom_properties de POST /v3/transactions/ é armazenada na transação como custom_values e pode ser usada em condições com o caminho de campo custom_values.<key>. Por exemplo, uma transação enviada com "custom_properties": {"channel": "mobile_app"} corresponde à condição custom_values.channel eq "mobile_app". Todos os operadores acima funcionam com propriedades personalizadas, que também podem ser comparadas com outros campos ou usadas em filtros de velocidade. No construtor de regras do Console, as chaves observadas em transações ingeridas recentemente aparecem automaticamente no seletor de campos da condição, em Custom Properties. Você também pode referenciar uma chave antes que qualquer transação a contenha: escolha Enter custom property no mesmo grupo e digite a chave exatamente como a sua integração a envia (as chaves diferenciam maiúsculas de minúsculas). A regra simplesmente não corresponde até que cheguem transações com essa chave.

​

Recusa automática por lista de bloqueio

Antes de avaliar qualquer regra, a Didit verifica as entidades da transação nas listas de bloqueio da sua aplicação. Se qualquer correspondência for encontrada, a transação é recusada imediatamente, e as regras não são avaliadas. As seguintes entidades são verificadas: Quando ocorre uma correspondência na lista de bloqueio:

• O status da transação é definido como DECLINED
• O motivo da decisão é definido como blocklisted
• Um registro de atividade é criado para fins de auditoria

​

Triagem de transações

A Didit se integra a provedores externos de AML e de análise de blockchain para enriquecer as transações com inteligência de risco. Quando uma transação é enviada, o sistema pode:

• Analisar contrapartes em bases globais de sanções e listas de monitoramento
• Avaliar endereços de carteira (em transações cripto) com base em dados de inteligência de blockchain, incluindo exposição a mixers, conexões com entidades sancionadas e interações com serviços de alto risco
• Verificar o status AML do solicitante cruzando o usuário vinculado à transação com os resultados mais recentes da sua triagem de AML

Os resultados da triagem são anexados à transação e entram na pontuação do mecanismo de regras. Se uma contraparte ou carteira corresponder a uma lista de sanções, a regra correspondente sinaliza ou recusa a transação automaticamente.

​

Próximos passos