Listar dispositivos de una entidad

curl --request GET \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>'

{
  "success": true,
  "devices": [
    {
      "devices[].id": "<string>",
      "devices[].deviceId": "<string>",
      "devices[].externalId": "<string>",
      "devices[].entityId": "<string>",
      "devices[].entityExternalId": "<string>",
      "devices[].entityTaxId": "<string>",
      "devices[].deviceName": "<string>",
      "devices[].deviceDetails": {},
      "devices[].platform": "<string>",
      "devices[].manufacturer": "<string>",
      "devices[].model": "<string>",
      "devices[].brand": "<string>",
      "devices[].osName": "<string>",
      "devices[].osVersion": "<string>",
      "devices[].browser": "<string>",
      "devices[].browserVersion": "<string>",
      "devices[].latitude": 123,
      "devices[].longitude": 123,
      "devices[].city": "<string>",
      "devices[].region": "<string>",
      "devices[].country": "<string>",
      "devices[].countryCode": "<string>",
      "devices[].ipAddress": "<string>",
      "devices[].isEmulator": true,
      "devices[].isRooted": true,
      "devices[].isBlocked": true,
      "devices[].isTrusted": true,
      "devices[].firstSeenAt": "<string>",
      "devices[].lastSeenAt": "<string>",
      "devices[].createdAt": "<string>",
      "devices[].updatedAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

GET

devices

entity

{entityId}

Listar dispositivos de una entidad

curl --request GET \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>'

{
  "success": true,
  "devices": [
    {
      "devices[].id": "<string>",
      "devices[].deviceId": "<string>",
      "devices[].externalId": "<string>",
      "devices[].entityId": "<string>",
      "devices[].entityExternalId": "<string>",
      "devices[].entityTaxId": "<string>",
      "devices[].deviceName": "<string>",
      "devices[].deviceDetails": {},
      "devices[].platform": "<string>",
      "devices[].manufacturer": "<string>",
      "devices[].model": "<string>",
      "devices[].brand": "<string>",
      "devices[].osName": "<string>",
      "devices[].osVersion": "<string>",
      "devices[].browser": "<string>",
      "devices[].browserVersion": "<string>",
      "devices[].latitude": 123,
      "devices[].longitude": 123,
      "devices[].city": "<string>",
      "devices[].region": "<string>",
      "devices[].country": "<string>",
      "devices[].countryCode": "<string>",
      "devices[].ipAddress": "<string>",
      "devices[].isEmulator": true,
      "devices[].isRooted": true,
      "devices[].isBlocked": true,
      "devices[].isTrusted": true,
      "devices[].firstSeenAt": "<string>",
      "devices[].lastSeenAt": "<string>",
      "devices[].createdAt": "<string>",
      "devices[].updatedAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

Resumen

Recupera todos los dispositivos registrados para una entidad específica, ordenados por última actividad. Usa este endpoint para monitorear patrones de uso de dispositivos, detectar acceso sospechoso y construir reglas de detección de fraude basadas en dispositivos.

Endpoint

GET 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 cuyos dispositivos deseas recuperar

Parámetros de Consulta

limit

number

default:"50"

Número máximo de dispositivos a devolver por página (máx: 1000)Ejemplo: ?limit=100

offset

number

default:"0"

Número de dispositivos a omitir para paginaciónEjemplo: ?offset=50

Respuesta

success

boolean

Indica si la solicitud fue exitosa

devices

array

Array de objetos de dispositivo ordenados por lastSeenAt (más reciente primero)

devices[].id

string

UUID interno del dispositivo de gu1

devices[].deviceId

string

Identificador del dispositivo

devices[].externalId

string

Identificador externo del dispositivo

devices[].entityId

string

UUID de la entidad asociada

devices[].entityExternalId

string

ID externo de la entidad (desnormalizado)

devices[].entityTaxId

string

Tax ID de la entidad (desnormalizado)

devices[].deviceName

string

Nombre del dispositivo definido por el usuario o nombre del hardware

devices[].deviceDetails

object

Metadatos adicionales del dispositivo (objeto JSON). Detalles por plataforma.

devices[].platform

string

Plataforma del dispositivo (android, ios, web)

devices[].manufacturer

string

Fabricante del dispositivo

devices[].model

string

Modelo del dispositivo

devices[].brand

string

Marca del dispositivo

devices[].osName

string

Nombre del sistema operativo

devices[].osVersion

string

Versión del sistema operativo

devices[].browser

string

Nombre del navegador (solo web)

devices[].browserVersion

string

Versión del navegador (solo web)

devices[].latitude

number

Latitud geográfica

devices[].longitude

number

Longitud geográfica

devices[].city

string

Nombre de la ciudad

devices[].region

string

Estado/provincia

devices[].country

string

Nombre del país

devices[].countryCode

string

Código de país ISO

devices[].ipAddress

string

Última dirección IP conocida

devices[].isEmulator

boolean

Si el dispositivo es un emulador

devices[].isRooted

boolean

Si el dispositivo está rooteado/jailbreakeado

devices[].isBlocked

boolean

Si el dispositivo está bloqueado

devices[].isTrusted

boolean

Si el dispositivo es confiable

devices[].firstSeenAt

string

Marca de tiempo de primera vez visto (ISO 8601)

devices[].lastSeenAt

string

Marca de tiempo de última vez visto (ISO 8601)

devices[].createdAt

string

Marca de tiempo de creación

devices[].updatedAt

string

Marca de tiempo de última actualización

pagination

object

Información de paginación

pagination.total

number

Número total de dispositivos para esta entidad

pagination.limit

number

Límite de tamaño de página usado

pagination.offset

number

Desplazamiento usado

pagination.hasMore

boolean

Si hay más páginas disponibles

Ejemplos

Consulta Básica

curl https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Con Paginación

curl "https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de Respuesta

{
  "success": true,
  "devices": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "deviceId": "840e89e4d46efd67",
      "externalId": "840e89e4d46efd67",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityExternalId": "user_12345",
      "entityTaxId": "20-12345678-9",
      "deviceName": "Galaxy A15",
      "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": true,
      "firstSeenAt": "2026-01-20T10:00:00Z",
      "lastSeenAt": "2026-01-30T14:30:00Z",
      "createdAt": "2026-01-20T10:00:00Z",
      "updatedAt": "2026-01-30T14:30:00Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "deviceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityExternalId": "user_12345",
      "entityTaxId": null,
      "deviceName": null,
      "deviceDetails": {},
      "platform": "web",
      "manufacturer": null,
      "model": null,
      "brand": null,
      "osName": "Windows",
      "osVersion": null,
      "browser": "Chrome",
      "browserVersion": "120.0.6099.129",
      "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-25T08:15:00Z",
      "lastSeenAt": "2026-01-30T12:00:00Z",
      "createdAt": "2026-01-25T08:15:00Z",
      "updatedAt": "2026-01-30T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Respuestas de Error

401 Unauthorized

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

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to read 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": "DEVICES_FETCH_FAILED",
    "message": "Failed to fetch entity devices"
  }
}

Casos de Uso

Panel de Inventario de Dispositivos

Construye un panel mostrando todos los dispositivos usados por tus entidades:

async function getDeviceInventory(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Agrupar por plataforma
  const byPlatform = data.devices.reduce((acc, device) => {
    acc[device.platform] = (acc[device.platform] || 0) + 1;
    return acc;
  }, {});

  console.log('Dispositivos por plataforma:', byPlatform);
  return data.devices;
}

Detección de Fraude

Detecta patrones de dispositivos sospechosos:

async function detectSuspiciousDevices(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Marcar dispositivos sospechosos
  const suspicious = data.devices.filter(device =>
    device.isEmulator ||
    device.isRooted ||
    device.isBlocked
  );

  if (suspicious.length > 0) {
    console.warn('Dispositivos sospechosos encontrados:', suspicious);
  }

  return suspicious;
}

Análisis Geográfico

Analiza ubicaciones de dispositivos para anomalías:

async function analyzeDeviceLocations(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Obtener países únicos
  const countries = new Set(
    data.devices.map(d => d.countryCode).filter(Boolean)
  );

  // Marcar si hay dispositivos de múltiples países
  if (countries.size > 1) {
    console.warn('Dispositivos desde múltiples países:', Array.from(countries));
  }

  return Array.from(countries);
}

Monitoreo de Actividad

Monitorea actividad reciente de dispositivos:

async function getRecentDevices(entityId, hours = 24) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();
  const cutoff = new Date(Date.now() - hours * 60 * 60 * 1000);

  // Filtrar dispositivos activos en las últimas N horas
  const recentDevices = data.devices.filter(device =>
    new Date(device.lastSeenAt) > cutoff
  );

  console.log(`${recentDevices.length} dispositivos activos en las últimas ${hours} horas`);
  return recentDevices;
}

Mejores Prácticas de Paginación

Iterar a Través de Todas las Páginas

async function getAllDevices(entityId) {
  const allDevices = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.gu1.ai/devices/entity/${entityId}?limit=${limit}&offset=${offset}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    const data = await response.json();
    allDevices.push(...data.devices);

    hasMore = data.pagination.hasMore;
    offset += limit;
  }

  console.log(`Total de dispositivos: ${allDevices.length}`);
  return allDevices;
}

Próximos Pasos

Crear Dispositivo

Registrar un nuevo dispositivo

API de Eventos

Aprende sobre registro automático de dispositivos

Detección de Fraude

Construye reglas de fraude basadas en dispositivos

Matriz de Riesgo

Configura puntuación de riesgo con datos de dispositivos

Registrar un dispositivo para una entidad Resumen de la API de eventos de usuario

⌘I

​Resumen

​Endpoint

​Autenticación

​Parámetros de Ruta

​Parámetros de Consulta

​Respuesta

​Ejemplos

​Consulta Básica

​Con Paginación

​Ejemplo de Respuesta

​Respuestas de Error

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Panel de Inventario de Dispositivos

​Detección de Fraude

​Análisis Geográfico

​Monitoreo de Actividad

​Mejores Prácticas de Paginación

​Iterar a Través de Todas las Páginas

​Próximos Pasos

Crear Dispositivo

API de Eventos

Detección de Fraude

Matriz de Riesgo

Resumen

Endpoint

Autenticación

Parámetros de Ruta

Parámetros de Consulta

Respuesta

Ejemplos

Consulta Básica

Con Paginación

Ejemplo de Respuesta

Respuestas de Error

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Panel de Inventario de Dispositivos

Detección de Fraude

Análisis Geográfico

Monitoreo de Actividad

Mejores Prácticas de Paginación

Iterar a Través de Todas las Páginas

Próximos Pasos