Colas vía API

Las colas son el mecanismo de NORA para alimentar a tus robots con unidades de trabajo (items). Esta página documenta los endpoints públicos que te permiten encolar y consultar items de una cola desde tus sistemas (ERP, backend, scripts) usando una API Key, sin necesidad del token de un agente.

Si buscas la guía conceptual de colas, revisa Colas.

Autenticación y prefijo

• URL base de producción: https://nora-api.valisoftconsulting.com
• Prefijo de la API: /api/v1
• Autenticación: cabecera X-API-Key: nora_ak_...

Cada endpoint exige un scope concreto en la API Key. Consulta cómo crear y limitar claves en autenticación.

Acción	Scope requerido
Encolar item(s)	queues:write (o una clave sin restricción de scopes)
Listar items	queues:read (o una clave sin restricción de scopes)

Nota

Las colas se identifican por nombre en estos endpoints (by-name/{name}). El nombre es único dentro de tu organización. Si la cola no existe, la API responde 404.

Envoltura de respuesta

Todas las respuestas van envueltas. Las operaciones simples usan SuccessResponse:

{
  "success": true,
  "data": { }
}

Los listados usan PaginatedResponse, que añade meta:

{
  "success": true,
  "data": [ ],
  "meta": { "page": 1, "limit": 20, "total": 0, "pages": 0 }
}

Estados de un item de cola

El campo status de cada item evoluciona durante su ciclo de vida. Los valores posibles son:

Estado	Significado
new	Listo para tomar. Es el valor por defecto al crear.
in_progress	Un robot lo está procesando.
pending_review	A la espera de aprobación humana.
completed	Procesado con éxito (con result).
failed	Falló o fue rechazado (ver error_message, retry_count).
dead_letter	Superó max_retries; no se reintenta solo.

stateDiagram-v2
  [*] --> new
  new --> in_progress
  in_progress --> completed
  in_progress --> pending_review
  in_progress --> failed
  pending_review --> new : aprobado
  pending_review --> failed : rechazado
  failed --> dead_letter : sin reintentos
  failed --> new : reintento

El número máximo de reintentos se define a nivel de cola (max_retries, entre 0 y 10; por defecto 3).

Encolar un item

POST /api/v1/queues/by-name/{name}/items

• Scope: queues:write
• Límite de tasa: 60 solicitudes/minuto (por API Key, o por IP).

Cuerpo de la petición (AddQueueItemRequest):

Campo	Tipo	Requerido	Descripción
data	objeto	Sí	Carga de negocio del item (JSON libre).
priority	entero	No (3)	1 = baja, 3 = normal, 5 = urgente.
reference	string | null	No	Clave de negocio del productor; es buscable y se muestra en la lista.
deadline	fecha-hora ISO 8601 | null	No	SLA: los items con deadline más cercano se despachan primero.
postpone	fecha-hora ISO 8601 | null	No	El agente omite el item hasta que pase este momento.

Ejemplo con curl:

curl -X POST \
  "https://nora-api.valisoftconsulting.com/api/v1/queues/by-name/facturas/items" \
  -H "X-API-Key: nora_ak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": { "factura_id": "F-2026-0042", "monto": 1280.50 },
    "priority": 5,
    "reference": "F-2026-0042",
    "deadline": "2026-06-30T23:59:00Z"
  }'

Respuesta 200:

{
  "success": true,
  "data": {
    "id": "5b1c0a3e-2f4d-4a91-9c10-7e2f8c4d1a22",
    "queue_id": "0a9f7b2c-1d3e-4f56-8a7b-9c0d1e2f3a4b",
    "status": "new",
    "priority": 5,
    "reference": "F-2026-0042",
    "deadline": "2026-06-30T23:59:00Z",
    "postpone": null,
    "data": { "factura_id": "F-2026-0042", "monto": 1280.50 },
    "result": null,
    "retry_count": 0,
    "error_message": null,
    "processed_by": null,
    "created_at": "2026-06-19T14:00:00Z",
    "processed_at": null,
    "reviewed_by": null,
    "reviewed_at": null
  }
}

Encolar items en lote (bulk)

POST /api/v1/queues/by-name/{name}/items/bulk

• Scope: queues:write
• Límite de tasa: 20 solicitudes/minuto (por API Key, o por IP).
• Máximo 1000 items por solicitud.

Cuerpo de la petición (BulkAddQueueItemsRequest):

