Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

API de reclamación

Reclama dispositivos licenciados en tu organización desde un programa, consulta su propiedad y libéralos, con cada código de rechazo explicado.

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:

  1. El dispositivo está conectado a internet con su conexión a la nube activada.
  2. 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.
  3. 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étodoRutaPermisoFunción
POST/api/iot/claimiot_provisioning.claimReclamar un dispositivo, o comprobarlo con una simulación
GET/api/iot/devices/{deviceId}/ownershipiot_provisioning.claimProcedencia de un dispositivo, su certificado y su ajuste de liberación
PATCH/api/iot/devices/{deviceId}/ownershipiot_provisioning.releasePermitir o impedir la liberación desde la página propia del dispositivo
POST/api/iot/claim/release/{deviceId}iot_provisioning.releaseDevolver 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

CampoRegla
serialObligatorio. De 6 a 32 letras, dígitos y guiones; no distingue mayúsculas de minúsculas
secretObligatorio. 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
nameOpcional, de 1 a 128 caracteres. Por defecto: el número de serie
iotAssetIdOpcional. El emplazamiento o activo donde colocar el dispositivo
dryRunOpcional. 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

EstadostatusSignificado
201claimedEl dispositivo ya es tuyo
200claimed con alreadyOwned: trueTu organización ya lo posee; no ha cambiado nada
200claimableLa simulación ha sido correcta; la respuesta contiene serial, model, type y hw
200in_progressHay una reclamación de este dispositivo en curso ahora mismo; consulta la lista de dispositivos en unos instantes

Otros campos de una reclamación:

CampoSignificado
name, renamedEl 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
recreatedtrue cuando tu organización era propietaria del dispositivo pero su registro había sido eliminado; se ha vuelto a crear
placementSolo 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.reasonEstadocodeMensajeQué hacer
not_claimable409CONFLICTEste 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_button409CONFLICTAbre 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_secret400VALIDATION_ERROREl 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_limited429RATE_LIMIT_EXCEEDEDDemasiados intentos. Inténtalo más tarde.Espera; consulta los límites de intentos más abajo
device_limit403FEATURE_NOT_AVAILABLESe 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 porLímite por hora
Número de serie5 códigos de reclamación incorrectos
Miembro20 intentos fallidos (para una clave: el titular de la clave)
Dirección de origen30 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.

Estadodetails.reasonSignificado
400confirm_mismatch«Escribe el número de serie del dispositivo exactamente para confirmar.»
404not_from_pool«Este dispositivo no se añadió desde el pool de fábrica.»
409still_referencedAlgo 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