Skip to main content
GET
/
events
/
user
Listar
curl --request GET \
  --url http://api.gu1.ai/events/user \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "events": [
    {
      "events[].id": "<string>",
      "events[].eventType": "<string>",
      "events[].userId": "<string>",
      "events[].entityId": "<string>",
      "events[].entityExternalId": "<string>",
      "events[].taxId": "<string>",
      "events[].timestamp": "<string>",
      "events[].deviceId": "<string>",
      "events[].ipAddress": "<string>",
      "events[].country": "<string>",
      "events[].isVpn": true,
      "events[].isProxy": true,
      "events[].metadata": {},
      "events[].createdAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

​
Resumen

Recupera eventos de usuario con potentes capacidades de filtrado. Usa este endpoint para consultar eventos por usuario, entidad, tipo de evento, rango de fechas y más. Perfecto para construir registros de auditoría, herramientas de investigación de fraude y dashboards de análisis.
Lógica OR para IDs de Entidad: Al consultar por identificadores de entidad (entity_id, entity_external_id, tax_id), el sistema usa lógica OR, devolviendo eventos que coincidan con cualquiera de los identificadores proporcionados.

​
Endpoint

GET 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

​
user_id
string
Filtra eventos por identificador de usuarioEjemplo: ?user_id=user_12345
​
entity_id
string
Filtra eventos por UUID de entidadEjemplo: ?entity_id=550e8400-e29b-41d4-a716-446655440000
​
entity_external_id
string
Filtra eventos por identificador externo de entidadEjemplo: ?entity_external_id=user_12345
​
tax_id
string
Filtra eventos por número de identificación tributariaEjemplo: ?tax_id=20242455496
​
event_type
string
Filtra eventos por tipo (ej., LOGIN_SUCCESS, TRANSFER_SUCCESS)Ejemplo: ?event_type=LOGIN_SUCCESS
​
start_date
string
Filtra eventos después de esta fecha (formato ISO 8601)Ejemplo: ?start_date=2026-01-01T00:00:00Z
​
end_date
string
Filtra eventos antes de esta fecha (formato ISO 8601)Ejemplo: ?end_date=2026-01-31T23:59:59Z
​
limit
number
default:"100"
Número máximo de eventos a devolver por página (máx: 1000)Ejemplo: ?limit=50
​
offset
number
default:"0"
Número de eventos a omitir para paginaciónEjemplo: ?offset=100

​
Respuesta

​
success
boolean
Indica si la solicitud fue exitosa
​
events
array
Array de objetos de evento ordenados por timestamp (más reciente primero)
​
events[].id
string
UUID del evento
​
events[].eventType
string
Tipo de evento
​
events[].userId
string
Identificador de usuario
​
events[].entityId
string
UUID de entidad
​
events[].entityExternalId
string
Identificador externo de entidad
​
events[].taxId
string
ID tributario
​
events[].timestamp
string
Timestamp del evento (ISO 8601)
​
events[].deviceId
string
Identificador del dispositivo
​
events[].ipAddress
string
Dirección IP
​
events[].country
string
Código de país
​
events[].isVpn
boolean
Bandera de detección de VPN
​
events[].isProxy
boolean
Bandera de detección de proxy
​
events[].metadata
object
Metadatos específicos del evento
​
events[].createdAt
string
Timestamp de creación del registro
​
pagination
object
Información de paginación
​
pagination.total
number
Número total de eventos que coinciden con los filtros
​
pagination.limit
number
Tamaño de página usado
​
pagination.offset
number
Offset usado
​
pagination.hasMore
boolean
Si hay más páginas disponibles

​
Ejemplos

​
Consulta Básica

curl "https://api.gu1.ai/events/user?entity_external_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtrar por Tipo de Evento

curl "https://api.gu1.ai/events/user?entity_external_id=user_12345&event_type=LOGIN_SUCCESS" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtrar por Rango de Fechas

curl "https://api.gu1.ai/events/user?entity_external_id=user_12345&start_date=2026-01-01T00:00:00Z&end_date=2026-01-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Ejemplo de Respuesta

{
  "success": true,
  "events": [
    {
      "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",
      "isVpn": false,
      "isProxy": false,
      "metadata": {},
      "createdAt": "2026-01-30T14:30:00Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "eventType": "TRANSFER_SUCCESS",
      "userId": "user_12345",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityExternalId": "user_12345",
      "taxId": "20242455496",
      "timestamp": "2026-01-30T12:15:00Z",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "metadata": {
        "amount": 5000,
        "currency": "ARS",
        "destinationAccountId": "0170042640000004234411"
      },
      "createdAt": "2026-01-30T12:15:00Z"
    }
  ],
  "pagination": {
    "total": 145,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}

​
Respuestas de Error

​
400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid date format"
  }
}

