Integração e Triggers

O Scoring Engine recebe eventos exclusivamente via HTTP REST. O backend/ é o único cliente: ele observa eventos de transação no Kafka, aplica debounce + deduplicação em Redis (TTL 10min para financial, 30min para behavior) e dispara POST /api/v1/scoring/transaction/deposit.

Em versões anteriores existia também um consumer Kafka direto no scoring/ (tópico atlas.l2.transaction.deposit). Esse caminho foi removido — toda dedup/debounce vive no backend/ para concentrar a lógica de orquestração e evitar duplicação.

Dead Letter Queue (output)

A DLQ atlas.scoring.dlq continua ativa, mas agora é alimentada apenas pelo producer do scoring/ — quando a publicação do resultado em atlas.l3.user.score falha, o envelope é roteado pra DLQ. Falhas de correlação Camunda retornam HTTP 502 ao caller (backend) e ficam visíveis nos logs do backend/.

{
  "score": { "eid": "...", "scores_final": 78, "...": "..." },
  "error": "kafka: write timeout publishing to atlas.l3.user.score",
  "original_topic": "atlas.l3.user.score",
  "failed_at": "2026-03-13T14:22:10Z"
}

Monitore o tópico atlas.scoring.dlq em produção. Mensagens na DLQ indicam falha de publicação Kafka (broker offline, write timeout). Falhas de Camunda/payload aparecem como erros HTTP nos logs do backend.

Trigger via HTTP

Endpoint

POST /api/v1/scoring/transaction/deposit
Content-Type: application/json

Respostas

Status	Significado
`202 Accepted`	Processo iniciado com sucesso
`200 OK`	Evento já está sendo processado (`businessKey = eid` ativo)
`422 Unprocessable Entity`	Payload inválido — campos obrigatórios ausentes
`502 Bad Gateway`	Camunda indisponível

202 Accepted:

{
  "eid": "550e8400-e29b-41d4-a716-446655440000",
  "process_instance_id": "a1b2c3d4-...",
  "status": "triggered"
}

200 OK (já ativo):

{
  "eid": "550e8400-e29b-41d4-a716-446655440000",
  "process_instance_id": "a1b2c3d4-...",
  "status": "already_active"
}

422 Unprocessable Entity:

{
  "error": "eid is required",
  "code": "INVALID_INPUT",
  "request_id": "req_xyz789"
}

Schema do Payload de Depósito

Schema completo do evento DepositEvent para ambos os canais (Kafka e HTTP):

Campos de Identidade e Evento

string

required

Event ID único (UUID v4). Usado como businessKey para deduplicação no Camunda. Mesmo eid nunca é processado duas vezes.

string

required

ID do operador na plataforma Atlas.

string

required

ID da marca dentro da organização.

string

required

Identificador externo do usuário no sistema do operador.

string

required

Sempre "deposit" para este endpoint.

string

required

Timestamp do evento em UTC. Formato: YYYY-MM-DDTHH:MM:SSZ

Campos de Perfil do Usuário (PII)

Estes campos são processados apenas no consumer Go. Nunca chegam ao Camunda e não aparecem no output de score (conformidade LGPD).

string

Nome do usuário.

string

Sobrenome do usuário.

string

CPF do usuário (formato: 000.000.000-00).

string

Data de nascimento. Formato: YYYY-MM-DDTHH:MM:SSZ

string

E-mail do usuário.

string

Telefone com DDD internacional (ex: +5511999999999).

string

Endereço IP da sessão do usuário.

string

País de residência (código ISO 3166-1 alpha-2).

string

Estado (UF para Brasil, ex: SP).

string

Cidade.

string

CEP (formato: 00000-000).

string

Gênero: "M", "F" ou null.

string

Status do KYC: "" (não iniciado), "pending", "approved", "rejected".

string

Data de cadastro. Formato: YYYY-MM-DDTHH:MM:SSZ

string

Canal de cadastro: "web", "mobile_android", "mobile_ios", "api".

string

Status da conta: "ACTIVE", "BLOCKED", etc.

boolean

required

Se true, o evento é descartado silenciosamente pelo consumer sem processamento.

Campos da Transação

string

required

ID único da transação no sistema do operador.

number

required

Valor do depósito em BRL. Usado diretamente pelas regras DMN.

number

required

Saldo antes do depósito em BRL.

number

required

Saldo após o depósito em BRL. Deve ser before_balance + amount.

boolean

required

true se este é o primeiro depósito do usuário.

string

required

Status da transação: "RECEIVED", "COMPLETED", etc.

string

required

Timestamp da transação em UTC.

Scores de Entrada (sempre zerados)

integer

Sempre 0 na entrada. Preenchido pelo engine.

integer

Sempre 0 na entrada.

integer

Sempre 0 na entrada.

integer

Sempre 0 na entrada.

integer

Sempre 0 — módulo futuro.

integer

Sempre 0 — módulo futuro.

IPS / Contas Vinculadas

object

required

Informações de contas vinculadas detectadas por IP/device.

Show Campos do objeto ips

boolean

required

true se o dispositivo/IP está associado a outras contas.

