Listar - gu1

Visão Geral

Recupera eventos de usuários com recursos poderosos de filtragem. Use este endpoint para consultar eventos por usuário, entidade, tipo de evento, intervalo de datas e muito mais. Perfeito para construir trilhas de auditoria, ferramentas de investigação de fraude e dashboards de análise.

Lógica OU para IDs de Entidade: Ao consultar por identificadores de entidade (entity_id, entity_external_id, tax_id), o sistema usa lógica OU, retornando eventos que correspondam a qualquer um dos identificadores fornecidos.

Endpoint

GET https://api.gu1.ai/events/user

Autenticação

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

Authorization: Bearer YOUR_API_KEY

Parâmetros de Consulta

user_id

string

Filtrar eventos por identificador de usuárioExemplo: ?user_id=user_12345

entity_id

string

Filtrar eventos por UUID de entidadeExemplo: ?entity_id=550e8400-e29b-41d4-a716-446655440000

entity_external_id

string

Filtrar eventos por identificador externo de entidadeExemplo: ?entity_external_id=user_12345

tax_id

string

Filtrar eventos por número de identificação fiscalExemplo: ?tax_id=20242455496

event_type

string

Filtrar eventos por tipo (ex: LOGIN_SUCCESS, TRANSFER_SUCCESS)Exemplo: ?event_type=LOGIN_SUCCESS

start_date

string

Filtrar eventos após esta data (formato ISO 8601)Exemplo: ?start_date=2026-01-01T00:00:00Z

end_date

string

Filtrar eventos antes desta data (formato ISO 8601)Exemplo: ?end_date=2026-01-31T23:59:59Z

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[].entityExternalId

string

Identificador externo da entidade

events[].taxId

string

ID fiscal

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[].isVpn

boolean

Flag de detecção de VPN

events[].isProxy

boolean

Flag de detecção de proxy

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 correspondentes aos filtros

pagination.limit

number

Tamanho de página usado

pagination.offset

number

Offset usado

pagination.hasMore

boolean

Se há mais páginas disponíveis

Exemplos

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 Intervalo de Datas

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"

Exemplo de Resposta

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

Respostas de Erro

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

Trilha de Auditoria

Construa uma trilha de auditoria completa para conformidade:

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

Investigação de Fraude

Investigue atividade suspeita:

async function investigateSuspiciousActivity(entityExternalId) {
  // Obter logins falhos recentes
  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()}`, // Última hora
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  // Obter transferências recentes
  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
  };
}

Linha do Tempo do Usuário

Construa uma linha do tempo de atividade do usuário:

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

Dicas de Filtragem

Múltiplos Identificadores de Entidade

Você pode fornecer múltiplos identificadores de entidade para lançar uma rede mais ampla:

// Retornará eventos correspondentes a QUALQUER um desses 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

Combine múltiplos filtros para consultas precisas:

// Obter transferências falhas na ú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}` } }
);

Melhores Práticas de Paginação

Iterar Através de Todas as 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 Passos

Criar Evento

Rastrear novos eventos

Estatísticas de Eventos

Obter estatísticas agregadas

Listar por Entidade

Obter eventos para uma entidade específica

Detecção de Fraude

Construa regras de fraude com eventos

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 Consulta

​Resposta

​Exemplos

​Consulta Básica

​Filtrar por Tipo de Evento

​Filtrar por Intervalo de Datas

​Exemplo de Resposta

​Respostas de Erro

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​500 Internal Server Error

​Casos de Uso

​Trilha de Auditoria

​Investigação de Fraude

​Linha do Tempo do Usuário

​Dicas de Filtragem

​Múltiplos Identificadores de Entidade

​Combinando Filtros

​Melhores Práticas de Paginação

​Iterar Através de Todas as Páginas

​Próximos Passos

Criar Evento

Estatísticas de Eventos

Listar por Entidade

Detecção de Fraude

Visão Geral

Endpoint

Autenticação

Parâmetros de Consulta

Resposta

Exemplos

Consulta Básica

Filtrar por Tipo de Evento

Filtrar por Intervalo de Datas

Exemplo de Resposta

Respostas de Erro

400 Bad Request

401 Unauthorized

403 Forbidden

500 Internal Server Error

Casos de Uso

Trilha de Auditoria

Investigação de Fraude

Linha do Tempo do Usuário

Dicas de Filtragem

Múltiplos Identificadores de Entidade

Combinando Filtros

Melhores Práticas de Paginação

Iterar Através de Todas as Páginas

Próximos Passos