Klaviyo for Odoo

Guía de usuario

Esta guía cubre Klaviyo for Odoo. Es una sola aplicación que se instala una vez. Las partes para otras aplicaciones de Odoo se activan solas cuando esas aplicaciones están instaladas: Ventas, Inventario, Punto de venta, Comercio electrónico, Marketing por correo electrónico, Fidelización y Reparaciones, y en Odoo Enterprise, Suscripciones, Citas y Helpdesk. La sección 5 dice qué envía cada parte.

1. Antes de empezar

Odoo 17.0, 18.0, 19.0 o 20.0, en Odoo.sh o en tu propio servidor. Odoo Online no admite módulos de terceros, así que no puede usar este conector.
Una cuenta de Klaviyo y un usuario de Klaviyo que pueda autorizar aplicaciones.
Un usuario de Odoo del grupo Klaviyo Manager. Klaviyo User puede ver el estado. Los administradores del sistema ven además los tokens.
Si quieres que los cambios de consentimiento lleguen al instante, tu Odoo debe ser accesible desde internet por HTTPS. Sin dirección pública el conector funciona igual y consulta a Klaviyo cada 15 minutos.

2. Instalación

Abre Aplicaciones, quita el filtro "Aplicaciones" y busca "Klaviyo".
Instala Klaviyo for Odoo. No hay que instalar nada más: las partes para Ventas, Inventario y las otras aplicaciones de Odoo que uses se activan solas.
Aparece la aplicación Klaviyo. La primera vez te lleva al asistente de configuración.

Cada compañía tiene su propia cuenta de Klaviyo. En una base con varias compañías, abre la aplicación una vez por compañía.

3. Conectar con Klaviyo

En el asistente pulsa Connect with Klaviyo.
Entra en Klaviyo y aprueba los permisos que pide la aplicación. La lista de permisos, con el motivo de cada uno, está al final de esta guía.
Klaviyo te devuelve a Odoo y el asistente continúa.

Odoo guarda los tokens de acceso y de renovación cifrados (ver "Cómo se protegen los tokens" más abajo). Un pequeño servicio de FlexigoTech en connect.flexigotech.com solo pasa los tokens durante el inicio de sesión y al renovarlos. Nunca recibe contactos, pedidos ni otros datos. Tus datos van directos de Odoo a Klaviyo.

Si la conexión se rompe (por ejemplo, Klaviyo revoca la aplicación), la cuenta pasa a "disconnected" y los Klaviyo Manager reciben una actividad. Vuelve a pulsar Connect with Klaviyo. En el formulario de la cuenta están los botones Disconnect y Forget credentials: Disconnect revoca el token en Klaviyo y borra el webhook, y Forget credentials sirve cuando Klaviyo no pudo revocar el token.

Cómo se protegen los tokens

El token de acceso, el de renovación y el secreto del webhook se cifran con Fernet antes de escribirlos en la base de datos. La clave de cifrado sale de uno de dos sitios.

Si odoo.conf tiene la opción klaviyo_token_key (cualquier texto secreto largo), esa es la clave. Vive en el servidor, fuera de la base de datos, así que protege los tokens también si alguien consigue una copia de la base. Odoo 19 y 20 registran un aviso de opción desconocida en odoo.conf; es inofensivo.
Si la opción no está puesta, la clave se deriva del database.secret de la base. Esa clave está dentro de la base, así que protege frente a exportaciones, copias de una sola tabla y lecturas parciales, pero no frente a quien consiga la base entera.

Recomendamos poner klaviyo_token_key. Mantenla igual en todos los servidores que usen esa base y guarda una copia. Si la clave cambia o se pierde, Odoo no puede leer los tokens guardados. La cuenta pasa entonces al estado Error con el mensaje "Reconnect Klaviyo", no envía nada y no reintenta sin fin. Pulsa Connect with Klaviyo otra vez y los tokens nuevos se cifran con la clave actual. Si añades la opción a una base que ya funciona, los tokens existentes siguen funcionando y se recifran con la clave del servidor la próxima vez que cambien.

Al actualizar desde una versión que guardaba los tokens sin cifrar, se cifran durante la actualización.

4. El asistente de configuración

El asistente tiene cinco pasos y puedes volver atrás cuando quieras.

