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

# Envío de eventos con el SDK: captura en el cliente

> Didit captura inicios de sesión, partidas y actividad de sesión desde el dispositivo con una credencial acotada, aplicando vínculo y red en el servidor.

La mayoría de los [eventos](https://docs.didit.me/es/transaction-monitoring/events.md) relevantes para el fraude ocurren en el dispositivo: el inicio de sesión, la sesión, la ronda de juego y la telemetría de tiempos que distingue a una persona de un script. El canal del dispositivo los envía sin poner una clave de API en un navegador.

Tu backend emite una credencial de corta duración limitada a un usuario, y la aplicación envía eventos con ella.

## Flujo

**1. Emite una credencial de monitorización**

Tu backend invoca `POST /v3/events/sdk-token/` con tu clave de API y el `vendor_data` del usuario.

**2. Envía desde el dispositivo**

La aplicación envía una solicitud a `POST /v1/events/` (o `POST /v1/events/batch/`) con el encabezado `X-Monitoring-Token`.

**3. Las reglas se ejecutan como siempre**

El evento se enriquece, se agrega y se evalúa con exactamente las mismas [reglas](https://docs.didit.me/es/transaction-monitoring/event-rules.md) que un evento enviado desde el servidor.

## Emisión de una credencial

> [!NOTE]
>
> Para emitir credenciales, la [ingesta de eventos](https://docs.didit.me/es/transaction-monitoring/events.md) debe estar activada en la aplicación. Mientras esté desactivada, este endpoint responde `403` con `{"code": "event_monitoring_disabled"}` en lugar de entregar una credencial que nunca podría escribir.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user_391",
    "allowed_event_categories": ["auth", "session", "gameplay"],
    "ttl_seconds": 900,
    "max_uses": 1000,
    "bind_to_origin": "https://operator.example"
  }'
```

```json theme={null}
{
  "monitoring_token": "…",
  "expires_at": "2026-08-31T21:00:00Z",
  "allowed_event_categories": ["auth", "session", "gameplay"],
  "max_uses": 1000,
  "bind_to_origin": "https://operator.example"
}
```

| Campo | Valor predeterminado | Notas |
| - | - | - |
| `vendor_data` | obligatorio | El sujeto al que pertenecen todos los eventos enviados con esta credencial. |
| `entity_type` | `individual` | `individual` o `company`. |
| `allowed_event_categories` | todas | Limita lo que podría escribir una credencial filtrada. |
| `ttl_seconds` | 900 | 60 - 86400. |
| `max_uses` | 1000 | Un uso por **evento**, no por solicitud. |
| `bind_to_origin` | ninguno | Si se define, el `Origin` del navegador debe coincidir exactamente. |

## Envío

```bash theme={null}
curl -X POST https://verification.didit.me/v1/events/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "session-abc-login-1",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "session": { "session_id": "web-session-abc", "sequence": 1 },
    "device_context": { "fingerprint": "didit-fp-v2:a8c1" },
    "payload": { "method": "password" }
  }'
```

Fíjate en lo que el payload **no** incluye: ni clave de API ni sujeto. Ambos se imponen del lado del servidor.

## Lo que el servidor impone

* **Vinculación al sujeto.** La credencial queda limitada a un `vendor_data` en el momento de emitirla. Un bloque `subject` en el cuerpo de la solicitud se sobrescribe, de modo que un cliente manipulado no puede escribir en la línea de tiempo de otro usuario.
* **Contexto de red.** La dirección IP, el user agent, el accept-language y el origen se obtienen de la solicitud, y esos valores derivados por el servidor prevalecen sobre cualquier indicación del cliente en la evaluación de reglas. La evidencia de la regla registra la diferencia como [fuente del campo](https://docs.didit.me/es/transaction-monitoring/event-rules.md#evidencia).
* **Alcance por categoría.** Una credencial limitada a `session` no puede enviar un evento `payment`; se rechaza con `400`.
* **Presupuesto de usos.** Un lote consume un uso por evento, así que un lote de 500 eventos no puede eludir el límite de una credencial de 10 usos como si fuera un único uso.
* **Vinculación al origen.** Si `bind_to_origin` está definido, se rechaza toda solicitud cuyo `Origin` no coincida, incluida una que no tenga `Origin`.

## Envío por lotes

```bash theme={null}
curl -X POST https://verification.didit.me/v1/events/batch/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "…": "…" }, { "…": "…" } ] }'
```

Hasta 500 eventos por vaciado, con los mismos resultados por elemento que el [endpoint de lotes del servidor](https://docs.didit.me/es/transaction-monitoring/events.md#lotes). Un buen valor predeterminado es vaciar cada 25 eventos, cada 5 segundos o cuando la página o la aplicación pasa a segundo plano.

### Qué descartar ante contrapresión

Si tienes que descartar eventos, descarta los de menor valor. Estos se pueden descartar sin riesgo:

`session.page_view` · `session.sdk_heartbeat` · `session.sdk_loaded` · `session.device_seen` · `session.bot_signal_observed` · `bonus.promotion_viewed` · `affiliate.referral_clicked`

Estos no; envíalos primero:

todos los eventos `security`, `payment`, `dispute` y `responsible_gambling`, además de `gameplay.bet_placed`, `gameplay.bet_settled` y `gameplay.p2p_settlement`.

Los endpoints de listado devuelven, para cada evento, la misma clasificación que `is_droppable`, de modo que un cliente puede guiarse por ella en lugar de por una copia fija en el código.

## Compatibilidad de encabezados

El encabezado canónico es `X-Monitoring-Token`. `X-Transaction-Token` se acepta como alias temporal para que una aplicación que ya cuenta con una ruta de credenciales de transacciones pueda migrar de forma gradual.

> [!WARNING]
>
> El alias es transitorio y se eliminará antes de que la API de eventos alcance la disponibilidad general. Envía `X-Monitoring-Token` en el código nuevo.

## Elección del canal

| | Canal de dispositivo | Canal de servidor |
| - | - | - |
| Endpoint | `POST /v1/events/` | `POST /v3/events/` |
| Autenticación | `X-Monitoring-Token` | `x-api-key` |
| Sujeto | Vinculado a la credencial | En el payload |
| Ideal para | Inicios de sesión, sesiones, actividad de juego, telemetría | Pagos, disputas, eventos derivados del libro contable, cargas retroactivas |

Ambos generan registros de eventos idénticos y ejecutan las mismas reglas. Usa el canal de servidor siempre que no haya un usuario final presente.

## Siguientes pasos

> [card] [Ingesta de eventos](https://docs.didit.me/es/transaction-monitoring/events.md)
>
> El sobre, las categorías, la retención y la idempotencia.

> [card] [Reglas sobre eventos](https://docs.didit.me/es/transaction-monitoring/event-rules.md)
>
> Reglas de velocidad, proporción, secuencia y correlación.


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