Visão geral da API de eventos de usuário

​

O que são Eventos?

​

Recursos Principais

​

🔍 Detecção de Fraudes

​

📊 Análises Comportamentais

​

✅ Conformidade e Trilhas de Auditoria

​

🤖 Criação Automática de Entidades

​

📱 Integração com Dispositivos

​

Esquema de Evento

​

Campos Principais

• eventType - Tipo de evento (veja Tipos de Eventos abaixo)
• userId - Seu identificador de usuário
• entityId - UUID da entidade gu1
• entityExternalId - Seu ID externo de entidade
• taxId - Número de identificação fiscal (CPF, CNPJ, etc.)
• timestamp - Quando o evento ocorreu (ISO 8601)
• eventDate - Data de negócio opcional; quando enviada, as regras históricas a usam como ponto de partida para janelas de tempo. Padrão é igual a timestamp.

​

Informações do Dispositivo

• deviceId - Identificador único do dispositivo
• deviceDetails - Especificações completas do dispositivo (plataforma, SO, fabricante, modelo, etc.)

​

Localização e Rede

• ipAddress - Endereço IP da requisição
• country - Código de país ISO 3166-1
• isVpn - Flag de detecção de VPN
• isProxy - Flag de detecção de proxy
• isNewDevice - Flag de dispositivo novo para regras. Se você enviar na criação, a gu1 grava seu valor. Se omitir, a gu1 infere com deviceId + deviceDetails (registro de dispositivos, janela de 5 minutos). Detalhes: Criar evento de usuário — isNewDevice.

​

Dados Específicos do Evento

• failedAttemptsCount - Tentativas de autenticação falhas
• destinationAccountId - Conta de destino para transferências
• destinationCuit - CUIT de destino para transferências
• previousValue - Valor anterior (para eventos de mudança, com hash)
• metadata - Dados adicionais específicos do evento

​

Metadados

• userAgent - String de user agent do navegador
• metadata - Objeto flexível para dados personalizados

​

Tipos de Eventos

​

Autenticação (4 tipos)

• LOGIN_SUCCESS - Login bem-sucedido
• LOGIN_FAILED - Tentativa de login falha
• LOGOUT - Logout do usuário
• TOKEN_GENERATED - Token de autenticação gerado

​

Mudanças de Credenciais (5 tipos)

• PASSWORD_CHANGE - Senha alterada com sucesso
• PASSWORD_CHANGE_FAILED - Mudança de senha falhou
• EMAIL_CHANGE - Endereço de email alterado
• PHONE_CHANGE - Número de telefone alterado
• PIN_CHANGE - PIN alterado

​

Gerenciamento de Conta (5 tipos)

• ACCOUNT_LINKED - Conta bancária vinculada
• CONTACT_CREATED - Contato criado
• CONTACT_DELETED - Contato excluído
• ADDRESS_CHANGED - Endereço atualizado
• DEVICE_ADDED - Novo dispositivo adicionado
• DEVICE_DELETED - Dispositivo removido

​

Gerenciamento de Email (2 tipos)

• EMAIL_CREATED - Email criado
• EMAIL_ELIMINATED - Email eliminado

​

Navegação (1 tipo)

• NAVIGATION - Navegação de página/tela

​

Transferências (3 tipos)

• TRANSFER_SUCCESS - Transferência bem-sucedida
• TRANSFER_FAILED - Tentativa de transferência falhou
• TRANSFER_SCHEDULED - Transferência agendada

​

Saldo de Conta (2 tipos)

• BALANCE_CHECK - Saldo verificado
• BALANCE_CHECK_FAILED - Verificação de saldo falhou

​

Acesso à Conta (2 tipos)

• ACCOUNTS_VIEW - Contas visualizadas
• ACCOUNTS_VIEW_FAILED - Visualização de contas falhou

​

Histórico de Transações (2 tipos)

• TRANSACTIONS_VIEW - Transações visualizadas
• TRANSACTIONS_VIEW_FAILED - Visualização de transações falhou

​

Destinatários (3 tipos)

• SEARCH_RECIPIENTS - Destinatários pesquisados
• SEARCH_RECIPIENTS_FAILED - Pesquisa de destinatários falhou
• SCHEDULE_RECIPIENT_FAILED - Agendamento de destinatário falhou

​

Gerenciamento de Perfil (2 tipos)

• PROFILE_VIEW - Perfil visualizado
• PROFILE_UPDATED - Perfil atualizado

​

Mensagens (2 tipos)

• MESSAGES_VIEW - Mensagens visualizadas
• MESSAGES_VIEW_FAILED - Visualização de mensagens falhou

​

Titulares de Conta (2 tipos)

• ACCOUNT_HOLDERS_VIEW - Titulares de conta visualizados
• ACCOUNT_HOLDERS_VIEW_FAILED - Visualização de titulares falhou

​

Gerenciamento de Alias (4 tipos)

• ALIAS_VIEW - Alias visualizado
• ALIAS_VIEW_FAILED - Visualização de alias falhou
• ALIAS_CHANGE - Alias alterado
• ALIAS_CHANGE_FAILED - Mudança de alias falhou

​

Pagamento / Dispositivo (2 tipos)

