Nodo de n8n

Plan Business

El nodo de CRM para n8n que gestiona contactos, negocios y conversaciones

Instala n8n-nodes-pinlyx desde el panel Community Nodes, pega una clave de API y listo: un formulario enviado se convierte en un contacto, un negocio ganado en una factura y una conversación sin responder en un mensaje en el canal que vigile tu equipo. Ocho operaciones sobre tres recursos, sin dependencias en tiempo de ejecución y con licencia MIT.

Plan gratis para siempre · Sin tarjeta de crédito · Cancela cuando quieras

Última actualización:

3
Recursos
Contacto, negocio, conversación
8
Operaciones
Cinco de contactos, dos de negocios y una de conversaciones
0
Dependencias en ejecución
Cada llamada usa el helper HTTP del propio n8n
MIT
Licencia
Código en GitHub, publicado en npm

Definición

Un nodo comunitario de n8n es un paquete publicado en npm que una instancia de n8n instala en tiempo de ejecución y que añade un bloque nuevo al lienzo. No es un fork de n8n ni un receptor de webhooks que tengas que alojar y mantener activo tú.

n8n-nodes-pinlyx es el de Pinlyx. Se autentica con una clave de API que generas en el panel y da a un flujo ocho operaciones sobre contactos, negocios y conversaciones, con la paginación por cursor ya resuelta.

Publicado en npm como n8n-nodes-pinlyx, con el código en GitHub bajo licencia MIT. Probado con n8n 1.60 y versiones posteriores sobre Node.js 20.15 o superior. npm · GitHub

El nodo habla con la misma API REST pública que usaría un script, así que todo lo que hace se puede reproducir con curl, y lo que no hace está a un nodo HTTP Request de distancia.

Qué aporta el nodo a un flujo

Tres recursos, elegidos porque son los que de verdad necesita una automatización. Todo lo que ves aquí lo impone la API, no el nodo.

Contactos, cinco operaciones

Crear, obtener, listar, actualizar y archivar. El listado filtra por búsqueda, plataforma, correo electrónico, ID externo y Updated Since, que es el filtro en el que se apoya una sincronización incremental.

Negocios, dos operaciones

Crea un negocio con título, monto, moneda, etapa, probabilidad, fecha prevista de cierre y notas. Lístalos con filtros por etapa, contacto y búsqueda en el título.

Conversaciones, solo lectura

Los hilos con actividad reciente en todos los canales conectados, de más nuevo a más antiguo. Cada fila incluye el ID del contacto, el canal, un indicador de no leído y un breve adelanto del último mensaje.

El ID externo evita duplicados

Guarda tu propio identificador en un contacto y, si el flujo se vuelve a ejecutar, la API lo rechaza con un HTTP 409 que indica qué registro ya existe, en lugar de crear en silencio una segunda copia de la misma persona.

Paginación por cursor integrada

Activa Return All y el nodo recorre todas las páginas por ti. Si lo dejas desactivado, fija un límite. Una página tiene como máximo 100 filas para contactos y negocios y 50 para conversaciones, así que una lista grande son muchas peticiones la pidas como la pidas.

Clave con permisos, verificada en el servidor

La credencial guarda una sola clave de API. Cada operación declara el permiso que necesita, así que una clave sin contacts:write hace fallar una creación con un 403 en lugar de aparentar que funciona sin cambiar nada.

Cómo instalar el nodo

El nodo está publicado en npm como n8n-nodes-pinlyx y se instala como cualquier nodo comunitario: desde dentro de n8n, no copiando archivos en un servidor.

  1. Abre Settings y luego Community Nodes. Necesitas la cuenta de propietario de la instancia. Una cuenta de miembro no puede instalar paquetes.
  2. Haz clic en Install y escribe n8n-nodes-pinlyx. Acepta el aviso sobre nodos comunitarios e instala. n8n descarga el paquete y el nodo aparece en la búsqueda del lienzo en pocos segundos.
  3. Añade el nodo de Pinlyx a un flujo. Te pide una credencial antes de dejarte elegir un recurso, así que eso es lo siguiente que debes crear.

O, en una instancia autoalojada, desde la línea de comandos:

npm install n8n-nodes-pinlyx
# then restart n8n

