Criar um evento de usuário para regras e fraude

curl --request POST \
  --url http://api.gu1.ai/events/user \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "userId": "<string>",
  "entityId": "<string>",
  "entityExternalId": "<string>",
  "taxId": "<string>",
  "timestamp": "<string>",
  "eventDate": "<string>",
  "deviceId": "<string>",
  "deviceDetails": {},
  "ipAddress": "<string>",
  "country": "<string>",
  "isVpn": true,
  "isProxy": true,
  "isNewDevice": true,
  "failedAttemptsCount": 123,
  "destinationAccountId": "<string>",
  "destinationCuit": "<string>",
  "previousValue": "<string>",
  "metadata": {},
  "userAgent": "<string>"
}
'

{
  "success": true,
  "event": {
    "event.id": "<string>",
    "event.eventType": "<string>",
    "event.userId": "<string>",
    "event.entityId": "<string>",
    "event.entityExternalId": "<string>",
    "event.taxId": "<string>",
    "event.timestamp": "<string>",
    "event.eventDate": "<string>",
    "event.deviceId": "<string>",
    "event.ipAddress": "<string>",
    "event.country": "<string>",
    "event.createdAt": "<string>"
  },
  "entity": {
    "entity.id": "<string>",
    "entity.wasCreated": true
  },
  "rulesResult": {
    "rulesResult.decision": "<string>"
  },
  "rulesExecutionSummary": {}
}

POST

events

user

Criar um evento de usuário para regras e fraude

curl --request POST \
  --url http://api.gu1.ai/events/user \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "userId": "<string>",
  "entityId": "<string>",
  "entityExternalId": "<string>",
  "taxId": "<string>",
  "timestamp": "<string>",
  "eventDate": "<string>",
  "deviceId": "<string>",
  "deviceDetails": {},
  "ipAddress": "<string>",
  "country": "<string>",
  "isVpn": true,
  "isProxy": true,
  "isNewDevice": true,
  "failedAttemptsCount": 123,
  "destinationAccountId": "<string>",
  "destinationCuit": "<string>",
  "previousValue": "<string>",
  "metadata": {},
  "userAgent": "<string>"
}
'

{
  "success": true,
  "event": {
    "event.id": "<string>",
    "event.eventType": "<string>",
    "event.userId": "<string>",
    "event.entityId": "<string>",
    "event.entityExternalId": "<string>",
    "event.taxId": "<string>",
    "event.timestamp": "<string>",
    "event.eventDate": "<string>",
    "event.deviceId": "<string>",
    "event.ipAddress": "<string>",
    "event.country": "<string>",
    "event.createdAt": "<string>"
  },
  "entity": {
    "entity.id": "<string>",
    "entity.wasCreated": true
  },
  "rulesResult": {
    "rulesResult.decision": "<string>"
  },
  "rulesExecutionSummary": {}
}

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.

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

Endpoint

POST 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

withAutoEntity

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

Corpo da Requisição

eventType

string

required

Tipo de evento sendo rastreado. Deve ser um dos 41 tipos de eventos suportados (veja seção Tipos de Eventos abaixo).Exemplo: "LOGIN_SUCCESS"

userId

string

Seu identificador interno de usuário. Usado para agrupar eventos por usuário entre diferentes entidades.Exemplo: "user_12345"

entityId

string

UUID da entidade gu1. Forneça isso se você tiver o ID interno do gu1.

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.

entityExternalId

string

Seu identificador externo de entidade. Este é seu ID único para a entidade em seu sistema.Exemplo: "user_12345"

taxId

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"

timestamp

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"

eventDate

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.

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

deviceId

string

Identificador único para o dispositivo. Deve ser um identificador estável que persiste entre sessões.Exemplo: "840e89e4d46efd67"

deviceDetails

object

Informações detalhadas do dispositivo. Quando fornecido, o dispositivo será automaticamente registrado ou atualizado.Estrutura:

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

ipAddress

string

Endereço IP de onde o evento se originou (IPv4 ou IPv6).Exemplo: "10.40.64.231"

country

string

Código de país ISO 3166-1 alpha-2 onde o evento ocorreu.Exemplo: "AR"

isVpn

boolean

default:"false"

Se a conexão é através de uma VPN

isProxy

boolean

default:"false"

Se a conexão é através de um proxy

isNewDevice

boolean

Flag de dispositivo novo persistida no evento (is_new_device no banco). Veja Como funciona o isNewDevice abaixo.

failedAttemptsCount

number

default:"0"

Número de tentativas de autenticação falhas (para eventos de autenticação)Exemplo: 3

destinationAccountId

string

Identificador de conta de destino para eventos de transferência (CBU, CVU, etc.)Exemplo: "0170042640000004234411"

destinationCuit

string

CUIT de destino para eventos de transferênciaExemplo: "27281455496"

previousValue

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"

metadata

object

Dados adicionais específicos do evento como pares chave-valor. Use isso para campos personalizados específicos do seu caso de uso.Exemplo:

