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

# Criar um evento de usuário para regras e fraude

> Criar um evento de usuário para detecção de fraudes e validação de regras — para rastreamento de comportamento de usuários e detecção de fraude na gu1.

## Visão Geral

Cria um novo evento de usuário para rastrear ações e comportamentos dentro de sua aplicação. Eventos são usados para detecção de fraudes, monitoramento de conformidade, análises comportamentais e trilhas de auditoria. O sistema registra automaticamente dispositivos e pode opcionalmente criar entidades quando não existem. Quando um evento é criado, o motor de regras é executado automaticamente e retorna tanto o resultado das regras quanto um resumo detalhado de execução.

<Tip>
  📋 Eventos registram automaticamente dispositivos quando `deviceId` e `deviceDetails` são fornecidos, eliminando a necessidade de gerenciamento separado de dispositivos.
</Tip>

## Endpoint

```
POST https://api.gu1.ai/events/user
```

## Autenticação

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Parâmetros de Consulta

<ParamField query="withAutoEntity" type="boolean" default="false">
  Habilitar criação automática de entidade quando uma entidade com o `taxId` fornecido não existir. Quando verdadeiro, se o evento incluir um `taxId` e nenhuma entidade existir com esse ID fiscal, uma nova entidade de pessoa ou empresa será criada automaticamente.

  Exemplo: `?withAutoEntity=true`
</ParamField>

## Corpo da Requisição