Campo	Tipo	Requerido	Descripción
items	lista de objetos	Sí	Cada objeto es la carga de negocio (data) de un item.

El bulk solo lleva data

En el alta por lote, cada elemento de items se guarda íntegro como el campo data del item. Los campos priority, reference, deadline y postpone no se aplican por item: todos quedan con prioridad por defecto (3) y sin referencia ni SLA. Si necesitas esos atributos, usa el alta de item individual.

Ejemplo con curl:

curl -X POST \
  "https://nora-api.valisoftconsulting.com/api/v1/queues/by-name/facturas/items/bulk" \
  -H "X-API-Key: nora_ak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "factura_id": "F-2026-0043", "monto": 90.00 },
      { "factura_id": "F-2026-0044", "monto": 410.75 }
    ]
  }'

Respuesta 200 (devuelve cuántos items se añadieron):

{
  "success": true,
  "data": { "added": 2 }
}

Listar items de una cola

GET /api/v1/queues/by-name/{name}/items

• Scope: queues:read
• Límite de tasa: 60 solicitudes/minuto (por API Key, o por IP).

Parámetros de consulta:

Parámetro	Tipo	Por defecto	Restricciones
page	entero	1	entre 1 y 500
limit	entero	20	entre 1 y 100
status	string	(todos)	uno de: new, in_progress, pending_review, completed, failed, dead_letter

Valores del filtro status

El parámetro status acepta exactamente los estados internos reales del item: new, in_progress, pending_review, completed, failed, dead_letter. Cualquier otro valor devuelve 422.

Los items se devuelven ordenados por fecha de creación descendente (más recientes primero).

Ejemplo con curl (filtrando por estado):

curl -G \
  "https://nora-api.valisoftconsulting.com/api/v1/queues/by-name/facturas/items" \
  -H "X-API-Key: nora_ak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "status=completed" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=50"

Respuesta 200:

{
  "success": true,
  "data": [
    {
      "id": "5b1c0a3e-2f4d-4a91-9c10-7e2f8c4d1a22",
      "queue_id": "0a9f7b2c-1d3e-4f56-8a7b-9c0d1e2f3a4b",
      "status": "completed",
      "priority": 5,
      "reference": "F-2026-0042",
      "deadline": "2026-06-30T23:59:00Z",
      "postpone": null,
      "data": { "factura_id": "F-2026-0042", "monto": 1280.50 },
      "result": { "estado": "registrada" },
      "retry_count": 0,
      "error_message": null,
      "processed_by": "9d8c7b6a-5e4f-4321-8a90-0b1c2d3e4f5a",
      "created_at": "2026-06-19T14:00:00Z",
      "processed_at": "2026-06-19T14:05:00Z",
      "reviewed_by": null,
      "reviewed_at": null
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 1, "pages": 1 }
}

Ejemplo en Python

import requests

BASE = "https://nora-api.valisoftconsulting.com/api/v1"
HEADERS = {"X-API-Key": "nora_ak_xxxxxxxxxxxxxxxxxxxxxxxx"}

# Encolar un item con prioridad alta
resp = requests.post(
    f"{BASE}/queues/by-name/facturas/items",
    headers=HEADERS,
    json={
        "data": {"factura_id": "F-2026-0045", "monto": 75.0},
        "priority": 5,
        "reference": "F-2026-0045",
    },
)
resp.raise_for_status()
item = resp.json()["data"]
print(item["id"], item["status"])  # ... new

# Listar los items y revisar su estado real
resp = requests.get(
    f"{BASE}/queues/by-name/facturas/items",
    headers=HEADERS,
    params={"limit": 100},
)
resp.raise_for_status()
payload = resp.json()
print(payload["meta"]["total"], "items en total")
for it in payload["data"]:
    print(it["reference"], it["status"])

Errores comunes

Código	Causa
401	Falta la cabecera X-API-Key o la clave es inválida.
403	La clave no tiene el scope requerido (queues:read / queues:write).
404	No existe una cola con ese name en tu organización.
422	Cuerpo inválido (p. ej. más de 1000 items en bulk, o status no permitido).
429	Se superó el límite de tasa del endpoint.

Consejo

Define el reference con tu clave de negocio (número de factura, ID de pedido, etc.). Permite buscar el item en la consola y correlacionar el resultado del robot con tu sistema de origen.

Siguientes pasos

• Consulta cómo procesan los robots estos items en Colas.
• Revisa scopes y gestión de claves en autenticación.