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

# Puntuación de velocidad y anomalías

> Rastree la frecuencia de las acciones en ventanas de tiempo continuas, detecte anomalías de velocidad y ingiera automáticamente señales de riesgo cuando se superen los umbrales.

La API de puntuación de velocidad y anomalías rastrea la frecuencia con la que un sujeto realiza una acción determinada en múltiples ventanas de tiempo continuas: 1 minuto, 5 minutos, 1 hora y 24 horas. Cuando la puntuación de velocidad ponderada cruza un umbral, la plataforma crea automáticamente una [señal de riesgo](https://docs.truthlocks.com/es/guides/risk-signals.md), conectando la detección de anomalías directamente a la tubería del Firewall de Identidad Antifraude.

> [!NOTE]
>
> La puntuación de velocidad forma parte del [Cortafuegos de Identidad Anti-Fraude](https://docs.truthlocks.com/es/guides/risk-signals.md). Las señales generadas por anomalías de velocidad fluyen a la misma canalización que otras señales de fraude, por lo que puede consultarlas y revisarlas desde la página de la consola **Riesgo y Fraude > Señales** o el [punto de conexión de lista de señales](https://docs.truthlocks.com/es/api-reference/risk-signals/list.md).

## Cómo funciona

**1. Registrar acciones**

Llame a `POST /v1/risk/velocity/record` cada vez que un sujeto realice una acción rastreada: intentos de inicio de sesión, llamadas a la API, solicitudes de transacciones o cualquier tipo de acción personalizada.

**2. Seguimiento de ventana deslizante**

La plataforma incrementa los contadores para el sujeto y el tipo de acción en cuatro ventanas deslizantes (1 m, 5 m, 1 h, 24 h). Las ventanas se restablecen automáticamente cuando expiran.

**3. Puntuación ponderada**

Se calcula una puntuación de velocidad a partir de los recuentos de la ventana. Las ventanas cortas tienen un peso mayor para detectar ráfagas: 1 m × 30, 5 m × 20, 1 h × 10, 24 h × 5.

**4. Ingesta automática de señales**

Cuando la puntuación de velocidad alcanza 60 o más, la plataforma ingiere automáticamente una señal de riesgo con `signal_type: "velocity"`. No necesita una llamada a la API separada.

**5. Revisar y responder**

Consulta ventanas de velocidad para un sujeto, lista anomalías de alta velocidad en tu inquilino y revisa señales en la consola o a través de la API.

## Requisitos previos

* Un inquilino activo de Truthlocks con una clave API
* Datos de eventos de acción de su aplicación (intentos de inicio de sesión, llamadas API, transacciones o cualquier acción repetible)

## Grabación de una acción

Envíe una solicitud `POST` a `/v1/risk/velocity/record` con el asunto, el tipo de acción y metadatos opcionales:

```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()
```

La respuesta devuelve los recuentos de la ventana actual, la puntuación de velocidad calculada y si una señal de riesgo fue ingerida automáticamente:

```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 puntuación

La puntuación de velocidad es una suma ponderada de los recuentos de acciones en cuatro ventanas móviles. Las ventanas cortas tienen un peso mayor para priorizar la detección de ráfagas:

| Ventana | Peso | Propósito |
| :- | :- | :- |
| 1 minuto | 30 | Detecta ráfagas rápidas (relleno de credenciales, ataques automatizados) |
| 5 minutos | 20 | Detecta abuso sostenido a corto plazo |
| 1 hora | 10 | Identifica patrones a medio plazo |
| 24 horas | 5 | Marca anomalías persistentes durante períodos más largos |

La puntuación final está limitada a 100. Cuando la puntuación alcanza **60 o más**, se ingiere automáticamente una señal de riesgo con `signal_type: "velocity"`.

### Interpretación de la puntuación

| Rango de puntuación | Interpretación | Ejemplo |
| :- | :- | :- |
| 0–29 | Normal | Actividad de usuario típica |
| 30–59 | Elevado | Frecuencia superior a la media, vale la pena monitorear |
| 60–79 | Alto | Probablemente automatizado o abusivo — señal auto-ingestada |
| 80–100 | Crítico | Anomalía fuerte — se recomienda investigación inmediata |

## Consulta de ventanas de velocidad

Recuperar las ventanas de velocidad actuales para un sujeto 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()
```

La respuesta incluye todos los tipos de acciones rastreadas para el sujeto, con recuentos por ventana y la puntuación de velocidad calculada para cada uno:

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

## Listado de anomalías de alta velocidad

Consultar sujetos con puntuaciones de velocidad superiores a un umbral en su inquilino:

```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 incluye el sujeto, el tipo de acción, los recuentos de la ventana actual y la puntuación de velocidad que calificó la anomalía:

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

## Patrones de integración

### Bloquear o limitar ante alta velocidad

Utilice la puntuación de velocidad de la respuesta del registro para decidir si permitir, limitar o bloquear una acción:

```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 con detección de ATO

La puntuación de velocidad rastrea cualquier tipo de acción en múltiples ventanas de tiempo, mientras que [la detección de ATO](https://docs.truthlocks.com/es/guides/ato-detection.md) está específicamente optimizada para patrones de toma de control de cuentas basados en inicio de sesión con reglas de umbral y gestión de alertas integradas. Utilice ambos juntos para una protección por capas:

* **Puntuación de velocidad** para la detección general de abusos — abuso de la tasa de API, inundación de transacciones, spam de registro
* **Detección de ATO** para seguridad de inicio de sesión enfocada: velocidad de inicio de sesión fallida, alertas de relleno de credenciales, perfiles de riesgo del sujeto

### Monitorear a través de webhooks

Configure un [punto final de webhook](https://docs.truthlocks.com/es/guides/webhooks.md) para recibir notificaciones en tiempo real cuando se creen señales de riesgo basadas en la velocidad, para que su equipo de seguridad pueda responder sin sondeos.

### Tipos de acciones personalizadas

Puede rastrear cualquier tipo de acción que produzca su aplicación. Ejemplos comunes:

| Tipo de acción | Caso de uso |
| :- | :- |
| `login.failed` | Intentos de inicio de sesión fallidos |
| `api.request` | Frecuencia de llamadas a la API |
| `transaction.create` | Intentos de pago o transferencia |
| `registration.attempt` | Spam de creación de cuentas |
| `password.reset` | Abuso de restablecimiento de contraseña |
| `verification.request` | Inundación de solicitudes de verificación |

## Medición de uso

Cada llamada a `POST /v1/risk/velocity/record` incrementa el contador de uso de `antifraud.velocity_records` para su ciclo de facturación. Puede monitorear su consumo con la [API de uso](https://docs.truthlocks.com/es/api-reference/billing/usage.md) o en la consola en **Configuración > Facturación > Uso** en la sección **Antifraude**.

> [!NOTE]
>
> Las cuotas de registro de velocidad varían según el nivel del plan. Consulte la [descripción general de facturación](https://docs.truthlocks.com/es/billing/overview.md#metered-products) para obtener detalles sobre todos los productos medidos de Anti-Fraude.

## Qué sigue

* [Referencia de la API de registro de acción de velocidad](https://docs.truthlocks.com/es/api-reference/risk/velocity-record.md)
* [Referencia de la API de obtención de ventanas de velocidad](https://docs.truthlocks.com/es/api-reference/risk/velocity-windows.md)
* [Referencia de la API de lista de anomalías de velocidad](https://docs.truthlocks.com/es/api-reference/risk/velocity-anomalies.md)
* [Guía de señales de riesgo](https://docs.truthlocks.com/es/guides/risk-signals.md)
* [Guía de detección de toma de control de cuentas](https://docs.truthlocks.com/es/guides/ato-detection.md)
* [Guía de detección de deepfake e suplantación de identidad](https://docs.truthlocks.com/es/guides/deepfake-detection.md)


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