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

# Crear un evento de usuario para reglas y fraude

> Crea un evento de usuario para detección de fraude y validación de reglas — para seguimiento de comportamiento de usuarios y detección de fraude en gu1.

## Resumen

Crea un nuevo evento de usuario para rastrear acciones y comportamientos dentro de tu aplicación. Los eventos se usan para detección de fraude, monitoreo de cumplimiento, análisis de comportamiento y registros de auditoría. El sistema registra automáticamente dispositivos y puede opcionalmente crear entidades cuando no existen. Cuando se crea un evento, el motor de reglas se ejecuta automáticamente y devuelve tanto el resultado de las reglas como un resumen detallado de ejecución.

<Tip>
  📋 Los eventos registran automáticamente dispositivos cuando se proporcionan `deviceId` y `deviceDetails`, eliminando la necesidad de gestión separada de dispositivos.
</Tip>

## Endpoint

```
POST https://api.gu1.ai/events/user
```

## Autenticación

Requiere una clave API válida en el encabezado de Authorization:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Parámetros de Consulta

<ParamField query="withAutoEntity" type="boolean" default="false">
  Habilita la creación automática de entidad cuando no existe una entidad con el `taxId` proporcionado. Cuando es true, si el evento incluye un `taxId` y no existe ninguna entidad con ese ID tributario, se creará automáticamente una nueva entidad de persona o empresa.

  Ejemplo: `?withAutoEntity=true`
</ParamField>

## Cuerpo de la Solicitud

