> ## 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 un dispositivo para una entidad

> Registrar un dispositivo para una entidad — para fingerprinting de dispositivos y prevención de fraude en gu1, con ejemplos para create.

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

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

## Endpoint

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

## Autenticación

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

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

## Parámetros de Ruta

<ParamField path="entityId" type="string" required>
  UUID de la entidad a la que se asociará este dispositivo
</ParamField>

## Cuerpo de la Solicitud

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

<ParamField body="entityType" type="string">
  Tipo de entidad para auditoría. Opciones: `person`, `company`. Por defecto: `"person"`
</ParamField>

<ParamField body="entityExternalId" type="string">
  ID externo de la entidad (identificador de tu sistema). Se guarda desnormalizado en el dispositivo para consultas.
</ParamField>

<ParamField body="entityTaxId" type="string">
  Tax ID de la entidad (ej., CUIT, CPF). Se guarda desnormalizado en el dispositivo para consultas.
</ParamField>

<ParamField body="platform" type="string">
  Plataforma del dispositivo. Opciones:

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

  Ejemplo: `"android"`
</ParamField>

<ParamField body="manufacturer" type="string">
  Nombre del fabricante del dispositivo (ej., "samsung", "Apple", "Google")
</ParamField>

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

<ParamField body="brand" type="string">
  Nombre de la marca del dispositivo (ej., "samsung", "Apple")
</ParamField>

<ParamField body="deviceName" type="string">
  Nombre del dispositivo definido por el usuario o nombre del hardware
</ParamField>

<ParamField body="osVersion" type="string">
  Versión del sistema operativo (ej., "Android 16", "iOS 17.2", "Windows 11")
</ParamField>

<ParamField body="systemName" type="string">
  Nombre del sistema para dispositivos iOS (ej., "iOS")
</ParamField>

<ParamField body="systemVersion" type="string">
  Versión del sistema para dispositivos iOS (ej., "17.2")
</ParamField>

<ParamField body="browser" type="string">
  Nombre del navegador para plataforma web (ej., "Chrome", "Safari", "Firefox")
</ParamField>

<ParamField body="browserVersion" type="string">
  Versión del navegador para plataforma web (ej., "120.0.6099.129")
</ParamField>

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

  Ejemplo: `-34.6037`
</ParamField>

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

  Ejemplo: `-58.3816`
</ParamField>

<ParamField body="city" type="string">
  Nombre de la ciudad (ej., "Buenos Aires", "Nueva York", "Londres")
</ParamField>

<ParamField body="region" type="string">
  Estado o provincia (ej., "Buenos Aires", "California", "Ontario")
</ParamField>

<ParamField body="country" type="string">
  Nombre del país (ej., "Argentina", "Estados Unidos", "Canadá")
</ParamField>

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

<ParamField body="ipAddress" type="string">
  Dirección IP (IPv4 o IPv6) desde la cual el dispositivo está accediendo

  Ejemplo: `"10.40.64.231"`
</ParamField>

<ParamField body="isEmulator" type="boolean" default="false">
  Si este dispositivo está detectado como un emulador o simulador
</ParamField>

<ParamField body="isRooted" type="boolean" default="false">
  Si este dispositivo está rooteado (Android) o jailbreakeado (iOS)
</ParamField>

## Respuesta

<ResponseField name="success" type="boolean">
  Indica si la solicitud fue exitosa
</ResponseField>

<ResponseField name="device" type="object">
  El objeto del dispositivo creado

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

  <ResponseField name="device.deviceId" type="string">
    Tu identificador de dispositivo proporcionado
  </ResponseField>

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

  <ResponseField name="device.entityId" type="string">
    UUID de la entidad asociada
  </ResponseField>

  <ResponseField name="device.entityExternalId" type="string">
    ID externo de la entidad (desnormalizado)
  </ResponseField>

  <ResponseField name="device.entityTaxId" type="string">
    Tax ID de la entidad (desnormalizado)
  </ResponseField>

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

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

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

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

  <ResponseField name="device.deviceName" type="string">
    Nombre del dispositivo definido por el usuario o nombre del hardware
  </ResponseField>

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

  <ResponseField name="device.osName" type="string">
    Nombre del sistema operativo
  </ResponseField>

  <ResponseField name="device.osVersion" type="string">
    Versión del sistema operativo
  </ResponseField>

  <ResponseField name="device.browser" type="string">
    Nombre del navegador (solo web)
  </ResponseField>

  <ResponseField name="device.browserVersion" type="string">
    Versión del navegador (solo web)
  </ResponseField>

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

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

  <ResponseField name="device.city" type="string">
    Nombre de la ciudad
  </ResponseField>

  <ResponseField name="device.region" type="string">
    Estado/provincia
  </ResponseField>

  <ResponseField name="device.country" type="string">
    Nombre del país
  </ResponseField>

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

  <ResponseField name="device.ipAddress" type="string">
    Dirección IP
  </ResponseField>

  <ResponseField name="device.isEmulator" type="boolean">
    Bandera de detección de emulador
  </ResponseField>

  <ResponseField name="device.isRooted" type="boolean">
    Bandera de detección de root/jailbreak
  </ResponseField>

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

  <ResponseField name="device.isTrusted" type="boolean">
    Si el dispositivo está marcado como confiable
  </ResponseField>

  <ResponseField name="device.firstSeenAt" type="string">
    Primera vez que se vio el dispositivo (marca de tiempo ISO 8601)
  </ResponseField>

  <ResponseField name="device.lastSeenAt" type="string">
    Última vez que se vio el dispositivo (marca de tiempo ISO 8601)
  </ResponseField>

  <ResponseField name="device.createdAt" type="string">
    Marca de tiempo de creación del registro del dispositivo
  </ResponseField>

  <ResponseField name="device.updatedAt" type="string">
    Marca de tiempo de última actualización del registro del dispositivo
  </ResponseField>
</ResponseField>

## Ejemplos

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

## Ejemplo de Respuesta

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

## Respuestas de Error

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

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

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

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

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

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

  <Card title="API de Eventos" icon="bolt" href="/es/api-reference/events/create">
    Auto-registrar dispositivos vía eventos
  </Card>
</CardGroup>