Cómo conectar WordPress con Mautic (API OAuth2)

Para que tu web pueda enviar contactos a Mautic, primero hay que presentarlas: Mautic tiene que dar permiso a tu WordPress para crear y actualizar contactos. Se hace con la API de Mautic y el sistema de autorización OAuth2, el mismo tipo de conexión segura que usas cuando entras en una web "con tu cuenta de Google".

Solo tienes que hacerlo una vez. Después, el plugin mantiene la conexión activa por su cuenta.

Antes de empezar necesitas:

• El plugin instalado y, si es la versión PRO, con la licencia activada (Instalación y licencia).
• Acceso de administrador a tu Mautic.

1. Preparar Mautic: crear las credenciales de la API

1.1 Activar la API

Nota: Mautic puede estar en español o en inglés. Te indicamos los nombres de los menús en español y, entre paréntesis, en inglés, que es como aparecen en las capturas.

1. Entra en tu Mautic y abre Ajustes (Settings, la rueda dentada de arriba a la derecha) → Configuración (Configuration).
2. Ve a la sección Ajustes de API (API Settings).
3. Activa API habilitada (API enabled) y el protocolo OAuth 2.
4. Pulsa Guardar y cerrar (Save & Close).

Nota: si la API ya estaba activada (por ejemplo, porque usas otra integración), no tienes que tocar nada aquí.

1.2 Copiar la dirección de retorno del plugin

Mautic necesita saber a qué dirección de tu web debe volver después de autorizar la conexión. Esa dirección te la da el plugin:

1. En WordPress, ve a IndedLabs → Mautic PRO (o Mautic FREE) → Ajustes de Conexión.
2. Busca el campo OAuth Callback URL ("Copia esta URL y péguela en la configuración de OAuth en Mautic.").
3. Cópiala. La necesitas en el paso siguiente.

1.3 Crear las credenciales

1. En Mautic, ve a Ajustes → Credenciales API (API Credentials) y pulsa Nuevo (New).
2. En Protocolo de autorización (Authorisation Protocol), elige OAuth 2.
3. Ponle un Nombre (Name) que te ayude a reconocerla, por ejemplo Integración con WordPress.
4. En URI de redirección (Redirect URI), pega la OAuth Callback URL que copiaste del plugin.
5. Pulsa Guardar (Save).

Al guardar, Mautic te muestra tus credenciales: el ID del cliente (Client ID, también llamado Public Key) y la Clave secreta del cliente (Client Secret o Secret Key). Déjalas a mano, las necesitas en el siguiente paso.

Importante: el Client Secret es como una contraseña. No lo compartas ni lo publiques.

2. Conectar el plugin

Vuelve a WordPress, a Ajustes de Conexión:

1. En Mautic URL, escribe la dirección de tu Mautic, tal como la ves en el navegador pero sin nada detrás. Por ejemplo: https://mautic.tudominio.com.
2. Pega el Client ID y el Client Secret que te dio Mautic.
3. Pulsa Guardar cambios.
4. En la sección Autenticación OAuth, pulsa Conectar/Reconectar con Mautic.
5. Se abre la pantalla de Mautic pidiéndote que autorices el acceso. Si no tenías la sesión abierta en Mautic, primero te pedirá tu usuario y contraseña. Acepta.
6. Mautic te devuelve al plugin. El Estado debe mostrar Conectado.

¡Listo! Tu WordPress ya habla con Mautic.

Nota: una vez guardados, el Client ID y el Client Secret se muestran ocultos por seguridad. Si no los cambias, déjalos como están: se mantienen los guardados.

Nota: el usuario de Mautic con el que autorizas la conexión es el que "firma" todo lo que hace el plugin en Mautic. Usa un usuario administrador: algunas funciones (como crear campos personalizados o el aviso de bajas de la versión PRO) necesitan permisos de administración.

3. La conexión se mantiene sola

Mautic no da un permiso para siempre: entrega un token (una llave temporal) que caduca cada poco tiempo, normalmente en una o dos horas. El plugin lo renueva automáticamente con las tareas programadas de WordPress, así que no tienes que volver a conectar:

• Versión FREE: renueva el token cada hora.
• Versión PRO: comprueba el token cada 30 minutos y lo renueva antes de que caduque. Además, las visitas normales a tu web nunca esperan a Mautic: la renovación se hace siempre en segundo plano.