<ParamField body="eventType" type="string" required>
  Tipo de evento que se está rastreando. Debe ser uno de los tipos soportados (ver sección [Tipos de Eventos](#tipos-de-eventos)), incluyendo autenticación, transferencias, validación biométrica, etc.

  Ejemplo: `"LOGIN_SUCCESS"`
</ParamField>

<ParamField body="userId" type="string">
  Tu identificador interno de usuario. Se usa para agrupar eventos por usuario entre diferentes entidades.

  Ejemplo: `"user_12345"`
</ParamField>

<ParamField body="entityId" type="string">
  UUID de entidad de gu1. Proporciona esto si tienes el ID interno de gu1.

  <Note>
    **Identificación de Entidad**: Debes proporcionar al menos UNO de: `entityId`, `entityExternalId`, o `taxId`. Estos campos soportan lógica OR, por lo que el sistema encontrará la entidad usando cualquiera de estos identificadores. **Excepción SDK:** las organizaciones con el SDK habilitado pueden enviar solo un [`sessionId`](#sdk-events) para eventos anónimos pre-login.
  </Note>
</ParamField>

<ParamField body="entityExternalId" type="string">
  Tu identificador externo de entidad. Este es tu ID único para la entidad en tu sistema.

  Ejemplo: `"user_12345"`
</ParamField>

<ParamField body="taxId" type="string">
  Número de identificación tributaria (CPF, CNPJ, CUIT, etc.). Cuando se combina con `?withAutoEntity=true`, esto creará la entidad si no existe.

  Ejemplo: `"20242455496"`
</ParamField>

<ParamField body="timestamp" type="string">
  Cuándo ocurrió el evento en formato datetime ISO 8601. Si no se proporciona, toma por defecto la hora actual del servidor.

  Ejemplo: `"2026-01-30T14:30:00Z"`
</ParamField>

<ParamField body="eventDate" type="string">
  **Fecha de negocio** del evento. Las reglas históricas usan esta fecha como punto de partida para ventanas de tiempo (ej. "últimos 7 días").

  **Formato:** Cadena datetime ISO 8601 con zona horaria (ej. `"2026-01-30T14:30:00Z"` o `"2026-01-30T00:00:00.000Z"`).

  **Si no la envías:** El sistema usa el mismo valor que `timestamp` (o la hora actual del servidor si tampoco envías timestamp). El evento se trata como "ahora" para las reglas históricas; no hace falta enviarla cuando el evento es en tiempo real.
</ParamField>

<Note title="Resumen eventDate">
  * **Si se omite** → Se asigna `eventDate = timestamp` (o la hora actual). Las reglas históricas usan ese valor como punto de partida.
  * **Formato** → ISO 8601 con zona horaria: `"YYYY-MM-DDTHH:mm:ss.sssZ"` (ej. `"2026-01-30T00:00:00.000Z"`).
  * **Cuándo enviarla** → Cuando el evento ocurrió en una fecha distinta a la del envío (ej. eventos cargados a posteriori o en lote).
</Note>

<ParamField body="deviceId" type="string">
  Identificador único para el dispositivo. Este debe ser un identificador estable que persista entre sesiones.

  Ejemplo: `"840e89e4d46efd67"`
</ParamField>

<ParamField body="deviceDetails" type="object">
  Información detallada del dispositivo. Cuando se proporciona, el dispositivo será automáticamente registrado o actualizado.

  **Estructura:**

  ```json theme={null}
  {
    "platform": "android",
    "osName": "Android",
    "osVersion": "Android 16",
    "manufacturer": "samsung",
    "model": "SM-A156M",
    "brand": "samsung",
    "browser": "Chrome",
    "browserVersion": "120.0.6099.129",
    "latitude": -34.6037,
    "longitude": -58.3816,
    "city": "Buenos Aires",
    "region": "Buenos Aires",
    "country": "Argentina",
    "countryCode": "AR",
    "additionalDetails": {}
  }
  ```
</ParamField>

<ParamField body="ipAddress" type="string">
  Dirección IP desde la cual se originó el evento (IPv4 o IPv6).

  Ejemplo: `"10.40.64.231"`
</ParamField>

<ParamField body="country" type="string">
  Código de país ISO 3166-1 alfa-2 donde ocurrió el evento.

  Ejemplo: `"AR"`
</ParamField>

<ParamField body="isVpn" type="boolean" default="false">
  Si la conexión es a través de una VPN
</ParamField>

<ParamField body="isProxy" type="boolean" default="false">
  Si la conexión es a través de un proxy
</ParamField>

<ParamField body="isNewDevice" type="boolean">
  **Flag de dispositivo nuevo** persistido en el evento (`is_new_device` en base de datos). Ver [Cómo funciona `isNewDevice`](#como-funciona-isnewdevice) más abajo.
</ParamField>

<ParamField body="sessionId" type="string">
  Identificador de sesión del SDK (`sess_...`, máx. 64 caracteres). Para organizaciones con el SDK habilitado, un evento que trae solo `sessionId` (sin identificador de entidad) se acepta y persiste como **evento anónimo pre-login**; se vincula a la entidad más tarde, en el primer evento que traiga `sessionId` y un identificador de entidad juntos. Sin el SDK habilitado, sigue siendo obligatorio un identificador de entidad.

  Ejemplo: `"sess_a1b2c3d4"`
</ParamField>

<ParamField body="sdkSignals" type="object">
  Señales estructuradas emitidas por el SDK (separadas del `metadata` libre). Todos los campos opcionales: `sessionId`, `sessionDuration`, `integrityScore` (0–100), `integrityFlags` (`fetchHooked`, `prototypeModified`, `debuggerAttached`, `framingDetected`) y `behavioralSignals` (`keystrokeAvgMs`, `pasteDetected`, `completionTimeMs`, `touchVelocity`).
</ParamField>

<ParamField body="failedAttemptsCount" type="number" default="0">
  Número de intentos de autenticación fallidos (para eventos de autenticación)

  Ejemplo: `3`
</ParamField>

<ParamField body="destinationAccountId" type="string">
  Identificador de cuenta de destino para eventos de transferencia (CBU, CVU, etc.)

  Ejemplo: `"0170042640000004234411"`
</ParamField>

<ParamField body="destinationCuit" type="string">
  CUIT de destino para eventos de transferencia

  Ejemplo: `"27281455496"`
</ParamField>

<ParamField body="previousValue" type="string">
  Valor anterior para eventos de cambio de credenciales. Esto será automáticamente hasheado usando SHA-256 por seguridad.

  Ejemplo: `"old_password_hash"`
</ParamField>

<ParamField body="metadata" type="object">
  Datos adicionales específicos del evento como pares clave-valor. Usa esto para campos personalizados específicos de tu caso de uso.

  Ejemplo:

  ```json theme={null}
  {
    "amount": 5000,
    "currency": "ARS",
    "concept": "Payment",
    "reference": "INV-12345"
  }
  ```
</ParamField>

<ParamField body="userAgent" type="string">
  Cadena de user agent del navegador para eventos web

  Ejemplo: `"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..."`
</ParamField>

## Cómo funciona `isNewDevice`

El valor persistido en cada evento alimenta reglas de fraude (por ejemplo `historical.userEvent.newDevice` y filtros `isNewDevice: true` sobre `user_events`).

### Prioridad: si lo envías, se guarda tal cual

| Request                              | `isNewDevice` persistido                                                                             |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Envías `isNewDevice: true` o `false` | **Exactamente lo que enviaste** (gu1 no lo sobrescribe)                                              |
| Omites `isNewDevice`                 | gu1 **calcula** el valor (ver abajo); por defecto `false` si no hay datos de dispositivo suficientes |

Usá el flag explícito cuando tu app ya sabe si la sesión es en un dispositivo nuevo (SDK, almacenamiento local, registro propio). Omitilo cuando querés que gu1 lo infiera desde el registro de dispositivos.

### Si omites `isNewDevice` (inferencia en servidor)

gu1 solo calcula automáticamente cuando están **ambos**:

* `deviceId`
* `deviceDetails`

Flujo:

1. **Registra o actualiza** el dispositivo para la entidad resuelta (tabla `devices`).
2. Pone `isNewDevice` en `true` si:
   * No existe fila para `(organización, entidad, deviceId)`, o
   * El dispositivo existe pero `firstSeenAt` está dentro de los **últimos 5 minutos** (ventana de primer avistamiento).
3. En caso contrario `false` (dispositivo ya conocido por gu1 para esa entidad).

<Tip>
  Enviá `deviceId` + `deviceDetails` en login y eventos sensibles aunque setees `isNewDevice` vos mismo, para mantener el registro de dispositivos al día para otras reglas y auditoría.
</Tip>

### Nombre del campo en el body

`POST /events/user` usa **camelCase** en JSON: `isNewDevice`. El nombre `is_new_device` **no** se lee en este endpoint.

### Ejemplos

**Decide el cliente (cuando ya detectás dispositivo nuevo):**

```json theme={null}
{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "isNewDevice": true
}
```

**Inferencia en gu1 (omitir el flag; incluir dispositivo):**

```json theme={null}
{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "deviceDetails": { "platform": "android", "manufacturer": "samsung", "model": "SM-A156M" }
}
```

## Tipos de Eventos

<Tip>
  📋 Elige el tipo de evento más específico que coincida con tu caso de uso. Usa `OTHER_EVENT` solo cuando ningún tipo específico aplique.
</Tip>

### Eventos de Autenticación

* `LOGIN_SUCCESS` - Inicio de sesión exitoso
* `LOGIN_FAILED` - Intento de inicio de sesión fallido
* `LOGOUT` - Cierre de sesión de usuario
* `TOKEN_GENERATED` - Token de autenticación generado

### Eventos de Cambio de Credenciales

* `PASSWORD_CHANGE` - Contraseña cambiada exitosamente
* `PASSWORD_CHANGE_FAILED` - Intento de cambio de contraseña fallido
* `EMAIL_CHANGE` - Dirección de email cambiada
* `PHONE_CHANGE` - Número de teléfono cambiado
* `PIN_CHANGE` - PIN cambiado

### Eventos de Gestión de Cuenta

* `ACCOUNT_LINKED` - Cuenta bancaria vinculada
* `CONTACT_CREATED` - Contacto creado
* `CONTACT_DELETED` - Contacto eliminado
* `ADDRESS_CHANGED` - Dirección actualizada
* `DEVICE_ADDED` - Nuevo dispositivo agregado
* `DEVICE_DELETED` - Dispositivo eliminado

### Eventos de Gestión de Email

* `EMAIL_CREATED` - Email creado
* `EMAIL_ELIMINATED` - Email eliminado

### Eventos de Navegación

* `NAVIGATION` - Navegación de página o pantalla

### Eventos de Transferencia

* `TRANSFER_SUCCESS` - Transferencia exitosa
* `TRANSFER_FAILED` - Intento de transferencia fallido
* `TRANSFER_SCHEDULED` - Transferencia programada para el futuro

### Eventos de Saldo

* `BALANCE_CHECK` - Saldo de cuenta consultado
* `BALANCE_CHECK_FAILED` - Consulta de saldo fallida

### Eventos de Acceso a Cuenta

* `ACCOUNTS_VIEW` - Lista de cuentas visualizada
* `ACCOUNTS_VIEW_FAILED` - Visualización de cuentas fallida

### Eventos de Transacciones

* `TRANSACTIONS_VIEW` - Historial de transacciones visualizado
* `TRANSACTIONS_VIEW_FAILED` - Visualización de transacciones fallida

### Eventos de Destinatarios

* `SEARCH_RECIPIENTS` - Destinatarios buscados
* `SEARCH_RECIPIENTS_FAILED` - Búsqueda de destinatarios fallida
* `SCHEDULE_RECIPIENT_FAILED` - Programación de destinatario fallida

### Eventos de Perfil

* `PROFILE_VIEW` - Perfil de usuario visualizado
* `PROFILE_UPDATED` - Perfil de usuario actualizado

### Eventos de Mensajes

* `MESSAGES_VIEW` - Mensajes visualizados
* `MESSAGES_VIEW_FAILED` - Visualización de mensajes fallida

### Eventos de Titulares de Cuenta

* `ACCOUNT_HOLDERS_VIEW` - Titulares de cuenta visualizados
* `ACCOUNT_HOLDERS_VIEW_FAILED` - Visualización de titulares de cuenta fallida

### Eventos de Alias

* `ALIAS_VIEW` - Alias visualizado
* `ALIAS_VIEW_FAILED` - Visualización de alias fallida
* `ALIAS_CHANGE` - Alias cambiado
* `ALIAS_CHANGE_FAILED` - Cambio de alias fallido

### Pago / Dispositivo

* `CARD_ADDED` - Tarjeta de pago añadida
* `DEVICE_CONNECTED` - Dispositivo conectado

### Validación Biométrica

* `BIOMETRIC_VALIDATION_SUCCESS` - Validación biométrica exitosa
* `BIOMETRIC_VALIDATION_ERROR` - Validación biométrica fallida

### Eventos del SDK

* `SESSION_STARTED` - Beacon de sesión del SDK (pre-login)
* `SESSION_IDENTIFIED` - Sesión vinculada a una entidad (enviado con `sessionId` y un identificador de entidad)
* `SCREEN_VIEW` - Pantalla/navegación registrada por el SDK

### Otros Eventos

* `OTHER_EVENT` - Evento personalizado o genérico

## Respuesta

<ResponseField name="success" type="boolean">
  Indica si la solicitud fue exitosa
</ResponseField>

<ResponseField name="event" type="object">
  El objeto de evento creado

  <ResponseField name="event.id" type="string">
    UUID de evento interno de gu1
  </ResponseField>

  <ResponseField name="event.eventType" type="string">
    Tipo de evento creado
  </ResponseField>

  <ResponseField name="event.userId" type="string">
    Identificador de usuario
  </ResponseField>

  <ResponseField name="event.entityId" type="string">
    UUID de entidad asociada
  </ResponseField>

  <ResponseField name="event.entityExternalId" type="string">
    Identificador externo de entidad
  </ResponseField>

  <ResponseField name="event.taxId" type="string">
    Número de identificación tributaria
  </ResponseField>

  <ResponseField name="event.timestamp" type="string">
    Timestamp del evento (ISO 8601)
  </ResponseField>

  <ResponseField name="event.eventDate" type="string">
    Fecha de negocio usada por reglas históricas para ventanas de tiempo (ISO 8601). Igual a timestamp si no se envió.
  </ResponseField>

  <ResponseField name="event.deviceId" type="string">
    Identificador del dispositivo
  </ResponseField>

  <ResponseField name="event.ipAddress" type="string">
    Dirección IP
  </ResponseField>

  <ResponseField name="event.country" type="string">
    Código de país
  </ResponseField>

  <ResponseField name="event.createdAt" type="string">
    Timestamp de creación del registro de evento
  </ResponseField>
</ResponseField>

<ResponseField name="entity" type="object">
  Información de la entidad (cuando es creada automáticamente o existente)

  <ResponseField name="entity.id" type="string">
    UUID de entidad
  </ResponseField>

  <ResponseField name="entity.wasCreated" type="boolean">
    Si la entidad fue creada automáticamente por este evento
  </ResponseField>
</ResponseField>

<ResponseField name="rulesResult" type="object">
  Resultado de la ejecución del motor de reglas

  <ResponseField name="rulesResult.decision" type="string">
    Decisión final del motor de reglas (APPROVE, REVIEW, REJECT)
  </ResponseField>
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="object">
  Resumen detallado de la ejecución del motor de reglas, incluyendo todas las reglas evaluadas y sus resultados. Este objeto proporciona visibilidad completa de qué reglas se ejecutaron, qué condiciones se cumplieron, y cómo se tomó la decisión final. Estructura completa y ejemplo: [Resumen de Ejecución de Reglas](/es/api-reference/rules-execution-summary).
</ResponseField>

## Ejemplos

### Evento de Inicio de Sesión

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gu1.ai/events/user \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "LOGIN_SUCCESS",
      "entityExternalId": "user_12345",
      "userId": "user_12345",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "deviceDetails": {
        "platform": "android",
        "manufacturer": "samsung",
        "model": "SM-A156M",
        "osVersion": "Android 16"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/events/user', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventType: 'LOGIN_SUCCESS',
      entityExternalId: 'user_12345',
      userId: 'user_12345',
      deviceId: '840e89e4d46efd67',
      ipAddress: '10.40.64.231',
      country: 'AR',
      deviceDetails: {
        platform: 'android',
        manufacturer: 'samsung',
        model: 'SM-A156M',
        osVersion: 'Android 16'
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.post(
      'https://api.gu1.ai/events/user',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'eventType': 'LOGIN_SUCCESS',
          'entityExternalId': 'user_12345',
          'userId': 'user_12345',
          'deviceId': '840e89e4d46efd67',
          'ipAddress': '10.40.64.231',
          'country': 'AR',
          'deviceDetails': {
              'platform': 'android',
              'manufacturer': 'samsung',
              'model': 'SM-A156M',
              'osVersion': 'Android 16'
          }
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Evento de Transferencia

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gu1.ai/events/user \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "TRANSFER_SUCCESS",
      "entityExternalId": "user_12345",
      "destinationAccountId": "0170042640000004234411",
      "destinationCuit": "27281455496",
      "metadata": {
        "amount": 5000,
        "currency": "ARS",
        "concept": "Payment"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/events/user', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventType: 'TRANSFER_SUCCESS',
      entityExternalId: 'user_12345',
      destinationAccountId: '0170042640000004234411',
      destinationCuit: '27281455496',
      metadata: {
        amount: 5000,
        currency: 'ARS',
        concept: 'Payment'
      }
    })
  });
  ```

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

  response = requests.post(
      'https://api.gu1.ai/events/user',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'eventType': 'TRANSFER_SUCCESS',
          'entityExternalId': 'user_12345',
          'destinationAccountId': '0170042640000004234411',
          'destinationCuit': '27281455496',
          'metadata': {
              'amount': 5000,
              'currency': 'ARS',
              'concept': 'Payment'
          }
      }
  )
  ```
</CodeGroup>

### Crear Entidad Automáticamente

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.gu1.ai/events/user?withAutoEntity=true" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "LOGIN_SUCCESS",
      "taxId": "20242455496",
      "userId": "user_12345"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/events/user?withAutoEntity=true', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventType: 'LOGIN_SUCCESS',
      taxId: '20242455496',
      userId: 'user_12345'
    })
  });
  ```

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

  response = requests.post(
      'https://api.gu1.ai/events/user?withAutoEntity=true',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'eventType': 'LOGIN_SUCCESS',
          'taxId': '20242455496',
          'userId': 'user_12345'
      }
  )
  ```
