@segurosbolivar/n8n-nodes-conecta-custom

Nodo de n8n para consumir los servicios del API Gateway Conecta 2.0 de Seguros Bolívar.

El nodo funciona como el portal de desarrolladores: con el email y la contraseña del portal del
usuario (guardados en una credencial o recibidos en cada ejecución), el nodo verifica que tenga acceso a la categoría elegida y resuelve el
resto (credenciales de API, token OAuth2 y armado de la petición). Integrar un servicio de Conecta en
un workflow no requiere encadenar un nodo de token con un nodo HTTP Request.

Flujo con el portal

Categorías visibles, con la misma regla del portal: el staff (ADMIN, TECHNICAL,
SUPER_ADMIN) ve todas las categorías activas; los demás usuarios ven las de sus suscripciones
activas y las que administran (ownedCategoryIds). Las categorías abiertas sin suscripción no se
listan.

La sesión, las categorías y las credenciales se cachean 10 minutos en memoria por login (la clave
es un HMAC de ambiente, email y contraseña con una llave aleatoria del proceso: solo la reutiliza
quien conoce la contraseña). Un acceso revocado en el portal puede tardar hasta 10 minutos en
reflejarse en el nodo. El
token del gateway se reutiliza entre ejecuciones hasta un minuto antes de expirar, porque cada
llamada a /oauth2/token consume cuota del plan de uso de la API key. El OpenAPI de cada
categoría se cachea 5 minutos, así que una API publicada en el portal aparece sin liberar una
versión del paquete.

Ambientes

El ambiente lo define la credencial Conecta Portal: tiene la URL del Portal (login,
catálogo y credenciales) y la URL de Servicios (API Gateway: token y ejecución), además del
email y la contraseña. Cree una credencial por ambiente, por ejemplo Conecta Portal – Dev y
Conecta Portal – Prod. El paquete no trae URLs ni necesita variables de entorno, así que funciona
igual en instancias corporativas, de terceros y en n8n Cloud.

Solo se aceptan URLs https:// sin credenciales, query ni fragmento. El botón Test de la
credencial valida las URLs, el login y el acceso a categorías.

Las credenciales de n8n son de quien las crea: otros usuarios no las ven ni pueden usarlas salvo
que se compartan, y aun así no pueden leer la contraseña.

Login del portal

La credencial Conecta Portal es obligatoria en todos los modos: define el ambiente y sin ella
el editor no lista categorías.

El nodo nunca pide API key ni secretos: con el email y la contraseña del portal consulta en cada
ejecución las categorías del usuario (rechaza la ejecución si no tiene acceso a la elegida) y sus
credenciales de API. Origen del Login define de dónde salen email y contraseña:

En Por ejecución la contraseña debe ser una expresión: si se escribe literal (o se pega
{{ ... }} en modo Fixed), la ejecución falla a propósito para que no quede en el JSON del
workflow. Para cambiar un campo a expresión: pasar el cursor sobre el campo → Expression. La
credencial es opcional en este modo y solo sirve para que el editor liste las categorías del
usuario; sin ella se listan todas las activas y el acceso se valida al ejecutar.

La instancia local trae dos workflows de ejemplo, uno por opción ("Conecta · Opción A/B").

Uso

Modo Catálogo

1. Categoría → API: se cargan del portal del ambiente elegido. Al recorrer la lista de APIs se ve la
   descripción de cada una.
2. Descripción de la API (solo informativo): la descripción publicada; al abrirlo se ven
   también los parámetros, headers y body que recibe la API.
3. Parámetros y Headers: al elegir la API se muestran como casillas todos los que declara
   su OpenAPI, con los obligatorios marcados y, en la etiqueta, descripción y ejemplo. Si la API no
   declara ninguno, el formulario lo indica. Las casillas vacías toman el default del OpenAPI y
   los obligatorios sin valor detienen la ejecución con la lista de faltantes. Authorization,
   x-api-key y Content-Type los administra el nodo.
4. Plantilla del Body → Body (JSON): al seleccionar la plantilla, el body completo publicado
   en el portal (el example o, si solo hay schema, una plantilla con sus ejemplos) se carga en el
   editor JSON para modificarlo. Si se cambia de API sin volver a elegir la plantilla y el body no se
   editó, se usa la plantilla de la API actual. En multipart/form-data los valores complejos se
   serializan en su campo.