Conectar.
Quién envía el marketing. Elige Klaviyo, Odoo o los dos. Importa si también envías correos masivos desde Odoo, porque dos sistemas no deben escribir a la misma persona. Para email y para SMS eliges también quién manda en el consentimiento: Odoo, Klaviyo o los dos (una baja en cualquiera de los dos gana, y es el valor por defecto). Elige la lista de Klaviyo a la que se apuntan los nuevos suscriptores. Si esa lista usa doble confirmación, Klaviyo envía el correo de confirmación.
Qué sincronizar. Interruptores para contactos, actividad de email que vuelve a Odoo, catálogo, listas por etiquetas y borrado al eliminar, más el modo de prueba (sección 6). Cada parte instalada añade su propio interruptor, como pedidos, facturas sin pedido de venta, fidelización, reparaciones, listas de correo o visitantes de la tienda.
Histórico. Puedes enviar los contactos que ya tienes y los pedidos, entregas, pedidos del TPV, reparaciones, recompensas canjeadas, tickets, citas y suscripciones anteriores de las partes instaladas. Eliges una fecha de inicio y las fuentes. También se puede hacer más tarde con el botón Send history.
Resumen. Dice con palabras claras lo que va a pasar. Pulsa Start.

Todo funciona con los valores por defecto. Puedes volver a abrir el asistente con Set up Klaviyo en la cuenta: muestra tus opciones actuales y solo guarda lo que cambies.

5. Qué sincroniza cada parte

Klaviyo for Odoo (núcleo)

Qué	Sentido	Cuándo
Contactos con email o teléfono	Odoo a Klaviyo, como perfiles	Se encolan al crear o cambiar el contacto y los envía un trabajo que corre cada minuto
Mapeo de campos	Odoo a Klaviyo	Igual que los contactos. Los valores por defecto funcionan sin configurar. Añades campos en la pestaña Contacts
Etiquetas de contacto	Odoo a Klaviyo, como listas	Eliges las etiquetas en la pestaña Lists
Productos a la venta, variantes y categorías	Odoo al catálogo de Klaviyo	Cuando cambian, y una actualización diaria de stock y precios
Bajas y consentimiento explícito	En los dos sentidos	Al instante con el webhook; si no, cada 15 minutos
Aperturas, clics y correos recibidos en 30 días	Klaviyo a Odoo	Con el webhook, escritos en el contacto
Contactos existentes	Odoo a Klaviyo, en bloque	Cuando lo pides, desde el asistente

Detalles útiles:

Un perfil se identifica por email, por un teléfono en formato E.164 y por un identificador externo formado por un prefijo y el id de Odoo. Si cambias el email de un contacto, se actualiza el mismo perfil.
El teléfono se convierte con el país del contacto, o con el de la compañía si el contacto no tiene. Un número que no se puede convertir no se envía y el estado muestra un aviso.
Solo se envían los contactos que cumplen el filtro de la pestaña Contacts. Por defecto son los que tienen email o teléfono y no están archivados.
Odoo nunca suscribe a nadie por su cuenta. Una persona se suscribe en Klaviyo solo si dio consentimiento explícito en Odoo, es decir, con la casilla marcada en el contacto.
Una baja en Odoo (la lista negra de email o de teléfono) se envía a Klaviyo y gana a la casilla de consentimiento.
Una baja, un aviso de spam o una supresión manual en Klaviyo ponen la dirección en la lista negra de Odoo cuando manda Klaviyo o mandan los dos.

Partes que se activan con otras aplicaciones de Odoo

