Píxel de TikTok y API de eventos: guía de configuración paso a paso

¿Qué es la API de eventos de TikTok y en qué se diferencia del Píxel?

La API de eventos de TikTok envía las conversiones desde tu servidor o tu plataforma de e-commerce directamente a TikTok, mientras que el Píxel las envía desde el navegador del visitante. No compiten: son dos canales complementarios.

El punto débil del Píxel es el navegador: un bloqueador de anuncios, un banner de cookies rechazado o una pestaña cerrada justo después de pagar pueden hacer que la compra nunca llegue a TikTok. Por eso la propia documentación de TikTok recomienda configurar la API de eventos como segundo canal junto al Píxel, no como sustituto.

Si ya montaste la API de conversiones en Meta, la lógica te resultará familiar. Y si vas a usar anuncios de catálogo en ambas plataformas, conviene alinear los identificadores de producto desde el principio (lo explicamos en la guía de anuncios de catálogo de Meta).

¿Qué método de instalación te conviene?

Si tu tienda está en Shopify, WooCommerce, Tiendanube u otra plataforma con integración oficial de TikTok, empieza por esa integración; si tienes desarrollo propio, pasa a la integración directa con la API o a una solución de etiquetado del lado del servidor.

Para Tiendanube (Nuvemshop), el centro de ayuda de TikTok describe una integración oficial que conecta el Píxel y sincroniza el catálogo. Antes de montar nada por tu cuenta, revisa en el Administrador de eventos si tus eventos ya llegan también por servidor.

Los niveles de uso compartido de datos en Shopify

La app de TikTok para Shopify ofrece tres niveles y la API de eventos solo está activa en dos de ellos:

• Estándar: solo el Píxel de TikTok. Los bloqueadores de anuncios pueden impedir la recogida de datos.
• Mejorado: Píxel + API de eventos + Correspondencia avanzada.
• Máximo: todo lo anterior más las API de Shopify y el Pago de Shopify en la aplicación (según TikTok, en fase beta y no disponible para todos los anunciantes).

Regla práctica: si la app muestra el nivel Estándar, súbelo a Mejorado antes de plantearte otra integración. Y no pegues un segundo código del Píxel a mano en el tema: el mismo evento llegaría desde dos fuentes con event_id distintos y TikTok no podría desduplicarlo.

¿Cómo configurar el Píxel y la API de eventos paso a paso?

Todo empieza creando un Píxel en el Administrador de eventos; después conectas los eventos del navegador con el código del Píxel y los del servidor con un token de acceso. Con una app de plataforma bastan los pasos 1, 2 y 5; en una integración directa, todos son cosa tuya.

1. Crea el Píxel En TikTok Ads Manager ve a Herramientas > Administrador de eventos (Events Manager) > Conectar fuente de datos > Web e introduce la URL de tu tienda.
2. Elige el método de conexión Integración de socio (Shopify, Tiendanube, Google Tag Manager…) o configuración manual. Para webs, TikTok recomienda combinar el Píxel con la API de eventos.
3. Genera el token de acceso En la configuración del Píxel, apartado API de eventos, genera el token. Guárdalo como variable de entorno en el servidor; nunca en el código del navegador ni en un repositorio público.
4. Envía los eventos del servidor Cada evento lleva nombre, event_time en formato Unix, event_id, URL de la página y claves de correspondencia: ttclid, _ttp, correo y teléfono con hash, IP y agente de usuario.
5. Prueba y publica En la pestaña Eventos de prueba verás por separado los eventos del navegador y del servidor. Después, en la vista general del Píxel, confirma que el método de conexión combina servidor y navegador.

¿Qué eventos estándar debes enviar en una tienda online?

El mínimo para un e-commerce es ViewContent, AddToCart, InitiateCheckout y Purchase, siempre con los parámetros de valor y moneda. La lista de eventos estándar de TikTok recoge la compra con el nombre Purchase.

Desde el 1 de mayo de 2025, TikTok renombró CompletePayment como Purchase (y SubmitForm como Lead); los nombres antiguos se convierten automáticamente en segundo plano, así que tu código sigue funcionando. PlaceAnOrder y ClickButton, en cambio, dejarán de estar disponibles en 2027. En una instalación nueva usa Purchase y, si dependes de PlaceAnOrder, planifica el cambio campaña a campaña antes de esa fecha.

Si vas a usar anuncios de catálogo, content_ids debe coincidir exactamente con el ID del producto en el catálogo; si no, el evento se atribuye al anuncio pero no al producto. Decide también una sola vez si value incluye envío e impuestos (IVA en España, IVA o impuestos locales en Latinoamérica) y aplica la misma regla en todos los canales: de eso depende tu cálculo del ROAS. Si vendes en varios países, envía currency con el código ISO real de cada pedido (EUR, MXN, COP, ARS, CLP o USD), nunca una moneda fija.

¿Cómo funciona la desduplicación de eventos con event_id?

