Resumen

​

¿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

• 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)

​

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 - Si es la primera vez que se ve este dispositivo

​

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

​

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

​

Otro (1 tipo)

• OTHER_EVENT - Evento personalizado/genérico

​

Creación Automática de Entidades

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

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

​

Registro de Dispositivos

• 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

​

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

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