</CodeGroup>

## Ejemplo de Respuesta

```json theme={null}
{
  "success": true,
  "event": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "eventType": "LOGIN_SUCCESS",
    "userId": "user_12345",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityExternalId": "user_12345",
    "taxId": "20242455496",
    "timestamp": "2026-01-30T14:30:00Z",
    "deviceId": "840e89e4d46efd67",
    "ipAddress": "10.40.64.231",
    "country": "AR",
    "createdAt": "2026-01-30T14:30:00Z"
  },
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "wasCreated": false
  },
  "rulesResult": {
    "decision": "APPROVE",
    "riskScore": 25
  },
  "rulesExecutionSummary": {
    "totalRulesEvaluated": 12,
    "rulesTriggered": 1,
    "executionTimeMs": 145,
    "decision": "APPROVE",
    "triggeredRules": [
      {
        "ruleId": "rule_123",
        "ruleName": "Multiple Login Attempts",
        "severity": "MEDIUM",
        "action": "REVIEW",
        "conditionsMet": ["failed_attempts > 2"]
      }
    ]
  }
}
```

## Respuestas de Error

### 400 Bad Request

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one entity identifier is required: entityId, entityExternalId, or taxId"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to create events"
  }
}
```

### 404 Not Found

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity not found. Use ?withAutoEntity=true to auto-create entities."
  }
}
```

