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

# Resumen de la API de eventos de usuario

> Rastrea acciones y comportamientos de usuarios para detección de fraude, monitoreo de cumplimiento y análisis — para seguimiento de comportamiento de usuarios.

## ¿Qué son los Eventos?

Los eventos representan acciones de usuario y actividades del sistema que ocurren dentro de tu aplicación. Cada evento captura quién realizó la acción, qué hicieron, cuándo sucedió, y desde qué dispositivo y ubicación. Los eventos son la base de la detección de fraude, monitoreo de cumplimiento, registros de auditoría y análisis de comportamiento.

## Características Clave

### 🔍 Detección de Fraude

Detecta patrones sospechosos como ubicaciones de inicio de sesión inusuales, múltiples intentos de autenticación fallidos, cambios rápidos de credenciales o comportamientos de transacción anormales.

### 📊 Análisis de Comportamiento

Construye perfiles de comportamiento de usuarios, identifica anomalías y detecta tomas de cuenta analizando secuencias y patrones de eventos.

### ✅ Cumplimiento y Registros de Auditoría

Mantén registros detallados de auditoría de todas las actividades de usuarios para cumplimiento regulatorio (GDPR, SOC 2, PCI-DSS) e investigaciones internas.

### 🤖 Creación Automática de Entidades

Crea automáticamente entidades de persona o empresa cuando se reciben eventos con información de identificación tributaria, optimizando flujos de onboarding.

### 📱 Integración de Dispositivos

Registra y rastrea automáticamente dispositivos cuando los eventos incluyen información del dispositivo, habilitando reglas de fraude basadas en dispositivos.

## Esquema de Eventos

Cada registro de evento contiene:

### Campos Core

* `eventType` - Tipo de evento (ver Tipos de Eventos abajo)
* `userId` - Tu identificador de usuario
* `entityId` - UUID de entidad gu1
* `entityExternalId` - Tu ID externo de entidad
* `taxId` - Número de identificación tributaria (CPF, CNPJ, etc.)
* `timestamp` - Cuándo ocurrió el evento (ISO 8601)
* `eventDate` - Fecha de negocio opcional; cuando se envía, las reglas históricas la usan como punto de partida para ventanas de tiempo. Por defecto es igual a `timestamp`.

### Información del Dispositivo

* `deviceId` - Identificador único del dispositivo
* `deviceDetails` - Especificaciones completas del dispositivo (plataforma, SO, fabricante, modelo, etc.)

### Ubicación y Red

