Evolution API: Códigos QR que No Se Generan
Guía práctica para resolver el error de generación de QR codes en Evolution API (GitHub Issue #1761)
🎯 Solución Rápida
- Problema: Evolution API no genera códigos QR para WhatsApp
- Causa: Variable
CONFIG_SESSION_PHONE_VERSIONobsoleta - Solución: Cambiar imagen a
evoapicloud/evolution-api:homolog - Acción: Eliminar variable
CONFIG_SESSION_PHONE_VERSIONde tu configuración - Resultado: QR codes funcionando nuevamente ✅
🔴 El Problema
Si estás usando Evolution API y de repente los códigos QR dejaron de generarse, no estás solo. A partir del 13 de octubre de 2025, múltiples administradores reportaron este mismo problema:
- ❌ Al crear una instancia de WhatsApp, el código QR no aparece
- ❌ La instancia se queda en estado
"connecting"para siempre - ❌ El contador de QR muestra
count=0 - ❌ No hay forma de conectar nuevas instancias de WhatsApp
🔍 ¿Por Qué Sucede?
El problema está documentado en GitHub Issue #1761 del repositorio oficial de Evolution API.
La Causa Raíz
Si tienes configurada la variable de entorno CONFIG_SESSION_PHONE_VERSION con un valor específico (por ejemplo 2.3000.1023204200), WhatsApp la rechaza como incompatible con su protocolo actual.
¿Por qué? WhatsApp actualizó su sistema y las versiones hardcoded quedaron obsoletas.
Imágenes Afectadas
Las siguientes imágenes de Docker presentan este problema:
- ❌
atendai/evolution-api:v2.2.3(desactualizada) - ❌
evoapicloud/evolution-api:v2.3.4(sin fix)
✅ La Solución Paso a Paso
Paso 1: Identificar tu Configuración Actual
Revisa tu archivo docker-compose.yml o tu configuración de Docker y busca estas líneas:
# CONFIGURACIÓN PROBLEMÁTICA
services:
evolution-api:
image: atendai/evolution-api:v2.2.3 # ← Imagen vieja
environment:
- CONFIG_SESSION_PHONE_VERSION=2.3000.1023204200 # ← PROBLEMA
- CONFIG_SESSION_PHONE_CLIENT=TuEmpresa
- CONFIG_SESSION_PHONE_NAME=ChromePaso 2: Actualizar a la Imagen con Fix
Cambia la imagen Docker a la versión homolog que incluye la corrección:
# CONFIGURACIÓN CORREGIDA
services:
evolution-api:
image: evoapicloud/evolution-api:homolog # ← Nueva imagen
environment:
# CONFIG_SESSION_PHONE_VERSION=2.3000.1023204200 # ← COMENTADA/ELIMINADA
- CONFIG_SESSION_PHONE_CLIENT=TuEmpresa
- CONFIG_SESSION_PHONE_NAME=ChromeLa imagen
evoapicloud/evolution-api:homolog detecta automáticamente la versión compatible de WhatsApp, eliminando la necesidad de configurar CONFIG_SESSION_PHONE_VERSION manualmente.
Paso 3: Aplicar los Cambios
Si usas Docker Compose:
# Detener el servicio actual
docker-compose down
# Descargar la nueva imagen
docker-compose pull
# Iniciar con la nueva configuración
docker-compose up -dSi usas Docker Swarm:
# Actualizar el stack
docker stack deploy -c docker-compose.yml nombre_del_stackPaso 4: Verificar que Funciona
Una vez reiniciado el servicio:
- Crea una nueva instancia de WhatsApp desde la API
- Verifica que el código QR se genere correctamente
- El contador debería mostrar
count=1 - El estado de la instancia cambiará de
connectingaopenuna vez escanees el QR
📊 Antes y Después
| Aspecto | Antes (Con Problema) | Después (Solucionado) |
|---|---|---|
| Generación de QR | ❌ count=0 | ✅ count=1 |
| Estado de instancia | ❌ connecting (permanente) | ✅ open (conectado) |
| Imagen Docker | atendai/evolution-api:v2.2.3 | evoapicloud/evolution-api:homolog |
| CONFIG_SESSION_PHONE_VERSION | Hardcoded (obsoleto) | Auto-detectado ✨ |
⚠️ Notas Importantes
Sobre la Imagen "homolog"
La imagen homolog es una versión de desarrollo que incluye correcciones recientes. Una vez que Evolution API lance una versión estable (ej: v2.3.5) que incluya este fix, te recomendamos migrar a esa versión.
Monitorea: Releases de Evolution API
🎯 ¿Por Qué Funcionaba Antes y Ahora No?
WhatsApp actualiza constantemente su protocolo de conexión. Lo que funcionaba hace un mes puede dejar de funcionar si usas valores hardcoded que quedan obsoletos.
Lección Aprendida
En lugar de definir versiones específicas manualmente (CONFIG_SESSION_PHONE_VERSION), es mejor dejar que la aplicación detecte automáticamente la versión compatible. Esto hace tu instalación más resiliente a cambios en el protocolo WhatsApp.
🔗 Referencias
- 📖 GitHub Issue #1761 - QR Code Generation Failure
- 📦 Evolution API en Docker Hub
- 📚 Documentación Oficial Evolution API
💡 ¿Necesitas Ayuda?
Si después de aplicar estos pasos sigues teniendo problemas, o necesitas ayuda con la configuración de Evolution API en tu infraestructura, podemos ayudarte.
Soporte Técnico
Especialistas en infraestructura WhatsApp Business con Evolution API
Contactar por WhatsApp