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

La mayoría de los eventos 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

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.

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.

Las reglas se ejecutan como siempre

El evento se enriquece, se agrega y se evalúa con exactamente las mismas reglas que un evento enviado desde el servidor.

Emisión de una credencial

Para emitir credenciales, la ingesta de eventos 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.

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"
  }'

{
  "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

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

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

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.

Primeros pasos

Funciones

Referencia

Consola

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

Flujo

Emisión de una credencial

Envío

Lo que el servidor impone

Envío por lotes

Qué descartar ante contrapresión

Compatibilidad de encabezados

Elección del canal

Siguientes pasos

Ingesta de eventos

Reglas sobre eventos

​Flujo

​Emisión de una credencial

​Envío

​Lo que el servidor impone

​Envío por lotes

​Qué descartar ante contrapresión

​Compatibilidad de encabezados

​Elección del canal

​Siguientes pasos

Ingesta de eventos

Reglas sobre eventos

Flujo

Emisión de una credencial

Envío

Lo que el servidor impone

Envío por lotes

Qué descartar ante contrapresión

Compatibilidad de encabezados

Elección del canal

Siguientes pasos