Skip to main content
POST
/
devices
/
entity
/
{entityId}
Criar
curl --request POST \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deviceId": "<string>",
  "entityType": "<string>",
  "entityExternalId": "<string>",
  "entityTaxId": "<string>",
  "platform": "<string>",
  "manufacturer": "<string>",
  "model": "<string>",
  "brand": "<string>",
  "deviceName": "<string>",
  "osVersion": "<string>",
  "systemName": "<string>",
  "systemVersion": "<string>",
  "browser": "<string>",
  "browserVersion": "<string>",
  "latitude": 123,
  "longitude": 123,
  "city": "<string>",
  "region": "<string>",
  "country": "<string>",
  "countryCode": "<string>",
  "ipAddress": "<string>",
  "isEmulator": true,
  "isRooted": true
}
'
{
  "success": true,
  "device": {
    "device.id": "<string>",
    "device.deviceId": "<string>",
    "device.externalId": "<string>",
    "device.entityId": "<string>",
    "device.entityExternalId": "<string>",
    "device.entityTaxId": "<string>",
    "device.platform": "<string>",
    "device.manufacturer": "<string>",
    "device.model": "<string>",
    "device.brand": "<string>",
    "device.deviceName": "<string>",
    "device.deviceDetails": {},
    "device.osName": "<string>",
    "device.osVersion": "<string>",
    "device.browser": "<string>",
    "device.browserVersion": "<string>",
    "device.latitude": 123,
    "device.longitude": 123,
    "device.city": "<string>",
    "device.region": "<string>",
    "device.country": "<string>",
    "device.countryCode": "<string>",
    "device.ipAddress": "<string>",
    "device.isEmulator": true,
    "device.isRooted": true,
    "device.isBlocked": true,
    "device.isTrusted": true,
    "device.firstSeenAt": "<string>",
    "device.lastSeenAt": "<string>",
    "device.createdAt": "<string>",
    "device.updatedAt": "<string>"
  }
}

​
Visão Geral

Registre manualmente um dispositivo para uma entidade específica. Este endpoint permite adicionar informações de dispositivo quando não são capturadas automaticamente através de eventos, útil para migrações de dados, testes ou fluxos de registro manual.
Registro Automático: Na maioria dos casos, dispositivos são registrados automaticamente quando você cria eventos de usuário com informações de dispositivo. O registro manual é tipicamente necessário apenas para:
  • Migração de dados de dispositivos existentes
  • Testes e desenvolvimento
  • Preenchimento retroativo de registros históricos de dispositivos

​
Endpoint

POST https://api.gu1.ai/devices/entity/{entityId}

​
Autenticação

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

​
Parâmetros de Caminho

​
entityId
string
required
UUID da entidade para associar este dispositivo

​
Corpo da Requisição

​
deviceId
string
required
Identificador único para este dispositivo. Deve ser um identificador estável que persiste entre sessões (ex: impressão digital do dispositivo, IMEI, ID de publicidade)
​
entityType
string
Tipo da entidade para auditoria. Opções: person, company. Padrão: "person"
​
entityExternalId
string
ID externo da entidade (identificador do seu sistema). Armazenado desnormalizado no dispositivo para consultas.
​
entityTaxId
string
Tax ID da entidade (ex: CUIT, CPF). Armazenado desnormalizado no dispositivo para consultas.
​
platform
string
Plataforma do dispositivo. Opções:
  • android - Dispositivo Android
  • ios - Dispositivo iOS
  • web - Navegador web
Exemplo: "android"
​
manufacturer
string
Nome do fabricante do dispositivo (ex: “samsung”, “Apple”, “Google”)
​
model
string
Identificador do modelo do dispositivo (ex: “SM-A156M”, “iPhone 15 Pro”, “Pixel 8”)
​
brand
string
Nome da marca do dispositivo (ex: “samsung”, “Apple”)
​
deviceName
string
Nome do dispositivo definido pelo usuário ou nome do hardware
​
osVersion
string
Versão do sistema operacional (ex: “Android 16”, “iOS 17.2”, “Windows 11”)
​
systemName
string
Nome do sistema para dispositivos iOS (ex: “iOS”)
​
systemVersion
string
Versão do sistema para dispositivos iOS (ex: “17.2”)
​
browser
string
Nome do navegador para plataforma web (ex: “Chrome”, “Safari”, “Firefox”)
​
browserVersion
string
Versão do navegador para plataforma web (ex: “120.0.6099.129”)
​
latitude
number
Coordenada de latitude geográfica (-90 a 90)Exemplo: -34.6037
​
longitude
number
Coordenada de longitude geográfica (-180 a 180)Exemplo: -58.3816
​
city
string
Nome da cidade (ex: “Buenos Aires”, “Nova York”, “Londres”)
​
region
string
Estado ou província (ex: “Buenos Aires”, “Califórnia”, “Ontário”)
​
country
string
Nome do país (ex: “Argentina”, “Estados Unidos”, “Canadá”)
​
countryCode
string
Código de país ISO 3166-1 alpha-2 (ex: “AR”, “US”, “CA”)
​
ipAddress
string
Endereço IP (IPv4 ou IPv6) de onde o dispositivo está acessandoExemplo: "10.40.64.231"
​
isEmulator
boolean
default:"false"
Se este dispositivo foi detectado como emulador ou simulador
​
isRooted
boolean
default:"false"
Se este dispositivo tem root (Android) ou jailbreak (iOS)

​
Resposta