<ParamField body="eventType" type="string" required>
  Tipo de evento sendo rastreado. Deve ser um dos 41 tipos de eventos suportados (veja seção [Tipos de Eventos](#tipos-de-eventos) abaixo).

  Exemplo: `"LOGIN_SUCCESS"`
</ParamField>

<ParamField body="userId" type="string">
  Seu identificador interno de usuário. Usado para agrupar eventos por usuário entre diferentes entidades.

  Exemplo: `"user_12345"`
</ParamField>

<ParamField body="entityId" type="string">
  UUID da entidade gu1. Forneça isso se você tiver o ID interno do gu1.

  <Note>
    **Identificação de Entidade**: Você deve fornecer PELO MENOS UM de: `entityId`, `entityExternalId` ou `taxId`. Esses campos suportam lógica OU, então o sistema encontrará a entidade usando qualquer um desses identificadores. **Exceção do SDK:** organizações com o SDK habilitado podem enviar apenas um [`sessionId`](#sdk-events) para eventos anônimos pré-login.
  </Note>
</ParamField>

<ParamField body="entityExternalId" type="string">
  Seu identificador externo de entidade. Este é seu ID único para a entidade em seu sistema.

  Exemplo: `"user_12345"`
</ParamField>

<ParamField body="taxId" type="string">
  Número de identificação fiscal (CPF, CNPJ, CUIT, etc.). Quando combinado com `?withAutoEntity=true`, isso criará a entidade se ela não existir.

  Exemplo: `"20242455496"`
</ParamField>

<ParamField body="timestamp" type="string">
  Quando o evento ocorreu em formato datetime ISO 8601. Se não fornecido, usa o horário atual do servidor como padrão.

  Exemplo: `"2026-01-30T14:30:00Z"`
</ParamField>

<ParamField body="eventDate" type="string">
  **Data de negócio** do evento. Usada pelas regras históricas como ponto de partida para janelas de tempo (ex.: "últimos 7 dias").

  **Formato:** String datetime ISO 8601 com fuso horário (ex. `"2026-01-30T14:30:00Z"` ou `"2026-01-30T00:00:00.000Z"`).

  **Se não enviar:** O sistema usa o mesmo valor que `timestamp` (ou a hora atual do servidor se nenhum for enviado). O evento é tratado como "agora" nas regras históricas; não é necessário enviar quando o evento é em tempo real.
</ParamField>

<Note title="Resumo eventDate">
  * **Se omitida** → Definimos `eventDate = timestamp` (ou hora atual). As regras históricas usam esse valor como ponto de partida.
  * **Formato** → ISO 8601 com fuso: `"YYYY-MM-DDTHH:mm:ss.sssZ"` (ex. `"2026-01-30T00:00:00.000Z"`).
  * **Quando enviar** → Quando o evento ocorreu em data diferente da do envio (ex. eventos carregados depois ou em lote).
</Note>

<ParamField body="deviceId" type="string">
  Identificador único para o dispositivo. Deve ser um identificador estável que persiste entre sessões.

  Exemplo: `"840e89e4d46efd67"`
</ParamField>

<ParamField body="deviceDetails" type="object">
  Informações detalhadas do dispositivo. Quando fornecido, o dispositivo será automaticamente registrado ou atualizado.

  **Estrutura:**

  ```json theme={null}
  {
    "platform": "android",
    "osName": "Android",
    "osVersion": "Android 16",
    "manufacturer": "samsung",
    "model": "SM-A156M",
    "brand": "samsung",
    "browser": "Chrome",
    "browserVersion": "120.0.6099.129",
    "latitude": -34.6037,
    "longitude": -58.3816,
    "city": "Buenos Aires",
    "region": "Buenos Aires",
    "country": "Argentina",
    "countryCode": "AR",
    "additionalDetails": {}
  }
  ```
</ParamField>

<ParamField body="ipAddress" type="string">
  Endereço IP de onde o evento se originou (IPv4 ou IPv6).

  Exemplo: `"10.40.64.231"`
</ParamField>

<ParamField body="country" type="string">
  Código de país ISO 3166-1 alpha-2 onde o evento ocorreu.

  Exemplo: `"AR"`
</ParamField>

<ParamField body="isVpn" type="boolean" default="false">
  Se a conexão é através de uma VPN
</ParamField>

<ParamField body="isProxy" type="boolean" default="false">
  Se a conexão é através de um proxy
</ParamField>

<ParamField body="isNewDevice" type="boolean">
  **Flag de dispositivo novo** persistida no evento (`is_new_device` no banco). Veja [Como funciona o `isNewDevice`](#como-funciona-o-isnewdevice) abaixo.
</ParamField>

<ParamField body="sessionId" type="string">
  Identificador de sessão do SDK (`sess_...`, máx. 64 caracteres). Para organizações com o SDK habilitado, um evento que traz apenas `sessionId` (sem identificador de entidade) é aceito e persistido como **evento anônimo pré-login**; é vinculado à entidade depois, no primeiro evento que trouxer `sessionId` e um identificador de entidade juntos. Sem o SDK habilitado, um identificador de entidade continua obrigatório.

  Exemplo: `"sess_a1b2c3d4"`
</ParamField>

<ParamField body="sdkSignals" type="object">
  Sinais estruturados emitidos pelo SDK (separados do `metadata` livre). Todos os campos opcionais: `sessionId`, `sessionDuration`, `integrityScore` (0–100), `integrityFlags` (`fetchHooked`, `prototypeModified`, `debuggerAttached`, `framingDetected`) e `behavioralSignals` (`keystrokeAvgMs`, `pasteDetected`, `completionTimeMs`, `touchVelocity`).
</ParamField>

<ParamField body="failedAttemptsCount" type="number" default="0">
  Número de tentativas de autenticação falhas (para eventos de autenticação)

  Exemplo: `3`
</ParamField>

<ParamField body="destinationAccountId" type="string">
  Identificador de conta de destino para eventos de transferência (CBU, CVU, etc.)

  Exemplo: `"0170042640000004234411"`
</ParamField>

<ParamField body="destinationCuit" type="string">
  CUIT de destino para eventos de transferência

  Exemplo: `"27281455496"`
</ParamField>

<ParamField body="previousValue" type="string">
  Valor anterior para eventos de mudança de credenciais. Isso será automaticamente convertido em hash usando SHA-256 para segurança.

  Exemplo: `"old_password_hash"`
</ParamField>

<ParamField body="metadata" type="object">
  Dados adicionais específicos do evento como pares chave-valor. Use isso para campos personalizados específicos do seu caso de uso.

  Exemplo:

  ```json theme={null}
  {
    "amount": 5000,
    "currency": "ARS",
    "concept": "Payment",
    "reference": "INV-12345"
  }
  ```
</ParamField>

<ParamField body="userAgent" type="string">
  String de user agent do navegador para eventos web

  Exemplo: `"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..."`
</ParamField>

## Como funciona o `isNewDevice`

O valor persistido em cada evento alimenta regras de fraude (por exemplo `historical.userEvent.newDevice` e filtros `isNewDevice: true` em `user_events`).

### Prioridade: se você enviar, persistimos o seu valor

| Request                                   | `isNewDevice` persistido                                                                     |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| Você envia `isNewDevice: true` ou `false` | **Exatamente o que você enviou** (a gu1 não sobrescreve)                                     |
| Você omite `isNewDevice`                  | A gu1 **calcula** o valor (veja abaixo); padrão `false` sem dados de dispositivo suficientes |

Use o flag explícito quando seu app já sabe se a sessão é em dispositivo novo (SDK, armazenamento local, registro próprio). Omita quando quiser que a gu1 infira pelo registro de dispositivos.

### Quando você omite `isNewDevice` (inferência no servidor)

A gu1 só calcula automaticamente quando **ambos** estão presentes:

* `deviceId`
* `deviceDetails`

Fluxo:

1. **Registra ou atualiza** o dispositivo da entidade resolvida (tabela `devices`).
2. Define `isNewDevice` como `true` se:
   * Não existir linha para `(organização, entidade, deviceId)`, ou
   * O dispositivo existir mas `firstSeenAt` estiver nos **últimos 5 minutos** (janela de primeira visualização).
3. Caso contrário `false` (dispositivo já conhecido pela gu1 para essa entidade).

<Tip>
  Envie `deviceId` + `deviceDetails` em login e eventos sensíveis mesmo quando definir `isNewDevice` manualmente, para manter o registro de dispositivos atualizado para outras regras e auditoria.
</Tip>

### Nome do campo no body

`POST /events/user` usa **camelCase** no JSON: `isNewDevice`. O nome `is_new_device` **não** é lido neste endpoint.

### Exemplos

**Cliente decide (quando você já detecta dispositivo novo):**

```json theme={null}
{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "isNewDevice": true
}
```

**Inferência pela gu1 (omitir o flag; incluir dispositivo):**

```json theme={null}
{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "deviceDetails": { "platform": "android", "manufacturer": "samsung", "model": "SM-A156M" }
}
```

## Tipos de Eventos

<Tip>
  📋 Escolha o tipo de evento mais específico que corresponda ao seu caso de uso. Use `OTHER_EVENT` apenas quando nenhum tipo específico se aplique.
</Tip>

### Eventos de Autenticação

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

### Eventos de Mudança de Credenciais

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

### Eventos de Gerenciamento de Conta

* `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

### Eventos de Gerenciamento de Email

* `EMAIL_CREATED` - Email criado
* `EMAIL_ELIMINATED` - Email eliminado

### Eventos de Navegação

* `NAVIGATION` - Navegação de página ou tela

### Eventos de Transferência

* `TRANSFER_SUCCESS` - Transferência bem-sucedida
* `TRANSFER_FAILED` - Tentativa de transferência falhou
* `TRANSFER_SCHEDULED` - Transferência agendada para o futuro

### Eventos de Saldo

* `BALANCE_CHECK` - Saldo da conta verificado
* `BALANCE_CHECK_FAILED` - Verificação de saldo falhou

### Eventos de Acesso à Conta

* `ACCOUNTS_VIEW` - Lista de contas visualizada
* `ACCOUNTS_VIEW_FAILED` - Visualização de contas falhou

### Eventos de Transação

* `TRANSACTIONS_VIEW` - Histórico de transações visualizado
* `TRANSACTIONS_VIEW_FAILED` - Visualização de transações falhou

### Eventos de Destinatário

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

### Eventos de Perfil

* `PROFILE_VIEW` - Perfil de usuário visualizado
* `PROFILE_UPDATED` - Perfil de usuário atualizado

### Eventos de Mensagem

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

### Eventos de Titular de Conta

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

### Eventos de Alias

* `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

* `CARD_ADDED` - Cartão de pagamento adicionado
* `DEVICE_CONNECTED` - Dispositivo conectado

### Validação Biométrica

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

### Eventos do SDK

* `SESSION_STARTED` - Beacon de sessão do SDK (pré-login)
* `SESSION_IDENTIFIED` - Sessão vinculada a uma entidade (enviado com `sessionId` e um identificador de entidade)
* `SCREEN_VIEW` - Tela/navegação registrada pelo SDK

### Outros Eventos

* `OTHER_EVENT` - Evento personalizado ou genérico

## Resposta

<ResponseField name="success" type="boolean">
  Indica se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="event" type="object">
  O objeto do evento criado

  <ResponseField name="event.id" type="string">
    UUID interno do evento no gu1
  </ResponseField>

  <ResponseField name="event.eventType" type="string">
    Tipo de evento criado
  </ResponseField>

  <ResponseField name="event.userId" type="string">
    Identificador do usuário
  </ResponseField>

  <ResponseField name="event.entityId" type="string">
    UUID da entidade associada
  </ResponseField>

  <ResponseField name="event.entityExternalId" type="string">
    Identificador externo da entidade
  </ResponseField>

  <ResponseField name="event.taxId" type="string">
    Número de identificação fiscal
  </ResponseField>

  <ResponseField name="event.timestamp" type="string">
    Timestamp do evento (ISO 8601)
  </ResponseField>

  <ResponseField name="event.eventDate" type="string">
    Data de negócio usada pelas regras históricas para janelas de tempo (ISO 8601). Igual ao timestamp quando não enviada.
  </ResponseField>

  <ResponseField name="event.deviceId" type="string">
    Identificador do dispositivo
  </ResponseField>

  <ResponseField name="event.ipAddress" type="string">
    Endereço IP
  </ResponseField>

  <ResponseField name="event.country" type="string">
    Código do país
  </ResponseField>

  <ResponseField name="event.createdAt" type="string">
    Timestamp de criação do registro do evento
  </ResponseField>
</ResponseField>

<ResponseField name="entity" type="object">
  Informações da entidade (quando criada automaticamente ou existente)

  <ResponseField name="entity.id" type="string">
    UUID da entidade
  </ResponseField>

  <ResponseField name="entity.wasCreated" type="boolean">
    Se a entidade foi criada automaticamente por este evento
  </ResponseField>
</ResponseField>

<ResponseField name="rulesResult" type="object">
  Resultado da execução do motor de regras

  <ResponseField name="rulesResult.decision" type="string">
    Decisão final do motor de regras (APPROVE, REVIEW, REJECT)
  </ResponseField>
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="object">
  Resumo detalhado da execução do motor de regras, incluindo todas as regras avaliadas e seus resultados. Este objeto fornece visibilidade completa de quais regras foram executadas, quais condições foram atendidas e como a decisão final foi tomada. Estrutura completa e exemplo: [Resumo de Execução de Regras](/pt/api-reference/rules-execution-summary).
</ResponseField>

## Exemplos

### Evento de Login

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gu1.ai/events/user \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "LOGIN_SUCCESS",
      "entityExternalId": "user_12345",
      "userId": "user_12345",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "deviceDetails": {
        "platform": "android",
        "manufacturer": "samsung",
        "model": "SM-A156M",
        "osVersion": "Android 16"
      }
    }'
  ```

  ```javascript 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',
      userId: 'user_12345',
      deviceId: '840e89e4d46efd67',
      ipAddress: '10.40.64.231',
      country: 'AR',
      deviceDetails: {
        platform: 'android',
        manufacturer: 'samsung',
        model: 'SM-A156M',
        osVersion: 'Android 16'
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gu1.ai/events/user',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'eventType': 'LOGIN_SUCCESS',
          'entityExternalId': 'user_12345',
          'userId': 'user_12345',
          'deviceId': '840e89e4d46efd67',
          'ipAddress': '10.40.64.231',
          'country': 'AR',
          'deviceDetails': {
              'platform': 'android',
              'manufacturer': 'samsung',
              'model': 'SM-A156M',
              'osVersion': 'Android 16'
          }
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Evento de Transferência

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gu1.ai/events/user \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "TRANSFER_SUCCESS",
      "entityExternalId": "user_12345",
      "destinationAccountId": "0170042640000004234411",
      "destinationCuit": "27281455496",
      "metadata": {
        "amount": 5000,
        "currency": "ARS",
        "concept": "Payment"
      }
    }'
  ```

  ```javascript 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'
      }
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gu1.ai/events/user',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'eventType': 'TRANSFER_SUCCESS',
          'entityExternalId': 'user_12345',
          'destinationAccountId': '0170042640000004234411',
          'destinationCuit': '27281455496',
          'metadata': {
              'amount': 5000,
              'currency': 'ARS',
              'concept': 'Payment'
          }
      }
  )
  ```
</CodeGroup>

### Criar Entidade Automaticamente

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.gu1.ai/events/user?withAutoEntity=true" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "LOGIN_SUCCESS",
      "taxId": "20242455496",
      "userId": "user_12345"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/events/user?withAutoEntity=true', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventType: 'LOGIN_SUCCESS',
      taxId: '20242455496',
      userId: 'user_12345'
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gu1.ai/events/user?withAutoEntity=true',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'eventType': 'LOGIN_SUCCESS',
          'taxId': '20242455496',
          'userId': 'user_12345'
      }
  )
  ```