3.1 Cron externo para que sea puntual (sólo PRO)

Las tareas programadas de WordPress solo se ejecutan cuando alguien visita la web. En webs con poco tráfico pueden retrasarse. Para que la renovación sea puntual pase lo que pase, puedes programarla desde tu hosting:

1. En Ajustes de Conexión, sección Renovación automática del token (Cron), pulsa Copiar junto a la URL del cron.
2. En el cPanel de tu hosting, ve a Trabajos de cron y crea una tarea cada 30 minutos.
3. Como comando, pega la línea que el plugin te muestra en Ejemplo de cron en cPanel.

Importante: la URL del cron lleva una clave secreta única. Mantenla en privado.

Si abres esa URL en el navegador, verás una respuesta corta que indica cómo está la conexión:

Respuesta	Qué significa
fresh	El token sigue vigente; no ha hecho falta hacer nada.
refreshed	Se ha renovado el token.
paused_after_error	Una renovación reciente falló; se reintentará en unos minutos.
reconnect_required	Mautic ha rechazado el acceso: tienes que volver a conectar.
refresh_failed	La renovación ha fallado en este momento.

Nota: en la versión PRO, lo que WooCommerce envía a Mautic (pedidos, cambios de estado, inicios de sesión) también se hace en segundo plano con estas tareas programadas, para que tus clientes nunca esperen a Mautic al comprar. Si tu web tiene las tareas programadas de WordPress desactivadas y no tiene un cron del servidor, el plugin te avisará en el escritorio: el cron externo de este apartado lo soluciona.

4. Si la conexión se pierde

Si algo impide hablar con Mautic, el plugin pausa sus módulos y te lo dice con un aviso en el escritorio de WordPress. Mientras dure la pausa no vuelve a llamar a Mautic, así que tu web no se ralentiza. En cuanto vuelves a conectar, todo se reanuda solo.

Aviso	Qué significa	Qué hacer
"La conexión con Mautic no está configurada o ha caducado…"	Falta completar la conexión, o se ha perdido la autorización.	Revisa el punto 2 y pulsa Conectar/Reconectar con Mautic.
"Mautic ha rechazado la conexión y hay que volver a autorizarla…" (sólo PRO)	Mautic ya no acepta el acceso guardado: la autorización ha caducado, o las credenciales de la API se han borrado o cambiado en Mautic.	Pulsa Conectar/Reconectar con Mautic. Si falla, comprueba en Mautic (Credenciales API) que la credencial sigue existiendo y que el Client ID y el Client Secret coinciden.

5. Si Mautic va lento o no responde (sólo PRO)

La versión PRO está preparada para que un problema de Mautic nunca frene tu web:

• Si una llamada a Mautic falla porque no responde, el plugin deja de llamarlo durante 2 minutos. En ese tiempo, el checkout, los formularios y las páginas funcionan con normalidad, sin quedarse esperando.
• En cuanto Mautic vuelve a responder, todo sigue como siempre.
• Lo que WooCommerce envía en segundo plano se reintenta (hasta 3 veces, cada 5 minutos), así que un pedido hecho mientras Mautic estaba caído llega igualmente.
• Un formulario de Elementor enviado justo durante la pausa, en cambio, no llega a Mautic, porque se envía al momento.

Preguntas frecuentes

¿Tengo que volver a conectar cada cierto tiempo? No. El plugin renueva la conexión solo. Solo tendrás que reconectar si alguien borra o cambia las credenciales de la API en Mautic, o si Mautic rechaza el acceso por otro motivo.

Al pulsar «Conectar/Reconectar con Mautic» Mautic me da un error de redirección. La URI de redirección de la credencial en Mautic no coincide con la OAuth Callback URL del plugin. Cópiala de nuevo desde el plugin, pégala en Mautic, guarda y vuelve a intentarlo.

¿Qué pongo en Mautic URL: con barra al final o sin ella? Sin nada detrás del dominio: https://mautic.tudominio.com. Si tu Mautic está en una carpeta, incluye la carpeta: https://tudominio.com/mautic.

¿Puedo conectar varias webs al mismo Mautic? Sí. Crea una credencial de API distinta en Mautic para cada web, con la OAuth Callback URL de cada una.