> ## 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.

# Listar dispositivos de uma entidade

> Obter todos os dispositivos de uma entidade — para fingerprinting de dispositivos e prevenção de fraude na gu1, com exemplos para list.

## 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:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Parâmetros de Caminho

<ParamField path="entityId" type="string" required>
  UUID da entidade cujos dispositivos você deseja recuperar
</ParamField>

## Parâmetros de Consulta

<ParamField query="limit" type="number" default="50">
  Número máximo de dispositivos a retornar por página (máx: 1000)

  Exemplo: `?limit=100`
</ParamField>

<ParamField query="offset" type="number" default="0">
  Número de dispositivos a pular para paginação

  Exemplo: `?offset=50`
</ParamField>

## Resposta

<ResponseField name="success" type="boolean">
  Indica se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="devices" type="array">
  Array de objetos de dispositivos ordenados por `lastSeenAt` (mais recente primeiro)

  <ResponseField name="devices[].id" type="string">
    UUID interno do dispositivo no gu1
  </ResponseField>

  <ResponseField name="devices[].deviceId" type="string">
    Identificador do dispositivo
  </ResponseField>

  <ResponseField name="devices[].externalId" type="string">
    Identificador externo do dispositivo
  </ResponseField>

  <ResponseField name="devices[].entityId" type="string">
    UUID da entidade associada
  </ResponseField>

  <ResponseField name="devices[].entityExternalId" type="string">
    ID externo da entidade (desnormalizado)
  </ResponseField>

  <ResponseField name="devices[].entityTaxId" type="string">
    Tax ID da entidade (desnormalizado)
  </ResponseField>

  <ResponseField name="devices[].deviceName" type="string">
    Nome do dispositivo definido pelo usuário ou nome do hardware
  </ResponseField>

  <ResponseField name="devices[].deviceDetails" type="object">
    Metadados adicionais do dispositivo (objeto JSON). Detalhes por plataforma.
  </ResponseField>

  <ResponseField name="devices[].platform" type="string">
    Plataforma do dispositivo (android, ios, web)
  </ResponseField>

  <ResponseField name="devices[].manufacturer" type="string">
    Fabricante do dispositivo
  </ResponseField>

  <ResponseField name="devices[].model" type="string">
    Modelo do dispositivo
  </ResponseField>

  <ResponseField name="devices[].brand" type="string">
    Marca do dispositivo
  </ResponseField>

  <ResponseField name="devices[].osName" type="string">
    Nome do sistema operacional
  </ResponseField>

  <ResponseField name="devices[].osVersion" type="string">
    Versão do sistema operacional
  </ResponseField>

  <ResponseField name="devices[].browser" type="string">
    Nome do navegador (somente web)
  </ResponseField>

  <ResponseField name="devices[].browserVersion" type="string">
    Versão do navegador (somente web)
  </ResponseField>

  <ResponseField name="devices[].latitude" type="number">
    Latitude geográfica
  </ResponseField>

  <ResponseField name="devices[].longitude" type="number">
    Longitude geográfica
  </ResponseField>

  <ResponseField name="devices[].city" type="string">
    Nome da cidade
  </ResponseField>

  <ResponseField name="devices[].region" type="string">
    Estado/província
  </ResponseField>

  <ResponseField name="devices[].country" type="string">
    Nome do país
  </ResponseField>

  <ResponseField name="devices[].countryCode" type="string">
    Código do país ISO
  </ResponseField>

  <ResponseField name="devices[].ipAddress" type="string">
    Último endereço IP conhecido
  </ResponseField>

  <ResponseField name="devices[].isEmulator" type="boolean">
    Se o dispositivo é um emulador
  </ResponseField>

  <ResponseField name="devices[].isRooted" type="boolean">
    Se o dispositivo tem root/jailbreak
  </ResponseField>

  <ResponseField name="devices[].isBlocked" type="boolean">
    Se o dispositivo está bloqueado
  </ResponseField>

  <ResponseField name="devices[].isTrusted" type="boolean">
    Se o dispositivo é confiável
  </ResponseField>

  <ResponseField name="devices[].firstSeenAt" type="string">
    Timestamp da primeira vez visto (ISO 8601)
  </ResponseField>

  <ResponseField name="devices[].lastSeenAt" type="string">
    Timestamp da última vez visto (ISO 8601)
  </ResponseField>

  <ResponseField name="devices[].createdAt" type="string">
    Timestamp de criação
  </ResponseField>

  <ResponseField name="devices[].updatedAt" type="string">
    Timestamp da última atualização
  </ResponseField>
</ResponseField>

<ResponseField name="pagination" type="object">
  Informações de paginação

  <ResponseField name="pagination.total" type="number">
    Número total de dispositivos desta entidade
  </ResponseField>

  <ResponseField name="pagination.limit" type="number">
    Limite de tamanho de página usado
  </ResponseField>

  <ResponseField name="pagination.offset" type="number">
    Offset usado
  </ResponseField>

  <ResponseField name="pagination.hasMore" type="boolean">
    Se há mais páginas disponíveis
  </ResponseField>
</ResponseField>

## Exemplos

### Consulta Básica

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(data.devices);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY'
      }
  )

  data = response.json()
  print(data['devices'])
  ```
</CodeGroup>

### Com Paginação

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000?limit=20&offset=0" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000?limit=20&offset=0',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(`Page 1 of ${Math.ceil(data.pagination.total / 20)} pages`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'limit': 20, 'offset': 0}
  )

  data = response.json()
  print(f"Page 1 of {data['pagination']['total'] // 20 + 1} pages")
  ```
</CodeGroup>

## Exemplo de Resposta

```json theme={null}
{
  "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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to read devices"
  }
}
```

### 404 Not Found

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

### 500 Internal Server Error

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Criar Dispositivo" icon="plus" href="/pt/api-reference/devices/create">
    Registrar um novo dispositivo
  </Card>

  <Card title="API de Eventos" icon="bolt" href="/pt/api-reference/events/overview">
    Aprenda sobre registro automático de dispositivos
  </Card>

  <Card title="Detecção de Fraude" icon="shield-check" href="/pt/use-cases/transaction-monitoring/fraud-detection">
    Construa regras de fraude baseadas em dispositivos
  </Card>

  <Card title="Matriz de Risco" icon="table-cells" href="/pt/api-reference/risk-matrix/list">
    Configure pontuação de risco com dados de dispositivos
  </Card>
</CardGroup>