Agencia de Marketing Digital y Mercadeo Relacional en Miami y LATAM: Dysruptia, tu socio estratégico para el éxito en línea

¡Hablemos!

+573009135392

Menú
  1. Home
  2. IA
Cómo Solucionar el Problema de Códigos QR en Evolution API con Docker Guía técnica paso a paso
Nilson Portocarrero
octubre 12, 2025

Cómo Solucionar el Problema de Códigos QR en Evolution API con Docker Guía técnica paso a paso


Tabla de Contenidos

  1. Introducción
  2. ¿Qué es Evolution API?
  3. El Problema: QR No Generado
  4. ¿Por Qué Ocurre Este Problema?
  5. La Solución: Construir Desde el Código Fuente
  6. Prerrequisitos
  7. Guía Paso a Paso
  8. Verificar la Solución
  9. Mantenimiento y Actualizaciones
  10. Solución de Problemas Comunes
  11. Conclusión

Introducción

Si has estado trabajando con Evolution API para integrar WhatsApp en tus aplicaciones y te has encontrado con el frustrante problema de que no se genera el código QR al intentar vincular una nueva instancia con un número de teléfono, no estás solo. Este es un problema común que afecta a muchos desarrolladores que utilizan las imágenes Docker oficiales de Evolution API.

En este artículo te mostraré paso a paso cómo resolví este problema construyendo Evolution API directamente desde el código fuente en GitHub, obteniendo así la versión más reciente y funcional. Esta guía está diseñada para que cualquier persona, incluso sin experiencia avanzada en Docker, pueda seguirla y resolver el problema en minutos.

¿Qué es Evolution API?

Evolution API es una solución de código abierto que permite integrar WhatsApp en aplicaciones y sistemas mediante una API REST. Es especialmente popular entre desarrolladores que necesitan:

  • Enviar y recibir mensajes de WhatsApp programáticamente
  • Crear chatbots y automatizaciones de WhatsApp
  • Integrar WhatsApp con CRMs, sistemas de tickets y otras herramientas empresariales
  • Gestionar múltiples instancias de WhatsApp desde una sola API centralizada

El Problema: QR No Generado

Al intentar crear una nueva instancia en Evolution API para vincular un número de WhatsApp, el sistema simplemente no genera el código QR necesario para completar la autenticación. Esto hace imposible conectar nuevas instancias de WhatsApp a través de la API.


Pantalla de Evolution API mostrando la ausencia del código QR

¿Por Qué Ocurre Este Problema?

La causa principal es que las imágenes Docker oficiales en Docker Hub están desactualizadas. Específicamente, las versiones públicas como atendai/evolution-api:homolog se quedaron en la versión 2.2.3, que tiene bugs conocidos relacionados con la generación de códigos QR.

Mientras tanto, el repositorio oficial en GitHub ya tiene versiones más recientes (2.3.5 y superiores) que han corregido estos problemas, pero estas versiones actualizadas no están disponibles como imágenes pre-construidas en Docker Hub.

⚠️ Nota Importante: Este problema NO está relacionado con tu configuración, tus credenciales o tu servidor. Es un problema de la versión del software que se soluciona actualizando a una versión más reciente desde el código fuente oficial.

La Solución: Construir Desde el Código Fuente

La solución es construir la imagen Docker de Evolution API directamente desde el código fuente de GitHub, usando la versión 2.3.5 (o la más reciente disponible). Este proceso es más sencillo de lo que parece y te llevará aproximadamente 10-15 minutos.

Prerrequisitos

Antes de comenzar, asegúrate de tener:

  • Docker instalado en tu servidor o máquina local (versión 20.10 o superior recomendada)
  • Docker Compose instalado (si estás usando docker-compose.yml para gestionar contenedores)
  • Git instalado para clonar el repositorio de GitHub
  • Acceso SSH a tu servidor (si trabajas en un servidor remoto)
  • Tu instalación actual de Evolution API funcionando (aunque no genere QR)
  • Al menos 2GB de espacio libre en disco para construir la imagen

Terminal mostrando Docker y Git instalados correctamente
Verificación de Docker y Git instalados en el sistema

Guía Paso a Paso

1 Clonar el Repositorio de Evolution API

Primero, vamos a descargar el código fuente oficial de Evolution API desde GitHub. Este paso lo haremos en el directorio home de tu usuario (~), lo cual mantendrá todo organizado.

# Navegar al directorio home
cd ~

# Clonar el repositorio oficial de Evolution API
git clone https://github.com/EvolutionAPI/evolution-api.git

# Entrar al directorio clonado
cd evolution-api

