Desarrolladores
Construya sobre Hermetry
Conecte dispositivos por MQTT o HTTPS, trabaje con su organización a través de la API REST, reaccione a eventos con webhooks firmados y permita que los asistentes de IA lean sus datos mediante MCP.
Cuatro vías de acceso
Una plataforma, cuatro interfaces
Los dispositivos usan la API de dispositivo. Sus sistemas usan la API REST y los webhooks. Los asistentes de IA usan MCP. Nunca coloque una clave de API en un dispositivo ni un token de dispositivo en una integración.
API de dispositivo
Los dispositivos envían datos y reciben comandos por MQTT o HTTPS. Inician sesión con un token de dispositivo, un nombre de usuario y contraseña de MQTT, o un certificado.
API REST
Su ERP, MES, sistema de tickets o script llama a Hermetry con una clave de API que solo tiene los permisos que usted elige.
Webhooks
Hermetry llama a su sistema cuando ocurre algo: un dispositivo que se desconecta, una alarma que se abre, un comando que termina.
Servidores MCP
Un asistente de IA que admite MCP llama a las herramientas de Hermetry con una clave de API o un inicio de sesión, y nunca puede hacer más de lo que puede hacer esa persona.
API de dispositivo
Envíe su primera lectura
Por MQTT, el dispositivo mantiene una conexión abierta. Por HTTPS, envía una petición por mensaje. Las cargas útiles son las mismas.
MQTT
- MQTT 3.1.1, TLS en el puerto 8883 (TLS 1.2 o posterior), al host indicado en la tarjeta Detalles de conexión del dispositivo
- Nombre de usuario: el token de acceso del dispositivo, contraseña vacía
- Los temas empiezan por
v1/; use QoS 1 - Una lectura es un objeto JSON plano, o
tsyvaluescuando el dispositivo conoce la hora
CONNECT port 8883 (TLS)
username: <device access token>, password: empty
SUBSCRIBE v1/attributes/set (QoS 1)
SUBSCRIBE v1/attributes/res/+ (QoS 1)
SUBSCRIBE v1/rpc/req/+ (QoS 1)
PUBLISH v1/attributes/req/1 {}
PUBLISH v1/telemetry {"temperature": 21.5, "humidity": 40}
{"temperature": 21.5, "humidity": 40, "door_open": false}
{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}
HTTPS
- Un POST por mensaje, con el token en una cabecera
Authorization: Bearer - Las mismas formas de carga útil y reglas de claves que en MQTT, hasta 64 KiB
- Los comandos esperan en un long poll de hasta 60 segundos
- Los dispositivos con batería que despiertan, envían y vuelven a dormir encajan mejor
curl -X POST 'https://<your-host>/api/v1/telemetry' \
-H 'Authorization: Bearer <device access token>' \
-H 'Content-Type: application/json' \
-d '{"ts":1759572000000,"values":{"temperature":21.5,"humidity":40}}'
curl -X GET 'https://<your-host>/api/v1/rpc?timeout=20000' \
-H 'Authorization: Bearer <device access token>'
API REST
Llame a la API con una clave con alcance limitado
Una clave de API actúa como el miembro que la creó, limitada a los permisos que marque para ella. No hay intercambio de tokens: la clave se envía en cada llamada.
- Las claves tienen el formato
sk_live_…y se muestran una sola vez - Los permisos se eligen módulo a módulo, nunca más de los que usted tiene
- Cada clave caduca: 90 días por defecto, como máximo un año
- Una lista de IP permitidas de hasta 100 subredes limita desde dónde funciona una clave
- Las rutas cuelgan de su organización:
/tenant/<tenantId>/api/…
curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
-H "Authorization: Bearer sk_live_…"
GET /tenant/{tenantId}/api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity
Webhooks
Reaccione a eventos y compruebe que vienen de nosotros
Cada entrega es un POST con el evento en el cuerpo y una firma en las cabeceras. Verifique X-Webhook-Signature-V2 con su secreto de firma antes de confiar en el cuerpo.
- Solo direcciones HTTPS, con hasta 20 cabeceras personalizadas propias
- Los filtros de eventos entregan solo los eventos cuya carga útil coincide
- El mismo id
X-Webhook-Deliveryen cada reintento, para que pueda descartar duplicados - CloudEvents 1.0 en lugar del envoltorio por defecto, si lo prefiere
{
"webhookId": "…",
"tenantId": "…",
"event": "device.disconnected",
"createdAt": "2026-11-03T12:00:30.000Z",
"data": { "deviceId": "…", "name": "router-17", "reason": "timeout" }
}
import crypto from 'crypto';
function verifyWebhook(body: string, timestamp: string, signatureV2: string, secret: string): boolean {
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
// Reject deliveries older than 5 minutes.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const a = Buffer.from(expected);
const b = Buffer.from(signatureV2);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Límites
Límites que conviene prever
Un límite responde 429 con una cabecera Retry-After. Espere ese tiempo, retroceda en las repeticiones y nunca reintente sin cambios un 400, 401, 403, 404 o 422.
| Límite | Valor por defecto | Se aplica a |
|---|---|---|
| Límite por dirección | 120 peticiones por minuto | Cada dirección IP que llama |
| Límite por clave | 1.000 llamadas por minuto | Cada clave de API |
| Comandos | 10 por minuto por dispositivo, 600 por minuto por organización | Comandos a dispositivos |
| Herramientas MCP | 120 llamadas de lectura y 20 de escritura por minuto | Cada credencial |
| Cuerpo HTTP de dispositivo | Hasta 64 KiB | Cada mensaje de dispositivo |
Asistentes de IA
Conecte un asistente de IA por MCP
Cada módulo tiene su propio servidor MCP bajo la dirección de su espacio de trabajo. MCP está desactivado hasta que un administrador lo active, y un asistente solo ve las herramientas que su persona puede usar.
- Dispositivos, lecturas y paneles: solo lectura
- Alarmas: reconocer una de inmediato; borrar una requiere que lo haga una segunda persona
- Las respuestas se limitan a 10 segundos y 256 KiB
- Las credenciales, tokens y claves de dispositivo nunca se devuelven
https://<your host>/tenant/<tenantId>/api/mcp/iot_device
https://<your host>/tenant/<tenantId>/api/mcp/telemetry
https://<your host>/tenant/<tenantId>/api/mcp/iot_alarm
https://<your host>/tenant/<tenantId>/api/mcp/dashboard
Escalar y ampliar
Cuando un dispositivo se convierte en mil
Importar desde CSV
Añada cientos de dispositivos desde un archivo. Cada importación se comprueba primero, se aplica tras la revisión y puede deshacerse.
Reclamación y aprovisionamiento
Dispositivos reclamados con un código, o registrados en la primera conexión mediante una sesión de aprovisionamiento.
Firmware firmado en oleadas
Usted firma las imágenes en su propio pipeline y registra solo claves públicas. Los despliegues salen en oleadas.
Sus propios códecs
Decodifique un sensor LoRaWAN que la biblioteca no cubre con un códec que publique: una tabla JSON, nunca un script.
Bloque de script
Cuando los bloques listos de un flujo no bastan, ejecute su propio JavaScript en cada mensaje.
Sus propios widgets
Guarde una tarjeta configurada como widget, o cree widgets a partir de una plantilla HTML con su propio formulario de ajustes.
Referencia
Referencia de la API
Empiece a construir en Hermetry
Cree una organización, añada un dispositivo y haga su primera llamada a la API.

