> ## 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 dispositivos > Rastreie e monitore dispositivos usados por suas entidades para detecção de fraudes e segurança. Consulte o esquema do request, códigos de resposta. ## O que são Dispositivos? Dispositivos representam o hardware físico ou virtual usado por suas entidades (pessoas ou empresas) para acessar sua aplicação. Cada registro de dispositivo inclui informações detalhadas sobre a plataforma, sistema operacional, fabricante, modelo, geolocalização e flags de segurança. ## Recursos Principais ### 🔍 Detecção de Fraudes Rastreie múltiplos logins de dispositivos, detecte padrões suspeitos e identifique possíveis apropriações de contas monitorando o uso de dispositivos entre entidades. ### 🛡️ Monitoramento de Segurança Detecte automaticamente emuladores, dispositivos com root/jailbreak, VPNs e proxies para prevenir atividades fraudulentas e aplicar políticas de segurança. ### 📍 Rastreamento de Geolocalização Capture informações geográficas precisas incluindo latitude, longitude, cidade, região e país para cada dispositivo para detectar padrões de acesso anômalos. ### 📊 Análise de Comportamento do Usuário Analise impressões digitais de dispositivos, rastreie mudanças de dispositivos e construa perfis comportamentais para identificar padrões normais vs. suspeitos. ## Esquema de Dispositivo Cada registro de dispositivo contém as seguintes informações: ### Informações da Plataforma * `platform` - android, ios, ou web * `osName` - Nome do sistema operacional (ex: "Android", "iOS", "Windows") * `osVersion` - Versão do SO (ex: "Android 16", "iOS 17.2") * `manufacturer` - Fabricante do dispositivo (ex: "samsung", "Apple") * `model` - Modelo do dispositivo (ex: "SM-A156M", "iPhone 15 Pro") * `brand` - Marca do dispositivo * `deviceName` - Nome do dispositivo definido pelo usuário ### Informações do Navegador (Plataforma Web) * `browser` - Nome do navegador (ex: "Chrome", "Safari") * `browserVersion` - Versão do navegador ### Geolocalização * `latitude` - Latitude geográfica (-90 a 90) * `longitude` - Longitude geográfica (-180 a 180) * `city` - Nome da cidade * `region` - Estado ou província * `country` - Nome do país * `countryCode` - Código ISO 3166-1 alpha-2 * `ipAddress` - Último endereço IP conhecido ### Flags de Segurança * `isEmulator` - Detectado como emulador ou simulador * `isRooted` - Dispositivo tem root (Android) ou jailbreak (iOS) * `isBlocked` - Dispositivo foi bloqueado por razões de segurança * `isTrusted` - Dispositivo foi marcado como confiável ### Rastreamento * `firstSeenAt` - Primeira vez que este dispositivo foi visto * `lastSeenAt` - Timestamp da atividade mais recente ## Integração com Eventos Dispositivos são automaticamente registrados quando você cria eventos de usuário usando a API de Eventos. Quando um evento inclui `deviceId` e `deviceDetails`, o sistema irá: 1. **Verificar se o dispositivo existe** - Procurar por um registro de dispositivo existente 2. **Criar ou atualizar** - Criar um novo registro de dispositivo ou atualizar o existente com as informações mais recentes 3. **Rastrear atividade** - Atualizar o timestamp `lastSeenAt` 4. **Vincular à entidade** - Associar o dispositivo com a entidade do evento Este registro automático elimina a necessidade de gerenciamento manual de dispositivos na maioria dos casos. ## Casos de Uso ### Detecção de Apropriação de Conta Monitore quando uma entidade usa repentinamente um novo dispositivo ou múltiplos dispositivos em um curto período de tempo para detectar possíveis apropriações de conta. ### Detecção de Anomalia Geográfica Rastreie localizações de dispositivos e identifique padrões de acesso suspeitos, como logins de diferentes países em prazos impossíveis. ### Detecção de Emulador Bloqueie ou sinalize contas usando emuladores, que são comumente associados a automação e fraude. ### Impressão Digital de Dispositivo Construa perfis únicos de dispositivos para rastrear entidades através de sessões e detectar multi-contabilidade ou compartilhamento de contas. ### Requisitos de Conformidade Mantenha trilhas de auditoria de dispositivos usados para acesso, necessários para muitos frameworks de conformidade (PCI-DSS, SOC 2, etc.). ## Início Rápido ### 1. Registro Automático via Eventos ```javascript theme={null} // Dispositivos são criados automaticamente quando você envia eventos 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', deviceDetails: { platform: 'android', manufacturer: 'samsung', model: 'SM-A156M', osVersion: 'Android 16' }, ipAddress: '10.40.64.231', city: 'Buenos Aires', country: 'Argentina', countryCode: 'AR' }) }); ``` ### 2. Registro Manual de Dispositivo ```javascript theme={null} // Ou registre dispositivos manualmente const response = await fetch('https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ deviceId: '840e89e4d46efd67', platform: 'android', manufacturer: 'samsung', model: 'SM-A156M', osVersion: 'Android 16', city: 'Buenos Aires', country: 'Argentina', countryCode: 'AR' }) }); ``` ### 3. Consultar Dispositivos ```javascript theme={null} // Obter todos os dispositivos de uma entidade const response = await fetch('https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }); ``` ## Melhores Práticas ### Sempre Inclua Informações de Dispositivo Ao enviar eventos, sempre inclua `deviceId` e o máximo de detalhes do dispositivo possível para melhorar a precisão da detecção de fraudes. ### Use IDs de Dispositivo Consistentes Certifique-se de que suas aplicações cliente gerem identificadores de dispositivos estáveis que persistam entre inicializações de aplicativos e sessões. ### Rastreie Mudanças Geográficas Monitore os campos `city` e `countryCode` para detectar mudanças de localização suspeitas. ### Revise Flags de Segurança Revise regularmente dispositivos com `isEmulator: true` ou `isRooted: true` e tome as ações apropriadas. ### Defina Níveis de Confiança Marque dispositivos conhecidos como bons com `isTrusted: true` para reduzir falsos positivos em suas regras de fraude. ## Próximos Passos Registrar um dispositivo manualmente para uma entidade Consultar todos os dispositivos de uma entidade Aprenda sobre o registro automático de dispositivos via eventos Construa regras de detecção de fraude usando dados de dispositivos