Skip to main content
POST
/
devices
/
entity
/
{entityId}
Crear
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>"
  }
}

​
Resumen

Registra manualmente un dispositivo para una entidad específica. Este endpoint te permite agregar información de dispositivo cuando no es capturada automáticamente a través de eventos, útil para migraciones de datos, pruebas o flujos de registro manual.
Registro Automático: En la mayoría de los casos, los dispositivos se registran automáticamente cuando creas eventos de usuario con información del dispositivo. El registro manual típicamente solo es necesario para:
  • Migrar datos de dispositivos existentes
  • Pruebas y desarrollo
  • Rellenar registros históricos de dispositivos

​
Endpoint

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

​
Autenticación

Requiere una clave API válida en el encabezado Authorization: 
Authorization: Bearer YOUR_API_KEY

​
Parámetros de Ruta

​
entityId
string
required
UUID de la entidad a la que se asociará este dispositivo

​
Cuerpo de la Solicitud

​
deviceId
string
required
Identificador único para este dispositivo. Debe ser un identificador estable que persista a través de sesiones (ej., huella digital del dispositivo, IMEI, ID de publicidad)
​
entityType
string
Tipo de entidad para auditoría. Opciones: person, company. Por defecto: "person"
​
entityExternalId
string
ID externo de la entidad (identificador de tu sistema). Se guarda desnormalizado en el dispositivo para consultas.
​
entityTaxId
string
Tax ID de la entidad (ej., CUIT, CPF). Se guarda desnormalizado en el dispositivo para consultas.
​
platform
string
Plataforma del dispositivo. Opciones:
  • android - Dispositivo Android
  • ios - Dispositivo iOS
  • web - Navegador web
Ejemplo: "android"
​
manufacturer
string
Nombre del fabricante del dispositivo (ej., “samsung”, “Apple”, “Google”)
​
model
string
Identificador del modelo del dispositivo (ej., “SM-A156M”, “iPhone 15 Pro”, “Pixel 8”)
​
brand
string
Nombre de la marca del dispositivo (ej., “samsung”, “Apple”)
​
deviceName
string
Nombre del dispositivo definido por el usuario o nombre del hardware
​
osVersion
string
Versión del sistema operativo (ej., “Android 16”, “iOS 17.2”, “Windows 11”)
​
systemName
string
Nombre del sistema para dispositivos iOS (ej., “iOS”)
​
systemVersion
string
Versión del sistema para dispositivos iOS (ej., “17.2”)
​
browser
string
Nombre del navegador para plataforma web (ej., “Chrome”, “Safari”, “Firefox”)
​
browserVersion
string
Versión del navegador para plataforma web (ej., “120.0.6099.129”)
​
latitude
number
Coordenada de latitud geográfica (-90 a 90)Ejemplo: -34.6037
​
longitude
number
Coordenada de longitud geográfica (-180 a 180)Ejemplo: -58.3816
​
city
string
Nombre de la ciudad (ej., “Buenos Aires”, “Nueva York”, “Londres”)
​
region
string
Estado o provincia (ej., “Buenos Aires”, “California”, “Ontario”)
​
country
string
Nombre del país (ej., “Argentina”, “Estados Unidos”, “Canadá”)
​
countryCode
string
Código de país ISO 3166-1 alpha-2 (ej., “AR”, “US”, “CA”)
​
ipAddress
string
Dirección IP (IPv4 o IPv6) desde la cual el dispositivo está accediendoEjemplo: "10.40.64.231"
​
isEmulator
boolean
default:"false"
Si este dispositivo está detectado como un emulador o simulador
​
isRooted
boolean
default:"false"
Si este dispositivo está rooteado (Android) o jailbreakeado (iOS)

​
Respuesta

​
success
boolean
Indica si la solicitud fue exitosa
​
device
object
El objeto del dispositivo creado
​
device.id
string
UUID interno del dispositivo de gu1
​
device.deviceId
string
Tu identificador de dispositivo proporcionado
​
device.externalId
string
Identificador externo del dispositivo (igual que deviceId)
​
device.entityId
string
UUID de la entidad asociada
​
device.entityExternalId
string
ID externo de la entidad (desnormalizado)
​
device.entityTaxId
string
Tax ID de la entidad (desnormalizado)
​
device.platform
string
Plataforma del dispositivo (android, ios, web)
​
device.manufacturer
string
Fabricante del dispositivo
​
device.model
string
Modelo del dispositivo
​
device.brand
string
Marca del dispositivo
​
device.deviceName
string
Nombre del dispositivo definido por el usuario o nombre del hardware
​
device.deviceDetails
object
Metadatos adicionales del dispositivo (objeto JSON). Por plataforma: Android (hardware, buildId, sdkVersion), iOS (systemName, identifierForVendor), Web (userAgent, etc.)
​
device.osName
string
Nombre del sistema operativo
​
device.osVersion
string
Versión del sistema operativo
​
device.browser
string
Nombre del navegador (solo web)
​
device.browserVersion
string
Versión del navegador (solo web)
​
device.latitude
number
Latitud geográfica
​
device.longitude
number
Longitud geográfica
​
device.city
string
Nombre de la ciudad
​
device.region
string
Estado/provincia
​
device.country
string
Nombre del país
​
device.countryCode
string
Código de país ISO
​
device.ipAddress
string
Dirección IP
​
device.isEmulator
boolean
Bandera de detección de emulador
​
device.isRooted
boolean
Bandera de detección de root/jailbreak
​
device.isBlocked
boolean
Si el dispositivo está bloqueado
​
device.isTrusted
boolean
Si el dispositivo está marcado como confiable
​
device.firstSeenAt
string
Primera vez que se vio el dispositivo (marca de tiempo ISO 8601)
​
device.lastSeenAt
string
Última vez que se vio el dispositivo (marca de tiempo ISO 8601)
​
device.createdAt
string
Marca de tiempo de creación del registro del dispositivo
​
device.updatedAt
string
Marca de tiempo de última actualización del registro del dispositivo

​
Ejemplos

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

​
Ejemplo de Respuesta

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

​
Respuestas de Error

​
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

​
Probar Reglas de Fraude

Crea dispositivos de prueba con características específicas para verificar que tus reglas de detección de fraude funcionen correctamente: 
// Crear un dispositivo sospechoso para pruebas
await createDevice({
  deviceId: 'test_emulator_001',
  platform: 'android',
  isEmulator: true,
  isRooted: true
});

​
Migración de Datos

Migra datos históricos de dispositivos desde tu sistema existente: 
// Importación masiva de dispositivos desde sistema legacy
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 Dispositivos

Permite a los clientes registrar manualmente sus dispositivos: 
// Cliente agrega manualmente un nuevo dispositivo confiable
await createDevice({
  deviceId: deviceFingerprint,
  platform: 'web',
  browser: 'Chrome',
  browserVersion: '120.0',
  city: userLocation.city,
  country: userLocation.country
});

​
Próximos Pasos

Listar Dispositivos

Consultar dispositivos de una entidad

API de Eventos

Auto-registrar dispositivos vía eventos