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

# Señales de riesgo

> Ingiere señales de detección de fraude de cualquier fuente, normaliza los eventos de identidad en señales puntuadas y las consulta por entidad, puntuación o tipo.

Las señales de riesgo le permiten alimentar datos de detección de fraude en Truthlocks desde cualquier proveedor ascendente: servicios de huellas dactilares de dispositivos, API de reputación de IP, herramientas de verificación de correo electrónico, motores de análisis de documentos o sus propias reglas internas. Una vez ingeridas, las señales están disponibles a través de la API y la página **Riesgo y Fraude > Señales** en la consola.

> [!NOTE]
>
> El Firewall de Identidad Antifraude está **generalmente disponible**. Las cinco rutas de detección —ingesta directa de señales, normalización de eventos, escaneo de deepfakes, detección de ATO y puntuación de velocidad— están integradas con ejemplos de API en varios idiomas (cURL, JavaScript, Python), guías de principio a fin y [notificaciones de webhook](https://docs.truthlocks.com/es/guides/webhooks.md) en tiempo real para todos los tipos de señales. Las [decisiones de riesgo](https://docs.truthlocks.com/es/api-reference/risk/evaluate.md) automatizadas, la [gestión de casos](#case-management) y la [exportación de SIEM de fraude](#siem-export) ya están disponibles.

Puede crear señales de cinco maneras:

* **Ingesta directa** — envíe una señal completamente puntuada a través de `POST /v1/risk/signals` cuando ya tenga una puntuación de riesgo de un proveedor externo. Admite reintentos idempotentes a través del encabezado `Idempotency-Key`.
* **Normalización de eventos** — envíe un evento de identidad sin procesar a través de `POST /v1/risk/events` y deje que la plataforma lo asigne a un tipo de señal y una puntuación base automáticamente. Consulte [normalización de eventos](#event-normalization).
* **Puntuación de señales de deepfake y suplantación de identidad** — envíe indicadores o puntuaciones producidos externamente para la evaluación del umbral a través de `POST /v1/risk/deepfake/scan`. Los escaneos que obtienen una puntuación de 60 o más ingieren automáticamente una señal de riesgo. Consulte la [guía de detección de deepfakes](https://docs.truthlocks.com/es/guides/deepfake-detection.md).
* **Detección de toma de control de cuenta** — evalúe los eventos de inicio de sesión contra heurísticas basadas en velocidad a través de `POST /v1/risk/ato/evaluate`. Las alertas se crean y las señales de riesgo se ingieren automáticamente cuando se superan los umbrales. Consulte la [guía de detección de ATO](https://docs.truthlocks.com/es/guides/ato-detection.md).
* **Puntuación de velocidad y anomalías** — registre las acciones del sujeto a través de `POST /v1/risk/velocity/record` y haga que la plataforma rastree la frecuencia en ventanas de tiempo continuas (1 m, 5 m, 1 h, 24 h). Las acciones que producen una puntuación de velocidad ponderada de 60 o más ingieren automáticamente una señal de riesgo. Consulte la [guía de puntuación de velocidad](https://docs.truthlocks.com/es/guides/velocity-scoring.md).

### Elegir una ruta de ingesta

| Escenario | Usar | Punto final |
| :- | :- | :- |
| Tiene una puntuación de riesgo de una herramienta externa de fraude | Ingesta directa | `POST /v1/risk/signals` |
| Desea que los eventos nativos de la plataforma (inicios de sesión fallidos, detecciones de deepfake) se puntúen automáticamente | Normalización de eventos | `POST /v1/risk/events` |
| Desea puntuar los indicadores de deepfake o suplantación de identidad proporcionados | Escaneo de deepfake | `POST /v1/risk/deepfake/scan` |
| Desea detectar intentos de toma de control de cuentas basados en la velocidad de inicio de sesión | Detección de ATO | `POST /v1/risk/ato/evaluate` |
| Desea detectar anomalías de velocidad en cualquier tipo de acción | Puntuación de velocidad | `POST /v1/risk/velocity/record` |
| Utiliza múltiples fuentes de señal | Las cinco — las señales llegan a la misma tubería | Cualquier punto final |

Las cinco rutas producen los mismos registros de señales de riesgo. Puede consultar, filtrar y revisar las señales de cualquier ruta utilizando el [punto final de lista](https://docs.truthlocks.com/es/api-reference/risk-signals/list.md) y la página de la consola **Riesgo y Fraude > Señales**.

## Cómo funciona

**1. Ingerir señales**

Envíe una solicitud `POST` a `/v1/risk/signals` con la fuente de la señal, el tipo, la puntuación de riesgo y el sujeto al que se refiere. Adjunte cualquier contexto adicional en el objeto `payload`.

**2. Consultar y filtrar**

Utilice `GET /v1/risk/signals` para listar señales con filtros por fuente, tipo de señal, sujeto y puntuación mínima. Los resultados se paginan con paginación basada en cursor.

**3. Revisar en la consola**

Abre **Riesgo y Fraude > Señales** en la consola del inquilino para explorar señales, filtrar por fuente o puntuación, e inspeccionar detalles de señales individuales.

## Requisitos previos

* Un inquilino activo de Truthlocks con una clave API
* Al menos una fuente de detección de fraude ascendente que produzca señales puntuadas

## Ingesta de una señal

Envíe una solicitud `POST` con los campos requeridos:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/signals \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "signal_source": "external",
    "signal_type": "velocity",
    "risk_score": 85,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f",
    "payload": {
      "ip": "203.0.113.42",
      "country": "US",
      "reason": "multiple_accounts_same_device"
    },
    "ip_address": "203.0.113.42"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/signals", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    signal_source: "external",
    signal_type: "velocity",
    risk_score: 85,
    subject_type: "user",
    subject_id: "usr_8f14e45f",
    payload: {
      ip: "203.0.113.42",
      country: "US",
      reason: "multiple_accounts_same_device",
    },
    ip_address: "203.0.113.42",
  }),
});
const signal = await response.json();
```

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

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/signals",
    headers={
        "X-API-Key": "tl_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "signal_source": "external",
        "signal_type": "velocity",
        "risk_score": 85,
        "subject_type": "user",
        "subject_id": "usr_8f14e45f",
        "payload": {
            "ip": "203.0.113.42",
            "country": "US",
            "reason": "multiple_accounts_same_device",
        },
        "ip_address": "203.0.113.42",
    },
)
signal = resp.json()
```

### Campos obligatorios

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `signal_source` | string | Origen de la señal — `verification`, `login`, `attestation`, `external`, o `manual` |
| `signal_type` | string | Qué se detectó (por ejemplo, `velocity`, `geo_anomaly`, `device_fingerprint`, `behavior`, `deepfake`, `ato`, `impersonation`) |
| `risk_score` | integer | Puntuación de riesgo de `0` (seguro) a `100` (alto riesgo). Las puntuaciones iguales o superiores a 80 activan la revisión automática. |
| `subject_type` | string | Tipo de entidad: `user`, `issuer`, `attestation`, `session`, `ip`, o `device` |
| `subject_id` | string | Identificador de la entidad que se está evaluando |

### Campos opcionales

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `payload` | object | JSON arbitrario con contexto específico de la señal (direcciones IP, geolocalización, razones) |
| `ip_address` | string | Dirección IP de origen asociada con este evento |
| `user_agent` | string | Cadena User-Agent asociada con este evento |

### Idempotencia

Incluya un encabezado `Idempotency-Key` (UUID) para evitar señales duplicadas durante los reintentos. Si envía la misma clave dos veces, el duplicado se ignora silenciosamente.

## Consulta de señales

### Listar con filtros

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

Filtros disponibles:

| Parámetro | Descripción |
| :- | :- |
| `source` | Filtrar por fuente de señal |
| `signal_type` | Filtrar por tipo de señal |
| `subject_type` | Filtrar por tipo de sujeto |
| `subject_id` | Filtrar por ID de sujeto |
| `min_score` | Umbral de puntuación mínima (0–100) |
| `limit` | Resultados por página (máx. 100) |
| `cursor` | Cursor para la página siguiente |

### Obtener una sola señal

```bash theme={null}
curl https://api.truthlocks.com/v1/risk/signals/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: tl_live_..."
```

## Vista de Console

La página **Riesgo y Fraude > Señales** en la consola proporciona una lista de todas las señales ingeridas, que se puede buscar y filtrar. Cada fila muestra la fuente, el tipo, la puntuación (codificada por colores según la gravedad), la referencia del sujeto y la marca de tiempo.

Utilice los filtros en la parte superior de la página para restringir los resultados por fuente, tipo de señal o puntuación mínima. Haga clic en cualquier fila para ver los detalles completos de la señal, incluido el objeto de metadatos `payload`.

## Directrices de puntuación

La puntuación consistente entre fuentes hace que el análisis posterior sea más fiable. Recomendamos los siguientes rangos:

| Rango | Interpretación | Ejemplo |
| :- | :- | :- |
| 0 – 30 | Bajo riesgo | Dispositivo conocido bueno, IP de buena reputación |
| 30 – 60 | Riesgo moderado | Uso de VPN, velocidad de nuevas cuentas |
| 60 – 80 | Riesgo crítico | Correo electrónico desechable, IP de centro de datos |
| 80 – 100 | Riesgo crítico | Dispositivo de fraude conocido, viaje imposible |

> [!WARNING]
>
> Las puntuaciones iguales o superiores a 80 activan decisiones de revisión automáticas. La interpretación de la puntuación más allá del umbral automático depende de usted; la plataforma almacena y devuelve las puntuaciones tal cual y no las normaliza entre fuentes.

## Normalización de eventos

En lugar de construir señales de riesgo manualmente, puede enviar eventos de identidad sin procesar y dejar que la plataforma los normalice en señales automáticamente. Esto es útil cuando desea alimentar eventos nativos de la plataforma —inicios de sesión fallidos, firmas no válidas, sospechosos de deepfake— directamente en la tubería de riesgo sin asignarlos usted mismo a tipos de señales.

Envíe una solicitud `POST` a `/v1/risk/events` con el origen, tipo y asunto del evento:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/events \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_source": "login",
    "event_type": "login.failed.repeated",
    "subject_id": "user_abc123",
    "ip_address": "198.51.100.42",
    "payload": { "attempt_count": 8, "window_seconds": 120 }
  }'
```

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

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

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/events",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "event_source": "login",
        "event_type": "login.failed.repeated",
        "subject_id": "user_abc123",
        "ip_address": "198.51.100.42",
        "payload": {"attempt_count": 8, "window_seconds": 120},
    },
)
result = resp.json()
```

La respuesta incluye tanto el `event_id` sin procesar como el `signal_id` normalizado, para que pueda rastrear la tubería completa desde el evento hasta la señal:

```json theme={null}
{
  "event_id": "2a4b6c8d-...",
  "signal_id": "9f3a1c2d-...",
  "event_type": "login.failed.repeated",
  "signal_type": "ato",
  "risk_score": 70,
  "normalized": true,
  "created_at": "2027-05-01T10:00:00Z"
}
```

Cuando `normalized` es `true`, el evento coincidió con una asignación conocida. Cuando `false`, la plataforma utilizó el recurso genérico.

### Mapeos de eventos incorporados

La plataforma viene con mapeos precalibrados para eventos de identidad comunes:

| Tipo de evento | Tipo de señal | Puntuación base |
| :- | :- | :- |
| `verification.failed` | behavior | 60 |
| `verification.invalid_sig` | behavior | 75 |
| `login.failed.repeated` | ato | 70 |
| `login.suspicious_geo` | geo\_anomaly | 65 |
| `attestation.deepfake_suspect` | deepfake | 85 |
| `session.hijack_suspect` | ato | 90 |

Se aceptan tipos de eventos desconocidos con el tipo de señal `behavior` y una puntuación base de 10.

### Campos de evento

**Requerido:**

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `event_source` | string | Sistema que generó el evento — `attestation`, `verification`, `login`, o `consumer_portal` |
| `event_type` | string | Nombre del evento sin procesar (por ejemplo, `login.failed.repeated`, `attestation.deepfake_suspect`) |
| `subject_id` | string | Identificador de la entidad involucrada en el evento |

**Opcional:**

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `event_ref_id` | string | ID de referencia externa (ID de atestación, ID de sesión) para referencias cruzadas |
| `ip_address` | string | Dirección IP de origen |
| `payload` | object | Carga útil de evento sin procesar para contexto de enriquecimiento |

> [!NOTE]
>
> Utilice la normalización de eventos cuando sus eventos se originen dentro de la plataforma (inicios de sesión, verificaciones, atestaciones). Utilice el [punto final de ingesta de señales](https://docs.truthlocks.com/es/api-reference/risk/ingest-signal.md) directo cuando ya tenga una señal puntuada de una fuente externa.

## Aislamiento de inquilinos

Las señales de riesgo están completamente aisladas por inquilino utilizando [seguridad a nivel de fila (RLS)](https://docs.truthlocks.com/es/security/rls.md). Cada señal está vinculada al inquilino autenticado en el momento de la ingesta, y las consultas solo pueden devolver señales que pertenecen al inquilino que realiza la llamada.

## Detección de deepfake e impersonación

La [API de detección de deepfakes](https://docs.truthlocks.com/es/guides/deepfake-detection.md) extiende la canalización de señales de riesgo con escaneo automatizado de contenido manipulado y fraude de identidad. Envíe imágenes, videos, documentos o atestaciones para su análisis, y los escaneos que excedan el umbral de riesgo crean automáticamente una señal de riesgo, sin necesidad de una llamada API adicional.

Consulte la [guía de detección de deepfake e suplantación de identidad](https://docs.truthlocks.com/es/guides/deepfake-detection.md) para conocer el flujo de trabajo completo, la referencia de indicadores y los ejemplos de código.

## Detección de apropiación de cuenta

La [API de detección de ATO](https://docs.truthlocks.com/es/guides/ato-detection.md) extiende la canalización de señales de riesgo con monitoreo de inicio de sesión basado en velocidad. Envíe eventos de inicio de sesión a `POST /v1/risk/ato/evaluate` y la plataforma rastrea los intentos fallidos por sujeto en una ventana móvil de una hora. Cuando un sujeto cruza un umbral (5, 10 o 20 inicios de sesión fallidos), se crea una alerta y se ingiere automáticamente una señal de riesgo, sin necesidad de una llamada API adicional.

Consulte la [guía de detección de apropiación de cuentas](https://docs.truthlocks.com/es/guides/ato-detection.md) para conocer el flujo de trabajo completo, la referencia de umbrales y los patrones de integración.

## Puntuación de velocidad y anomalías

La [API de puntuación de velocidad](https://docs.truthlocks.com/es/guides/velocity-scoring.md) extiende la canalización de señales de riesgo con seguimiento de acciones de múltiples ventanas y detección de anomalías. Registre cualquier acción del sujeto a través de `POST /v1/risk/velocity/record` y la plataforma rastrea la frecuencia en cuatro ventanas móviles (1 m, 5 m, 1 h, 24 h). Se calcula una puntuación de velocidad ponderada a partir de los recuentos de ventanas, sesgada hacia ventanas cortas para la detección de ráfagas. Cuando la puntuación alcanza 60 o más, se ingiere automáticamente una señal de riesgo con `signal_type: "velocity"`, sin necesidad de una llamada API adicional.

Consulte la [guía de puntuación de velocidad y anomalías](https://docs.truthlocks.com/es/guides/velocity-scoring.md) para conocer el flujo de trabajo completo, el modelo de puntuación y los patrones de integración.

## Notificaciones de webhook

Las señales de riesgo creadas por cualquiera de las cinco rutas de detección pueden activar notificaciones [webhook](https://docs.truthlocks.com/es/guides/webhooks.md) en tiempo real. Suscríbase a `risk.signal.created` o `risk.signal.escalated` para reaccionar a nuevas señales sin sondeo. Esto cubre señales de ingesta directa, normalización de eventos, escaneos de deepfake, alertas de ATO y anomalías de velocidad.

Consulte la [guía de webhooks](https://docs.truthlocks.com/es/guides/webhooks.md#risk-signal-notifications) para ejemplos de carga útil y patrones de integración.

## Medición de uso

Las funciones antifraude se miden por ciclo de facturación. Cada ruta de detección incrementa su propio contador de uso:

| Métrica | Acción medida |
| :- | :- |
| `antifraud.risk_signals` | Señales de riesgo ingeridas o generadas (las cinco rutas) |
| `antifraud.deepfake_scans` | Solicitudes de escaneo de deepfake e suplantación de identidad |
| `antifraud.velocity_records` | Registros de acción de puntuación de velocidad |

Las cuotas varían según el nivel del plan. Puede verificar su consumo actual 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**. Para verificar si una operación específica está permitida antes de realizarla, use el [punto final de verificación de límites](https://docs.truthlocks.com/es/api-reference/billing/entitlements.md).

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

La respuesta incluye todos los contadores Anti-Fraude con los campos `used`, `limit` y `period` para que pueda monitorear el consumo programáticamente.

> [!NOTE]
>
> Consulte la [descripción general de facturación](https://docs.truthlocks.com/es/billing/overview.md#metered-products) para obtener la lista completa de 16 productos medidos y sus tarifas predeterminadas.

## Qué sigue

* [Guía de puntuación de velocidad y anomalías](https://docs.truthlocks.com/es/guides/velocity-scoring.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)
* [Referencia de la API de ingesta de señal de riesgo](https://docs.truthlocks.com/api-reference/risk-signals/ingest)
* [Referencia de la API de normalización de eventos de identidad](https://docs.truthlocks.com/es/api-reference/risk/normalize-event.md)
* [Referencia de la API de lista de señales de riesgo](https://docs.truthlocks.com/es/api-reference/risk-signals/list.md)
* [Referencia de la API de obtención de señal de riesgo](https://docs.truthlocks.com/es/api-reference/risk-signals/get.md)
* [Seguridad a nivel de fila](https://docs.truthlocks.com/es/security/rls.md)


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