Skip to main content
GET
http://api.gu1.ai
/
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