​
401 Unauthorized

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

​
403 Forbidden

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

​
500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "EVENTS_FETCH_FAILED",
    "message": "Failed to fetch events"
  }
}

​
Casos de Uso

​
Registro de Auditoría

Construye un registro de auditoría completo para cumplimiento: 
async function getAuditTrail(entityExternalId, startDate, endDate) {
  const response = await fetch(
    `https://api.gu1.ai/events/user?` +
    `entity_external_id=${entityExternalId}&` +
    `start_date=${startDate}&` +
    `end_date=${endDate}&` +
    `limit=1000`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();
  return data.events.map(event => ({
    timestamp: event.timestamp,
    action: event.eventType,
    user: event.userId,
    device: event.deviceId,
    ipAddress: event.ipAddress
  }));
}

​
Investigación de Fraude

Investiga actividad sospechosa: 
async function investigateSuspiciousActivity(entityExternalId) {
  // Obtiene inicios de sesión fallidos recientes
  const failedLogins = await fetch(
    `https://api.gu1.ai/events/user?` +
    `entity_external_id=${entityExternalId}&` +
    `event_type=LOGIN_FAILED&` +
    `start_date=${new Date(Date.now() - 86400000).toISOString()}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  // Obtiene transferencias recientes
  const transfers = await fetch(
    `https://api.gu1.ai/events/user?` +
    `entity_external_id=${entityExternalId}&` +
    `event_type=TRANSFER_SUCCESS&` +
    `start_date=${new Date(Date.now() - 86400000).toISOString()}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  return {
    failedLogins: (await failedLogins.json()).events,
    transfers: (await transfers.json()).events
  };
}

​
Línea de Tiempo de Usuario

Construye una línea de tiempo de actividad de usuario: 
async function getUserTimeline(userId, limit = 50) {
  const response = await fetch(
    `https://api.gu1.ai/events/user?user_id=${userId}&limit=${limit}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();
  return data.events;
}

​
Consejos de Filtrado

​
Múltiples Identificadores de Entidad

Puedes proporcionar múltiples identificadores de entidad para ampliar la búsqueda: 
// Devolverá eventos que coincidan con CUALQUIERA de estos identificadores
const response = await fetch(
  `https://api.gu1.ai/events/user?` +
  `entity_external_id=user_12345&` +
  `tax_id=20242455496`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

​
Combinando Filtros

Combina múltiples filtros para consultas precisas: 
// Obtiene transferencias fallidas en la última semana
const lastWeek = new Date(Date.now() - 7 * 86400000).toISOString();

const response = await fetch(
  `https://api.gu1.ai/events/user?` +
  `entity_external_id=user_12345&` +
  `event_type=TRANSFER_FAILED&` +
  `start_date=${lastWeek}`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

​
Mejores Prácticas de Paginación

​
Iterar a Través de Todas las Páginas

async function getAllEvents(entityExternalId) {
  const allEvents = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.gu1.ai/events/user?` +
      `entity_external_id=${entityExternalId}&` +
      `limit=${limit}&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );

    const data = await response.json();
    allEvents.push(...data.events);

    hasMore = data.pagination.hasMore;
    offset += limit;
  }

  return allEvents;
}

​
Próximos Pasos

Crear Evento

Rastrea nuevos eventos

Estadísticas de Eventos

Obtén estadísticas agregadas

Listar por Entidad

Obtén eventos para una entidad específica

Detección de Fraude

Construye reglas de fraude con eventos