Listar por Entidade

Visão Geral

Recupera todos os eventos associados a uma entidade específica, fornecendo uma linha do tempo completa de atividades. Este endpoint pesquisa entre múltiplos identificadores de entidade (entity_id, entity_external_id, tax_id) para garantir que você obtenha todos os eventos relacionados à entidade, independentemente de qual identificador foi usado ao criar os eventos.

📋 Este endpoint pesquisa automaticamente por ID de entidade, ID externo e ID fiscal, então você obterá todos os eventos independentemente de qual identificador foi usado quando foram criados.

Endpoint

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

Autenticação

Requer uma chave de API válida no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Parâmetros de Caminho

entityId

string

required

UUID da entidade cujos eventos você deseja recuperar

Parâmetros de Consulta

limit

number

default:"100"

Número máximo de eventos a retornar por página (máx: 1000)Exemplo: ?limit=50

offset

number

default:"0"

Número de eventos a pular para paginaçãoExemplo: ?offset=100

Resposta

success

boolean

Indica se a requisição foi bem-sucedida

events

array

Array de objetos de eventos ordenados por timestamp (mais recente primeiro)

events[].id

string

UUID do evento

events[].eventType

string

Tipo de evento

events[].userId

string

Identificador do usuário

events[].entityId

string

UUID da entidade

events[].timestamp

string

Timestamp do evento (ISO 8601)

events[].deviceId

string

Identificador do dispositivo

events[].ipAddress

string

Endereço IP

events[].country

string

Código do país

events[].metadata

object

Metadados específicos do evento

events[].createdAt

string

Timestamp de criação do registro

pagination

object

Informações de paginação

pagination.total

number

Número total de eventos para esta entidade

pagination.limit

number

Tamanho de página usado

pagination.offset

number

Offset usado

pagination.hasMore

boolean

Se há mais páginas disponíveis

entity

object

Informações da entidade

entity.id

string

UUID da entidade

entity.external_id

string

Identificador externo da entidade

entity.tax_id

string

ID fiscal

entity.name

string

Nome da entidade

entity.type

string

Tipo de entidade (person, company, etc.)

Exemplos

Consulta Básica

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

Com Paginação

curl "https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplo de Resposta

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

Respostas de Erro

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

Trilha de Auditoria da Entidade

Gerar uma trilha de auditoria completa para uma entidade:

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

Revisão de Conformidade

Revisar atividade da entidade para conformidade:

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();

  // Verificar bandeiras vermelhas
  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
  };
}

Visualização da Linha do Tempo da Entidade

Construir uma linha do tempo para visualização:

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();

  // Agrupar eventos por data
  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
  };
}

Avaliação de Risco

Avaliar risco da entidade baseado no histórico 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 = [];

  // Verificar logins falhos
  const failedLogins = data.events.filter(e => e.eventType === 'LOGIN_FAILED').length;
  if (failedLogins > 3) {
    riskScore += 20;
    riskFactors.push(`${failedLogins} tentativas de login falhas`);
  }

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

  // Verificar transferências 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} transferências nas últimas 24 horas`);
  }

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

Melhores Práticas de Paginação

Carregar Todos os 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 Passos

Criar Evento

Rastrear novos eventos

Listar Eventos

Consultar eventos com filtros

Estatísticas de Eventos

Obter estatísticas agregadas

Análise de Risco

Analisar risco da entidade

Começando

Casos de Uso

Webhooks

Pessoa

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Enriquecimento

Integrações

Tutoriais Interativos

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Caminho

​Parâmetros de Consulta

​Resposta

​Exemplos

​Consulta Básica

​Com Paginação

​Exemplo de Resposta

​Respostas de Erro

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Trilha de Auditoria da Entidade

​Revisão de Conformidade

​Visualização da Linha do Tempo da Entidade

​Avaliação de Risco

​Melhores Práticas de Paginação

​Carregar Todos os Eventos

​Próximos Passos

Criar Evento

Listar Eventos

Estatísticas de Eventos

Análise de Risco

Visão Geral

Endpoint

Autenticação

Parâmetros de Caminho

Parâmetros de Consulta

Resposta

Exemplos

Consulta Básica

Com Paginação

Exemplo de Resposta

Respostas de Erro

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Trilha de Auditoria da Entidade

Revisão de Conformidade

Visualização da Linha do Tempo da Entidade

Avaliação de Risco

Melhores Práticas de Paginação

Carregar Todos os Eventos

Próximos Passos