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

# Registrar um dispositivo para uma entidade

> Registrar um dispositivo para uma entidade — para fingerprinting de dispositivos e prevenção de fraude na gu1, com exemplos para create.

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

<Note>
  **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
</Note>

## Endpoint

```
POST 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 para associar este dispositivo
</ParamField>

## Corpo da Requisição

<ParamField body="deviceId" type="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)
</ParamField>

<ParamField body="entityType" type="string">
  Tipo da entidade para auditoria. Opções: `person`, `company`. Padrão: `"person"`
</ParamField>

<ParamField body="entityExternalId" type="string">
  ID externo da entidade (identificador do seu sistema). Armazenado desnormalizado no dispositivo para consultas.
</ParamField>

<ParamField body="entityTaxId" type="string">
  Tax ID da entidade (ex: CUIT, CPF). Armazenado desnormalizado no dispositivo para consultas.
</ParamField>

<ParamField body="platform" type="string">
  Plataforma do dispositivo. Opções:

  * `android` - Dispositivo Android
  * `ios` - Dispositivo iOS
  * `web` - Navegador web

  Exemplo: `"android"`
</ParamField>

<ParamField body="manufacturer" type="string">
  Nome do fabricante do dispositivo (ex: "samsung", "Apple", "Google")
</ParamField>

<ParamField body="model" type="string">
  Identificador do modelo do dispositivo (ex: "SM-A156M", "iPhone 15 Pro", "Pixel 8")
</ParamField>

<ParamField body="brand" type="string">
  Nome da marca do dispositivo (ex: "samsung", "Apple")
</ParamField>

<ParamField body="deviceName" type="string">
  Nome do dispositivo definido pelo usuário ou nome do hardware
</ParamField>

<ParamField body="osVersion" type="string">
  Versão do sistema operacional (ex: "Android 16", "iOS 17.2", "Windows 11")
</ParamField>

<ParamField body="systemName" type="string">
  Nome do sistema para dispositivos iOS (ex: "iOS")
</ParamField>

<ParamField body="systemVersion" type="string">
  Versão do sistema para dispositivos iOS (ex: "17.2")
</ParamField>

<ParamField body="browser" type="string">
  Nome do navegador para plataforma web (ex: "Chrome", "Safari", "Firefox")
</ParamField>

<ParamField body="browserVersion" type="string">
  Versão do navegador para plataforma web (ex: "120.0.6099.129")
</ParamField>

<ParamField body="latitude" type="number">
  Coordenada de latitude geográfica (-90 a 90)

  Exemplo: `-34.6037`
</ParamField>

<ParamField body="longitude" type="number">
  Coordenada de longitude geográfica (-180 a 180)

  Exemplo: `-58.3816`
</ParamField>

<ParamField body="city" type="string">
  Nome da cidade (ex: "Buenos Aires", "Nova York", "Londres")
</ParamField>

<ParamField body="region" type="string">
  Estado ou província (ex: "Buenos Aires", "Califórnia", "Ontário")
</ParamField>

<ParamField body="country" type="string">
  Nome do país (ex: "Argentina", "Estados Unidos", "Canadá")
</ParamField>

<ParamField body="countryCode" type="string">
  Código de país ISO 3166-1 alpha-2 (ex: "AR", "US", "CA")
</ParamField>

<ParamField body="ipAddress" type="string">
  Endereço IP (IPv4 ou IPv6) de onde o dispositivo está acessando

  Exemplo: `"10.40.64.231"`
</ParamField>

<ParamField body="isEmulator" type="boolean" default="false">
  Se este dispositivo foi detectado como emulador ou simulador
</ParamField>

<ParamField body="isRooted" type="boolean" default="false">
  Se este dispositivo tem root (Android) ou jailbreak (iOS)
</ParamField>

## Resposta

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

<ResponseField name="device" type="object">
  O objeto do dispositivo criado

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

  <ResponseField name="device.deviceId" type="string">
    Seu identificador de dispositivo fornecido
  </ResponseField>

  <ResponseField name="device.externalId" type="string">
    Identificador externo do dispositivo (mesmo que deviceId)
  </ResponseField>

  <ResponseField name="device.entityId" type="string">
    UUID da entidade associada
  </ResponseField>

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

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

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

  <ResponseField name="device.manufacturer" type="string">
    Fabricante do dispositivo
  </ResponseField>

  <ResponseField name="device.model" type="string">
    Modelo do dispositivo
  </ResponseField>

  <ResponseField name="device.brand" type="string">
    Marca do dispositivo
  </ResponseField>

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

  <ResponseField name="device.deviceDetails" type="object">
    Metadados adicionais do dispositivo (objeto JSON). Por plataforma: Android (hardware, buildId, sdkVersion), iOS (systemName, identifierForVendor), Web (userAgent, etc.)
  </ResponseField>

  <ResponseField name="device.osName" type="string">
    Nome do sistema operacional
  </ResponseField>

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

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

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

  <ResponseField name="device.latitude" type="number">
    Latitude geográfica
  </ResponseField>

  <ResponseField name="device.longitude" type="number">
    Longitude geográfica
  </ResponseField>

  <ResponseField name="device.city" type="string">
    Nome da cidade
  </ResponseField>

  <ResponseField name="device.region" type="string">
    Estado/província
  </ResponseField>

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

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

  <ResponseField name="device.ipAddress" type="string">
    Endereço IP
  </ResponseField>

  <ResponseField name="device.isEmulator" type="boolean">
    Flag de detecção de emulador
  </ResponseField>

  <ResponseField name="device.isRooted" type="boolean">
    Flag de detecção de root/jailbreak
  </ResponseField>

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

  <ResponseField name="device.isTrusted" type="boolean">
    Se o dispositivo está marcado como confiável
  </ResponseField>

  <ResponseField name="device.firstSeenAt" type="string">
    Primeira vez que o dispositivo foi visto (timestamp ISO 8601)
  </ResponseField>

  <ResponseField name="device.lastSeenAt" type="string">
    Última vez que o dispositivo foi visto (timestamp ISO 8601)
  </ResponseField>

  <ResponseField name="device.createdAt" type="string">
    Timestamp de criação do registro do dispositivo
  </ResponseField>

  <ResponseField name="device.updatedAt" type="string">
    Timestamp da última atualização do registro do dispositivo
  </ResponseField>
</ResponseField>

## Exemplos

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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'
    })
  });

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

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

  response = requests.post(
      'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          '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'
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Exemplo de Resposta

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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_DEVICE_ID",
    "message": "Device ID is required"
  }
}
```

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

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

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

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

<CardGroup cols={2}>
  <Card title="Listar Dispositivos" icon="list" href="/pt/api-reference/devices/list">
    Consultar dispositivos de uma entidade
  </Card>

  <Card title="API de Eventos" icon="bolt" href="/pt/api-reference/events/create">
    Registrar dispositivos automaticamente via eventos
  </Card>
</CardGroup>