Aplicación de Odoo	Qué se envía	Cuándo
Ventas	Placed Order y Ordered Product	Al confirmar un pedido
Ventas	Cancelled Order	Al cancelar un pedido que Klaviyo ya conocía como realizado
Ventas	Refunded Order, uno por pedido con el total acumulado	Tras un periodo de espera (48 horas por defecto, configurable) desde el último reembolso
Ventas	Placed Order y Ordered Product de las facturas sin pedido de venta (B2B), y Refunded Order cuando se rectifican	Opcional, desactivado por defecto
Ventas	Puntuaciones del cliente en el perfil: Lifecycle Stage, RFM Segment, RFM Recency, Frequency y Monetary Score, Number of Orders, Total Spent y Last Order Date	Cada noche, para los contactos cuyas puntuaciones cambiaron
Ventas	Pedidos anteriores	Cuando lo pides, en el paso de histórico
Inventario	Fulfilled Order, con número de seguimiento y transportista	Al hacerse una entrega. Una entrega parcial y su pedido pendiente son dos eventos
Punto de venta	Placed Order y Ordered Product, con los mismos nombres que Ventas y el canal POS	Al pagarse un pedido en la caja
Punto de venta	Refunded Order, uno por pedido con el total acumulado, y Refunded Order Adjustment para una devolución hecha después de enviarlo	Tras el mismo periodo de espera que Ventas
Punto de venta	La última tienda del cliente (Most Recent Store ID, Name y Location) en el perfil	Tras cada pedido pagado en la caja
Punto de venta	Pedidos anteriores de la caja	Cuando lo pides, en el paso de histórico
Comercio electrónico	Viewed Product, Added to Cart y Started Checkout, enviados desde el navegador del visitante por el script de Klaviyo	Solo después de que el visitante acepte las cookies opcionales de la barra de cookies de Odoo, o si gestionas tú el consentimiento de los visitantes
Comercio electrónico	La página pública del producto, su imagen y las categorías de la tienda en el catálogo de Klaviyo	Cuando un producto se publica o cambia
Comercio electrónico	Una casilla de consentimiento en el pago para invitados	Solo si escribes un texto de consentimiento en la cuenta. Desactivada por defecto
Marketing por correo electrónico	Las listas de correo que elijas, como listas de Klaviyo, y las personas que están en ellas como perfiles, sin un segundo perfil cuando un contacto de Odoo tiene el mismo email	Cuando cambia una lista o una suscripción, y una revisión cada noche
Marketing por correo electrónico	El consentimiento para esa lista, enviado una sola vez por persona. Salir de una lista saca el perfil solo de esa lista	Cuando la persona entra en la lista o sale de ella
Fidelización	Loyalty Points, Loyalty Level, Loyalty Next Reward, Loyalty Points To Next Reward, Gift Card Balance, Active Gift Cards, eWallet Balance, Active Coupons y Coupon Expires On, en el perfil	Cuando cambia una tarjeta, un programa o una recompensa
Fidelización	Redeemed Reward, uno por pedido y tarjeta	5 minutos después del último cambio del canje
Reparaciones	Repair Created y Repair Completed	Al confirmar la reparación y al terminarla. La descripción de la reparación y las notas internas no se envían nunca
Helpdesk (Enterprise)	Opened Ticket y Closed Ticket	Al abrir un ticket y al llegar a una etapa cerrada. El texto libre del cliente no se envía nunca
Citas (Enterprise)	Booked Appointment y Cancelled Appointment	Al aceptar una reserva y al cancelarla
Suscripciones (Enterprise)	Started, Renewed y Cancelled Subscription, con el plan, el importe recurrente, los ingresos mensuales y las fechas	Al confirmar, renovar y cerrar la suscripción
Suscripciones (Enterprise)	Propiedades de suscripción en el perfil: estado, suscripciones activas, ingresos mensuales, próxima factura y fecha de alta	Cuando cambia una suscripción, y cada noche

Las notas, las secciones, los anticipos y las líneas vacías de un pedido no son productos. Confirmar un pedido dos veces, o pasarlo a borrador y confirmarlo otra vez, no envía nada nuevo. La pestaña Orders de la cuenta tiene los nombres de los eventos, el prefijo del identificador y un filtro para dejar fuera los pedidos que tu tienda online ya envía a Klaviyo.

Los pedidos de la caja sin cliente no se envían, y el email que se teclea en la caja para el recibo no se usa nunca. Las líneas que se cobran en la caja por un pedido de venta no se envían dos veces.

En la tienda online, el script de Klaviyo solo identifica a un visitante con datos ya guardados: un cliente con sesión iniciada, o un invitado después de enviar su dirección. Envía el email y el nombre, nunca el teléfono ni la dirección. Los empleados que navegan por la tienda no se rastrean, y en modo de prueba los visitantes anónimos no envían nada.

Cuando el marketing lo envía Klaviyo, un mailing de Odoo te avisa antes de salir hacia personas que ya son perfiles de Klaviyo. Una baja hecha en Klaviyo cierra también las suscripciones de las listas de correo que envías a Klaviyo.

6. Modo de prueba: probar en producción

El modo de prueba permite conectar una base real y revisar el resultado antes de que ningún cliente llegue a Klaviyo.

