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

API de acceso remoto

Abra, vuelva a entrar, cierre y liste sesiones del panel en routers con licencia reclamados desde un programa, con todas las denegaciones y límites.

Esta página es para integradores que abren el panel web de un router desde sus propias herramientas, por ejemplo una consola de soporte que lleva a un técnico directamente al panel del router de un cliente. Cómo funcionan las sesiones del panel para las personas está en Acceso remoto al panel de un router; los límites y los motivos por los que una sesión termina están en Límites y auditoría del acceso remoto.

Las rutas están bajo https://<your host>/tenant/<tenantId>. Las convenciones están en Fundamentos de la API REST.

Rutas

MétodoRutaPermisoFunción
GET/api/iot/devices/{deviceId}/remote-accessiot_remote_access.panel.openSi se puede abrir una sesión en este router, y sus sesiones abiertas
POST/api/iot/remote-access/sessionsiot_remote_access.panel.openAbrir una sesión del panel
POST/api/iot/remote-access/sessions/{sessionId}iot_remote_access.panel.openUn nuevo enlace de entrada para quien abrió la sesión
DELETE/api/iot/remote-access/sessions/{sessionId}iot_remote_access.panel.openCerrar una sesión
GET/api/iot/remote-access/sessionsiot_remote_access.sessions.readLas sesiones de la organización y el uso de este mes

Ambos permisos son permisos de administrador por defecto. El comando que indica a un router que abra su túnel no se puede enviar a través de la API de comandos (responde 403 rpc_method_reserved); estas rutas son la única vía, de modo que cada sesión se comprueba, se limita y se audita.

A quién pertenece la sesión

Una sesión abierta con una clave se abre como el titular de la clave: la lista de sesiones muestra al titular bajo Abierta por, y el registro de auditoría lo registra. Solo las solicitudes hechas como quien abrió la sesión pueden obtener un enlace de entrada para ella, de modo que el titular también puede volver a entrar desde la aplicación. Cualquier miembro o clave con iot_remote_access.panel.open puede cerrar cualquier sesión de la organización.

La sesión termina cuando el titular abandona la organización o cambian sus accesos, igual que una sesión abierta desde la aplicación. Revocar la clave no cierra las sesiones que ya abrió: ciérrelas con DELETE cuando su programa termine.

Advertencia

El enlace de entrada (openUrl) es una credencial. Quien lo abra primero, dentro de 60 segundos, entra en el panel del router sin iniciar sesión en Hermetry. Entréguelo solo a la persona que lo necesita, por un canal de confianza, y nunca lo escriba en un registro.

Compruebe primero un router

GET /api/iot/devices/{deviceId}/remote-access

{ "configured": true, "available": false, "reason": "offline", "metered": false, "open": [] }

reason es null cuando se puede abrir una sesión; en caso contrario, es uno de not_configured, device_not_found, not_claimed, unsupported, device_not_active, certificate_inactive u offline (los mismos motivos con los que la ruta de apertura rechaza). metered es true cuando el router está en su enlace móvil. open enumera las sesiones abiertas del router.

Abrir una sesión

POST /api/iot/remote-access/sessions

CampoRegla
deviceIdObligatorio. El id de dispositivo del router
targetpanel (el valor por defecto y el único)
confirmtrue para aceptar el límite de datos en un enlace móvil

El cuerpo es estricto: un campo desconocido produce un 400.

En un enlace móvil (LTE), la primera llamada no crea nada y responde 200 { "requiresConfirm": "metered", "capBytes": 52428800 }: cuántos bytes puede mover la sesión antes de cerrarse. Envíe de nuevo el mismo cuerpo con "confirm": true.

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/remote-access/sessions' \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"deviceId":"6f1c…","confirm":true}'

La llamada espera hasta 15 segundos a que el router acepte. Después responde 201:

{
  "sessionId": "dk3v…",
  "openUrl": "https://dk3v….<panel domain>/__open?t=…",
  "expiresAt": "2026-11-17T14:00:00.000Z",
  "metered": false
}

expiresAt es el fin definitivo, 4 horas después de la apertura. El router debe conectar su túnel en 90 segundos, o la sesión termina (no_dial).

Nuevo enlace de entrada

POST /api/iot/remote-access/sessions/{sessionId} (sin cuerpo) responde 200 { "openUrl": "…" } con un enlace nuevo de un solo uso, por ejemplo cuando el primero caducó sin usarse. Solo quien abrió la sesión recibe uno.

