Disparar jobs

El endpoint POST /api/v1/jobs/trigger lanza la ejecución de un proceso desde tus propios sistemas usando una API key. Es la forma recomendada de integrar NORA con aplicaciones externas, backends o automatizaciones que necesiten arrancar un robot bajo demanda.

Una vez creado el job, consulta su avance y resultado con el endpoint descrito en consultar jobs.

Resumen

Atributo	Valor
Método y ruta	POST /api/v1/jobs/trigger
URL base de producción	https://nora.valisoftconsulting.com
Autenticación	Cabecera X-API-Key: nora_ak_...
Scope requerido	jobs:write (o una key sin restricción de scopes)
Límite de tasa	30 peticiones por minuto, por IP
Disponibilidad	Planes Pro y Enterprise (la feature de API keys)

Nota

La autenticación de la API pública se hace con la cabecera X-API-Key, no con tokens Bearer. Crea y administra tus keys en Settings → API Keys. Cada key lleva scopes con el formato recurso:acción y, opcionalmente, una lista de IPs permitidas. Consulta autenticación para más detalle.

Cuerpo de la petición

El cuerpo es un objeto JSON con los siguientes campos:

Campo	Tipo	Requerido	Descripción
process_id	UUID	Sí	Identificador del proceso a ejecutar. El proceso debe existir, estar activo y pertenecer a tu organización.
machine_id	UUID	No	Máquina donde ejecutar el job. Si se omite, NORA selecciona automáticamente una máquina activa y conectada de tu organización.
input_data	objeto	No	Argumentos de entrada para el robot, como pares clave-valor. Máximo 1 MB serializado en JSON.
priority	entero	No	Prioridad del job. Por defecto 3. Ver la nota sobre prioridades.

Cómo se elige la máquina

machine_id es opcional porque las API keys no tienen scope para listar máquinas. Si lo omites, el servicio elige la máquina activa más antigua que no esté offline. Si no hay ninguna máquina conectada, la petición falla con un error de validación: “No hay máquinas online disponibles para ejecutar el job.” Si indicas un machine_id que está desactivado o desconectado, también se rechaza la petición.

Prioridades según el plan

El valor de priority debe estar entre 1 y 5. En la práctica, los planes Pro y Enterprise (los únicos con API keys) admiten las prioridades 1 (baja), 3 (normal, valor por defecto) y 5 (urgente). Enviar una prioridad no permitida por tu plan devuelve un error.

Respuesta

Respuesta 200 OK. Como todas las respuestas de la API, el resultado viene envuelto en un objeto con success y data. El campo data contiene el job recién creado (esquema JobResponse). Un job nuevo arranca en estado pending.

Campos relevantes de data:

Campo	Tipo	Descripción
id	UUID	Identificador del job. Úsalo para consultar su estado.
status	cadena	Estado del job. Valores: pending, assigned, running, completed, failed, cancelled.
process_id	UUID	Proceso ejecutado.
machine_id	UUID	Máquina asignada (la indicada o la autoseleccionada).
priority	entero	Prioridad efectiva del job.
input_data	objeto | null	Argumentos de entrada enviados.
output_data	objeto | null	Resultado del robot (se rellena al terminar).
created_at	fecha-hora	Momento de creación.
process_name	cadena | null	Nombre del proceso.
machine_name	cadena | null	Nombre de la máquina.

{
  "success": true,
  "data": {
    "id": "8b1f0a4c-7d2e-4a9b-9c3f-2e1d5a6b7c8d",
    "tenant_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "process_id": "3f9d2b10-4c6e-4f1a-bd2c-9a8b7c6d5e4f",
    "machine_id": "7e6d5c4b-3a2f-1b0c-9d8e-7f6a5b4c3d2e",
    "status": "pending",
    "priority": 3,
    "input_data": { "cliente": "ACME", "monto": 1250.5 },
    "output_data": null,
    "logs": null,
    "error_message": null,
    "started_at": null,
    "finished_at": null,
    "retry_count": 0,
    "stop_requested": false,
    "created_at": "2026-06-19T14:03:11.482Z",
    "updated_at": "2026-06-19T14:03:11.482Z",
    "process_name": "Conciliación bancaria",
    "machine_name": "BOT-PROD-01"
  }
}

Ejemplo con curl

curl -X POST "https://nora-api.valisoftconsulting.com/api/v1/jobs/trigger" \
  -H "X-API-Key: nora_ak_tu_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "process_id": "3f9d2b10-4c6e-4f1a-bd2c-9a8b7c6d5e4f",
    "input_data": { "cliente": "ACME", "monto": 1250.5 },
    "priority": 3
  }'

Ejemplo con Python (requests)

import requests

BASE_URL = "https://nora.valisoftconsulting.com"
API_KEY = "nora_ak_tu_clave_aqui"

resp = requests.post(
    f"{BASE_URL}/api/v1/jobs/trigger",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "process_id": "3f9d2b10-4c6e-4f1a-bd2c-9a8b7c6d5e4f",
        # "machine_id": "...",  # opcional: si se omite, NORA elige una máquina conectada
        "input_data": {"cliente": "ACME", "monto": 1250.5},
        "priority": 3,
    },
    timeout=30,
)
resp.raise_for_status()

job = resp.json()["data"]
print("Job creado:", job["id"], "->", job["status"])

Flujo de ejecución

sequenceDiagram
    participant Cli as Tu sistema
    participant API as NORA API
    participant Bot as Máquina (agente)
    Cli->>API: POST /api/v1/jobs/trigger (X-API-Key)
    API-->>Cli: 200 { data: { id, status: "pending" } }
    API->>Bot: Asigna el job a la máquina
    Bot-->>API: running -> completed / failed
    Cli->>API: GET /api/v1/jobs/{id} (sondeo de estado)
    API-->>Cli: 200 { data: { status, output_data } }

Errores comunes

Código	Causa
401	Falta la cabecera X-API-Key o la key es inválida.
403	La key no tiene el scope jobs:write, la IP no está permitida, o la suscripción no está activa.
404	El process_id (o el machine_id indicado) no existe en tu organización.
422	Cuerpo inválido: falta process_id, input_data supera 1 MB, o priority fuera de rango (1–5).
429	Se superó el límite de 30 peticiones por minuto.

Consejo

Tras disparar el job, no bloquees tu integración esperando: guarda el id y consulta el estado de forma periódica con consultar jobs.