Una salvedad que conviene conocer antes de planificar nada: n8n Cloud solo ofrece los nodos comunitarios que el propio n8n ha revisado y verificado, y este paquete todavía no ha pasado esa revisión. Las instancias autoalojadas instalan cualquier paquete publicado. En Cloud, las mismas operaciones están disponibles con el nodo HTTP Request contra la API REST; preferimos decirlo claramente a esconderlo en la letra pequeña.

El paquete no declara dependencias en tiempo de ejecución. Cada petición pasa por el helper HTTP del propio n8n, que es lo que permite a la credencial añadir la cabecera Authorization y lo que mantiene la instalación ligera.

Cómo crear la credencial

El nodo se autentica con una clave de API de Pinlyx: una clave, una cabecera y ningún ida y vuelta de OAuth.

  1. En el panel de Pinlyx, abre Ajustes y luego Desarrolladores. Crea una clave y ponle el nombre del flujo que la va a usar, para saber qué deja de funcionar el día que la revoques.
  2. Concede solo los permisos que necesita ese flujo. Un flujo que escribe contactos necesita contacts:read y contacts:write. Un informe de negocios necesita deals:read. Las conversaciones se leen con contacts:read.
  3. Copia el token una sola vez. Las claves de producción empiezan por csk_live_ y las de prueba por csk_test_. El token completo se muestra al crearlo y nunca más; después, el panel solo enseña su prefijo.
  4. Añade una credencial Pinlyx API en n8n y pégalo. Deja Base URL en https://api.pinlyx.com salvo que apuntes a un entorno de staging, y ejecuta la prueba de la credencial.

La prueba de la credencial hace la llamada autenticada más barata que existe:

curl https://api.pinlyx.com/v1/me \
  -H "Authorization: Bearer csk_live_YOUR_KEY"

Las claves de API forman parte del plan Business. En Free y Pro no hay ninguna clave que generar, así que la credencial no tiene nada que guardar. Es el único requisito previo que vale la pena comprobar antes de instalar nada.

El límite por defecto es de 60 peticiones por minuto y por clave. Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset, y si te pasas recibes un HTTP 429 con un Retry-After en segundos. Como el límite va por clave y no por espacio de trabajo, un flujo atrapado en un bucle se frena a sí mismo en lugar de dejar sin margen a tus otras integraciones.

Ocho operaciones sobre tres recursos

Esta es la superficie completa, no una selección de lo mejor.

Cada operación corresponde exactamente a un endpoint de la API pública v1, así que nada de esto se comporta distinto de una petición que escribirías a mano.

  • Contact, Create. Necesita al menos un nombre, nombre de usuario, teléfono, correo electrónico o ID externo. En Additional Fields van el correo, el teléfono, el nombre de usuario, la plataforma, las notas y tu propio ID externo.
  • Contact, Get. Un contacto por su ID numérico.
  • Contact, Get Many. Filtros por búsqueda de texto, plataforma, correo electrónico, ID externo y Updated Since.
  • Contact, Update. Una actualización parcial: un campo que no añades a la colección se queda como está en lugar de vaciarse.
  • Contact, Delete. Archiva en lugar de borrar. El historial de mensajes y los negocios vinculados se conservan, igual que cuando haces la misma acción en el panel.
  • Deal, Create. El título es obligatorio. El monto, la moneda, la etapa, la probabilidad, la fecha prevista de cierre, las notas y el ID de contacto son opcionales.
  • Deal, Get Many. Filtros por etapa, contacto y búsqueda en el título. Aquí la etapa acepta won y lost, porque leer un negocio cerrado no tiene problema aunque escribirlo sí.
  • Conversation, Get Many. Las conversaciones con actividad reciente en todos los canales conectados, de más nueva a más antigua, cada una con un adelanto del último mensaje.

El campo de plataforma de un contacto acepta Telegram, WhatsApp, Instagram, LinkedIn, X y Email. Registra el canal por el que llegó la persona, que es como el CRM agrupa luego sus conversaciones.

Lo que no está en esa lista no está en el nodo. El envío de mensajes, las etiquetas, la puntuación de leads, las tareas, las facturas y las campañas existen en la API REST. Simplemente no forman parte de estas ocho operaciones.

Flujo uno: un formulario enviado se convierte en un contacto

