Resumen de la API de eventos de usuario

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

Crear Evento

Envía eventos a la API

Listar Eventos

Consulta eventos con filtros

Estadísticas de Eventos

Obtén estadísticas agregadas de eventos

API de Dispositivos

Aprende sobre la integración de dispositivos

Listar dispositivos de una entidad Crear un evento de usuario para reglas y fraude

⌘I

​¿Qué son los Eventos?

​Características Clave

​🔍 Detección de Fraude

​📊 Análisis de Comportamiento

​✅ Cumplimiento y Registros de Auditoría

​🤖 Creación Automática de Entidades

​📱 Integración de Dispositivos

​Esquema de Eventos

​Campos Core

​Información del Dispositivo

​Ubicación y Red

​Datos Específicos del Evento

​Metadatos

​Tipos de Eventos

​Autenticación (4 tipos)

​Cambios de Credenciales (5 tipos)

​Gestión de Cuenta (5 tipos)

​Gestión de Email (2 tipos)

​Navegación (1 tipo)

​Transferencias (3 tipos)

​Saldo de Cuenta (2 tipos)

​Acceso a Cuenta (2 tipos)

​Historial de Transacciones (2 tipos)

​Destinatarios (3 tipos)

​Gestión de Perfil (2 tipos)

​Mensajes (2 tipos)

​Titulares de Cuenta (2 tipos)

​Gestión de Alias (4 tipos)

​Pago / Dispositivo (2 tipos)

​Validación Biométrica (2 tipos)

​Otro (1 tipo)

​Creación Automática de Entidades

​Registro de Dispositivos

​Inicio Rápido

​1. Rastrear Evento de Inicio de Sesión

​2. Rastrear Evento de Transferencia

​3. Consultar Eventos

​Mejores Prácticas

​Siempre Incluir Identificadores de Entidad

​Usar IDs de Usuario Consistentes

​Incluir Información del Dispositivo

​Precisión de Timestamp

​Metadatos Estructurados

​Selección de Tipo de Evento

​Rastreo de Eventos Fallidos

​Patrones de Integración

​Streaming de Eventos en Tiempo Real

​Carga de Eventos por Lotes

​Middleware de Eventos

​Casos de Uso

​Reglas de Detección de Fraude

​Registro de Auditoría de Cumplimiento

​Análisis de Comportamiento de Usuario

​Próximos Pasos