Crear un evento de usuario para reglas y fraude

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>",
  "eventDate": "<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.eventDate": "<string>",
    "event.deviceId": "<string>",
    "event.ipAddress": "<string>",
    "event.country": "<string>",
    "event.createdAt": "<string>"
  },
  "entity": {
    "entity.id": "<string>",
    "entity.wasCreated": true
  },
  "rulesResult": {
    "rulesResult.decision": "<string>"
  },
  "rulesExecutionSummary": {}
}

POST

events

user

Crear un evento de usuario para reglas y fraude

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>",
  "eventDate": "<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.eventDate": "<string>",
    "event.deviceId": "<string>",
    "event.ipAddress": "<string>",
    "event.country": "<string>",
    "event.createdAt": "<string>"
  },
  "entity": {
    "entity.id": "<string>",
    "entity.wasCreated": true
  },
  "rulesResult": {
    "rulesResult.decision": "<string>"
  },
  "rulesExecutionSummary": {}
}

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.

📋 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 tipos soportados (ver sección Tipos de Eventos), incluyendo autenticación, transferencias, validación biométrica, etc.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"

eventDate

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.

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

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

Flag de dispositivo nuevo persistido en el evento (is_new_device en base de datos). Ver Cómo funciona isNewDevice más abajo.

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

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:

Registra o actualiza el dispositivo para la entidad resuelta (tabla devices).
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).
En caso contrario false (dispositivo ya conocido por gu1 para esa entidad).

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.

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

{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "isNewDevice": true
}

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

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

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

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

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

string

Fecha de negocio usada por reglas históricas para ventanas de tiempo (ISO 8601). Igual a timestamp si no se envió.

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

rulesResult

object

Resultado de la ejecución del motor de reglas

rulesResult.decision

string

Decisión final del motor de reglas (APPROVE, REVIEW, REJECT)

rulesExecutionSummary

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.

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

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

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

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

Resumen de la API de eventos de usuario Listar eventos de usuario

⌘I

​Resumen

​Endpoint

​Autenticación

​Parámetros de Consulta

​Cuerpo de la Solicitud

​Cómo funciona isNewDevice

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

​Si omites isNewDevice (inferencia en servidor)

​Nombre del campo en el body

​Ejemplos

​Tipos de Eventos

​Eventos de Autenticación

​Eventos de Cambio de Credenciales

​Eventos de Gestión de Cuenta

​Eventos de Gestión de Email

​Eventos de Navegación

​Eventos de Transferencia

​Eventos de Saldo

​Eventos de Acceso a Cuenta

​Eventos de Transacciones

​Eventos de Destinatarios

​Eventos de Perfil

​Eventos de Mensajes

​Eventos de Titulares de Cuenta

​Eventos de Alias

​Pago / Dispositivo

​Validación Biométrica

​Otros Eventos

​Respuesta

​Ejemplos

​Evento de Inicio de Sesión

​Evento de Transferencia

​Crear Entidad Automáticamente

​Ejemplo de Respuesta

​Respuestas de Error

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Rastrear Patrones de Autenticación

​Monitorear Actividad de Transferencias

​Registro de Auditoría de Cumplimiento

​Mejores Prácticas

​Siempre Incluir Timestamps

​Rastrear Tanto Éxito como Fallo

​Usar Metadatos Estructurados

​Información del Dispositivo

​Manejar la Creación Automática con Cuidado

​Próximos Pasos

Listar Eventos

Estadísticas de Eventos

API de Dispositivos

Reglas de Fraude

Resumen

Endpoint

Autenticación

Parámetros de Consulta

Cuerpo de la Solicitud

Cómo funciona `isNewDevice`

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

Si omites `isNewDevice` (inferencia en servidor)

Nombre del campo en el body

Ejemplos

Tipos de Eventos

Eventos de Autenticación

Eventos de Cambio de Credenciales

Eventos de Gestión de Cuenta

Eventos de Gestión de Email

Eventos de Navegación

Eventos de Transferencia

Eventos de Saldo

Eventos de Acceso a Cuenta

Eventos de Transacciones

Eventos de Destinatarios

Eventos de Perfil

Eventos de Mensajes

Eventos de Titulares de Cuenta

Eventos de Alias

Pago / Dispositivo

Validación Biométrica

Otros Eventos

Respuesta

Ejemplos

Evento de Inicio de Sesión

Evento de Transferencia

Crear Entidad Automáticamente

Ejemplo de Respuesta

Respuestas de Error

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Rastrear Patrones de Autenticación

Monitorear Actividad de Transferencias

Registro de Auditoría de Cumplimiento

Mejores Prácticas

Siempre Incluir Timestamps

Rastrear Tanto Éxito como Fallo

Usar Metadatos Estructurados

Información del Dispositivo

Manejar la Creación Automática con Cuidado

Próximos Pasos