integer

required

Número de contas vinculadas detectadas.

string[]

required

Lista dos user_ext_id das contas vinculadas.

Histórico de Apostas Esportivas

boolean

required

O usuário fez apostas esportivas no período.

number

required

Volume total de apostas esportivas em BRL.

integer

required

Quantidade de apostas esportivas realizadas.

boolean

required

true se sports_bets_total_amount >= 2000.

boolean

required

true se 500 <= sports_bets_total_amount < 2000.

boolean

required

true se sports_bets_total_amount < 500.

Histórico de Apostas em Cassino

boolean

required

O usuário fez apostas em cassino no período.

number

required

Volume total de apostas em cassino em BRL.

integer

required

Quantidade de rodadas/partidas em cassino.

boolean

required

true se casino_bets_total_amount >= 2000.

boolean

required

true se 500 <= casino_bets_total_amount < 2000.

boolean

required

true se casino_bets_total_amount < 500.

Histórico de Depósitos

boolean

required

Sempre true para eventos de depósito.

number

required

Volume total depositado no período (mês corrente). Usado nas regras HIGH_MONTHLY_DEPOSIT_VOLUME e ELEVATED_MONTHLY_VOLUME.

integer

required

Número de depósitos no período.

boolean

required

true se deposits_total_amount >= 50000.

boolean

required

true se 20000 <= deposits_total_amount < 50000.

boolean

required

true se deposits_total_amount < 20000.

Histórico de Saques

boolean

required

O usuário realizou saques no período.

number

required

Volume total sacado em BRL. Usado para calcular withdrawalRatio.

integer

required

Número de saques realizados.

boolean

required

true se withdrawals_total_amount / deposits_total_amount >= 0.90.

boolean

required

true se ratio entre 0.70 e 0.90.

boolean

required

true se ratio < 0.70.

Histórico de Ganhos

boolean

required

O usuário teve ganhos no período.

number

required

Volume total de ganhos em BRL.

integer

required

Número de eventos de ganho.

boolean

required

true se winnings_total_amount >= 10000.

boolean

required

true se 1000 <= winnings_total_amount < 10000.

boolean

required

true se winnings_total_amount < 1000.

Payload de Exemplo Completo

Low Risk
High Risk

Jogador recreativo. Nenhuma regra DMN ativada. Score final esperado: 0.

{
  "eid": "a1b2c3d4-0000-0000-0000-000000000001",
  "organization_id": "org_simulate",
  "brand_id": "brand_simulate",
  "user_ext_id": "user_c875f165-4ee6-4c70-ad6a-c1e0d28e66df",
  "event": "deposit",
  "ip": "177.82.154.12",
  "timestamp": "2026-03-13T14:00:00Z",

  "first_name": "Ana",
  "last_name": "Silva",
  "document": "345.678.901-23",
  "birthdate": "1990-06-15T00:00:00Z",
  "country": "BR",
  "state": "SP",
  "city": "São Paulo",
  "post_code": "01310-100",
  "email": "user+test-low@example.com",
  "gender": "F",
  "is_test_account": false,
  "kyc_status": "approved",
  "phone": "+5511987654321",
  "registration_date": "2025-09-15T10:00:00Z",
  "registration_platform": "web",
  "status": "ACTIVE",

  "amount": 150.00,
  "before_balance": 320.50,
  "after_balance": 470.50,
  "is_first_transaction": false,
  "transaction_status": "RECEIVED",
  "transaction_dt": "2026-03-13T13:59:55Z",
  "transaction_id": "txn_low_001",

  "scores_final": 0, "scores_financial": 0, "scores_behavior": 0,
  "scores_aml": 0, "scores_ludopathy": 0, "score_ml": 0,

  "ips": {
    "has_linked_accounts": false,
    "linked_accounts_count": 0,
    "linked_accounts": []
  },

  "has_sports_bets": true,
  "sports_bets_total_amount": 80.00,
  "sports_bets_total_count": 3,
  "sports_bets_high": false,
  "sports_bets_moderate": false,
  "sports_bets_low": true,

  "has_casino_bets": false,
  "casino_bets_total_amount": 0.00,
  "casino_bets_total_count": 0,
  "casino_bets_high": false,
  "casino_bets_moderate": false,
  "casino_bets_low": false,

  "has_deposits": true,
  "deposits_total_amount": 800.00,
  "deposits_total_count": 6,
  "deposits_high": false,
  "deposits_moderate": false,
  "deposits_low": true,

  "has_withdrawals": true,
  "withdrawals_total_amount": 40.00,
  "withdrawals_total_count": 2,
  "withdrawals_high": false,
  "withdrawals_moderate": false,
  "withdrawals_low": true,

  "has_winnings": false,
  "winnings_total_amount": 0.00,
  "winnings_total_count": 0,
  "winnings_high": false,
  "winnings_moderate": false,
  "winnings_low": false
}

Indicadores máximos de lavagem e ludopatia. Score final esperado: ~98.