Es el motivo más habitual para usar este nodo. Un cliente potencial rellena un formulario y el registro ya está en el CRM antes de que nadie abra una pestaña.

  1. Dispara el flujo con el formulario. Un Form Trigger de n8n, un nodo Webhook detrás de tu propio formulario o un nodo de Typeform o Google Forms. Sirve cualquier cosa que entregue un objeto JSON al siguiente nodo.
  2. Asigna los campos a Contact, Create. El nombre sale del campo de nombre, y en Additional Fields van el correo, el teléfono y las notas. Pon Platform en Email cuando el lead haya llegado sin un usuario de mensajería.
  3. Pon como External ID el ID del envío. Este es el campo que permite volver a ejecutar el flujo sin riesgo. Una segunda creación con el mismo ID externo se rechaza con un HTTP 409, y el cuerpo del error indica qué contacto ya existe, así que al repetir obtienes un aviso de duplicado y no una persona duplicada.
  4. Activa Continue On Fail cuando las repeticiones sean habituales. Con la opción activada, el 409 llega como un elemento con un mensaje de error y el resto del lote sigue adelante. Con ella desactivada, la ejecución se detiene, que es lo que quieres en la primera ejecución y no lo que quieres a las tres de la mañana.

Si necesitas un upsert de verdad en lugar de un 409, la API REST tiene un endpoint por lotes que busca coincidencias por ID externo, correo electrónico, teléfono o nombre de usuario y acepta hasta 200 filas por petición. El nodo no lo expone. Apunta un nodo HTTP Request a POST /v1/contacts/batch y obtendrás el mismo comportamiento con una llamada en lugar de doscientas.

Flujo dos: un negocio ganado se convierte en una factura

Merece la pena leer esto antes de construirlo, porque el diseño obvio es el equivocado.

Un negocio no se puede pasar a ganado desde la API de ninguna manera. Ganar un negocio registra un ingreso en el libro contable del CRM, así que esa transición se reserva a propósito para el panel, donde una persona la está viendo. El nodo lo refleja: Deal, Create rechaza las etapas won y lost, y no existe ninguna operación de actualización. Los negocios ganados se leen; no se escriben.

  1. Consulta los negocios ganados de forma programada. Un Schedule Trigger cada quince minutos que alimenta Pinlyx, Deal, Get Many con el filtro Stage en Won.
  2. Quédate solo con los que no has visto. Los negocios llegan ordenados del ID más alto al más bajo. Guarda el ID más alto que hayas procesado en los datos estáticos del flujo y descarta todo lo que sea igual o inferior, o escribe el ID del negocio en la referencia de la factura y deja que la herramienta contable rechace la repetición.
  3. Crea la factura. Pasa el título, el monto y la moneda al nodo de facturación que ya uses. El negocio incluye un ID de contacto, así que un Contact, Get delante te da la dirección de correo a la que enviarla.

Si quince minutos es demasiado lento, no acortes la consulta. Suscríbete: Pinlyx lanza un webhook saliente en deal.won, firmado con HMAC-SHA256 en una cabecera X-Webhook-Signature y con el nombre del evento en X-Webhook-Event. Apúntalo a un nodo Webhook de n8n y la factura sale segundos después de que alguien cierre el negocio, sin gastar nada de tu cupo de consultas. Lo mismo vale para contact.created, contact.updated y message.received.

Flujo tres: leer las conversaciones y repartirlas

Conversation, Get Many devuelve los hilos con actividad reciente en todos los canales conectados: Telegram, WhatsApp, Instagram, X, correo electrónico y el chat en vivo de la web en una sola lista. Cada fila incluye el ID del contacto, el canal, si está sin leer y hasta 160 caracteres del último mensaje.

  1. Trae la lista reciente de forma programada. Un límite de 50 cubre la mayoría de las bandejas de entrada. Quédate con las filas sin leer usando un nodo IF antes de gastar nada en ellas.
  2. Clasifica el adelanto. Pasa el texto del adelanto por el nodo de modelo que uses y pide una sola etiqueta: pregunta sobre precios, incidencia de soporte, spam o nada que hacer.
  3. Actúa según la etiqueta. Publica las preguntas sobre precios en el canal que vigila tu equipo de ventas, abre un ticket para las incidencias de soporte y guarda la clasificación con Contact, Update para que quede en el registro y no solo en el chat.

Antes de construirlo conviene conocer dos límites. El adelanto es solo un adelanto: el nodo no puede recorrer el hilo completo de mensajes, así que un clasificador solo ve el último mensaje. Además, el nodo no puede etiquetar un contacto ni enviar una respuesta. Ambas cosas existen en la API REST y en el servidor MCP; ninguna forma parte de estas ocho operaciones.

