Contact Form 7 - Klaviyo Integration

Plugin de WordPress que integra Contact Form 7 con Klaviyo para sincronizar automáticamente los envíos de formularios con tus listas de Klaviyo.

Características

• ✅ Integración completa con la API de Klaviyo (versión 2024-10-15)
• ✅ Mapeo flexible de campos por formulario
• ✅ Detección automática de tipos de campos (email, nombre, teléfono, etc.)
• ✅ Soporte para campos personalizados
• ✅ Soporte para todos los tipos de campos de CF7 (text, email, tel, checkbox, select, etc.)
• ✅ Panel de configuración intuitivo
• ✅ Logs de errores y seguimiento de envíos
• ✅ Validación de API Key
• ✅ Escalable y fácil de extender

Requisitos

• WordPress 5.0 o superior
• PHP 7.4 o superior
• Contact Form 7 (plugin activo)
• Cuenta de Klaviyo con API Key

Instalación

1. Sube la carpeta cf7-klaviyo-integration al directorio /wp-content/plugins/
2. Activa el plugin desde el menú 'Plugins' en WordPress
3. Ve a Ajustes > CF7 Klaviyo para configurar tu API Key

Configuración

1. Configurar la API de Klaviyo

1. Ve a Ajustes > CF7 Klaviyo en el admin de WordPress
2. Introduce tu Private API Key de Klaviyo
   • Puedes obtenerla en: Klaviyo Dashboard > Account > Settings > API Keys
3. (Opcional) Ajusta la versión de la API si es necesario (por defecto: 2024-10-15)
4. Haz clic en "Probar Conexión" para verificar que todo funciona
5. Guarda la configuración

2. Configurar un Formulario

1. Ve a Contact > Formularios de Contacto
2. Edita el formulario que quieras integrar con Klaviyo
3. Haz clic en la pestaña "Klaviyo"
4. Activa la casilla "Activar integración con Klaviyo"
5. Haz clic en "Cargar Listas" para obtener tus listas de Klaviyo
6. Selecciona la lista de destino
7. Mapea los campos del formulario:
   • Email: Campo obligatorio para Klaviyo
   • Nombre (first_name)
   • Apellido (last_name)
   • Teléfono (phone_number)
   • Propiedad Personalizada: Para campos custom de Klaviyo
8. Guarda el formulario

Mapeo de Campos

El plugin detecta automáticamente el tipo de campo más apropiado basándose en el nombre:

Nombre del campo CF7	Campo Klaviyo detectado
email, correo	email
nombre, name, first	first_name
apellido, last, surname	last_name
telefono, phone, tel, movil	phone_number
otros	custom (personalizado)

Puedes cambiar manualmente cualquier mapeo desde el editor del formulario.

Campos Personalizados

Para enviar campos personalizados a Klaviyo:

1. Selecciona "Propiedad Personalizada" en el desplegable
2. Introduce el nombre del campo personalizado en Klaviyo
3. Usa snake_case o camelCase para los nombres (ej: fecha_nacimiento, company_name)

Tipos de Campos Soportados

El plugin soporta todos los tipos de campos de Contact Form 7:

• text - Texto simple
• email - Email (con validación)
• tel - Teléfono
• number - Números
• textarea - Área de texto
• select - Menú desplegable
• checkbox - Casillas de verificación
• radio - Botones de radio
• date - Fecha
• url - URL

Los campos de tipo array (checkbox, multi-select) se convierten automáticamente a texto separado por comas.

Estructura de Archivos

cf7-klaviyo-integration/
├── cf7-klaviyo-integration.php (archivo principal)
├── includes/
│   ├── class-cf7-klaviyo-settings.php (configuración global)
│   ├── class-cf7-klaviyo-api.php (API de Klaviyo)
│   ├── class-cf7-klaviyo-form-settings.php (configuración por formulario)
│   └── class-cf7-klaviyo-submission.php (manejo de envíos)
├── assets/
│   ├── js/
│   │   ├── admin.js
│   │   └── form-admin.js
│   └── css/
│       ├── admin.css
│       └── form-admin.css
└── README.md

API de Klaviyo

El plugin utiliza la API REST de Klaviyo v2024-10-15 con los siguientes endpoints:

• GET /api/lists/ - Obtener listas
• POST /api/profiles/ - Crear/actualizar perfiles
• POST /api/lists/{id}/relationships/profiles/ - Suscribir a lista
• POST /api/profile-subscription-bulk-create-jobs/ - Creación masiva

Logs y Debugging

El plugin registra automáticamente:

• ✅ Envíos exitosos
• ❌ Errores de API
• ⚠️ Campos faltantes o inválidos

Los logs se almacenan en:

1. WordPress Error Log (si WP_DEBUG está activado)
2. Tabla de base de datos wp_cf7_klaviyo_submissions

Para ver los logs en la base de datos:

SELECT * FROM wp_cf7_klaviyo_submissions ORDER BY created_at DESC;

Troubleshooting

No se envían los datos a Klaviyo

1. Verifica que la API Key esté correctamente configurada
2. Asegúrate de que el campo Email esté mapeado
3. Revisa los logs de WordPress para errores específicos
4. Verifica que la integración esté activada en el formulario

Error de conexión con la API

1. Verifica que tu API Key sea válida (Private Key, no Public Key)
2. Comprueba que no haya restricciones de firewall
3. Asegúrate de que tu servidor pueda hacer peticiones HTTPS externas

Los campos no se mapean correctamente

1. Verifica que los nombres de campos no contengan caracteres especiales
2. Para campos personalizados, usa nombres en snake_case
3. Guarda el formulario después de cambiar los mapeos

Preguntas Frecuentes

¿Puedo usar diferentes listas para diferentes formularios? Sí, cada formulario puede tener su propia lista de Klaviyo configurada.

¿Soporta doble opt-in? Sí, puedes activar la opción de doble opt-in en las opciones avanzadas de cada formulario.

¿Qué pasa si ya existe el email en Klaviyo? Klaviyo actualiza automáticamente el perfil existente con los nuevos datos.

¿Puedo desactivar los logs? Sí, en las opciones avanzadas de cada formulario puedes desactivar el registro de errores.

Changelog

1.0.0

• Versión inicial
• Integración completa con Klaviyo API v2024-10-15
• Mapeo de campos flexible
• Soporte para campos personalizados
• Panel de configuración
• Sistema de logs

Licencia

GPL v2 o superior

Autor

Konstantin WDK

• Web: webdesignerk.com
• Plugin URI: webdesignerk.com

Soporte

Para reportar problemas o solicitar características, contacta con Konstantin WDK a través de webdesignerk.com.