{
  "amount": 5000,
  "currency": "ARS",
  "concept": "Payment",
  "reference": "INV-12345"
}

userAgent

string

String de user agent do navegador para eventos webExemplo: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..."

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:

Registra ou atualiza o dispositivo da entidade resolvida (tabela devices).
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).
Caso contrário false (dispositivo já conhecido pela gu1 para essa entidade).

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.

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):

{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "isNewDevice": true
}

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

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

Tipos de Eventos

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

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

Outros Eventos

OTHER_EVENT - Evento personalizado ou genérico

Resposta

success

boolean

Indica se a requisição foi bem-sucedida

event

object

O objeto do evento criado

event.id

string

UUID interno do evento no gu1

event.eventType

string

Tipo de evento criado

event.userId

string

Identificador do usuário

event.entityId

string

UUID da entidade associada

event.entityExternalId

string

Identificador externo da entidade

event.taxId

string

Número de identificação fiscal

event.timestamp

string

Timestamp do evento (ISO 8601)

event.eventDate

string

Data de negócio usada pelas regras históricas para janelas de tempo (ISO 8601). Igual ao timestamp quando não enviada.

event.deviceId

string

Identificador do dispositivo

event.ipAddress

string

Endereço IP

event.country

string

Código do país

event.createdAt

string

Timestamp de criação do registro do evento

entity

object

Informações da entidade (quando criada automaticamente ou existente)

entity.id

string

UUID da entidade

entity.wasCreated

boolean

Se a entidade foi criada automaticamente por este evento

rulesResult

object

Resultado da execução do motor de regras

rulesResult.decision

string

Decisão final do motor de regras (APPROVE, REVIEW, REJECT)

rulesExecutionSummary

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.

Exemplos

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

Evento de Transferência

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

Criar Entidade Automaticamente

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

Exemplo de Resposta

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

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

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to create events"
  }
}

404 Not Found

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

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "EVENT_CREATE_FAILED",
    "message": "Failed to create event"
  }
}

Casos de Uso

Rastrear Padrões de Autenticação

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

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

// 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).

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

Listar Eventos

Consultar eventos com filtros

Estatísticas de Eventos

Obter estatísticas agregadas

API de Dispositivos

Aprenda sobre integração de dispositivos

Regras de Fraude

Construa regras usando dados de eventos

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

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Consulta

​Corpo da Requisição

​Como funciona o isNewDevice

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

​Quando você omite isNewDevice (inferência no servidor)

​Nome do campo no body

​Exemplos

​Tipos de Eventos

​Eventos de Autenticação

​Eventos de Mudança de Credenciais

​Eventos de Gerenciamento de Conta

​Eventos de Gerenciamento de Email

​Eventos de Navegação

​Eventos de Transferência

​Eventos de Saldo

​Eventos de Acesso à Conta

​Eventos de Transação

​Eventos de Destinatário

​Eventos de Perfil

​Eventos de Mensagem

​Eventos de Titular de Conta

​Eventos de Alias

​Pagamento / Dispositivo

​Validação Biométrica

​Outros Eventos

​Resposta

​Exemplos

​Evento de Login

​Evento de Transferência

​Criar Entidade Automaticamente

​Exemplo de Resposta

​Respostas de Erro

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Rastrear Padrões de Autenticação

​Monitorar Atividade de Transferência

​Trilha de Auditoria de Conformidade

​Melhores Práticas

​Sempre Inclua Timestamps

​Rastreie Sucesso e Falha

​Use Metadados Estruturados

​Informações de Dispositivo

​Manipule Criação Automática com Cuidado

​Próximos Passos

Listar Eventos

Estatísticas de Eventos

API de Dispositivos

Regras de Fraude

Visão Geral

Endpoint

Autenticação

Parâmetros de Consulta

Corpo da Requisição

Como funciona o `isNewDevice`

Prioridade: se você enviar, persistimos o seu valor

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

Nome do campo no body

Exemplos

Tipos de Eventos

Eventos de Autenticação

Eventos de Mudança de Credenciais

Eventos de Gerenciamento de Conta

Eventos de Gerenciamento de Email

Eventos de Navegação

Eventos de Transferência

Eventos de Saldo

Eventos de Acesso à Conta

Eventos de Transação

Eventos de Destinatário

Eventos de Perfil

Eventos de Mensagem

Eventos de Titular de Conta

Eventos de Alias

Pagamento / Dispositivo

Validação Biométrica

Outros Eventos

Resposta

Exemplos

Evento de Login

Evento de Transferência

Criar Entidade Automaticamente

Exemplo de Resposta

Respostas de Erro

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Rastrear Padrões de Autenticação

Monitorar Atividade de Transferência

Trilha de Auditoria de Conformidade

Melhores Práticas

Sempre Inclua Timestamps

Rastreie Sucesso e Falha

Use Metadados Estruturados

Informações de Dispositivo

Manipule Criação Automática com Cuidado

Próximos Passos