</CodeGroup>

## Exemplo de Resposta

```json theme={null}
{
  "success": true,
  "event": {
    "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",
    "createdAt": "2026-01-30T14:30:00Z"
  },
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "wasCreated": false
  },
  "rulesResult": {
    "decision": "APPROVE",
    "riskScore": 25
  },
  "rulesExecutionSummary": {
    "totalRulesEvaluated": 12,
    "rulesTriggered": 1,
    "executionTimeMs": 145,
    "decision": "APPROVE",
    "triggeredRules": [
      {
        "ruleId": "rule_123",
        "ruleName": "Multiple Login Attempts",
        "severity": "MEDIUM",
        "action": "REVIEW",
        "conditionsMet": ["failed_attempts > 2"]
      }
    ]
  }
}
```

## Respostas de Erro

### 400 Bad Request

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one entity identifier is required: entityId, entityExternalId, or taxId"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to create events"
  }
}
```

### 404 Not Found

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity not found. Use ?withAutoEntity=true to auto-create entities."
  }
}
```

### 500 Internal Server Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "EVENT_CREATE_FAILED",
    "message": "Failed to create event"
  }
}
```

## Casos de Uso

### Rastrear Padrões de Autenticação

```javascript theme={null}
// Rastrear logins bem-sucedidos e falhos
await createEvent({
  eventType: 'LOGIN_SUCCESS',
  entityExternalId: userId,
  deviceId: deviceFingerprint,
  ipAddress: req.ip
});