💡 Tip: Este directorio es solo temporal para construir la imagen. No afectará tu instalación actual de Evolution API que está corriendo en producción.

Terminal mostrando el proceso de clonación con git clone
Clonación del repositorio Evolution API desde GitHub

2 Seleccionar la Versión 2.3.5

Ahora vamos a ver todas las versiones disponibles y seleccionar la versión 2.3.5, que es estable y tiene el problema del QR resuelto.

# Ver las últimas 20 versiones disponibles
git tag | tail -20

# Hacer checkout de la versión 2.3.5
git checkout 2.3.5

📋 Nota: Si ves una versión más reciente que 2.3.5 en la lista (por ejemplo, 2.3.6 o 2.4.0), puedes usar esa en su lugar. Solo asegúrate de usar el mismo número de versión consistentemente en todos los pasos siguientes.

3 Construir la Imagen Docker

Este es el paso más importante. Vamos a construir la imagen Docker personalizada desde el código fuente. Este proceso puede tardar entre 5 y 15 minutos dependiendo de la velocidad de tu conexión a internet y los recursos de tu servidor.

# Construir la imagen Docker
# Reemplaza 'tuusuario' con tu nombre de usuario de Docker Hub
# O usa cualquier nombre que quieras para tu imagen
docker build -t tuusuario/evolution-api:2.3.5 .

# Ejemplo real usado en producción:
docker build -t dysruptia/evolution-api:2.3.5 .

Explicación del comando:

  • docker build: Comando para construir una imagen Docker desde un Dockerfile
  • -t tuusuario/evolution-api:2.3.5: Le da un nombre (tag) a tu imagen para identificarla
  • .: Indica que el Dockerfile está en el directorio actual

Terminal mostrando el proceso de construcción de Docker con las capas
Proceso de construcción de la imagen Docker mostrando las diferentes capas

Verás muchas líneas de texto mientras Docker descarga dependencias y construye la imagen. Esto es completamente normal. Espera pacientemente hasta que veas un mensaje similar a:

Successfully built 8a33d38dedcb
Successfully tagged dysruptia/evolution-api:2.3.5

Para verificar que la imagen se construyó correctamente, ejecuta:

docker images | grep tuusuario/evolution-api

Deberías ver algo como:

dysruptia/evolution-api    2.3.5    8a33d38dedcb    2 minutes ago    1.36GB

4 Actualizar Tu Archivo docker-compose.yml

Ahora vamos a actualizar tu instalación actual de Evolution API para que use la nueva imagen que acabas de construir.

# Navegar a tu directorio de Evolution API en producción
# Reemplaza la ruta con tu directorio real
cd /home/ubuntu/evolution-api

# Hacer un backup del archivo actual (por seguridad)
cp docker-compose.yml docker-compose.yml.backup

Ahora edita el archivo docker-compose.yml:

nano docker-compose.yml

Busca la sección de evolution-api y cambia solo la línea de la imagen:

ANTES:

evolution-api:
  container_name: evolution_api
  image: atendai/evolution-api:homolog  # ← Imagen antigua desactualizada
  # ... resto de la configuración sin cambios

DESPUÉS:

evolution-api:
  container_name: evolution_api
  image: dysruptia/evolution-api:2.3.5  # ← Tu nueva imagen construida
  # ... resto de la configuración sin cambios

Para guardar en nano: Presiona Ctrl+O, luego Enter, y finalmente Ctrl+X para salir del editor.

⚠️ Importante: Asegúrate de usar exactamente el mismo nombre de imagen que usaste en el Paso 3. Si usaste un nombre diferente a ‘dysruptia/evolution-api:2.3.5’, usa ese nombre aquí para mantener consistencia.

5 Reiniciar Evolution API

Finalmente, vamos a reiniciar el contenedor de Evolution API para que use la nueva imagen construida.

# Detener el contenedor actual de Evolution API
docker-compose stop evolution-api

# Eliminar el contenedor (NO elimina tus datos ni configuraciones)
docker-compose rm -f evolution-api

# Iniciar Evolution API con la nueva imagen
docker-compose up -d evolution-api

🛡️ No te preocupes: El comando rm solo elimina el contenedor, NO tus datos. Toda tu información, configuraciones, instancias de WhatsApp y bases de datos están guardadas en volúmenes Docker persistentes que permanecen intactos.

Para verificar que todo está funcionando correctamente, revisa los logs en tiempo real:

docker-compose logs -f evolution-api

Deberías ver mensajes indicando que Evolution API está iniciando correctamente. Presiona Ctrl+C para salir de la visualización de logs.

Logs de Docker mostrando Evolution API iniciando correctamente
Logs del contenedor mostrando inicio exitoso de Evolution API versión 2.3.5

