> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Rastreie ações e comportamentos de usuários para detecção de fraudes, monitoramento de conformidade e análises — para rastreamento de comportamento de usuários.

## O que são Eventos?

Eventos representam ações de usuários e atividades do sistema que ocorrem dentro de sua aplicação. Cada evento captura quem realizou a ação, o que foi feito, quando aconteceu e de qual dispositivo e localização. Eventos são a base da detecção de fraudes, monitoramento de conformidade, trilhas de auditoria e análises comportamentais.

## Recursos Principais

### 🔍 Detecção de Fraudes

Detecte padrões suspeitos como localizações de login incomuns, múltiplas tentativas de autenticação falhas, mudanças rápidas de credenciais ou comportamentos de transação anormais.

### 📊 Análises Comportamentais

Construa perfis de comportamento de usuários, identifique anomalias e detecte apropriações de contas analisando sequências e padrões de eventos.

### ✅ Conformidade e Trilhas de Auditoria

Mantenha registros detalhados de auditoria de todas as atividades de usuários para conformidade regulatória (GDPR, SOC 2, PCI-DSS) e investigações internas.

### 🤖 Criação Automática de Entidades

Crie automaticamente entidades de pessoas ou empresas quando eventos são recebidos com informações de ID fiscal, otimizando fluxos de onboarding.

### 📱 Integração com Dispositivos

Registre e rastreie dispositivos automaticamente quando eventos incluem informações de dispositivo, habilitando regras de fraude baseadas em dispositivos.

## Esquema de Evento

Cada registro de evento contém:

### 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`](/pt/api-reference/events/create#como-funciona-o-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

Suportamos 45+ tipos de eventos em várias categorias:

### 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

Eventos podem criar automaticamente entidades de pessoas ou empresas quando:

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

Isso elimina a necessidade de criar entidades separadamente antes de rastrear eventos, simplificando sua integração.

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

## Registro de Dispositivos

Quando eventos incluem `deviceId` e `deviceDetails`, dispositivos são automaticamente registrados e associados à entidade. Isso habilita:

* 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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

Forneça pelo menos um de: `entityId`, `entityExternalId` ou `taxId` para vincular eventos às entidades.

### Use IDs de Usuário Consistentes

Use o mesmo `userId` em todos os eventos de um usuário para construir perfis comportamentais precisos.

### Inclua Informações de Dispositivo

Sempre envie `deviceId` e `deviceDetails` quando disponível para habilitar detecção de fraude baseada em dispositivos.

### Precisão de Timestamp

Use timestamps ISO 8601 com informações de fuso horário para ordenação precisa de eventos e análise baseada em tempo.

### Metadados Estruturados

Use o campo `metadata` para informações específicas do evento, mas mantenha-o estruturado e consistente entre tipos de eventos similares.

### Seleção de Tipo de Evento

Escolha o tipo de evento mais específico disponível. Use `OTHER_EVENT` apenas quando nenhum tipo específico corresponder.

### Rastreamento de Eventos Falhos

Sempre rastreie eventos bem-sucedidos e falhos (ex: `LOGIN_SUCCESS` vs `LOGIN_FAILED`) para detecção de fraude abrangente.

## Padrões de Integração

### Streaming de Eventos em Tempo Real

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Criar Evento" icon="plus" href="/pt/api-reference/events/create">
    Enviar eventos para a API
  </Card>

  <Card title="Listar Eventos" icon="list" href="/pt/api-reference/events/list">
    Consultar eventos com filtros
  </Card>

  <Card title="Estatísticas de Eventos" icon="chart-bar" href="/pt/api-reference/events/stats">
    Obter estatísticas agregadas de eventos
  </Card>

  <Card title="API de Dispositivos" icon="mobile" href="/pt/api-reference/devices/overview">
    Aprenda sobre integração de dispositivos
  </Card>
</CardGroup>