En el asistente activa Test mode. El módulo trae una etiqueta de contacto llamada "Klaviyo test" y la usa por defecto.
Pon esa etiqueta a unos cuantos contactos de prueba.
Solo los contactos con la etiqueta se envían como perfiles y entran en listas y consentimiento. El resto se retiene.
Revisa los perfiles en Klaviyo. Desactiva el modo de prueba cuando estés conforme.

Mientras el modo de prueba está activo:

Una baja que viene de Klaviyo se aplica siempre en Odoo, con etiqueta o sin ella. Una suscripción de Klaviyo solo se aplica a los contactos con etiqueta.
Una baja hecha en Odoo para una dirección que ningún contacto con etiqueta tiene se retiene, porque Klaviyo crearía un perfil nuevo para darla de baja. Al salir del modo de prueba se envían las bajas retenidas y las casillas marcadas.
Una petición de borrado explícita (sección 7) se envía siempre, con etiqueta o sin ella.
El borrado automático al eliminar un contacto no se ejecuta para los contactos sin etiqueta, salvo que esta cuenta haya creado su perfil.
Los eventos de clientes sin etiqueta que estaban esperando cuando activaste el modo de prueba no se envían.

7. Protección de datos: borrar y liberar

Para borrar personas de Klaviyo:

Selecciona los contactos, abre Acciones y elige Erase from Klaviyo (GDPR). Solo los Klaviyo Manager ven esta acción.
Un diálogo avisa de que no se puede deshacer y de que también se bloquean otros contactos con el mismo email o número. Confirma.
Odoo pide a Klaviyo que borre los perfiles y marca los contactos como excluidos, para no enviarlos nunca más. Klaviyo hace el borrado en segundo plano, normalmente en pocos minutos.

Si Klaviyo no tiene perfil del contacto, no queda nada que borrar y se da por hecho. Klaviyo borra todos los perfiles que tengan el identificador indicado, así que un teléfono compartido puede afectar a otra persona. Por eso el conector usa el email cuando hay uno, y el teléfono solo si no hay email.

Si quieres que se borre el perfil de Klaviyo cada vez que se elimina un contacto en Odoo, activa "Erase the Klaviyo profile when a contact is deleted" en el asistente. Viene desactivado, porque eliminar un contacto duplicado no debe borrar a un cliente real. Fusionar duplicados nunca borra el perfil del contacto que se queda.

Después de un borrado el conector recuerda la dirección, como un hash con clave y no en claro, y no vuelve a enviar nada con ella a esa cuenta de Klaviyo, ni siquiera una baja. Para permitir de nuevo una dirección, selecciona el contacto y elige Release erased address (Klaviyo) en Acciones. Es un paso deliberado de un Klaviyo Manager.

Dos cosas que vimos en pruebas con una cuenta real:

Después de un borrado, la baja registrada para la dirección de email sigue en Klaviyo. Borrar un perfil no vuelve a activar una suscripción.
Klaviyo procesa los borrados en segundo plano. Una respuesta 202 solo significa "aceptado".

Los datos de categorías especiales no deben mapearse a propiedades de Klaviyo. Por defecto no se mapea ninguno.

8. La pestaña Status

Abre la cuenta de Klaviyo y ve a Status.

Últimas 24 horas: enviados, fallidos, saltados, avisos, limitados y en espera.
Salud: estado del token, del webhook, última pasada, último éxito, pasadas fallidas seguidas y estado de la carga del histórico.
See the jobs lista cada trabajo con el motivo que dio Klaviyo cuando falló. Retry failed jobs los devuelve a la cola.

Odoo crea una actividad para los Klaviyo Manager cuando:

cinco pasadas seguidas tienen fallos;
hay trabajo esperando y no ha llegado nada a Klaviyo en dos horas;
una petición de borrado falla o se queda sin intentos;
un cambio de consentimiento de Klaviyo no se pudo aplicar en Odoo.

Klaviyo limita cuántas peticiones acepta. Cuando responde "demasiadas peticiones", la cola espera lo que Klaviyo indica y sigue. Las peticiones fallidas se reintentan a 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas antes de darlas por fallidas.

9. Tiempos que conviene esperar

