Listar - gu1

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

Comenzando

Casos de Uso

Webhooks

Persona

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Documentos

Enriquecimiento

Integraciones

Tutoriales Interactivos

​Resumen

​Endpoint

​Autenticación

​Parámetros de Consulta

​Respuesta

​Ejemplos

​Consulta Básica

​Filtrar por Tipo de Evento

​Filtrar por Rango de Fechas

​Ejemplo de Respuesta

​Respuestas de Error

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​500 Internal Server Error

​Casos de Uso

​Registro de Auditoría

​Investigación de Fraude

​Línea de Tiempo de Usuario

​Consejos de Filtrado

​Múltiples Identificadores de Entidad

​Combinando Filtros

​Mejores Prácticas de Paginación

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

​Próximos Pasos

Crear Evento

Estadísticas de Eventos

Listar por Entidad

Detección de Fraude

Resumen

Endpoint

Autenticación

Parámetros de Consulta

Respuesta

Ejemplos

Consulta Básica

Filtrar por Tipo de Evento

Filtrar por Rango de Fechas

Ejemplo de Respuesta

Respuestas de Error

400 Bad Request

401 Unauthorized

403 Forbidden

500 Internal Server Error

Casos de Uso

Registro de Auditoría

Investigación de Fraude

Línea de Tiempo de Usuario

Consejos de Filtrado

Múltiples Identificadores de Entidad

Combinando Filtros

Mejores Prácticas de Paginación

Iterar a Través de Todas las Páginas

Próximos Pasos