Paginación, límites y qué aspecto tiene un error

Tres comportamientos que deciden si un flujo sobrevive a su primera semana real.

  • La paginación es por cursor. Una respuesta de listado incluye las filas y un cursor a la página siguiente. Return All sigue ese cursor hasta que se acaban las páginas; un límite para antes. El servidor limita cada página a 100 filas para contactos y negocios y a 50 para conversaciones, así que Return All sobre 4000 contactos son 40 peticiones, no una.
  • El límite de peticiones va por clave. Sesenta peticiones por minuto por defecto. Si te pasas, recibes un HTTP 429 con Retry-After en segundos, y las tres cabeceras X-RateLimit de cada respuesta te dicen lo cerca que estabas antes de que ocurriera.
  • Los errores explican el motivo. 401 significa que la clave es incorrecta o está revocada. 403 significa que la clave es válida pero no tiene el permiso que declara la operación. 404 significa que el ID no pertenece a este espacio de trabajo, que es a propósito la misma respuesta que para un ID que no existe. 409 significa una colisión de ID externo e indica qué registro tiene ya ese ID.

Una respuesta de listado de la API sobre la que funciona el nodo:

{
  "items": [ { "Id": 812, "Name": "Sarah Lin", "Platform": "email" } ],
  "nextCursor": 764,
  "hasMore": true
}

Las sincronizaciones incrementales funcionan con Updated Since. Guarda la marca de tiempo de la última ejecución correcta, pásala en la siguiente y traerás solo los pocos contactos que han cambiado, no todos. Esa es la diferencia entre una sincronización nocturna que termina y otra que gasta todo su cupo en filas que nadie ha tocado.

Límites claros

Lo que este nodo no hace

Seis cosas que es mejor leer aquí que descubrir a mitad de construir un flujo que dependa de ellas.

No puede enviar mensajes

La API REST puede poner en cola un mensaje de Telegram o un mensaje directo de X, y el servidor MCP también. Esas operaciones no están en este nodo. Si un flujo tiene que llegar a un cliente, usa un nodo HTTP Request o uno de los nodos de canal del propio n8n.

No puede marcar un negocio como ganado

Ganar un negocio registra un ingreso en el libro contable, así que esa transición solo se hace desde el panel. El nodo crea negocios y los lista. No los cierra, y Create rechaza directamente las etapas won y lost.

No hay nodo disparador

Es un nodo de acción. Para iniciar un flujo a partir de algo que pasa en el CRM, registra un webhook saliente y recíbelo con el nodo Webhook de n8n. También puedes consultar con un Schedule Trigger, pero gasta cupo de peticiones que el webhook no gasta.

No etiqueta, no puntúa ni asigna

Las etiquetas, la puntuación de leads, la asignación de responsable, las tareas y los cambios de etapa en el embudo existen en la API REST. Ninguno forma parte de las ocho operaciones. Contact, Update escribe los campos básicos y nada más.

No toca el dinero

Ni facturas, ni asientos contables, ni pagos, ni reembolsos. Nada de este nodo mueve dinero en ninguna dirección, que es el mismo límite que marca el servidor MCP.

Necesita el plan Business

Las claves de API son una función del plan Business. En Free y Pro no hay ninguna clave que pegar en la credencial, así que el nodo no tiene con qué autenticarse, por bien instalado que esté.

Nodo, webhook o servidor MCP

Tres formas de conectar el mismo CRM, cada una adecuada para un trabajo distinto. La mayoría de los equipos acaba usando dos.

El nodo de n8n

Trabajo determinista con una programación o un disparador

Sabes exactamente qué tiene que pasar y cuándo. Llega un formulario y se crea un contacto. Se cierra un negocio y sale una factura. La lógica vive en un lienzo que todo tu equipo puede leer, y una ejecución fallida queda a la vista en la lista de ejecuciones con los datos que la provocaron.

Ideal cuando la regla es fija y el volumen, estable.

Webhooks salientes

Reaccionar en cuanto pasa algo

Registra un endpoint en el CRM y te enviará los eventos contact.created, contact.updated, message.received, deal.won y el resto. Firmados con HMAC-SHA256, reintentados con espera progresiva y repetibles desde un registro de entregas. Combínalo con un nodo Webhook de n8n y recibirás los datos al momento en lugar de consultarlos.

