Skip to main content
POST
http://api.gu1.ai
/
events
/
user
Criar
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>",
  "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.deviceId": "<string>",
    "event.ipAddress": "<string>",
    "event.country": "<string>",
    "event.createdAt": "<string>"
  },
  "entity": {
    "entity.id": "<string>",
    "entity.wasCreated": true
  }
}

​
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.
📋 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"
​
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
default:"false"
Se esta é a primeira vez que este dispositivo é visto para esta entidade
​
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..."

​
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

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

​
Exemplos

​
Evento de Login

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

​
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

Sempre inclua informações de dispositivo quando disponível para habilitar regras de detecção de fraude baseadas em dispositivos.

​
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