Zolutium puede conectarse directamente con Pipefy para automatizar el envío de información entre ambas plataformas.
En este ejemplo crearemos una integración sencilla:
Cada vez que se crea un contacto en Zolutium, automáticamente se crea una nueva tarjeta en Pipefy.
La información que enviaremos será:
Nombre.
Correo electrónico.
Número de teléfono.
El flujo final será:
Nuevo contacto en Zolutium ↓ Workflow ↓ Custom Webhook ↓ API GraphQL de Pipefy ↓ Nueva tarjeta en Pipefy
Para realizar la integración necesitaremos preparar primero Pipefy y posteriormente configurar Zolutium.
1. Preparar el Pipe en Pipefy
Lo primero es definir en qué Pipe se crearán las nuevas tarjetas.
En nuestro ejemplo utilizaremos un Pipe llamado:
test
Al entrar al Pipe, revisa la URL del navegador.
Por ejemplo:
https://app.pipefy.com/pipes/307306462
El número que aparece después de /pipes/ corresponde al Pipe ID.
En nuestro ejemplo:
Pipe ID: 307306462
📌 Guarda este número. Lo necesitaremos posteriormente dentro del webhook.
2. Crear los campos que recibirá Pipefy
Dentro del Pipe entra a:
Formulario → Editar
Crea los campos que recibirán la información proveniente de Zolutium.
Para esta integración utilizaremos únicamente tres:
NOMBRE
Tipo recomendado:
Texto corto
CORREO ELECTRONICO
Tipo recomendado:
NUMERO
Tipo recomendado:
Teléfono
Durante las primeras pruebas puede ser conveniente mantenerlos como campos no obligatorios.
Esto facilita las pruebas si algún contacto todavía no tiene correo o teléfono.
3. Obtener los identificadores internos de los campos
Pipefy no utiliza únicamente el nombre que vemos visualmente en el formulario.
Cada campo tiene un identificador interno llamado:
field_id
Para consultarlo podemos utilizar GraphiQL.
Ejecuta una consulta como:
{ pipe(id: 307306462) { id name start_form_fields { id label type required } } }En nuestro ejemplo Pipefy respondió con los siguientes identificadores:
NOMBRE field_id: nombre CORREO ELECTRONICO field_id: correo_electronico NUMERO field_id: numero
Estos valores serán utilizados posteriormente para enviar la información desde Zolutium.
4. Realizar una prueba directamente en Pipefy 🧪
Antes de configurar Zolutium es recomendable comprobar que Pipefy puede crear correctamente una tarjeta mediante API.
En GraphiQL podemos ejecutar:
mutation { createCard(input: { pipe_id: 307306462, title: "Cliente Prueba", fields_attributes: [ { field_id: "nombre", field_value: "Cliente Prueba" }, { field_id: "correo_electronico", field_value: "[email protected]" }, { field_id: "numero", field_value: "+593999999999" } ] }) { card { id title } } }Pipefy utiliza createCard para crear una tarjeta y fields_attributes para enviar valores a los campos correspondientes.
Si todo está correctamente configurado, aparecerá una nueva tarjeta en el Pipe.
✅ Si la tarjeta aparece, sabemos que:
El Pipe ID es correcto.
Los Field IDs son correctos.
Los campos aceptan los valores enviados.
Pipefy puede crear la tarjeta.
Ahora podemos continuar con la autenticación.
5. Obtener el token de Pipefy 🔐
Este paso es fundamental.
El token es la credencial que permite que Zolutium se identifique ante Pipefy y tenga autorización para utilizar su API.
Sin un token válido, Pipefy rechazará la solicitud.
Opción utilizada para una prueba rápida
Si tu cuenta todavía tiene disponible la generación de Personal Access Tokens, puedes ingresar directamente a:
https://app.pipefy.com/tokens
Luego:
Haz clic en Generate new token.
Escribe una descripción que permita identificar para qué se utilizará.
Por ejemplo:
ZLT PIPEFY TEST
Haz clic en Save.
Copia el token generado.
Guárdalo en un lugar seguro.
La documentación de Pipefy mantiene la ruta /tokens para generar Personal Access Tokens. Sin embargo, la documentación actual también identifica este método como obsoleto y recomienda utilizar Service Accounts para nuevas integraciones.
⚠️ Nunca publiques el token en un artículo, captura de pantalla, correo o conversación pública.
En documentación siempre debes representarlo de esta manera:
TU_TOKEN_DE_PIPEFY
6. ¿Qué utilizar en una integración de producción?
Para integraciones nuevas y de producción, Pipefy recomienda utilizar una:
Service Account
Las Service Accounts separan las credenciales de integración de las cuentas personales de usuarios y utilizan el flujo client_credentials.
Una Service Account proporciona:
Client ID Client Secret Token Endpoint
Con esos datos se solicita un token de acceso.
Este mecanismo es más adecuado para integraciones permanentes y administradas.
📌 Para una prueba sencilla como la desarrollada en este ejemplo puede utilizarse el mecanismo de token disponible en la cuenta, pero para una implementación definitiva conviene revisar la migración a Service Account.
7. Guardar el token de forma segura en Zolutium
No recomendamos escribir el token directamente dentro del cuerpo del webhook.
Dentro de la configuración del Custom Webhook, crea o selecciona una clave segura.
Puedes asignarle un nombre como:
ZLT PIPEFY TEST
En el valor de esa clave debes guardar:
TU_TOKEN_REAL_DE_PIPEFY
Después, cuando configuremos la autorización, seleccionaremos esa clave.
De esta manera el token no tendrá que mostrarse directamente dentro de la configuración del webhook.
8. Crear el Workflow en Zolutium ⚙️
Ahora entra a:
Zolutium → Automatizaciones / Workflows
Crea un nuevo Workflow.
Como activador selecciona:
Contacto Creado
Nuestro flujo comenzará así:
Contacto Creado ↓ Acción
Después agrega una nueva acción:
Custom Webhook
El flujo quedará:
Contacto Creado ↓ Custom Webhook ↓ Final
9. Configurar el Custom Webhook
Ahora debemos indicarle a Zolutium a dónde enviar la información.
Utiliza:
Método: POST
La API GraphQL de Pipefy utiliza un endpoint único:
https://api.pipefy.com/graphql
Por lo tanto, la configuración será:
URL: https://api.pipefy.com/graphql Método: POST
10. Configurar la autorización
En la sección:
AUTORIZACIÓN
selecciona:
Bearer Token
Después selecciona la clave que creamos anteriormente:
ZLT PIPEFY TEST
La lógica internamente será:
Authorization: Bearer TU_TOKEN_DE_PIPEFY
Pipefy requiere autenticación para acceder a su API y utiliza el esquema Bearer para enviar el token.
⚠️ Si Zolutium ya tiene seleccionada la opción Bearer Token, no escribas manualmente:
Bearer TU_TOKEN
Debes introducir solamente el token dentro de la clave.
11. Configurar el tipo de contenido
En:
TIPO DE CONTENIDO
selecciona:
application/json
La configuración hasta este punto debe quedar:
Método: POST URL: https://api.pipefy.com/graphql Autorización: Bearer Token Token: ZLT PIPEFY TEST Content-Type: application/json
12. Configurar el cuerpo del mensaje
Ahora debemos indicarle a Pipefy qué debe crear y qué información debe colocar dentro de la tarjeta.
En nuestro Pipe utilizaremos:
Pipe ID: 307306462 NOMBRE: nombre CORREO: correo_electronico TELÉFONO: numero
En el cuerpo del mensaje utilizamos:
{ "query": "mutation { createCard(input: { pipe_id: 307306462, title: \"{{contact.name}}\", fields_attributes: [ { field_id: \"nombre\", field_value: \"{{contact.name}}\" }, { field_id: \"correo_electronico\", field_value: \"{{contact.email}}\" }, { field_id: \"numero\", field_value: \"{{contact.phone}}\" } ] }) { card { id title } } }" }13. ¿Qué información está tomando Zolutium?
Las siguientes variables son dinámicas:
{{contact.name}} {{contact.email}} {{contact.phone}}Por ejemplo, si en Zolutium tenemos:
Nombre: Patrick Ejemplo Correo: [email protected] Teléfono: +593999999999
Zolutium enviará esos datos a Pipefy.
Pipefy creará una tarjeta cuyo título será:
Patrick Ejemplo
Y dentro tendremos:
NOMBRE: Patrick Ejemplo CORREO ELECTRONICO: [email protected] NUMERO: +593999999999
14. Probar la integración 🧪
Antes de publicar el Workflow, realiza una prueba.
Selecciona un contacto que tenga:
Nombre Correo Teléfono
Después ejecuta:
Probar flujo de trabajo
El proceso debería ser:
Contacto de prueba ↓ Workflow ejecutado ↓ Webhook enviado ↓ Pipefy recibe la solicitud ↓ Nueva tarjeta
En nuestra prueba, el webhook se ejecutó sin errores y la tarjeta apareció correctamente dentro del Pipe test.
🎉 Esto confirma que la integración está funcionando.
15. Verificar siempre la tarjeta en Pipefy
Que el Webhook indique una ejecución correcta es una buena señal, pero recomendamos realizar una segunda comprobación.
Ve a:
Pipefy → Pipe test → Kanban
Busca la nueva tarjeta.
Ábrela y verifica:
NOMBRE CORREO ELECTRONICO NUMERO
Los tres datos deben coincidir con el contacto enviado desde Zolutium.
Solución de problemas 🛠️
❌ Error: Unauthorized
Si Pipefy responde con un error de autorización, revisa primero el token.
Las causas más comunes son:
Token incorrecto.
Token vencido.
Token revocado.
Token mal copiado.
Credencial sin permisos sobre el Pipe.
Método de autenticación que Pipefy ya no admite.
Pipefy identifica estos escenarios dentro de su documentación de errores Unauthorized.
Comprueba:
Authorization: Bearer Token
y confirma que la clave seleccionada contenga el token correcto.
❌ GraphiQL muestra “Unauthorized”
Si al intentar utilizar GraphiQL aparece:
Unauthorized You are not authorized to access this page
no significa necesariamente que tu consulta GraphQL esté mal.
Primero revisa:
Que hayas iniciado sesión en Pipefy.
Que tengas acceso al Pipe.
Que la cuenta tenga los permisos necesarios.
Que estés utilizando un método de autenticación admitido.
Una vez resuelto el acceso, vuelve a ejecutar la consulta.
❌ No se crea ninguna tarjeta
Revisa estos cinco puntos:
1. Método = POST 2. URL = https://api.pipefy.com/graphql 3. Bearer Token configurado 4. Pipe ID correcto 5. JSON correctamente escrito
Después revisa los registros de ejecución de Zolutium.
❌ El Webhook se ejecutó, pero Pipefy no hizo lo esperado
Con GraphQL hay una consideración importante:
Una respuesta HTTP 200 no significa necesariamente que toda la operación GraphQL haya sido exitosa. Pipefy explica que una solicitud puede devolver HTTP 200 y aun así incluir errores de aplicación dentro de la respuesta GraphQL.
Por eso debes revisar también el contenido de la respuesta.
Busca algo como:
"errors": [...]
Si aparece errors, revisa el mensaje que devuelve Pipefy.
❌ La tarjeta aparece pero no tiene correo
Comprueba que:
{{contact.email}}tenga información dentro del contacto de Zolutium.
También confirma que el Field ID sea:
correo_electronico
y no solamente:
CORREO ELECTRONICO
El primero es el identificador interno; el segundo es únicamente la etiqueta visible.
❌ El teléfono no aparece
Revisa:
{{contact.phone}}y verifica que Pipefy esté recibiendo el valor en:
field_id: numero
También comprueba que el contacto tenga teléfono antes de ejecutar el Workflow.
❌ La tarjeta se crea varias veces
Cada ejecución de:
createCard
crea una nueva tarjeta.
Por eso, si ejecutas cuatro veces la misma prueba, puedes obtener cuatro tarjetas iguales.
Esto no significa que la integración esté fallando.
Significa que la solicitud fue ejecutada cuatro veces.
Para producción se recomienda controlar cuándo entra un contacto al Workflow mediante:
Tags.
Filtros.
Condiciones.
Origen del lead.
Estados específicos.
❌ Todos los contactos se están enviando a Pipefy
Si el activador está configurado como:
Contacto Creado
sin ningún filtro, todos los contactos nuevos podrán entrar al Workflow.
Si solo deseas enviar determinados contactos, agrega una condición.
Por ejemplo:
Contacto Creado + Tag contiene: Enviar a Pipefy
Así puedes controlar exactamente qué contactos deben crear una tarjeta.
Seguridad del token 🔐
El token debe considerarse una contraseña.
Nunca debe aparecer en:
Capturas públicas.
Artículos de soporte.
Documentos compartidos.
Videos públicos.
Correos sin protección.
Código publicado.
En cualquier documentación utiliza:
TU_TOKEN_DE_PIPEFY
y nunca el valor real.
Si sospechas que un token fue expuesto, revócalo y genera una nueva credencial.
Resultado final ✅
Una vez finalizada la configuración tendremos:
ZOLUTIUM Nuevo contacto ↓ WORKFLOW Contacto Creado ↓ CUSTOM WEBHOOK POST + Bearer Token ↓ PIPEFY GRAPHQL API createCard ↓ PIPE TEST Nueva tarjeta
La tarjeta contendrá:
Nombre Correo electrónico Teléfono
Todo el proceso ocurre automáticamente y sin necesidad de utilizar una plataforma intermediaria.
Conclusión 🎯
La integración directa entre Zolutium y Pipefy permite convertir automáticamente nuevos contactos en tarjetas de Pipefy utilizando solamente un Workflow, un Custom Webhook y la API GraphQL.
La configuración puede entenderse en cuatro grandes etapas:
1. Preparar Pipefy 2. Obtener IDs y credenciales 3. Configurar Zolutium 4. Probar y validar
El orden es importante.
Primero comprobamos que Pipefy puede crear una tarjeta, después obtenemos la credencial necesaria para autenticarnos y finalmente conectamos Zolutium mediante el Custom Webhook.
Una vez realizada una prueba exitosa, el Workflow puede publicarse y comenzar a enviar contactos automáticamente. 🚀