Listar dispositivos de uma entidade

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 uma entidade

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

Visão Geral

Recupera todos os dispositivos registrados para uma entidade específica, ordenados por última atividade. Use este endpoint para monitorar padrões de uso de dispositivos, detectar acessos suspeitos e construir regras de detecção de fraude baseadas em dispositivos.

Endpoint

GET 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 cujos dispositivos você deseja recuperar

Parâmetros de Consulta

limit

number

default:"50"

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

offset

number

default:"0"

Número de dispositivos a pular para paginaçãoExemplo: ?offset=50

Resposta

success

boolean

Indica se a requisição foi bem-sucedida

devices

array

Array de objetos de dispositivos ordenados por lastSeenAt (mais recente primeiro)

devices[].id

string

UUID interno do dispositivo no gu1

devices[].deviceId

string

Identificador do dispositivo

devices[].externalId

string

Identificador externo do dispositivo

devices[].entityId

string

UUID da entidade associada

devices[].entityExternalId

string

ID externo da entidade (desnormalizado)

devices[].entityTaxId

string

Tax ID da entidade (desnormalizado)

devices[].deviceName

string

Nome do dispositivo definido pelo usuário ou nome do hardware

devices[].deviceDetails

object

Metadados adicionais do dispositivo (objeto JSON). Detalhes por plataforma.

devices[].platform

string

Plataforma do dispositivo (android, ios, web)

devices[].manufacturer

string

Fabricante do dispositivo

devices[].model

string

Modelo do dispositivo

devices[].brand

string

Marca do dispositivo

devices[].osName

string

Nome do sistema operacional

devices[].osVersion

string

Versão do sistema operacional

devices[].browser

string

Nome do navegador (somente web)

devices[].browserVersion

string

Versão do navegador (somente web)

devices[].latitude

number

Latitude geográfica

devices[].longitude

number

Longitude geográfica

devices[].city

string

Nome da cidade

devices[].region

string

Estado/província

devices[].country

string

Nome do país

devices[].countryCode

string

Código do país ISO

devices[].ipAddress

string

Último endereço IP conhecido

devices[].isEmulator

boolean

Se o dispositivo é um emulador

devices[].isRooted

boolean

Se o dispositivo tem root/jailbreak

devices[].isBlocked

boolean

Se o dispositivo está bloqueado

devices[].isTrusted

boolean

Se o dispositivo é confiável

devices[].firstSeenAt

string

Timestamp da primeira vez visto (ISO 8601)

devices[].lastSeenAt

string

Timestamp da última vez visto (ISO 8601)

devices[].createdAt

string

Timestamp de criação

devices[].updatedAt

string

Timestamp da última atualização

pagination

object

Informações de paginação

pagination.total

number

Número total de dispositivos desta entidade

pagination.limit

number

Limite de tamanho de página usado

pagination.offset

number

Offset usado

pagination.hasMore

boolean

Se há mais páginas disponíveis

Exemplos

Consulta Básica

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

Com Paginação

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

Exemplo de Resposta

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

Respostas de Erro

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

Dashboard de Inventário de Dispositivos

Construa um dashboard mostrando todos os dispositivos usados por suas 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('Devices by platform:', byPlatform);
  return data.devices;
}

Detecção de Fraude

Detecte padrões suspeitos de dispositivos:

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();

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

  if (suspicious.length > 0) {
    console.warn('Found suspicious devices:', suspicious);
  }

  return suspicious;
}

Análise Geográfica

Analise localizações de dispositivos para anomalias:

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();

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

  // Sinalizar se dispositivos de múltiplos países
  if (countries.size > 1) {
    console.warn('Devices from multiple countries:', Array.from(countries));
  }

  return Array.from(countries);
}

Monitoramento de Atividade

Monitore atividade recente 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 ativos nas últimas N horas
  const recentDevices = data.devices.filter(device =>
    new Date(device.lastSeenAt) > cutoff
  );

  console.log(`${recentDevices.length} devices active in last ${hours} hours`);
  return recentDevices;
}

Melhores Práticas de Paginação

Iterar Através de Todas as 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 devices: ${allDevices.length}`);
  return allDevices;
}

Próximos Passos

Criar Dispositivo

Registrar um novo dispositivo

API de Eventos

Aprenda sobre registro automático de dispositivos

Detecção de Fraude

Construa regras de fraude baseadas em dispositivos

Matriz de Risco

Configure pontuação de risco com dados de dispositivos

Registrar um dispositivo para uma entidade Visão geral da API de eventos de usuário

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Caminho

​Parâmetros de Consulta

​Resposta

​Exemplos

​Consulta Básica

​Com Paginação

​Exemplo de Resposta

​Respostas de Erro

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Dashboard de Inventário de Dispositivos

​Detecção de Fraude

​Análise Geográfica

​Monitoramento de Atividade

​Melhores Práticas de Paginação

​Iterar Através de Todas as Páginas

​Próximos Passos

Criar Dispositivo

API de Eventos

Detecção de Fraude

Matriz de Risco

Visão Geral

Endpoint

Autenticação

Parâmetros de Caminho

Parâmetros de Consulta

Resposta

Exemplos

Consulta Básica

Com Paginação

Exemplo de Resposta

Respostas de Erro

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Dashboard de Inventário de Dispositivos

Detecção de Fraude

Análise Geográfica

Monitoramento de Atividade

Melhores Práticas de Paginação

Iterar Através de Todas as Páginas

Próximos Passos