> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pontuação de velocidade e anomalias

> Rastreie a frequência de ações em janelas de tempo contínuas, detecte anomalias de velocidade e ingira automaticamente sinais de risco quando os limites forem excedidos.

A API de pontuação de velocidade e anomalia rastreia a frequência com que um sujeito executa uma determinada ação em várias janelas de tempo contínuas — 1 minuto, 5 minutos, 1 hora e 24 horas. Quando a pontuação de velocidade ponderada ultrapassa um limite, a plataforma cria automaticamente um [sinal de risco](https://docs.truthlocks.com/pt/guides/risk-signals.md), conectando a detecção de anomalias diretamente ao pipeline do Firewall de Identidade Antifraude.

> [!NOTE]
>
> A pontuação de velocidade faz parte do [Firewall de Identidade Anti-Fraude](https://docs.truthlocks.com/pt/guides/risk-signals.md). Os sinais gerados por anomalias de velocidade fluem para o mesmo pipeline que outros sinais de fraude, para que você possa consultá-los e revisá-los na página do console **Risco e Fraude > Sinais** ou no [endpoint de listagem de sinais](https://docs.truthlocks.com/pt/api-reference/risk-signals/list.md).

## Como funciona

**1. Registrar ações**

Chame `POST /v1/risk/velocity/record` cada vez que um sujeito realizar uma ação rastreada — tentativas de login, chamadas de API, solicitações de transação ou qualquer tipo de ação personalizada.

**2. Rastreamento de janela contínua**

A plataforma incrementa contadores para o assunto e tipo de ação em quatro janelas contínuas (1 m, 5 m, 1 h, 24 h). As janelas são redefinidas automaticamente quando expiram.

**3. Pontuação ponderada**

Uma pontuação de velocidade é calculada a partir das contagens da janela. Janelas curtas são ponderadas mais pesadamente para detectar picos: 1 m × 30, 5 m × 20, 1 h × 10, 24 h × 5.

**4. Ingestão automática de sinais**

Quando a pontuação de velocidade atinge 60 ou mais, a plataforma ingere automaticamente um sinal de risco com `signal_type: "velocity"`. Você não precisa de uma chamada de API separada.

**5. Revisar e responder**

Consulte janelas de velocidade para um assunto, liste anomalias de alta velocidade em seu locatário e revise sinais na console ou via API.

## Pré-requisitos

* Um inquilino Truthlocks ativo com uma chave de API
* Dados de eventos de ação de seu aplicativo (tentativas de login, chamadas de API, transações ou qualquer ação repetível)

## Registrando uma ação

Envie uma requisição `POST` para `/v1/risk/velocity/record` com o assunto, tipo de ação e metadados opcionais:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/velocity/record \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user_abc123",
    "action_type": "login.failed",
    "ip_address": "198.51.100.42"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/velocity/record", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject_id: "user_abc123",
    action_type: "login.failed",
    ip_address: "198.51.100.42",
  }),
});
const result = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/velocity/record",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "subject_id": "user_abc123",
        "action_type": "login.failed",
        "ip_address": "198.51.100.42",
    },
)
result = resp.json()
```

A resposta retorna as contagens da janela atual, a pontuação de velocidade calculada e se um sinal de risco foi ingerido automaticamente:

```json theme={null}
{
  "subject_id": "user_abc123",
  "action_type": "login.failed",
  "windows": {
    "1m": 3,
    "5m": 8,
    "1h": 15,
    "24h": 42
  },
  "velocity_score": 72,
  "signal_ingested": true,
  "signal_id": "a1b2c3d4-..."
}
```

## Modelo de pontuação

A pontuação de velocidade é uma soma ponderada das contagens de ações em quatro janelas contínuas. Janelas curtas têm maior peso para priorizar a detecção de picos:

| Janela | Peso | Propósito |
| :- | :- | :- |
| 1 minuto | 30 | Detecta rajadas rápidas (credential stuffing, ataques automatizados) |
| 5 minutos | 20 | Deteta abuso sustentado de curto prazo |
| 1 hora | 10 | Identifica padrões de médio prazo |
| 24 horas | 5 | Sinaliza anomalias persistentes por períodos mais longos |

A pontuação final é limitada a 100. Quando a pontuação atinge **60 ou mais**, um sinal de risco é automaticamente ingerido com `signal_type: "velocity"`.

### Interpretação da pontuação

| Faixa de pontuação | Interpretação | Exemplo |
| :- | :- | :- |
| 0–29 | Normal | Atividade típica do usuário |
| 30–59 | Elevado | Frequência acima da média, vale a pena monitorar |
| 60–79 | Alto | Provavelmente automatizado ou abusivo — sinal auto-ingerido |
| 80–100 | Crítico | Anomalia forte — investigação imediata recomendada |

## Consultando janelas de velocidade

Recupere as janelas de velocidade atuais para um assunto específico:

```bash cURL theme={null}
curl https://api.truthlocks.com/v1/risk/velocity/user_abc123 \
  -H "X-API-Key: tl_live_..."
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/velocity/user_abc123", {
  headers: { "X-API-Key": "tl_live_..." },
});
const windows = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.get(
    "https://api.truthlocks.com/v1/risk/velocity/user_abc123",
    headers={"X-API-Key": "tl_live_..."},
)
windows = resp.json()
```

A resposta inclui todos os tipos de ação rastreados para o sujeito, com contagens por janela e a pontuação de velocidade calculada para cada um:

```json theme={null}
{
  "subject_id": "user_abc123",
  "actions": [
    {
      "action_type": "login.failed",
      "windows": {
        "1m": 0,
        "5m": 2,
        "1h": 8,
        "24h": 23
      },
      "velocity_score": 45
    },
    {
      "action_type": "api.request",
      "windows": {
        "1m": 12,
        "5m": 45,
        "1h": 200,
        "24h": 800
      },
      "velocity_score": 87
    }
  ]
}
```

## Listando anomalias de alta velocidade

Consulte os assuntos com pontuações de velocidade acima de um limite em seu locatário:

```bash cURL theme={null}
curl "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25" \
  -H "X-API-Key: tl_live_..."
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25",
  { headers: { "X-API-Key": "tl_live_..." } }
);
const anomalies = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.get(
    "https://api.truthlocks.com/v1/risk/velocity",
    params={"min_score": 50, "limit": 25},
    headers={"X-API-Key": "tl_live_..."},
)
anomalies = resp.json()
```

Cada resultado inclui o assunto, tipo de ação, contagens da janela atual e a pontuação de velocidade que qualificou a anomalia:

```json theme={null}
{
  "anomalies": [
    {
      "subject_id": "user_abc123",
      "action_type": "login.failed",
      "windows": {
        "1m": 5,
        "5m": 12,
        "1h": 30,
        "24h": 85
      },
      "velocity_score": 68,
      "last_recorded_at": "2027-07-03T14:22:00Z"
    }
  ],
  "cursor": "eyJsYXN0X2lkIjo..."
}
```

## Padrões de integração

### Bloquear ou limitar em alta velocidade

Use a pontuação de velocidade da resposta do registro para decidir se permite, limita ou bloqueia uma ação:

```javascript theme={null}
const result = await recordAction(subjectId, "api.request", ipAddress);

