Listar por Entidad

Resumen

Recupera todos los eventos asociados con una entidad específica, proporcionando una línea de tiempo completa de actividad. Este endpoint busca a través de múltiples identificadores de entidad (entity_id, entity_external_id, tax_id) para asegurar que obtengas todos los eventos relacionados a la entidad independientemente de qué identificador se usó al crear los eventos.

📋 Este endpoint busca automáticamente por ID de entidad, ID externo e ID tributario, así que obtendrás todos los eventos independientemente de qué identificador se usó cuando fueron creados.

Endpoint

GET https://api.gu1.ai/events/user/entity/{entityId}

Autenticación

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

Authorization: Bearer YOUR_API_KEY

Parámetros de Ruta

entityId

string

required

UUID de la entidad cuyos eventos deseas recuperar

Parámetros de Consulta

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[].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[].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 para esta entidad

pagination.limit

number

Tamaño de página usado

pagination.offset

number

Offset usado

pagination.hasMore

boolean

Si hay más páginas disponibles

entity

object

Información de la entidad

entity.id

string

UUID de entidad

entity.external_id

string

Identificador externo de entidad

entity.tax_id

string

ID tributario

entity.name

string

Nombre de la entidad

entity.type

string

Tipo de entidad (person, company, etc.)

Ejemplos

Consulta Básica

curl https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Con Paginación

curl "https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000?limit=50&offset=0" \
  -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",
      "timestamp": "2026-01-30T14:30:00Z",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "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",
      "timestamp": "2026-01-30T12:15:00Z",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "metadata": {
        "amount": 5000,
        "currency": "ARS"
      },
      "createdAt": "2026-01-30T12:15:00Z"
    }
  ],
  "pagination": {
    "total": 145,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  },
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "user_12345",
    "tax_id": "20242455496",
    "name": "John Doe",
    "type": "person"
  }
}

Respuestas de Error

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

404 Not Found

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

500 Internal Server Error

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

Casos de Uso

Registro de Auditoría de Entidad

Genera un registro de auditoría completo para una entidad:

async function getEntityAuditTrail(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}?limit=1000`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  const auditTrail = {
    entity: data.entity,
    totalEvents: data.pagination.total,
    events: data.events.map(event => ({
      timestamp: event.timestamp,
      action: event.eventType,
      device: event.deviceId,
      location: `${event.ipAddress} (${event.country})`,
      metadata: event.metadata
    }))
  };

  return auditTrail;
}

Revisión de Cumplimiento

Revisa actividad de entidad para cumplimiento:

async function complianceReview(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Verifica señales de alerta
  const loginAttempts = data.events.filter(e => e.eventType === 'LOGIN_FAILED');
  const transfers = data.events.filter(e => e.eventType === 'TRANSFER_SUCCESS');
  const credentialChanges = data.events.filter(e =>
    ['PASSWORD_CHANGE', 'EMAIL_CHANGE', 'PHONE_CHANGE'].includes(e.eventType)
  );

  return {
    entityInfo: data.entity,
    redFlags: {
      failedLogins: loginAttempts.length,
      totalTransfers: transfers.length,
      credentialChanges: credentialChanges.length
    },
    requiresReview: loginAttempts.length > 5 || credentialChanges.length > 3
  };
}

Visualización de Línea de Tiempo de Entidad

Construye una línea de tiempo para visualización:

async function buildEntityTimeline(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Agrupa eventos por fecha
  const timeline = data.events.reduce((acc, event) => {
    const date = event.timestamp.split('T')[0];
    if (!acc[date]) {
      acc[date] = [];
    }
    acc[date].push({
      time: event.timestamp,
      type: event.eventType,
      details: event.metadata
    });
    return acc;
  }, {});

  return {
    entity: data.entity,
    timeline
  };
}

Evaluación de Riesgo

Evalúa riesgo de entidad basado en historial de eventos:

async function assessEntityRisk(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  let riskScore = 0;
  const riskFactors = [];

  // Verifica inicios de sesión fallidos
  const failedLogins = data.events.filter(e => e.eventType === 'LOGIN_FAILED').length;
  if (failedLogins > 3) {
    riskScore += 20;
    riskFactors.push(`${failedLogins} intentos de inicio de sesión fallidos`);
  }

  // Verifica uso de VPN
  const vpnEvents = data.events.filter(e => e.metadata?.isVpn).length;
  if (vpnEvents > 5) {
    riskScore += 15;
    riskFactors.push(`${vpnEvents} eventos a través de VPN`);
  }

  // Verifica transferencias rápidas
  const transfers = data.events.filter(e => e.eventType === 'TRANSFER_SUCCESS');
  const recentTransfers = transfers.filter(e =>
    new Date(e.timestamp) > new Date(Date.now() - 86400000)
  );
  if (recentTransfers.length > 5) {
    riskScore += 25;
    riskFactors.push(`${recentTransfers.length} transferencias en las últimas 24 horas`);
  }

  return {
    entity: data.entity,
    riskScore: Math.min(riskScore, 100),
    riskLevel: riskScore > 50 ? 'HIGH' : riskScore > 25 ? 'MEDIUM' : 'LOW',
    riskFactors
  };
}

Mejores Prácticas de Paginación

Cargar Todos los Eventos

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

  while (hasMore) {
    const response = await fetch(
      `https://api.gu1.ai/events/user/entity/${entityId}?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 {
    entity: data.entity,
    events: allEvents
  };
}

Próximos Pasos

Crear Evento

Rastrea nuevos eventos

Listar Eventos

Consulta eventos con filtros

Estadísticas de Eventos

Obtén estadísticas agregadas

Análisis de Riesgo

Analiza riesgo de entidad

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 Ruta

​Parámetros de Consulta

​Respuesta

​Ejemplos

​Consulta Básica

​Con Paginación

​Ejemplo de Respuesta

​Respuestas de Error

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Registro de Auditoría de Entidad

​Revisión de Cumplimiento

​Visualización de Línea de Tiempo de Entidad

​Evaluación de Riesgo

​Mejores Prácticas de Paginación

​Cargar Todos los Eventos

​Próximos Pasos

Crear Evento

Listar Eventos

Estadísticas de Eventos

Análisis de Riesgo

Resumen

Endpoint

Autenticación

Parámetros de Ruta

Parámetros de Consulta

Respuesta

Ejemplos

Consulta Básica

Con Paginación

Ejemplo de Respuesta

Respuestas de Error

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Registro de Auditoría de Entidad

Revisión de Cumplimiento

Visualización de Línea de Tiempo de Entidad

Evaluación de Riesgo

Mejores Prácticas de Paginación

Cargar Todos los Eventos

Próximos Pasos