// Login falho com contagem de tentativas
await createEvent({
  eventType: 'LOGIN_FAILED',
  entityExternalId: userId,
  failedAttemptsCount: 3
});
```

### Monitorar Atividade de Transferência

```javascript theme={null}
// Rastrear transferências para detecção de fraudes
await createEvent({
  eventType: 'TRANSFER_SUCCESS',
  entityExternalId: userId,
  destinationAccountId: destinationAccount,
  metadata: {
    amount: transferAmount,
    currency: 'ARS'
  }
});
```

### Trilha de Auditoria de Conformidade

```javascript theme={null}
// Rastrear todas as mudanças de perfil
await createEvent({
  eventType: 'PROFILE_UPDATED',
  entityExternalId: userId,
  metadata: {
    fieldsChanged: ['email', 'phone'],
    previousEmail: 'old@example.com',
    newEmail: 'new@example.com'
  }
});
```

## Melhores Práticas

### Sempre Inclua Timestamps

Forneça timestamps explícitos quando eventos são enfileirados ou armazenados em buffer para manter a ordenação cronológica precisa.

### Rastreie Sucesso e Falha

Sempre rastreie eventos bem-sucedidos e falhos para detecção de fraude e análises abrangentes.

### Use Metadados Estruturados

Mantenha os metadados consistentes entre tipos de eventos similares para permitir melhor análise e consulta.

### Informações de Dispositivo

Inclua `deviceId` e `deviceDetails` quando disponíveis para manter o registro de dispositivos. Envie `isNewDevice` explicitamente se sua integração já classifica dispositivos novos; caso contrário, omita e deixe a gu1 inferir (veja [Como funciona o `isNewDevice`](#como-funciona-o-isnewdevice)).

### Manipule Criação Automática com Cuidado

Use `withAutoEntity=true` apenas quando você tiver certeza de que o ID fiscal é válido e deseja que entidades sejam criadas automaticamente.

## Próximos Passos

<CardGroup cols={2}>
  <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
  </Card>

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

  <Card title="Regras de Fraude" icon="shield-check" href="/pt/use-cases/transaction-monitoring/fraud-detection">
    Construa regras usando dados de eventos
  </Card>
</CardGroup>