API de n8n: crea un inventario de workflows y compara instantáneas locales
Usa la API de n8n para recopilar workflows con paginación por cursor, guardar un inventario local de ID y nombres e informar de altas, ausencias y cambios de nombre.
Comprobado con las fuentes citadas el .
Objetivo y requisitos del inventario con la API de n8n
Este tutorial utiliza la API de n8n para recopilar todas las páginas de workflows devueltas y comparar una instantánea local de ID y nombres con otra anterior. Necesitas acceso a la API, permiso para crear una clave y un entorno local de Python. La documentación de la API de n8n indica que Cloud Starter, Pro y Enterprise, así como todas las ediciones autoalojadas, admiten acceso a la API; excluye la prueba gratuita. Esta disponibilidad refleja la documentación revisada, que no identifica una versión desplegada.
El resultado abarca los workflows accesibles para la cuenta y la clave utilizadas en la recopilación, sin demostrar que incluya toda la instancia. Detecta diferencias en los elementos presentes y sus nombres, no cambios en la definición de los workflows, su comportamiento de ejecución o su estado de publicación. No se establece que las páginas constituyan una instantánea de un momento concreto: los cambios durante la recopilación pueden afectar al resultado.
Creemos que un inventario pequeño es un punto de partida útil porque mantiene clara la pregunta de la revisión: ¿qué ID y nombres de workflows han cambiado?
Sources: n8n-docs/docs/connect/n8n-api/api-reference.md at main · n8n-io/n8n-docs · GitHub, Workflow | Connect | n8n Docs
1. Prepara la clave y la raíz de la API
En Settings > n8n API, crea una clave con una etiqueta y una fecha de caducidad. Enterprise admite claves con ámbitos de permisos: selecciona workflow:list para acceder a la colección. Las claves de las ediciones distintas de Enterprise tienen acceso completo a los recursos y capacidades de la cuenta; limitar este script a GET no convierte esas credenciales en credenciales de solo lectura.
Configura N8N_API_ROOT en tu entorno local con la dirección HTTPS de tu instancia seguida de /api/v1. En Cloud, usa el host app.n8n.cloud de tu espacio de trabajo; en despliegues autoalojados, usa el host de tu instancia y conserva cualquier ruta base específica del despliegue. Configura N8N_API_KEY por separado. Mantén la clave fuera de las instantáneas y los ejemplos compartidos.
Sources: n8n-docs/docs/connect/n8n-api/authentication.md at main · n8n-io/n8n-docs · GitHub, Authentication | Connect | n8n Docs
2. Recopila todas las páginas y guarda el inventario
La solicitud documentada para obtener la colección es GET /api/v1/workflows. Envía X-N8N-API-KEY en cada solicitud. El tamaño de página predeterminado documentado es 100 y el máximo es 250; este ejemplo solicita 100. Omite los filtros active, name, tags y de proyecto. Sigue esta secuencia:
- Solicita la colección de workflows sin filtros que reduzcan el inventario.
- Acumula los datos de cada página y rechaza los ID de workflows duplicados.
- Pasa nextCursor sin modificar como siguiente parámetro cursor.
- Termina cuando nextCursor sea null; rechaza los cursores repetidos o las respuestas mal formadas.
- Guarda el mapa completo de ID y nombres con las claves ordenadas.
El siguiente código es un ejemplo editorial propuesto, no una herramienta de n8n probada. Guarda los dos párrafos de código siguientes, en orden, como inventory.py. Utiliza la biblioteca estándar de Python. Ejecútalo con python3 inventory.py después de configurar las variables de entorno. El detalle de la estructura de la respuesta procede en parte de la referencia de los mantenedores de n8n en una rama en evolución, no de una garantía del cliente para una versión concreta.
import json, os from pathlib import Path from urllib.parse import urlencode from urllib.request import Request, urlopen root = os.environ['N8N_API_ROOT'].rstrip('/') key = os.environ['N8N_API_KEY'] items, seen, cursor = {}, set(), None while True: params = {'limit': 100} if cursor is not None: params['cursor'] = cursor request = Request(root + '/workflows?' + urlencode(params), headers={'X-N8N-API-KEY': key}, method='GET') with urlopen(request, timeout=30) as response: page = json.load(response) if not isinstance(page, dict) or not isinstance(page.get('data'), list) or 'nextCursor' not in page: raise ValueError('Incomplete collection: malformed page')
for workflow in page['data']: identifier, name = workflow['id'], workflow['name'] if not isinstance(identifier, str) or not isinstance(name, str) or identifier in items: raise ValueError('Incomplete collection: invalid or duplicate ID/name') items[identifier] = name cursor = page['nextCursor'] if cursor is None: break if not isinstance(cursor, str) or not cursor or cursor in seen: raise ValueError('Incomplete collection: invalid or repeated cursor') seen.add(cursor) with open('inventory.candidate.json', 'w', encoding='utf-8') as output: json.dump(items, output, sort_keys=True, ensure_ascii=False, indent=2) print('Complete collection saved as inventory.candidate.json')
El script solo escribe cuando termina la recopilación. Tras una ejecución fallida, no compares un archivo candidato antiguo. Conserva por separado tu referencia completa anterior. Ordenar las claves permite que el mapa de nombres indexado por ID sea reproducible independientemente del orden de la API. Guarda los metadatos de la recopilación por separado.
Sources: Authentication | Connect | n8n Docs, Workflow | Connect | n8n Docs, Pagination | Connect | n8n Docs, n8n-docs/docs/connect/n8n-api/pagination.md at main · n8n-io/n8n-docs · GitHub, n8n/.agents/skills/public-api/reference.md at master · n8n-io/n8n · GitHub, json — JSON encoder and decoder — Python 3.13.16 documentation
3. Compara las instantáneas y revisa el resultado
Tras la primera recopilación correcta, conserva el archivo candidato como inventory.previous.json. En una ejecución posterior que termine correctamente, guarda este código de comparación propuesto como compare.py y ejecuta python3 compare.py. Carga ambos mapas JSON y compara los ID antes que los nombres.
import json with open('inventory.previous.json', encoding='utf-8') as source: before = json.load(source) with open('inventory.candidate.json', encoding='utf-8') as source: after = json.load(source) report = { 'added': {k: after[k] for k in sorted(after.keys() - before.keys())}, 'missing': {k: before[k] for k in sorted(before.keys() - after.keys())}, 'renamed': {k: {'before': before[k], 'after': after[k]} for k in sorted(before.keys() & after.keys()) if before[k] != after[k]} } print(json.dumps(report, sort_keys=True, ensure_ascii=False, indent=2))
Estos ejemplos sintéticos ilustran las comparaciones esperadas, no resultados de pruebas observados. Una entrada ausente significa que ya no se observa; revisa el acceso y las condiciones de recopilación antes de interpretarlo como una eliminación.
| Anterior | Candidato | Informe |
|---|---|---|
| a: Pedidos | a: Pedidos | Todas las categorías vacías |
| a: Pedidos | a: Pedidos; b: Contactos | b añadido |
| a: Pedidos; b: Contactos | a: Pedidos | b ausente |
| a: Pedidos | a: Recepción de pedidos | a renombrado |
Asignaríamos una persona revisora antes de sustituir la referencia: un informe de diferencias resulta más útil cuando alguien decide qué significa cada cambio.
Sources: Workflow | Connect | n8n Docs, json — JSON encoder and decoder — Python 3.13.16 documentation
4. Resuelve los problemas antes de aceptar una instantánea
La referencia de workflows de la API de n8n documenta estos significados de las respuestas. Utiliza las comprobaciones propuestas a continuación para investigar, sin tratar cada estado como un diagnóstico completo.
| Estado | Significado | Comprobación propuesta |
|---|---|---|
| 400 | Solicitud no válida o mal formada | Comprueba los parámetros y que el cursor no se haya modificado |
| 401 | No autorizado | Comprueba la clave y la cabecera de autenticación |
| 403 | Acceso prohibido | Revisa el acceso de la cuenta y los ámbitos de permisos de Enterprise |
Sources: Workflow | Connect | n8n Docs, n8n-docs/docs/connect/n8n-api/authentication.md at main · n8n-io/n8n-docs · GitHub, Authentication | Connect | n8n Docs, n8n-docs/docs/connect/n8n-api/pagination.md at main · n8n-io/n8n-docs · GitHub