* `ipAddress` - Dirección IP de la solicitud
* `country` - Código de país ISO 3166-1
* `isVpn` - Bandera de detección de VPN
* `isProxy` - Bandera de detección de proxy
* `isNewDevice` - Flag de dispositivo nuevo para reglas. **Si lo envías al crear, gu1 guarda tu valor.** Si lo omites, gu1 lo infiere con `deviceId` + `deviceDetails` (registro de dispositivos, ventana de 5 minutos). Detalle: [Crear evento de usuario — `isNewDevice`](/es/api-reference/events/create#como-funciona-isnewdevice).

### Datos Específicos del Evento

* `failedAttemptsCount` - Intentos de autenticación fallidos
* `destinationAccountId` - Cuenta de destino para transferencias
* `destinationCuit` - CUIT de destino para transferencias
* `previousValue` - Valor anterior (para eventos de cambio, hasheado)
* `metadata` - Datos adicionales específicos del evento

### Metadatos

* `userAgent` - Cadena de user agent del navegador
* `metadata` - Objeto flexible para datos personalizados

## Tipos de Eventos

Soportamos 45+ tipos de eventos en varias categorías:

### Autenticación (4 tipos)

* `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

### Cambios de Credenciales (5 tipos)

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

### Gestión de Cuenta (5 tipos)

* `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

### Gestión de Email (2 tipos)

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

### Navegación (1 tipo)

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

### Transferencias (3 tipos)

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

### Saldo de Cuenta (2 tipos)

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

### Acceso a Cuenta (2 tipos)

* `ACCOUNTS_VIEW` - Cuentas visualizadas
* `ACCOUNTS_VIEW_FAILED` - Visualización de cuentas fallida

### Historial de Transacciones (2 tipos)

* `TRANSACTIONS_VIEW` - Transacciones visualizadas
* `TRANSACTIONS_VIEW_FAILED` - Visualización de transacciones fallida

### Destinatarios (3 tipos)

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

### Gestión de Perfil (2 tipos)

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

### Mensajes (2 tipos)

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

### Titulares de Cuenta (2 tipos)

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

### Gestión de Alias (4 tipos)

* `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 (2 tipos)

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

### Validación Biométrica (2 tipos)

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

### Otro (1 tipo)

* `OTHER_EVENT` - Evento personalizado/genérico

## Creación Automática de Entidades

Los eventos pueden crear automáticamente entidades de persona o empresa cuando:

1. Incluyes `taxId` en el evento
2. Agregas el parámetro de consulta `?withAutoEntity=true`
3. La entidad aún no existe

Esto elimina la necesidad de crear entidades por separado antes de rastrear eventos, optimizando tu integración.

```javascript theme={null}
// Entidad creada automáticamente si no existe
POST /events/user?withAutoEntity=true
{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "userId": "user_12345"
}
```

## Registro de Dispositivos

Cuando los eventos incluyen `deviceId` y `deviceDetails`, los dispositivos se registran automáticamente y se asocian con la entidad. Esto habilita:

* Huella digital de dispositivos
* Detección de múltiples dispositivos
* Reglas de fraude basadas en ubicación
* Análisis de comportamiento de dispositivos

## Inicio Rápido

### 1. Rastrear Evento de Inicio de Sesión

```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',
    deviceId: '840e89e4d46efd67',
    ipAddress: '10.40.64.231',
    country: 'AR',
    deviceDetails: {
      platform: 'android',
      manufacturer: 'samsung',
      model: 'SM-A156M'
    }
  })
});
```

### 2. Rastrear Evento de Transferencia

```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'
    }
  })
});
```

### 3. Consultar Eventos

```javascript theme={null}
const response = await fetch(
  'https://api.gu1.ai/events/user?entity_external_id=user_12345&event_type=LOGIN_SUCCESS',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
```

## Mejores Prácticas

### Siempre Incluir Identificadores de Entidad

Proporciona al menos uno de: `entityId`, `entityExternalId`, o `taxId` para vincular eventos a entidades.

### Usar IDs de Usuario Consistentes

Usa el mismo `userId` en todos los eventos para un usuario para construir perfiles de comportamiento precisos.

### Incluir Información del Dispositivo

Siempre envía `deviceId` y `deviceDetails` cuando estén disponibles para habilitar la detección de fraude basada en dispositivos.

### Precisión de Timestamp

Usa timestamps ISO 8601 con información de zona horaria para ordenamiento preciso de eventos y análisis basado en tiempo.

### Metadatos Estructurados

Usa el campo `metadata` para información específica del evento pero mantenlo estructurado y consistente entre tipos de eventos similares.

### Selección de Tipo de Evento

Elige el tipo de evento más específico disponible. Usa `OTHER_EVENT` solo cuando ningún tipo específico coincida.

### Rastreo de Eventos Fallidos

Siempre rastrea eventos exitosos y fallidos (ej., `LOGIN_SUCCESS` vs `LOGIN_FAILED`) para detección de fraude integral.

## Patrones de Integración

### Streaming de Eventos en Tiempo Real

```javascript theme={null}
// Transmite eventos a medida que ocurren
async function trackEvent(eventType, userId, details) {
  try {
    const response = await fetch('https://api.gu1.ai/events/user', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        eventType,
        entityExternalId: userId,
        timestamp: new Date().toISOString(),
        ...details
      })
    });

    if (!response.ok) {
      console.error('Event tracking failed:', await response.text());
    }
  } catch (error) {
    console.error('Event tracking error:', error);
  }
}
```

### Carga de Eventos por Lotes

```javascript theme={null}
// Para migración de datos históricos o cargas masivas
async function uploadBatchEvents(events) {
  for (const event of events) {
    await trackEvent(
      event.type,
      event.userId,
      {
        timestamp: event.timestamp,
        deviceId: event.deviceId,
        ipAddress: event.ipAddress,
        metadata: event.metadata
      }
    );
    // Agregar delay para respetar límites de tasa
    await new Promise(resolve => setTimeout(resolve, 100));
  }
}
```

### Middleware de Eventos

```javascript theme={null}
// Centraliza el rastreo de eventos en middleware
function eventTrackingMiddleware(eventType) {
  return async (req, res, next) => {
    // Rastrea evento antes de procesar solicitud
    await trackEvent(eventType, req.user.id, {
      deviceId: req.deviceId,
      ipAddress: req.ip,
      userAgent: req.headers['user-agent']
    });

    next();
  };
}

app.post('/login', eventTrackingMiddleware('LOGIN_SUCCESS'), loginHandler);
```

## Casos de Uso

### Reglas de Detección de Fraude

```javascript theme={null}
// Ejemplo: Detectar transferencias rápidas
const recentTransfers = await fetch(
  'https://api.gu1.ai/events/user?' +
  'entity_external_id=user_12345&' +
  'event_type=TRANSFER_SUCCESS&' +
  `start_date=${new Date(Date.now() - 3600000).toISOString()}`, // Última hora
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

const data = await recentTransfers.json();
if (data.events.length > 5) {
  console.warn('Rapid transfer activity detected!');
}
```

### Registro de Auditoría de Cumplimiento

```javascript theme={null}
// Genera reporte de auditoría para una entidad
const events = await fetch(
  `https://api.gu1.ai/events/user/entity/${entityId}?limit=1000`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

const auditReport = data.events.map(event => ({
  timestamp: event.timestamp,
  action: event.eventType,
  user: event.userId,
  device: event.deviceId,
  location: `${event.city}, ${event.country}`
}));
```

### Análisis de Comportamiento de Usuario

```javascript theme={null}
// Analiza patrones de inicio de sesión
const stats = await fetch(
  'https://api.gu1.ai/events/user/stats?user_id=user_12345',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

const loginEvents = stats.data.stats.find(s => s.event_type === 'LOGIN_SUCCESS');
console.log(`Total logins: ${loginEvents.count}`);
console.log(`Last login: ${loginEvents.last_occurrence}`);
```

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Crear Evento" icon="plus" href="/es/api-reference/events/create">
    Envía eventos a la API
  </Card>

  <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 de eventos
  </Card>

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