Verificar que la Solución Funciona

¡Momento de la verdad! Ahora vamos a verificar que el código QR se genera correctamente.

  1. Accede a tu panel de Evolution API (generalmente en http://tu-servidor:8080 o el puerto configurado)
  2. Crea una nueva instancia de WhatsApp desde la interfaz web
  3. ¡El código QR debería aparecer inmediatamente!
  4. Escanea el código QR con tu teléfono desde la aplicación de WhatsApp
  5. La instancia debería conectarse exitosamente en segundos

Código QR generado exitosamente en Evolution API
Código QR generado correctamente después de la actualización

✅ Si el QR aparece y puedes conectar tu WhatsApp exitosamente, ¡felicitaciones! Has solucionado el problema de forma definitiva.

Mantenimiento y Actualizaciones Futuras

Ahora que has construido Evolution API desde el código fuente, aquí hay algunos consejos para mantenerlo actualizado y optimizado:

1. Guardar la Imagen (Opcional pero Recomendado)

Puedes hacer un backup de tu imagen construida por si necesitas restaurarla en otro servidor:

docker save dysruptia/evolution-api:2.3.5 | gzip > ~/evolution-api-2.3.5-backup.tar.gz

2. Actualizar a Nuevas Versiones

Cuando Evolution API lance una nueva versión y quieras actualizarte:

cd ~/evolution-api
git fetch --tags
git checkout 2.4.0  # Reemplaza con la nueva versión disponible
docker build -t dysruptia/evolution-api:2.4.0 .

# Luego actualiza tu docker-compose.yml con la nueva versión y reinicia

3. Documentar Tu Configuración

Mantén un archivo de notas con la siguiente información para referencia futura:

  • Versión actual de Evolution API que estás usando en producción
  • Fecha de construcción de la imagen
  • Cualquier personalización que hayas hecho en el código
  • Problemas resueltos y sus soluciones específicas
  • Variables de entorno personalizadas

Solución de Problemas Comunes

Problema: ‘Permission denied’ al ejecutar docker build

Solución: Tu usuario necesita permisos para ejecutar comandos Docker sin sudo. Ejecuta:

sudo usermod -aG docker $USER
newgrp docker

# Verifica que funciona sin sudo
docker ps

Problema: La construcción se queda atascada o muy lenta

Solución: Esto es normal si tu conexión a internet es lenta. Docker está descargando todas las dependencias necesarias de Node.js y otras librerías. Dale tiempo (hasta 15-20 minutos en conexiones lentas). Puedes verificar el progreso con docker system df.

Problema: Error ‘no space left on device’

Solución: Tu servidor se quedó sin espacio en disco. Limpia imágenes y contenedores antiguos que ya no uses:

# Limpia todo lo que no se está usando (¡cuidado con este comando!)
docker system prune -a

# O limpia selectivamente solo imágenes sin usar
docker image prune -a

Problema: Aún no aparece el QR después de actualizar

Solución: Verifica los siguientes puntos en orden:

  • Confirma que estás usando la imagen correcta: docker-compose config | grep image
  • Verifica que el contenedor se reinició: docker-compose ps
  • Revisa los logs buscando errores: docker-compose logs evolution-api | grep -i error
  • Intenta crear una instancia completamente nueva (no reutilizar una existente)
  • Verifica las variables de entorno, especialmente CONFIG_SESSION_PHONE_VERSION

Conclusión

El problema de los códigos QR que no se generan en Evolution API es frustrante, pero como has visto, tiene una solución directa y definitiva: construir la imagen Docker desde el código fuente oficial en GitHub para obtener la versión más reciente y funcional (2.3.5 o superior).

Esta guía te ha mostrado paso a paso cómo hacerlo, y aunque el proceso puede parecer técnico al principio, en realidad es bastante sencillo y solo toma unos 10-15 minutos. Lo mejor de todo es que una vez que has construido tu propia imagen, tienes control total sobre la versión que usas y puedes actualizarla cuando quieras, sin depender de imágenes desactualizadas en Docker Hub.

Los beneficios de esta solución incluyen:

  • ✅ Códigos QR funcionando al 100%
  • ✅ Control total sobre las actualizaciones
  • ✅ Acceso a las últimas correcciones de bugs
  • ✅ Mejor rendimiento y estabilidad
  • ✅ Posibilidad de personalizar el código si lo necesitas

Si esta guía te ayudó, considera compartirla con otros desarrolladores que puedan estar enfrentando el mismo problema. La comunidad de código abierto se fortalece cuando compartimos soluciones y aprendemos juntos.

Recursos Adicionales

Enlaces Útiles