### 500 Internal Server Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "EVENT_CREATE_FAILED",
    "message": "Failed to create event"
  }
}
```

## Casos de Uso

### Rastrear Patrones de Autenticación

```javascript theme={null}
// Rastrea inicios de sesión exitosos y fallidos
await createEvent({
  eventType: 'LOGIN_SUCCESS',
  entityExternalId: userId,
  deviceId: deviceFingerprint,
  ipAddress: req.ip
});

// Inicio de sesión fallido con conteo de intentos
await createEvent({
  eventType: 'LOGIN_FAILED',
  entityExternalId: userId,
  failedAttemptsCount: 3
});
```

### Monitorear Actividad de Transferencias

```javascript theme={null}
// Rastrea transferencias para detección de fraude
await createEvent({
  eventType: 'TRANSFER_SUCCESS',
  entityExternalId: userId,
  destinationAccountId: destinationAccount,
  metadata: {
    amount: transferAmount,
    currency: 'ARS'
  }
});
```

### Registro de Auditoría de Cumplimiento

```javascript theme={null}
// Rastrea todos los cambios de perfil
await createEvent({
  eventType: 'PROFILE_UPDATED',
  entityExternalId: userId,
  metadata: {
    fieldsChanged: ['email', 'phone'],
    previousEmail: 'old@example.com',
    newEmail: 'new@example.com'
  }
});
```

## Mejores Prácticas

### Siempre Incluir Timestamps

Proporciona timestamps explícitos cuando los eventos están en cola o en buffer para mantener un ordenamiento cronológico preciso.

### Rastrear Tanto Éxito como Fallo

Siempre rastrea eventos exitosos y fallidos para detección de fraude y análisis integral.

### Usar Metadatos Estructurados

Mantén los metadatos consistentes entre tipos de eventos similares para habilitar mejor análisis y consultas.

### Información del Dispositivo

Incluí `deviceId` y `deviceDetails` cuando estén disponibles para mantener el registro de dispositivos. Enviá `isNewDevice` explícito si tu integración ya clasifica dispositivos nuevos; si no, omitilo y dejá que gu1 infiera (ver [Cómo funciona `isNewDevice`](#como-funciona-isnewdevice)).

### Manejar la Creación Automática con Cuidado

Usa `withAutoEntity=true` solo cuando estés seguro de que el ID tributario es válido y quieres que las entidades se creen automáticamente.

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Listar Eventos" icon="list" href="/es/api-reference/events/list">
    Consulta eventos con filtros
  </Card>

  <Card title="Estadísticas de Eventos" icon="chart-bar" href="/es/api-reference/events/stats">
    Obtén estadísticas agregadas
  </Card>

  <Card title="API de Dispositivos" icon="mobile" href="/es/api-reference/devices/overview">
    Aprende sobre la integración de dispositivos
  </Card>

  <Card title="Reglas de Fraude" icon="shield-check" href="/es/use-cases/transaction-monitoring/fraud-detection">
    Construye reglas usando datos de eventos
  </Card>
</CardGroup>