{
  "eid": "b9c8d7e6-ffff-ffff-ffff-ffffffffffff",
  "organization_id": "org_simulate",
  "brand_id": "brand_simulate",
  "user_ext_id": "user_highrisk_demo_001",
  "event": "deposit",
  "ip": "189.120.44.7",
  "timestamp": "2026-03-13T14:00:01Z",

  "first_name": "Carlos",
  "last_name": "Souza",
  "document": "123.456.789-00",
  "birthdate": "1985-03-22T00:00:00Z",
  "country": "BR",
  "state": "RJ",
  "city": "Rio de Janeiro",
  "post_code": "20040-020",
  "email": "user+highrisk@example.com",
  "gender": "M",
  "is_test_account": false,
  "kyc_status": "pending",
  "phone": "+5521987654321",
  "registration_date": "2026-02-23T08:00:00Z",
  "registration_platform": "mobile_android",
  "status": "ACTIVE",

  "amount": 35000.00,
  "before_balance": 5200.00,
  "after_balance": 40200.00,
  "is_first_transaction": false,
  "transaction_status": "RECEIVED",
  "transaction_dt": "2026-03-13T13:59:58Z",
  "transaction_id": "txn_high_001",

  "scores_final": 0, "scores_financial": 0, "scores_behavior": 0,
  "scores_aml": 0, "scores_ludopathy": 0, "score_ml": 0,

  "ips": {
    "has_linked_accounts": true,
    "linked_accounts_count": 7,
    "linked_accounts": [
      "user_linked_01", "user_linked_02", "user_linked_03",
      "user_linked_04", "user_linked_05", "user_linked_06", "user_linked_07"
    ]
  },

  "has_sports_bets": true,
  "sports_bets_total_amount": 5000.00,
  "sports_bets_total_count": 42,
  "sports_bets_high": true,
  "sports_bets_moderate": false,
  "sports_bets_low": false,

  "has_casino_bets": true,
  "casino_bets_total_amount": 4500.00,
  "casino_bets_total_count": 87,
  "casino_bets_high": true,
  "casino_bets_moderate": false,
  "casino_bets_low": false,

  "has_deposits": true,
  "deposits_total_amount": 80000.00,
  "deposits_total_count": 12,
  "deposits_high": true,
  "deposits_moderate": false,
  "deposits_low": false,

  "has_withdrawals": true,
  "withdrawals_total_amount": 76000.00,
  "withdrawals_total_count": 9,
  "withdrawals_high": true,
  "withdrawals_moderate": false,
  "withdrawals_low": false,

  "has_winnings": true,
  "winnings_total_amount": 12000.00,
  "winnings_total_count": 3,
  "winnings_high": true,
  "winnings_moderate": false,
  "winnings_low": false
}

Testando Localmente

Use o Makefile do módulo scoring/ para publicar os dois perfis de teste:

# Publica dois eventos: low-risk e high-risk com identidade padrão
make kafka-produce

# Sobrescrever a identidade do operador
make kafka-produce ORG_ID=org_acme BRAND_ID=brand_betx USER_EXT_ID=user_abc123

# Consumir o resultado do scoring
make kafka-consume TOPIC=atlas.l3.user.score

# Verificar mensagens na DLQ
make kafka-consume TOPIC=atlas.scoring.dlq

Abra o Camunda Cockpit em http://localhost:8092/camunda (demo/demo) para acompanhar as instâncias de processo em execução, inspecionar variáveis e verificar Incidents.

make cockpit  # abre o Cockpit no browser

Get Started

Quickstart

Event Tracking

Backfill S3

Analytics & Reports

Risk & Scoring

Compliance

Monitoria & Alertas

Platform

Resources

Dead Letter Queue (output)

Trigger via HTTP

Endpoint

Respostas

Schema do Payload de Depósito

Campos de Identidade e Evento

Campos de Perfil do Usuário (PII)

Campos da Transação

Scores de Entrada (sempre zerados)

IPS / Contas Vinculadas

Histórico de Apostas Esportivas

Histórico de Apostas em Cassino

Histórico de Depósitos

Histórico de Saques

Histórico de Ganhos

Payload de Exemplo Completo

Testando Localmente

​Dead Letter Queue (output)

​Trigger via HTTP

​Endpoint

​Respostas

​Schema do Payload de Depósito

​Campos de Identidade e Evento

​Campos de Perfil do Usuário (PII)

​Campos da Transação

​Scores de Entrada (sempre zerados)

​IPS / Contas Vinculadas

​Histórico de Apostas Esportivas

​Histórico de Apostas em Cassino

​Histórico de Depósitos

​Histórico de Saques

​Histórico de Ganhos

​Payload de Exemplo Completo

​Testando Localmente

Dead Letter Queue (output)

Trigger via HTTP

Endpoint

Respostas

Schema do Payload de Depósito

Campos de Identidade e Evento

Campos de Perfil do Usuário (PII)

Campos da Transação

Scores de Entrada (sempre zerados)

IPS / Contas Vinculadas

Histórico de Apostas Esportivas

Histórico de Apostas em Cassino

Histórico de Depósitos

Histórico de Saques

Histórico de Ganhos

Payload de Exemplo Completo

Testando Localmente