if (result.velocity_score >= 80) {
  await blockSubject(subjectId);
  await notifySecurityTeam(result);
} else if (result.velocity_score >= 60) {
  await throttleRequests(subjectId, { maxPerMinute: 5 });
} else if (result.velocity_score >= 30) {
  await addRateLimitWarning(subjectId);
}
```

### Combinar com detecção de ATO

A pontuação de velocidade rastreia qualquer tipo de ação em várias janelas de tempo, enquanto a [detecção de ATO](https://docs.truthlocks.com/pt/guides/ato-detection.md) é especificamente otimizada para padrões de aquisição de conta baseados em login com regras de limite e gerenciamento de alertas integrados. Use ambos juntos para proteção em camadas:

* **Pontuação de velocidade** para detecção geral de abuso — abuso de taxa de API, inundação de transações, spam de registro
* **Detecção de ATO** para segurança de login focada — velocidade de login falho, alertas de preenchimento de credenciais, perfis de risco do sujeito

### Monitorizar via webhooks

Configure um [endpoint de webhook](https://docs.truthlocks.com/pt/guides/webhooks.md) para receber notificações em tempo real quando sinais de risco baseados em velocidade forem criados, para que sua equipe de segurança possa responder sem sondagem.

### Tipos de ação personalizados

Você pode rastrear qualquer tipo de ação que seu aplicativo produza. Exemplos comuns:

| Tipo de ação | Caso de uso |
| :- | :- |
| `login.failed` | Tentativas de login falhadas |
| `api.request` | Frequência de chamadas da API |
| `transaction.create` | Tentativas de pagamento ou transferência |
| `registration.attempt` | Spam de criação de conta |
| `password.reset` | Abuso de redefinição de senha |
| `verification.request` | Inundação de solicitações de verificação |

## Medição de uso

Cada chamada para `POST /v1/risk/velocity/record` incrementa o contador de uso `antifraud.velocity_records` para o seu ciclo de faturamento. Você pode monitorar seu consumo com a [API de uso](https://docs.truthlocks.com/pt/api-reference/billing/usage.md) ou no console em **Configurações > Faturamento > Uso** na seção **Anti-Fraude**.

> [!NOTE]
>
> As cotas de registro de velocidade variam de acordo com o nível do plano. Consulte a [visão geral de faturamento](https://docs.truthlocks.com/pt/billing/overview.md#metered-products) para obter detalhes sobre todos os produtos medidos Anti-Fraude.

## O que vem a seguir

* [Registrar referência da API de ação de velocidade](https://docs.truthlocks.com/pt/api-reference/risk/velocity-record.md)
* [Obter referência da API de janelas de velocidade](https://docs.truthlocks.com/pt/api-reference/risk/velocity-windows.md)
* [Listar referência da API de anomalias de velocidade](https://docs.truthlocks.com/pt/api-reference/risk/velocity-anomalies.md)
* [Guia de sinais de risco](https://docs.truthlocks.com/pt/guides/risk-signals.md)
* [Guia de detecção de aquisição de conta](https://docs.truthlocks.com/pt/guides/ato-detection.md)
* [Guia de detecção de deepfake e personificação](https://docs.truthlocks.com/pt/guides/deepfake-detection.md)


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