Skip to main content
POST
http://api.gu1.ai
/
events
/
user
Crear
curl --request POST \
  --url http://api.gu1.ai/events/user \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "userId": "<string>",
  "entityId": "<string>",
  "entityExternalId": "<string>",
  "taxId": "<string>",
  "timestamp": "<string>",
  "deviceId": "<string>",
  "deviceDetails": {},
  "ipAddress": "<string>",
  "country": "<string>",
  "isVpn": true,
  "isProxy": true,
  "isNewDevice": true,
  "failedAttemptsCount": 123,
  "destinationAccountId": "<string>",
  "destinationCuit": "<string>",
  "previousValue": "<string>",
  "metadata": {},
  "userAgent": "<string>"
}
'
{
  "success": true,
  "event": {
    "event.id": "<string>",
    "event.eventType": "<string>",
    "event.userId": "<string>",
    "event.entityId": "<string>",
    "event.entityExternalId": "<string>",
    "event.taxId": "<string>",
    "event.timestamp": "<string>",
    "event.deviceId": "<string>",
    "event.ipAddress": "<string>",
    "event.country": "<string>",
    "event.createdAt": "<string>"
  },
  "entity": {
    "entity.id": "<string>",
    "entity.wasCreated": true
  }
}

​
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.
📋 Los eventos registran automáticamente dispositivos cuando se proporcionan deviceId y deviceDetails, eliminando la necesidad de gestión separada de dispositivos.

​
Endpoint

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

​
Autenticación

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

​
Parámetros de Consulta

​
withAutoEntity
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

​
Cuerpo de la Solicitud

​
eventType
string
required
Tipo de evento que se está rastreando. Debe ser uno de los 41 tipos de eventos soportados (ver sección Tipos de Eventos abajo).Ejemplo: "LOGIN_SUCCESS"
​
userId
string
Tu identificador interno de usuario. Se usa para agrupar eventos por usuario entre diferentes entidades.Ejemplo: "user_12345"
​
entityId
string
UUID de entidad de gu1. Proporciona esto si tienes el ID interno de gu1.
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.
​
entityExternalId
string
Tu identificador externo de entidad. Este es tu ID único para la entidad en tu sistema.Ejemplo: "user_12345"
​
taxId
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"
​
timestamp
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"
​
deviceId
string
Identificador único para el dispositivo. Este debe ser un identificador estable que persista entre sesiones.Ejemplo: "840e89e4d46efd67"
​
deviceDetails
object
Información detallada del dispositivo. Cuando se proporciona, el dispositivo será automáticamente registrado o actualizado.Estructura:
{
  "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": {}
}
​
ipAddress
string
Dirección IP desde la cual se originó el evento (IPv4 o IPv6).Ejemplo: "10.40.64.231"
​
country
string
Código de país ISO 3166-1 alfa-2 donde ocurrió el evento.Ejemplo: "AR"
​
isVpn
boolean
default:"false"
Si la conexión es a través de una VPN
​
isProxy
boolean
default:"false"
Si la conexión es a través de un proxy
​
isNewDevice
boolean
default:"false"
Si esta es la primera vez que se ve este dispositivo para esta entidad
​
failedAttemptsCount
number
default:"0"
Número de intentos de autenticación fallidos (para eventos de autenticación)Ejemplo: 3
​
destinationAccountId
string
Identificador de cuenta de destino para eventos de transferencia (CBU, CVU, etc.)Ejemplo: "0170042640000004234411"
​
destinationCuit
string
CUIT de destino para eventos de transferenciaEjemplo: "27281455496"
​
previousValue
string
Valor anterior para eventos de cambio de credenciales. Esto será automáticamente hasheado usando SHA-256 por seguridad.Ejemplo: "old_password_hash"
​
metadata
object
Datos adicionales específicos del evento como pares clave-valor. Usa esto para campos personalizados específicos de tu caso de uso.Ejemplo:
{
  "amount": 5000,
  "currency": "ARS",
  "concept": "Payment",
  "reference": "INV-12345"
}
​
userAgent
string
Cadena de user agent del navegador para eventos webEjemplo: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..."

​
Tipos de Eventos

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

​
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

​
Otros Eventos

  • OTHER_EVENT - Evento personalizado o genérico

​
Respuesta

​
success
boolean
Indica si la solicitud fue exitosa
​
event
object
El objeto de evento creado
​
event.id
string
UUID de evento interno de gu1
​
event.eventType
string
Tipo de evento creado
​
event.userId
string
Identificador de usuario
​
event.entityId
string
UUID de entidad asociada
​
event.entityExternalId
string
Identificador externo de entidad
​
event.taxId
string
Número de identificación tributaria
​
event.timestamp
string
Timestamp del evento (ISO 8601)
​
event.deviceId
string
Identificador del dispositivo
​
event.ipAddress
string
Dirección IP
​
event.country
string
Código de país
​
event.createdAt
string
Timestamp de creación del registro de evento
​
entity
object
Información de la entidad (cuando es creada automáticamente o existente)
​
entity.id
string
UUID de entidad
​
entity.wasCreated
boolean
Si la entidad fue creada automáticamente por este evento

​
Ejemplos

​
Evento de Inicio de Sesión

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

​
Evento de Transferencia

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

​
Crear Entidad Automáticamente

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

​
Ejemplo de Respuesta

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

​
Respuestas de Error

​
400 Bad Request

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

​
401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

​
403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to create events"
  }
}

​
404 Not Found

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

​
500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "EVENT_CREATE_FAILED",
    "message": "Failed to create event"
  }
}

​
Casos de Uso

​
Rastrear Patrones de Autenticación

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

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

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

Siempre incluye información del dispositivo cuando esté disponible para habilitar reglas de detección de fraude basadas en dispositivos.

​
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

Listar Eventos

Consulta eventos con filtros

Estadísticas de Eventos

Obtén estadísticas agregadas

API de Dispositivos

Aprende sobre la integración de dispositivos

Reglas de Fraude

Construye reglas usando datos de eventos