Introducción a la API

La API pública de NORA te permite integrar la plataforma RPA con tus propios sistemas: disparar y consultar jobs, leer assets, encolar y consumir queue items, y listar máquinas y procesos. Toda la superficie pública se autentica con una API key (cabecera X-API-Key) y devuelve respuestas JSON con un formato consistente.

Esta API es ideal para escenarios como: lanzar una automatización desde un ERP o un formulario web, alimentar una cola de trabajo desde un sistema externo, o consultar el resultado de un job desde un pipeline de datos.

URL base y prefijo

Entorno	URL base
Producción	`https://nora.valisoftconsulting.com`

Todos los endpoints de la API pública viven bajo el prefijo /api/v1. Por lo tanto, la URL completa de un recurso se construye así:

https://nora-api.valisoftconsulting.com/api/v1/<recurso>

Por ejemplo, para disparar un job harías una petición a https://nora-api.valisoftconsulting.com/api/v1/jobs/trigger.

Autenticación

La API pública usa API keys enviadas en la cabecera HTTP X-API-Key. Cada clave tiene el prefijo nora_ak_ y se crea desde Settings → API Keys en la aplicación.

X-API-Key: nora_ak_xxxxxxxxxxxxxxxxxxxxxxxx

Cada API key puede limitarse mediante scopes con la forma recurso:acción (por ejemplo jobs:read, jobs:write, assets:read, queues:write) y, opcionalmente, una lista de IPs permitidas. Para los detalles completos sobre scopes, creación y rotación de claves, consulta autenticación.

Requisito de plan

La capacidad de usar API keys es la feature api_keys, disponible solo en los planes Pro y Enterprise. En los planes Free y Starter no se pueden crear claves ni consumir los endpoints públicos.

Plan	`api_keys`	Límite de claves
Free	No	0
Starter	No	0
Pro	Sí	5
Enterprise	Sí	Sin límite

Las rutas públicas están protegidas por el plan activo de la organización: si una clave sobrevive a una bajada de plan que ya no incluye api_keys, dejará de funcionar.

Formato de respuesta

Las respuestas correctas se envuelven en un objeto con success y data. Para un único recurso, data contiene el objeto:

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending"
  }
}

Las listas paginadas añaden además un objeto meta con la información de paginación:

{
  "success": true,
  "data": [ { "id": "..." } ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 57,
    "pages": 3
  }
}

Los errores siguen una forma distinta, con success: false y un objeto error:

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Esta función requiere el plan pro. Tu plan actual: starter.",
    "details": {
      "error": "feature_not_available",
      "feature": "api_keys",
      "current_plan": "starter",
      "required_plan": "pro"
    }
  }
}

El campo details es opcional y aporta contexto adicional según el error.

Panorama de recursos

La superficie pública de la API cubre estos recursos:

Recurso	Para qué sirve	Documentación
Jobs	Disparar, consultar y detener ejecuciones	jobs
Colas	Encolar y listar queue items por nombre	colas
Assets	Leer un asset descifrado por nombre	assets
Máquinas	Listar las máquinas de la organización	máquinas
Procesos	Listar los procesos activos	procesos
Webhooks	Disparar un proceso vía webhook	webhooks

flowchart TD
  C["Tu sistema (cliente)"] -->|"X-API-Key: nora_ak_..."| A["API NORA /api/v1"]
  A --> J["Jobs"]
  A --> Q["Colas"]
  A --> S["Assets"]
  A --> M["Máquinas"]
  A --> P["Procesos"]
  A --> W["Webhooks"]

Primer ejemplo con curl

Este ejemplo dispara un proceso creando un nuevo job. El único campo obligatorio es process_id; si omites machine_id, NORA selecciona automáticamente una máquina en línea y activa de tu organización.

curl -X POST "https://nora-api.valisoftconsulting.com/api/v1/jobs/trigger" \
  -H "X-API-Key: nora_ak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "process_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "input_data": { "cliente": "ACME", "monto": 1250 },
    "priority": 3
  }'

Respuesta (recortada):

{
  "success": true,
  "data": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "process_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "machine_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "status": "pending",
    "priority": 3,
    "created_at": "2026-06-19T14:05:00Z"
  }
}