• CARD_ADDED - Cartão de pagamento adicionado
• DEVICE_CONNECTED - Dispositivo conectado

​

Validação Biométrica (2 tipos)

• BIOMETRIC_VALIDATION_SUCCESS - Validação biométrica bem-sucedida
• BIOMETRIC_VALIDATION_ERROR - Validação biométrica falhou

​

Outros (1 tipo)

• OTHER_EVENT - Evento personalizado/genérico

​

Criação Automática de Entidades

1. Você inclui taxId no evento
2. Você adiciona o parâmetro de consulta ?withAutoEntity=true
3. A entidade ainda não existe

// Entidade criada automaticamente se não existir
POST /events/user?withAutoEntity=true
{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "userId": "user_12345"
}

​

Registro de Dispositivos

• Impressão digital de dispositivos
• Detecção de múltiplos dispositivos
• Regras de fraude baseadas em localização
• Análise de comportamento de dispositivos

​

Início Rápido

​

1. Rastrear Evento de Login

const response = await fetch('https://api.gu1.ai/events/user', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    eventType: 'LOGIN_SUCCESS',
    entityExternalId: 'user_12345',
    deviceId: '840e89e4d46efd67',
    ipAddress: '10.40.64.231',
    country: 'AR',
    deviceDetails: {
      platform: 'android',
      manufacturer: 'samsung',
      model: 'SM-A156M'
    }
  })
});

​

2. Rastrear Evento de Transferência

const response = await fetch('https://api.gu1.ai/events/user', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    eventType: 'TRANSFER_SUCCESS',
    entityExternalId: 'user_12345',
    destinationAccountId: '0170042640000004234411',
    destinationCuit: '27281455496',
    metadata: {
      amount: 5000,
      currency: 'ARS',
      concept: 'Payment'
    }
  })
});

​

3. Consultar Eventos

const response = await fetch(
  'https://api.gu1.ai/events/user?entity_external_id=user_12345&event_type=LOGIN_SUCCESS',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

​

Melhores Práticas

​

Sempre Inclua Identificadores de Entidade

​

Use IDs de Usuário Consistentes

​

Inclua Informações de Dispositivo

​

Precisão de Timestamp

​

Metadados Estruturados

​

Seleção de Tipo de Evento

​

Rastreamento de Eventos Falhos

​

Padrões de Integração

​

Streaming de Eventos em Tempo Real

// Transmitir eventos conforme ocorrem
async function trackEvent(eventType, userId, details) {
  try {
    const response = await fetch('https://api.gu1.ai/events/user', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        eventType,
        entityExternalId: userId,
        timestamp: new Date().toISOString(),
        ...details
      })
    });

    if (!response.ok) {
      console.error('Event tracking failed:', await response.text());
    }
  } catch (error) {
    console.error('Event tracking error:', error);
  }
}

​

Upload de Eventos em Lote

// Para migração de dados históricos ou uploads em massa
async function uploadBatchEvents(events) {
  for (const event of events) {
    await trackEvent(
      event.type,
      event.userId,
      {
        timestamp: event.timestamp,
        deviceId: event.deviceId,
        ipAddress: event.ipAddress,
        metadata: event.metadata
      }
    );
    // Adicionar delay para respeitar limites de taxa
    await new Promise(resolve => setTimeout(resolve, 100));
  }
}

​

Middleware de Eventos

// Centralizar rastreamento de eventos em middleware
function eventTrackingMiddleware(eventType) {
  return async (req, res, next) => {
    // Rastrear evento antes de processar requisição
    await trackEvent(eventType, req.user.id, {
      deviceId: req.deviceId,
      ipAddress: req.ip,
      userAgent: req.headers['user-agent']
    });

    next();
  };
}

app.post('/login', eventTrackingMiddleware('LOGIN_SUCCESS'), loginHandler);

​

Casos de Uso

​

Regras de Detecção de Fraude

// Exemplo: Detectar transferências rápidas
const recentTransfers = await fetch(
  'https://api.gu1.ai/events/user?' +
  'entity_external_id=user_12345&' +
  'event_type=TRANSFER_SUCCESS&' +
  `start_date=${new Date(Date.now() - 3600000).toISOString()}`, // Última hora
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

const data = await recentTransfers.json();
if (data.events.length > 5) {
  console.warn('Rapid transfer activity detected!');
}

​

Trilha de Auditoria de Conformidade

// Gerar relatório de auditoria para uma entidade
const events = await fetch(
  `https://api.gu1.ai/events/user/entity/${entityId}?limit=1000`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

const auditReport = data.events.map(event => ({
  timestamp: event.timestamp,
  action: event.eventType,
  user: event.userId,
  device: event.deviceId,
  location: `${event.city}, ${event.country}`
}));

​

Análise de Comportamento do Usuário

// Analisar padrões de login
const stats = await fetch(
  'https://api.gu1.ai/events/user/stats?user_id=user_12345',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

const loginEvents = stats.data.stats.find(s => s.event_type === 'LOGIN_SUCCESS');
console.log(`Total logins: ${loginEvents.count}`);
console.log(`Last login: ${loginEvents.last_occurrence}`);

​

Próximos Passos