Una suscripción nueva puede tardar unos cinco minutos en verse en Klaviyo, aunque la petición se aceptó al instante.
Los cambios de contactos llegan a Klaviyo en uno o dos minutos, cuando corre el trabajo de la cola.
Klaviyo acepta la petición de un evento antes de guardarlo. Si falta un evento, mira la página de estado antes de volver a enviarlo. Klaviyo guarda un solo evento por identificador.
Klaviyo ignora los eventos de direcciones que terminan en example.com. Usa direcciones reales al probar.

10. Límites conocidos

Odoo Online no está soportado.
El consentimiento por SMS usa las mismas reglas que el email, pero no se ha comprobado con una cuenta de Klaviyo habilitada para SMS.
Pedidos de venta: los cambios hechos a un pedido después de confirmarlo no se vuelven a enviar, y un pedido cancelado y confirmado de nuevo no envía un segundo Placed Order. Una devolución de mercancía no envía evento; el dinero va por los reembolsos.
Punto de venta: la caja no envía Cancelled Order ni Fulfilled Order, y no pide el consentimiento de marketing.
Tienda online: un sitio con política de seguridad de contenido (CSP) tiene que permitir static.klaviyo.com y a.klaviyo.com. Back in Stock no está incluido.
Marketing por correo electrónico: darse de baja de una sola lista en Klaviyo no llega a Odoo; una baja total sí. Cambiar el nombre de una lista de correo en Odoo no lo cambia en Klaviyo. Los envíos, aperturas y clics de los mailings de Odoo no se envían.
Fidelización: un canje deshecho después de enviarse no se retira en Klaviyo. En Odoo 17 solo las tarjetas regalo, los cupones y los códigos envían Redeemed Reward, y el paso de histórico no ofrece canjes.
Reparaciones, Helpdesk y Citas: una reparación cancelada, una cita que cambia de hora, las valoraciones de los tickets y los SLA no envían nada. En Odoo 17, cancelar una cita para uno de más de dos asistentes no envía nada.
Suscripciones: pausar, reanudar y las ventas adicionales (upsells) no envían evento (se ven en las propiedades del perfil), y las facturas recurrentes no se envían como pedidos.
Un contacto sin email ni teléfono no puede ser un perfil.
El conector no fusiona perfiles de Klaviyo. Si dos perfiles chocan, el trabajo falla con el motivo y decides tú qué fusionar en Klaviyo.
Las direcciones borradas siguen excluidas hasta que un responsable las libera.

11. Ayuda

Envía al soporte de FlexigoTech las cifras de la página de estado, el texto de un trabajo fallido y tu versión de Odoo. Cómo escribirnos, y en cuánto respondemos, está en la página de soporte.

Permisos que pide la aplicación

Al conectar, Klaviyo te pide aprobar estos 14 permisos (scopes). Cada uno lo usa una llamada que hace el módulo.

Permiso	Para qué
accounts:read	Leer el id, el nombre, la zona horaria y la moneda de la cuenta al conectar, y comprobar que el token funciona.
profiles:read	Encontrar el perfil detrás de un error de duplicado, leer el estado de suscripción al consultar y comprobar el resultado de las importaciones en bloque.
profiles:write	Crear y actualizar perfiles a partir de los contactos de Odoo.
lists:read	Cargar tus listas para elegir la de consentimiento y encontrar una lista que ya tenga el nombre de una etiqueta.
lists:write	Crear una lista para una etiqueta elegida y añadir o quitar perfiles.
events:write	Enviar eventos de pedidos y el histórico de eventos en bloque.
events:read	Leer los eventos de consentimiento cuando Odoo no tiene dirección pública para un webhook, y comprobar lo guardado.
metrics:read	Encontrar las métricas de consentimiento de Klaviyo, necesarias para leer esos eventos.
subscriptions:write	Suscribir a quien dio su consentimiento en Odoo y dar de baja a quien se dio de baja en Odoo.
catalogs:read	Comprobar el estado de los artículos del catálogo antes de actualizarlos o borrarlos.
catalogs:write	Crear, actualizar y borrar artículos, variantes y categorías del catálogo.
data-privacy:write	Enviar peticiones de borrado cuando un responsable pide borrar un contacto.
webhooks:read	Comprobar que el webhook que creó Odoo sigue existiendo y está activo.
webhooks:write	Crear el webhook que trae a Odoo las bajas y la actividad de email, y quitarlo al desconectar.