Esta página es para integradores que añaden routers, pasarelas y controladores licenciados a una organización desde sus propias herramientas, por ejemplo una aplicación de instalador o un script de puesta en marcha. Los pasos en la aplicación están en Adding and claiming devices; cómo se protege la reclamación está en Device identity and claiming security.
Las rutas están bajo https://<your host>/tenant/<tenantId>. Las convenciones están en REST API basics.
Antes de llamar
Un dispositivo licenciado solo puede reclamarse mientras alguien esté junto a él:
- El dispositivo está conectado a internet con su conexión a la nube activada.
- Alguien abre la ventana de reclamación en la página Cloud del propio dispositivo. La ventana permanece abierta como máximo 15 minutos y se cierra tras una reclamación correcta.
- Su programa envía el número de serie y el código de reclamación del dispositivo mientras la ventana está abierta.
No existe ninguna ruta para abrir la ventana de reclamación: se abre únicamente en el dispositivo.
Rutas
| Método | Ruta | Permiso | Función |
|---|---|---|---|
| POST | /api/iot/claim | iot_provisioning.claim | Reclamar un dispositivo, o comprobarlo con una simulación |
| GET | /api/iot/devices/{deviceId}/ownership | iot_provisioning.claim | Procedencia de un dispositivo, su certificado y su ajuste de liberación |
| PATCH | /api/iot/devices/{deviceId}/ownership | iot_provisioning.release | Permitir o impedir la liberación desde la página propia del dispositivo |
| POST | /api/iot/claim/release/{deviceId} | iot_provisioning.release | Devolver un dispositivo al pool de fábrica |
Los cuatro son permisos de administrador por defecto. Colocar el dispositivo reclamado en un emplazamiento o activo en la misma llamada requiere también iot_asset.relations.manage en la clave.
Reclamar un dispositivo
POST /api/iot/claim
| Campo | Regla |
|---|---|
serial | Obligatorio. De 6 a 32 letras, dígitos y guiones; no distingue mayúsculas de minúsculas |
secret | Obligatorio. El código de reclamación de 20 caracteres de la página Cloud del dispositivo. Los guiones, espacios y mayúsculas se ignoran; O se lee como 0, e I y L como 1 |
name | Opcional, de 1 a 128 caracteres. Por defecto: el número de serie |
iotAssetId | Opcional. El emplazamiento o activo donde colocar el dispositivo |
dryRun | Opcional. true comprueba todo y no reclama nada |
El cuerpo es estricto: un campo desconocido produce un 400. El código de reclamación nunca se devuelve.
curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/claim' \
-H 'Authorization: Bearer sk_live_…' \
-H 'Content-Type: application/json' \
-d '{"serial":"RT420-2610-000123","secret":"7KQ2-M9XH-D4TB-6WRA-1NZC","name":"Pump house router","iotAssetId":"8d0e…"}'
{
"status": "claimed",
"serial": "RT420-2610-000123",
"deviceId": "6f1c…",
"model": "…",
"profileId": "a1b2…",
"name": "Pump house router",
"renamed": false,
"placement": "placed"
}
Respuestas
| Estado | status | Significado |
|---|---|---|
| 201 | claimed | El dispositivo ya es tuyo |
| 200 | claimed con alreadyOwned: true | Tu organización ya lo posee; no ha cambiado nada |
| 200 | claimable | La simulación ha sido correcta; la respuesta contiene serial, model, type y hw |
| 200 | in_progress | Hay una reclamación de este dispositivo en curso ahora mismo; consulta la lista de dispositivos en unos instantes |
Otros campos de una reclamación:
| Campo | Significado |
|---|---|
name, renamed | El nombre del dispositivo. Si ya existe un dispositivo con ese nombre, se añade un número (Pump house router (2)) y renamed es true |
recreated | true cuando tu organización era propietaria del dispositivo pero su registro había sido eliminado; se ha vuelto a crear |
placement | Solo si enviaste iotAssetId: placed, not_permitted (la clave no tiene iot_asset.relations.manage), unavailable (los emplazamientos y activos están desactivados) o failed. La reclamación se mantiene en todos los casos |
Un dispositivo reclamado recibe una copia del perfil de dispositivo de su modelo y su certificado de fábrica como credencial X.509, y se reconecta a tu organización en segundos. Se envía un evento de webhook iot.device.claimed (véase Webhook event reference).
Rechazos
Cada rechazo incluye uno de cinco códigos en details.reason. Ramifica según él, no según el mensaje.
details.reason | Estado | code | Mensaje | Qué hacer |
|---|---|---|---|---|
not_claimable | 409 | CONFLICT | Este dispositivo no se puede añadir. Comprueba el número de serie; si es correcto, el dispositivo pertenece a otra cuenta: pide al vendedor que lo libere. | Comprueba el número de serie. Un número desconocido, un dispositivo retirado y un dispositivo de otra organización responden todos esto; nunca se indica el propietario |
press_claim_button | 409 | CONFLICT | Abre la ventana de reclamación en la página Cloud del dispositivo (permanece abierta 15 minutos) y vuelve a intentarlo. | Abre la ventana en el dispositivo y reintenta |
bad_secret | 400 | VALIDATION_ERROR | El número de serie o el código de reclamación no son correctos. | Vuelve a leer el código en la página Cloud |
rate_limited | 429 | RATE_LIMIT_EXCEEDED | Demasiados intentos. Inténtalo más tarde. | Espera; consulta los límites de intentos más abajo |
device_limit | 403 | FEATURE_NOT_AVAILABLE | Se ha alcanzado el límite de dispositivos de esta cuenta. | Elimina un dispositivo o cambia el plan |
Mientras la ventana de reclamación está cerrada, el código de reclamación no se comprueba en absoluto, así que una ventana cerrada nunca indica si un código era correcto. El límite de dispositivos se comprueba al final, antes de crear nada.
Límites de intentos
Los intentos fallidos (un número de serie desconocido, una ventana de reclamación cerrada, un código incorrecto) se cuentan en una hora deslizante. Cuando uno de estos límites se llena, los intentos que cubre responden rate_limited:
| Contado por | Límite por hora |
|---|---|
| Número de serie | 5 códigos de reclamación incorrectos |
| Miembro | 20 intentos fallidos (para una clave: el titular de la clave) |
| Dirección de origen | 30 intentos fallidos |
Una simulación ejecuta las mismas comprobaciones, y una simulación fallida cuenta como una reclamación fallida. No pruebes códigos en bucle: cinco códigos incorrectos bloquean el número de serie durante la hora.
Propiedad
GET /api/iot/devices/{deviceId}/ownership responde { ownership, capabilities }. Para un dispositivo reclamado, ownership tiene fromPool: true, serial, model, claimedAt, claimedByUserId, certificate (status, notAfter), allowDeviceRelease y blockers (lo que aún hace referencia al dispositivo). Un dispositivo creado en tu organización responde fromPool: false. El nombre de quien reclamó (claimedBy) requiere un permiso de miembro que las claves nunca tienen, así que una clave solo recibe el id.
PATCH con { "allowDeviceRelease": false } impide que nadie libere el dispositivo con el botón de su propia página Cloud. El valor por defecto es true.
Liberar un dispositivo
POST /api/iot/claim/release/{deviceId} con { "confirmSerial": "RT420-2610-000123", "reason": "Returned to supplier" } (reason hasta 500 caracteres) devuelve el dispositivo al pool de fábrica. La respuesta es 200 { serial, unitStatus, certificateKept }. Sus datos permanecen en tu organización; el siguiente propietario debe estar junto al dispositivo para reclamarlo. Se envía un evento de webhook iot.device.released.
| Estado | details.reason | Significado |
|---|---|---|
| 400 | confirm_mismatch | «Escribe el número de serie del dispositivo exactamente para confirmar.» |
| 404 | not_from_pool | «Este dispositivo no se añadió desde el pool de fábrica.» |
| 409 | still_referenced | Algo todavía hace referencia al dispositivo, por ejemplo un emplazamiento o activo donde está colocado; details.moduleId y details.count indican qué es. Elimínalo primero |