Cerrar una sesión

DELETE /api/iot/remote-access/sessions/{sessionId} termina la sesión de inmediato: la pestaña del navegador deja de funcionar en aproximadamente un segundo y al router se le indica que cierre el túnel. La respuesta es 200 { "session": {...} }. Cerrar una sesión que ya terminó responde igual, sin registrar nada dos veces.

Listar sesiones

GET /api/iot/remote-access/sessions?state=all&deviceId=…&limit=100

ParámetroValoresPor defecto
stateopen o allopen
deviceIdUn id de dispositivotodos los routers
limit1 o más; se devuelven como máximo 500 filas100

Los parámetros desconocidos se rechazan con 400. Las sesiones vienen de la más reciente a la más antigua:

{
  "sessions": [
    {
      "sessionId": "dk3v…", "deviceId": "6f1c…", "userId": "u-55…", "state": "CONNECTED",
      "closeReason": null, "metered": false,
      "createdAt": "2026-11-17T10:00:00.000Z", "expiresAt": "2026-11-17T14:00:00.000Z",
      "connectedAt": "2026-11-17T10:00:04.000Z", "lastActivityAt": "2026-11-17T10:12:40.000Z", "closedAt": null,
      "bytesUp": 182044, "bytesDown": 5310221, "mine": true
    }
  ],
  "usage": { "monthBytes": 734003200, "monthBytesLimit": 10737418240, "openLimit": 10, "open": 2 }
}

state es PENDING (esperando al router), CONNECTED o CLOSED. closeReason es uno de los códigos de Límites y auditoría del acceso remoto. mine es true para las sesiones abiertas por el titular de la clave. En usage, un límite null significa que su plan no fija ninguno. Las sesiones terminadas se conservan 180 días.

Rechazos

Cada rechazo incluye details.reason.

Estadodetails.reasoncodeMensaje
404device_not_foundNOT_FOUNDDispositivo no encontrado.
409not_claimedCONFLICTRechazado: el dispositivo no es un router con licencia reclamado
409unsupportedCONFLICTEste router todavía no admite el acceso al panel. Actualice su firmware.
409device_not_activeCONFLICTEl dispositivo no está activo.
409certificate_inactiveCONFLICTEl router no tiene un certificado válido. Vuelva a aprovisionarlo.
409offlineCONFLICTEl router está desconectado.
403monthly_bytesQUOTA_EXCEEDEDSe ha agotado la cuota de datos del panel de este mes. (details.limit)
409device_busyCONFLICTEste router ya tiene 3 sesiones abiertas del panel. Cierre una primero.
403tenant_limitQUOTA_EXCEEDEDSe ha alcanzado el límite de sesiones abiertas del panel de su plan. Cierre una primero. (details.limit, details.current)
409opt_inCONFLICTEl acceso al panel está desactivado en este router. Active «Permitir el acceso al panel desde mi cuenta en la nube» en la página Nube del router.
409router_busyCONFLICTEl router rechazó la sesión: ya tiene el máximo de sesiones de panel que permite.
409router_refusedCONFLICTEl router rechazó la sesión del panel. (details.error)
504router_unreachablePROVIDER_UNAVAILABLEEl router no respondió. Inténtelo de nuevo en un momento.
503not_configuredPROVIDER_UNAVAILABLEEl acceso al panel no está configurado en esta instalación.
404session_not_foundNOT_FOUNDSesión del panel no encontrada.
409session_closedCONFLICTEsta sesión del panel ha terminado.
403not_openerFORBIDDENSolo quien abrió esta sesión del panel puede entrar en ella.

Reintente solo router_unreachable y offline, tras una pausa. Para opt_in, alguien en el router debe activar el acceso al panel; no se puede hacer desde Hermetry.

Límites

LímiteValor
Sesiones abiertas por router3
Sesiones abiertas por organizaciónValor de su plan (usage.openLimit)
Datos del panel por mesValor de su plan (usage.monthBytesLimit)
Duración de la sesión4 horas desde la apertura, sea cual sea la actividad
Tiempo de inactividad30 minutos sin tráfico
Enlace de entradaUn uso, dentro de 60 segundos
El router debe conectarseEn 90 segundos
Límite de datos en un enlace móvilcapBytes por sesión