Máquinas

Una máquina en NORA representa un equipo físico o virtual —solo Windows o macOS— donde se instala el agente de NORA y donde realmente corren los robots. Cada máquina pertenece a una organización (tenant), tiene una credencial propia (la machine key) y puede ejecutar uno o varios jobs a la vez según su configuración.

Modelo de una máquina

Los campos principales de una máquina (modelo Machine) son:

Campo	Tipo	Descripción
name	texto	Nombre legible de la máquina (mínimo 2 caracteres).
machine_key	secreto	Credencial con la que el agente se autentica. Se guarda hasheada y, además, cifrada para poder revelarla una sola vez.
status	enum	Estado operativo: online, offline, busy o maintenance.
is_active	bool	Si está activa y puede recibir trabajo. Por defecto true.
max_concurrent_jobs	entero	Número máximo de jobs simultáneos. Por defecto 1.
last_seen_at	fecha	Último heartbeat recibido del agente.
missed_heartbeats	entero	Latidos perdidos consecutivos (sirve para marcarla offline).
system_info	objeto	Información de sistema reportada por el agente.
display_resolution, color_depth, dpi_scaling, session_mode	varios	Configuración de pantalla para la ejecución (ver más abajo).

La machine key se muestra una sola vez

Al crear la máquina, la API devuelve machine_key en texto plano solo en esa respuesta. Después solo se ve la pista de los últimos 4 caracteres (machine_key_last4, p. ej. ****a1b2). Un administrador puede volver a revelarla con GET /machines/{id}/key (operación auditada), o regenerar el paquete del agente, que ya la incluye en su archivo .env.

Registrar y aprobar una máquina

El alta de una máquina la realiza un usuario con rol admin desde la API privada (autenticación de sesión, no API key):

curl -X POST https://nora-api.valisoftconsulting.com/api/v1/machines \
  -H "Authorization: Bearer <token-de-sesion>" \
  -H "Content-Type: application/json" \
  -d '{"name": "BOT-CONTABILIDAD-01"}'

Respuesta (envuelta en data, ver introducción a la API):

{
  "success": true,
  "data": {
    "id": "0f4c…",
    "name": "BOT-CONTABILIDAD-01",
    "machine_key": "nora_mk_…",
    "status": "offline",
    "created_at": "2026-06-19T10:00:00Z"
  }
}

A continuación se descarga el paquete del agente para la plataforma deseada (platform=windows o platform=macos). NORA genera un ZIP con el ejecutable del agente, un README.txt con los pasos de instalación, el script de instalación y un archivo .env que ya contiene la NORA_MACHINE_KEY y la URL de la API. Al instalarse, el agente se registra para arrancar con el sistema y empieza a enviar heartbeats; entonces la máquina pasa de offline a online.

No existe un paso manual de “aprobación”: la máquina queda lista en cuanto el agente, autenticado con su machine key, se conecta por primera vez. Para retirar una máquina, desactívala (is_active=false) o elimínala (solo si no tiene jobs en su historial).

flowchart TD
    A[Admin crea la máquina] --> B[Descarga el paquete del agente]
    B --> C[Instala el agente en Windows o macOS]
    C --> D[Agente se autentica con la machine key]
    D --> E[Heartbeats: status pasa a online]
    E --> F[Lista para ejecutar jobs]

Estados

Estado	Significado
offline	Sin conexión. Es el estado inicial al crearla.
online	Conectada y disponible para recibir trabajo.
busy	Ocupada ejecutando uno o más jobs.
maintenance	En mantenimiento; no se le asigna trabajo.

El filtro status de los listados de la API privada acepta online, offline, busy y maintenance. El endpoint público acepta online, offline y busy.

Grupos de máquinas

Un grupo de máquinas (MachineGroup) reúne varias máquinas bajo un nombre para repartir trabajo entre ellas en lugar de fijar un job a un equipo concreto. La pertenencia es una relación muchos-a-muchos (MachineGroupMember).

Disponibilidad

Los grupos de máquinas están protegidos por una feature del plan (machine_groups). Si tu plan no la incluye, los endpoints de grupos responderán con error de acceso.

Operaciones disponibles bajo el prefijo /api/v1/machine-groups (rol admin para crear, modificar y borrar; operator/viewer pueden listar):

Método y ruta	Acción
GET /machine-groups	Listar grupos del tenant.
POST /machine-groups	Crear grupo (name, opcional machine_ids).
PATCH /machine-groups/{group_id}	Renombrar o cambiar las máquinas del grupo.
DELETE /machine-groups/{group_id}	Eliminar el grupo.

curl -X POST https://nora-api.valisoftconsulting.com/api/v1/machine-groups \
  -H "Authorization: Bearer <token-de-sesion>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contabilidad", "machine_ids": ["0f4c…", "1a2b…"]}'

El objeto de respuesta de un grupo incluye id, name, machine_ids (lista) y created_at.

Resolución de pantalla

Los robots de interfaz dependen de la pantalla en la que corren. Cada máquina lleva una configuración de display que el agente aplica a la sesión donde ejecuta el robot. Es el equivalente de NORA a los ajustes de resolución de UiPath:

Campo	Valores permitidos	Por defecto	Notas
display_resolution	ANCHOxALTO, p. ej. 1920x1080	1920x1080	Ancho 640–7680, alto 480–4320.
color_depth	16, 24, 32	32	Profundidad de color (bits por píxel).
dpi_scaling	100, 125, 150, 175, 200	100	Escalado DPI, en porcentaje.
session_mode	rdp, console	rdp	Tipo de sesión donde corre el robot.

Sobre session_mode:

• rdp: el robot corre en una sesión RDP de bucle local con resolución, profundidad y DPI configurables. Es el modo recomendado para ejecución desatendida.
• console: el robot corre en la sesión de consola física del equipo y usa la resolución del adaptador. Es el equivalente al “Login to Console” de UiPath.

En Windows se pueden definir además windows_username y windows_password (esta última se cifra en el backend y nunca se devuelve en las respuestas; la API solo expone windows_autologon_configured) para iniciar sesión automáticamente en la máquina antes de ejecutar.

Estos valores se modifican con PUT /api/v1/machines/{machine_id} (rol admin u operator):

curl -X PUT https://nora-api.valisoftconsulting.com/api/v1/machines/0f4c… \
  -H "Authorization: Bearer <token-de-sesion>" \
  -H "Content-Type: application/json" \
  -d '{"display_resolution": "1920x1080", "color_depth": 32, "dpi_scaling": 125, "session_mode": "rdp"}'

Listar máquinas desde la API pública

Para integraciones externas, NORA expone un endpoint de solo lectura autenticado con API key:

GET /api/v1/machines/list
X-API-Key: nora_ak_...

Requiere el scope machines:read (o una key sin restricciones) y está limitado a 60 peticiones por minuto. Admite el filtro opcional ?status=online|offline|busy.

curl https://nora-api.valisoftconsulting.com/api/v1/machines/list \
  -H "X-API-Key: nora_ak_..."

{
  "data": [
    {
      "id": "0f4c…",
      "name": "BOT-CONTABILIDAD-01",
      "status": "online",
      "is_active": true,
      "max_concurrent_jobs": 1,
      "last_seen_at": "2026-06-19T10:05:00Z"
    }
  ],
  "total": 1
}

Consejo

La respuesta de este endpoint público no usa el envoltorio success/data de la API privada: devuelve directamente data (lista) y total.