Cuando el Píxel y la API de eventos envían la misma compra con el mismo nombre de evento y el mismo event_id, TikTok la cuenta una sola vez y conserva el primer evento recibido. Si falta el event_id o no coincide entre canales, el mismo pedido aparece dos veces en los informes.

Según el centro de ayuda de TikTok, los duplicados que llegan solo por el Píxel o solo por la API se desduplican dentro de las 48 horas siguientes al primer evento. Cuando se solapan Píxel y API, TikTok combina o desduplica los eventos con event y event_id idénticos recibidos después de 5 minutos y dentro de las 48 horas desde el primero. La desduplicación (o deduplicación) es obligatoria cuando envías el mismo evento por ambos canales; si repartes eventos distintos, por ejemplo AddToCart solo por el Píxel y Purchase solo por la API, es opcional.

Ejemplo: el pedido 10482

Una clienta de Madrid compra por 89,90 EUR. El evento del Píxel en la página de agradecimiento y el que envía tu servidor al registrar el pedido deben coincidir así:

• Píxel: event = Purchase, event_id = order_10482, value = 89.90, currency = EUR
• API de eventos: event = Purchase, event_id = order_10482, value = 89.90, currency = EUR

Si la misma tienda vende en México y el pedido es de 1.699 MXN, cambian value y currency (1699, MXN), pero el principio es idéntico. Usar el número de pedido como event_id es lo más seguro, porque tanto el navegador como el servidor lo conocen. Para eventos previos al pedido, como AddToCart, funciona combinar el ID del carrito con una marca de tiempo y pasarlo al servidor mediante la capa de datos.

¿Cómo mejorar la calidad de coincidencia de eventos (EMQ)?

La puntuación EMQ (Event Match Quality) del Administrador de eventos es una media ponderada de la cobertura de tus claves de correspondencia: cuantas más claves envíes en más eventos, más sube.

Las claves que TikTok enumera para la API de eventos son: el ID de clic (ttclid), la cookie propia _ttp, correo electrónico y teléfono (Correspondencia avanzada), el ID externo (external_id, como tu número de cliente o de fidelización), la dirección IP y el agente de usuario. El Píxel comparte IP y agente de usuario automáticamente; en la API de eventos tienes que añadirlos tú.

• Correo: quita espacios, pásalo a minúsculas y aplícale hash SHA-256.
• Teléfono: formato internacional sin espacios ni guiones (+34 612 34 56 78 → +34612345678; +52 55 1234 5678 → +525512345678) y después aplícale hash.
• external_id: envía tu ID de cliente con hash.
• ttclid y _ttp van tal cual, sin hash.
• En el evento del servidor, incluye la IP y el agente de usuario reales del visitante, no los de tu servidor.
• Valora activar la Correspondencia avanzada automática en el Píxel: aplica hash en el navegador al correo y al teléfono de los formularios.

Revisa con tu asesor legal que tu política de privacidad cubre este uso y que el Píxel no se dispara sin consentimiento: en España y el resto de la UE rigen el RGPD y la normativa de cookies, y en Latinoamérica cada país tiene su propia ley de protección de datos personales.

¿Cómo comprobar que funciona y qué errores son habituales?

Para validar la instalación combina la pestaña Eventos de prueba, la extensión TikTok Pixel Helper y la pestaña Diagnóstico del Administrador de eventos.

1. Abre Eventos de prueba y añade a tus peticiones del servidor el código de prueba (test_event_code) que aparece allí.
2. Recorre un flujo real en la tienda: ficha de producto, añadir al carrito, pago y un pedido de prueba.
3. Comprueba que cada evento llega desde el navegador y desde el servidor con el mismo event_id.
4. Ya en producción, vigila en la vista general el método de conexión (solo navegador, solo servidor o ambos), el EMQ y la hora de la última recepción.
5. Si Diagnóstico muestra un problema, su enlace de ayuda explica el impacto, los pasos para corregirlo y ejemplos de eventos afectados.

Aun bien configurado, TikTok no reportará exactamente los mismos pedidos que tu tienda: la ventana de atribución y las conversiones tras visualización explican la diferencia. Si quieres ver TikTok, Meta y Google junto a los pedidos reales en una misma tabla, el análisis de conversiones de Marpany los cruza por ti.

¿Qué hacer durante la primera semana?

El objetivo de la primera semana es confirmar que los datos fluyen bien y que las campañas optimizan hacia el evento correcto; los cambios de puja y presupuesto, después.

• Día 1: en Eventos de prueba, confirma que los eventos clave llegan por los dos canales con event_id coincidente.
• Días 2–3: compara las Purchase de TikTok con los pedidos de esos mismos días y busca duplicados.
• Días 3–5: completa las claves que falten en los tipos de evento con EMQ bajo.
• Día 7: verifica que tus campañas de conversiones web usan Purchase como evento de optimización.
• Siempre: repite la prueba tras cualquier cambio de tema, de checkout o de actualización de la app.

Si además quieres revisar estructura de campañas, segmentación y creatividades, nuestra guía de TikTok Ads es un buen punto de partida.