Importación masiva

La importación masiva provisiona un lote de fábrica completo de una sola vez. Subes un CSV de hardware IDs y asignaciones de profile; la plataforma valida cada fila, crea los registros de provisioning y te devuelve un manifest cifrado de un solo uso con las keys generadas para enviarlo a la fábrica. Cada dispositivo se conecta luego por su cuenta vía el flujo de key claim.

Esta es la ruta para cientos o miles de dispositivos. Para un solo dispositivo, usa registro manual.

El flujo de un vistazo

1. Prepara un CSV del lote — una fila por dispositivo.
2. Súbelo como admin del tenant. Cada fila se valida de forma independiente.
3. Revisa el resultado — registros creados, más un informe por fila de cualquier fallo y duplicado.
4. Descarga el manifest cifrado de las provisioning keys generadas (mostrado una vez).
5. Distribuye el manifest a la fábrica; las keys se graban en los dispositivos.
6. Los dispositivos reclaman su identidad en el primer arranque según el flujo de key claim.

Formato CSV

Una fila por dispositivo. La fila de cabecera nombra las columnas; el orden no importa.

Columna	Obligatorio	Descripción
hardware_id	sí	Identificador de hardware estable; único dentro del tenant
profile_id	sí	Device profile que hereda el dispositivo
name	no	Nombre legible del dispositivo
groups	no	Nombres de grupos; separa varios con ;
tags	no	Pares key=value; separa varios con ;

hardware_id,profile_id,name,groups,tags
AA:BB:CC:00:11:01,p_temp_sensor_v2,Cold Store Sensor 001,cold-store;floor-1,region=eu;line=A
AA:BB:CC:00:11:02,p_temp_sensor_v2,Cold Store Sensor 002,cold-store;floor-1,region=eu;line=A
AA:BB:CC:00:11:03,p_temp_sensor_v2,Cold Store Sensor 003,cold-store;floor-2,region=eu;line=B
AA:BB:CC:00:11:04,p_humidity_v1,Humidity Probe 001,cold-store;floor-2,region=eu;line=B

Consejo

Referencia un device profile existente en profile_id y mantén el CSV mínimo. El profile lleva tags, configuración, política de anchoring, esquema de telemetry y la política de credenciales, así que solo necesitas en el CSV las anulaciones por dispositivo.

Validación por fila e importación parcial

Cada fila se valida por su cuenta. Las comprobaciones de validación incluyen:

• hardware_id está presente y bien formado
• profile_id referencia un profile que existe en tu tenant
• hardware_id no está ya ocupado en el tenant (detección de duplicados)

Con la importación parcial habilitada, las filas válidas se importan aunque otras fallen — la importación no aborta en la primera fila errónea. El resultado informa de los desenlaces por fila para que puedas corregir y volver a subir solo los fallos:

{
  "imported": 498,
  "failed": 2,
  "rows": [
    { "row": 312, "hardware_id": "AA:BB:CC:00:12:38", "status": "duplicate", "reason": "hardware_id already exists in tenant" },
    { "row": 457, "hardware_id": "", "status": "invalid", "reason": "hardware_id is required" }
  ]
}

Nota

Los hardware IDs duplicados se informan por fila, no se tratan como un fallo total del lote completo. Volver a subir un CSV que se solapa con una importación previa simplemente informará de las filas solapadas como duplicados e importará el resto — es seguro reintentar.

El manifest de provisioning keys

En caso de éxito, la plataforma genera las provisioning keys del lote y las devuelve como un manifest cifrado de un solo uso. Como todo secreto en bruto en CORE-M, las keys se muestran una vez — solo se almacenan sus hashes SHA-256.

Peligro

El manifest es tu única copia de las provisioning keys en bruto. Descárgalo y guárdalo de forma segura en el momento en que se complete la importación. Si lo pierdes, no puedes recuperar las keys — debes regenerar los registros de provisioning y reimportar. Trata el manifest como material secreto de planta de fábrica: cifrado en tránsito y en reposo, con control de acceso, y bórralo una vez que las keys estén grabadas en los dispositivos.

Distribuye el manifest a tu fábrica o fabricante por contrato a través de un canal seguro. Cada dispositivo recibe su provisioning key grabada durante la fabricación.

Los dispositivos se conectan

Una vez que un dispositivo arranca en el campo con su provisioning key, reclama su identidad exactamente como se describe en el flujo de key claim: llama a POST /api/v1/provision, la plataforma deriva el tenant de la key, crea (o devuelve de forma idempotente) el dispositivo y emite su API key. Desde la perspectiva del dispositivo, la importación masiva es invisible — simplemente reclama y se conecta.

Relacionado

Provisioning por key claim Lo que hace cada dispositivo en el primer arranque tras una importación masiva.

Device profiles El profile referenciado por cada fila del CSV, que lleva los valores por defecto compartidos del lote.

Identidad y credenciales de dispositivo La unicidad de hardware_id y las credenciales que reciben los dispositivos al reclamar.