5. Opciones adicionales: parámetros y headers que la API no documenta en el portal.

Los valores que quedan de otra API se descartan al ejecutar y se reportan como aviso en la
traza de depuración.

Modo Petición Personalizada

Para servicios que aún no están publicados en el portal: método, ruta, parámetros de query,
headers y body a mano, contra el API Gateway del ambiente de la credencial. La ruta se valida
contra path traversal y caracteres no permitidos.

Depuración

Active Modo Depuración en el nodo para agregar un campo _debug a cada item de salida:

Sin modo depuración, un error igual muestra en el panel de n8n en qué paso falló, la lista de
pasos con su status y el cuerpo de la respuesta del backend. Con Continue On Fail, el item de
salida lleva success: false, error, phase y statusCode.

Desarrollo local

npm install
npm run build
docker compose up -d          # → http://localhost:5678

Cree en n8n una credencial Conecta Portal con las URLs del ambiente (ver
Ambientes). Ciclo de trabajo: npm run build && docker compose restart n8n. dist/ se monta como volumen, así que no hay que reconstruir la imagen. Con npm run dev (tsc --watch) solo hace falta el restart.

Dos detalles al probar en local:

• Cargado por directorio, el tipo del nodo es CUSTOM.conecta; instalado como paquete será
  @segurosbolivar/n8n-nodes-conecta-custom.conecta. Los workflows exportados de la instancia local no abren
  contra el paquete publicado. Para probar con fidelidad de publicación: npm pack e instalar el
  tarball como community package.
• El Dockerfile sí hornea el nodo en la imagen; sirve para probar el empaquetado tal como se
  despliega.

Instalación

En n8n: Settings → Community Nodes → Install con @segurosbolivar/n8n-nodes-conecta-custom,
o npm install @segurosbolivar/n8n-nodes-conecta-custom en el directorio de nodos de n8n.

Seguridad

• El nodo nunca guarda API keys ni secretos de cliente: los consulta al portal en cada ejecución
  y los mantiene solo en memoria.
• Los headers Authorization y x-api-key los pone siempre el nodo; los headers de transporte
  (Host, Content-Length, X-Forwarded-*, etc.) que lleguen del formulario se descartan.
• La petición solo sale hacia el origen del API Gateway del ambiente: un path que cambie de host
  se bloquea antes de enviar el token.
• El modo depuración enmascara tokens, API keys y cookies, pero sí incluye el body y la
  respuesta de la API. No lo deje activo en workflows que manejan datos personales.

Para reportar una vulnerabilidad, escriba a conecta@segurosbolivar.com en vez de abrir un issue
público.

Publicación

publish.yml usa el template institucional template-npm.yml: se publica a mano
(workflow_dispatch) o automáticamente al hacer merge a master que cambie version,
siempre desde master. Publica solo si la versión no existe en npm; si ya existe, se
omite sin fallar. La revisión es la del PR hacia master. npm run build vacía dist/
y compila sin sourcemaps; npm run verify:package revisa que el tarball solo tenga los
archivos permitidos, que incluya los nodos y credenciales declarados y que el código no
contenga hosts internos. prepublishOnly corre ambos.

El despliegue a la instancia interna de n8n lo hace aparte el pipeline institucional
(pipeline.yml). La operación interna (actualización del catálogo, prerrequisitos de
infraestructura) está en docs/OPERACION.md, que no se publica en npm.

Limitaciones conocidas

• Servicios sin categoría no aparecen. POST /services/import no asocia categoría, así que
  buena parte del catálogo importado queda fuera del alcance del nodo hasta que se categorice.
• Ejemplos irrecuperables. El nodo repara los example de body mal formados más comunes
  (comillas simples, comas colgantes, JSON truncado); si aun así no se puede parsear ni hay
  schema, la operación no genera campos y hay que usar Body JSON.
• Sin tooltips por casilla. n8n no permite ayuda dinámica por casilla; la descripción y el
  ejemplo van en la etiqueta de cada parámetro o header.
• El OpenAPI manda. Si el spec marca como opcional algo que el backend exige, el nodo no lo
  pide; el error del backend lo indica y hay que agregarlo como fila.
• Arreglos de objetos. El desglose recursivo del body aplana objetos anidados, pero un arreglo
  (aunque sea de objetos) se edita como un único campo con su JSON.

Cambios

Ver CHANGELOG.md.

Autores

Seguros Bolívar - Middleware