​
success
boolean
Indica se a requisição foi bem-sucedida
​
device
object
O objeto do dispositivo criado
​
device.id
string
UUID interno do dispositivo no gu1
​
device.deviceId
string
Seu identificador de dispositivo fornecido
​
device.externalId
string
Identificador externo do dispositivo (mesmo que deviceId)
​
device.entityId
string
UUID da entidade associada
​
device.entityExternalId
string
ID externo da entidade (desnormalizado)
​
device.entityTaxId
string
Tax ID da entidade (desnormalizado)
​
device.platform
string
Plataforma do dispositivo (android, ios, web)
​
device.manufacturer
string
Fabricante do dispositivo
​
device.model
string
Modelo do dispositivo
​
device.brand
string
Marca do dispositivo
​
device.deviceName
string
Nome do dispositivo definido pelo usuário ou nome do hardware
​
device.deviceDetails
object
Metadados adicionais do dispositivo (objeto JSON). Por plataforma: Android (hardware, buildId, sdkVersion), iOS (systemName, identifierForVendor), Web (userAgent, etc.)
​
device.osName
string
Nome do sistema operacional
​
device.osVersion
string
Versão do sistema operacional
​
device.browser
string
Nome do navegador (somente web)
​
device.browserVersion
string
Versão do navegador (somente web)
​
device.latitude
number
Latitude geográfica
​
device.longitude
number
Longitude geográfica
​
device.city
string
Nome da cidade
​
device.region
string
Estado/província
​
device.country
string
Nome do país
​
device.countryCode
string
Código do país ISO
​
device.ipAddress
string
Endereço IP
​
device.isEmulator
boolean
Flag de detecção de emulador
​
device.isRooted
boolean
Flag de detecção de root/jailbreak
​
device.isBlocked
boolean
Se o dispositivo está bloqueado
​
device.isTrusted
boolean
Se o dispositivo está marcado como confiável
​
device.firstSeenAt
string
Primeira vez que o dispositivo foi visto (timestamp ISO 8601)
​
device.lastSeenAt
string
Última vez que o dispositivo foi visto (timestamp ISO 8601)
​
device.createdAt
string
Timestamp de criação do registro do dispositivo
​
device.updatedAt
string
Timestamp da última atualização do registro do dispositivo

​
Exemplos

curl -X POST https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "840e89e4d46efd67",
    "platform": "android",
    "manufacturer": "samsung",
    "model": "SM-A156M",
    "brand": "samsung",
    "osVersion": "Android 16",
    "city": "Buenos Aires",
    "region": "Buenos Aires",
    "country": "Argentina",
    "countryCode": "AR",
    "latitude": -34.6037,
    "longitude": -58.3816,
    "ipAddress": "10.40.64.231"
  }'

​
Exemplo de Resposta

{
  "success": true,
  "device": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deviceId": "840e89e4d46efd67",
    "externalId": "840e89e4d46efd67",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityExternalId": null,
    "entityTaxId": null,
    "deviceName": null,
    "deviceDetails": {},
    "platform": "android",
    "manufacturer": "samsung",
    "model": "SM-A156M",
    "brand": "samsung",
    "osName": "Android",
    "osVersion": "Android 16",
    "browser": null,
    "browserVersion": null,
    "latitude": -34.6037,
    "longitude": -58.3816,
    "city": "Buenos Aires",
    "region": "Buenos Aires",
    "country": "Argentina",
    "countryCode": "AR",
    "ipAddress": "10.40.64.231",
    "isEmulator": false,
    "isRooted": false,
    "isBlocked": false,
    "isTrusted": false,
    "firstSeenAt": "2026-01-30T10:00:00Z",
    "lastSeenAt": "2026-01-30T10:00:00Z",
    "createdAt": "2026-01-30T10:00:00Z",
    "updatedAt": "2026-01-30T10:00:00Z"
  }
}

​
Respostas de Erro

​
400 Bad Request

{
  "success": false,
  "error": {
    "code": "MISSING_DEVICE_ID",
    "message": "Device ID is required"
  }
}

​
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 devices"
  }
}

​
404 Not Found

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

​
500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "DEVICE_CREATE_FAILED",
    "message": "Failed to create device"
  }
}

​
Casos de Uso

​
Testar Regras de Fraude

Crie dispositivos de teste com características específicas para verificar se suas regras de detecção de fraude funcionam corretamente: 
// Criar um dispositivo suspeito para testes
await createDevice({
  deviceId: 'test_emulator_001',
  platform: 'android',
  isEmulator: true,
  isRooted: true
});

​
Migração de Dados

Migre dados históricos de dispositivos do seu sistema existente: 
// Importação em massa de dispositivos do sistema legado
for (const legacyDevice of legacyDevices) {
  await createDevice({
    deviceId: legacyDevice.id,
    platform: legacyDevice.platform,
    manufacturer: legacyDevice.manufacturer,
    model: legacyDevice.model,
    city: legacyDevice.location.city,
    country: legacyDevice.location.country
  });
}

​
Registro Manual de Dispositivo

Permita que clientes registrem seus dispositivos manualmente: 
// Cliente adiciona manualmente um novo dispositivo confiável
await createDevice({
  deviceId: deviceFingerprint,
  platform: 'web',
  browser: 'Chrome',
  browserVersion: '120.0',
  city: userLocation.city,
  country: userLocation.country
});

​
Próximos Passos

Listar Dispositivos

Consultar dispositivos de uma entidade

API de Eventos

Registrar dispositivos automaticamente via eventos