Ideal cuando la latencia importa más que la simplicidad.

El servidor MCP

Criterio, no fontanería

Un asistente de IA decide en el momento de la llamada con el hilo real delante, en lugar de seguir una regla escrita semanas antes. Herramientas, recursos y prompts sobre un único endpoint autenticado, con cada llamada limitada por los permisos de la clave.

Ideal cuando la respuesta depende de entender la situación.

Preguntas frecuentes sobre la integración con n8n

Las preguntas que surgen en la primera hora, respondidas con el comportamiento real.

Es un nodo comunitario de n8n publicado en npm como n8n-nodes-pinlyx. Instalado en una instancia de n8n, añade al lienzo de flujos un bloque de Pinlyx con ocho operaciones: crear, obtener, listar, actualizar y archivar un contacto; crear y listar negocios, y listar las conversaciones recientes. Se autentica con una clave de API de Pinlyx con permisos y no tiene dependencias en tiempo de ejecución.
En un n8n autoalojado, abre Settings, luego Community Nodes, haz clic en Install y escribe n8n-nodes-pinlyx. Necesitas la cuenta de propietario de la instancia. También puedes ejecutar npm install n8n-nodes-pinlyx en el directorio de datos de n8n y reiniciar el proceso, que es la vía cuando el instalador de nodos comunitarios está desactivado en tu instancia.
n8n Cloud solo ofrece nodos comunitarios que n8n ha revisado y verificado, y este paquete todavía no ha pasado esa revisión. En Cloud, las mismas operaciones están disponibles con el nodo HTTP Request apuntando a la API REST de Pinlyx con la misma clave bearer, lo que supone más configuración pero exactamente el mismo comportamiento.
Business. Las claves de API son una función del plan Business, así que los espacios de trabajo Free y Pro no pueden generar la clave que necesita la credencial. Todo lo demás del nodo es gratis: el paquete tiene licencia MIT y no se cobra nada por instalarlo ni por usarlo.
Por sí solo, no. Es un nodo de acción, no un nodo disparador. Para iniciar un flujo a partir de un evento del CRM, registra un webhook saliente en el panel y recíbelo con el nodo Webhook de n8n. Los webhooks se lanzan, entre otros, en contact.created, contact.updated, message.received y deal.won, van firmados con HMAC-SHA256 en una cabecera X-Webhook-Signature y se reintentan con espera progresiva.
En Contact, Create, pon como External ID un identificador estable propio para esa persona, como el ID del envío del formulario o el ID de cliente en tu tienda. Una segunda creación con el mismo ID externo se rechaza con un HTTP 409 y el cuerpo del error indica el ID del contacto que ya existe. Activa Continue On Fail para que una repetición informe de la colisión en lugar de detener la ejecución.
No. No hay ninguna operación de envío. El envío existe en la API REST y en el servidor MCP, protegido por permisos como telegram:send y social:write, pero se deja fuera de este nodo a propósito. Un flujo que tenga que llegar a una persona necesita un nodo HTTP Request o uno de los nodos de canal del propio n8n.
La petición falla con un HTTP 403 en lugar de aparentar que ha funcionado. Cada operación declara el único permiso que necesita: contacts:read para las lecturas, contacts:write para crear, actualizar y eliminar, y deals:read y deals:write para las operaciones de negocios. Los permisos se aplican en el servidor, así que restringir una clave es una limitación real y no una simple indicación.
Usa el filtro Updated Since en Contact, Get Many. Guarda la marca de tiempo de tu última ejecución correcta, pásala en la siguiente y la API devolverá solo los contactos modificados en ese momento o después. Combinado con Return All, es la base de una sincronización incremental y mantiene una tarea nocturna dentro del límite de peticiones por minuto.
Sí, con licencia MIT en GitHub, en Pinlyx/n8n-nodes-pinlyx. El nodo es un único archivo de TypeScript más la definición de la credencial, así que leerlo entero lleva unos minutos y te dice exactamente a qué endpoint llama cada operación.

Listo para empezar

Lleva tu CRM a tus flujos

Instala el nodo, genera una clave con dos permisos y deja que el primer formulario enviado llegue como contacto. A partir de ahí, todo es cuestión de arrastrar un nodo más al lienzo.

Plan gratis para siempre · Preparado para el RGPD · Sin tarjeta de crédito