- La Pinterest Conversions API envía eventos de conversión desde un servidor a tu cuenta publicitaria de Pinterest, junto a la Pinterest Tag del navegador.
- Pinterest llama checkout a una compra completada; envíala con el valor, la moneda, el id del pedido y los artículos.
- Pinterest vincula los eventos mediante los datos del cliente con hash, la dirección IP junto con el user agent y el click id epik.
- Pinterest deduplica un evento de la Tag y un evento de la API con el mismo event_id y el mismo nombre de evento y conserva el primero; ROASaurus envía así los cinco eventos del recorrido de compra.
- Prueba primero con el modo de prueba: Pinterest deja los eventos de prueba fuera de los informes y de la optimización.
La Pinterest Conversions API es la forma de Pinterest de enviar eventos de conversión de servidor a servidor. Tu tienda, o una herramienta como ROASaurus, envía eventos como las compras directamente a tu cuenta publicitaria de Pinterest, en lugar de depender solo de la Pinterest Tag en el navegador del comprador. Pinterest usa los datos para los informes de conversiones, la optimización de campañas y la segmentación.
Esta guía cubre la API v5 y los eventos que acepta, el click id epik, cómo se aplica el hash a los datos del cliente, cómo funciona la deduplicación con la Pinterest Tag, cómo probar y cómo configurarlo todo en Shopify.
¿Qué es la Pinterest Conversions API?
La Pinterest Tag es un script en el navegador del comprador. La Conversions API hace el mismo trabajo desde un servidor. En la versión 5 de la API, envías los eventos al endpoint de eventos de tu cuenta publicitaria, autorizado con un token de acceso de conversiones que creas en Pinterest Ads Manager. Cada evento indica dónde ocurrió: para una tienda online, el action source es web.
Pinterest pide a los anunciantes que también usan la Tag que eviten contar una conversión dos veces, pasando un event_id con cada evento. También pide los eventos en tiempo real, o como máximo una hora después de que ocurran.
En Shopify, una conexión server-side tiene una ventaja clara: las compras salen del propio pedido. Shopify informa a ROASaurus de cada pedido pagado mediante un webhook, y ROASaurus lo envía a Pinterest poco después del pago, se haya disparado o no la Tag en el navegador. La guía de server-side tracking en Shopify explica la idea con más detalle.
- Se ejecuta en el navegador del comprador
- Los bloqueadores de anuncios y los errores de script pueden detenerla
- Informa de las visitas a las páginas a medida que ocurren
- Se ejecuta en un servidor
- Envía las compras a partir de los datos de tus pedidos
- Necesita al menos un email, o una dirección IP con un user agent
¿Qué eventos acepta la Pinterest Conversions API?
Pinterest tiene una lista fija de nombres de eventos estándar, escritos en minúsculas y con guiones bajos, como page_visit, add_to_cart y checkout. También puedes definir hasta 15 tipos de eventos personalizados por anunciante. ROASaurus asigna los cinco eventos de la tienda de Shopify así:
| Acción del comprador | Nombre del evento en la API | Deduplicado con la Tag en ROASaurus |
|---|---|---|
| Ve una página | page_visit | Sí |
| Ve un producto | view_content | Sí |
| Añade al carrito | add_to_cart | Sí |
| Inicia el checkout | initiate_checkout | Sí |
| Completa un pedido | checkout | Sí |
El nombre puede confundir. El checkout de Pinterest es la compra terminada, no el inicio del checkout. El inicio del checkout es un evento distinto, initiate_checkout.
Para el evento de checkout, Pinterest recomienda enviar el valor, la moneda, el id del pedido, los ids de contenido y el número de artículos. ROASaurus envía los cinco, además de la cantidad y el precio de cada artículo. Pinterest pide el valor antes de impuestos y envío. En Shopify, ROASaurus envía exactamente eso: el total del pedido menos impuestos y envío, desde el servidor y desde la etiqueta del navegador. Cuando una plataforma de tienda online no informa por separado de los impuestos y el envío, ROASaurus envía el total del pedido.
¿Cómo vincula Pinterest un evento con una persona?
Cada evento lleva datos del usuario. Pinterest exige al menos una de estas tres cosas: un email con hash, un id publicitario móvil con hash, o la dirección IP junto con el user agent. Una tienda online no tiene id publicitario, así que necesita el email o la dirección IP y el user agent. ROASaurus omite un evento que no tenga ninguno de los dos, en lugar de enviar uno que Pinterest no pueda usar.
| Campo | Qué contiene | Enviado como |
|---|---|---|
| em | Dirección de email | Hash SHA-256 del email en minúsculas |
| ph | Número de teléfono | Hash SHA-256 |
| fn, ln, ct, st, zp, country | Nombre, apellido, ciudad, provincia, código postal y país | Hash SHA-256 |
| external_id | Id de cliente de Shopify o id de visitante de ROASaurus | Hash SHA-256 |
| client_ip_address | La dirección IP del comprador | Valor en claro |
| client_user_agent | El user agent del navegador del comprador | Valor en claro |
| click_id | El valor de epik de un clic en un anuncio de Pinterest | Valor en claro |
El click id epik
El click id de Pinterest puede venir de dos sitios: un parámetro epik en la URL de la página de llegada, o la cookie _epik de tu dominio. La guía de la API de Pinterest recomienda pasar el valor de la cookie _epik, porque sigue funcionando cuando falta el parámetro de la URL o se ha eliminado, lo que da mejor cobertura.
ROASaurus lee ambos en tu tienda, usando el parámetro de la URL cuando un clic nuevo lo trae y la cookie en caso contrario. Guarda el click id junto con el visitante y lo envía en el campo click_id de cada evento del servidor, incluida la compra. Las visitas con un epik cuentan como visitas de Pinterest en los informes de atribución de ROASaurus.
POST https://api.pinterest.com/v5/ad_accounts/549755885175/events
{
"data": [{
"event_name": "checkout",
"action_source": "web",
"event_time": 1793016000,
"event_id": "order-5512345678901",
"event_source_url": "https://example-store.com/checkouts/…/thank-you",
"user_data": {
"em": ["a3f1…9c2e"],
"ph": ["7b40…11d8"],
"external_id": ["e05c…4a7f"],
"client_ip_address": "203.0.113.24",
"client_user_agent": "Mozilla/5.0 (iPhone; …)",
"click_id": "dj0yJnU9…"
},
"custom_data": {
"currency": "USD",
"value": "84",
"order_id": "5512345678901",
"content_ids": ["44123456789"],
"contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
"num_items": 2
}
}]
}¿Cómo funciona la deduplicación con la Pinterest Tag?
Si la Tag y la API informan ambas de una compra, Pinterest recibe dos eventos por un solo pedido. Para tratarlos como uno, necesita el mismo id en ambos lados: el id de evento de la Tag debe coincidir con el event_id del evento del servidor. Pinterest conserva el primer evento que recibe y elimina los duplicados que llegan en un plazo de 48 horas.
ROASaurus construye el id de compra a partir del id de pedido de Shopify. La compra del pedido 5512345678901 tiene el id de evento order-5512345678901, tanto en la Tag que se dispara en el checkout como en el evento del servidor.
Los cinco eventos se deduplican
Cada evento del recorrido de compra en ROASaurus tiene un solo id de evento, que usan la Tag en el navegador y el evento del servidor. La Tag usa los nombres propios de Pinterest para los mismos eventos: pagevisit, viewcontent, addtocart, initiatecheckout y checkout, que coinciden con page_visit, view_content, add_to_cart, initiate_checkout y checkout en la API. Así, cuando funcionan las dos, Pinterest se queda con una copia de cada visita de página, visualización de producto, añadido al carrito, inicio del checkout y compra.
Puedes usarlo de dos maneras:
- Tag y Conversions API juntas. La Tag aporta señales del navegador, el servidor completa lo que la Tag no recoge y Pinterest fusiona las copias.
- Usa la API sin la Tag. Deja vacío el Tag ID o desactiva Also load the browser tag. Cada evento se envía entonces una sola vez, solo desde el servidor.
El artículo de ayuda sobre el doble conteo cubre las mismas comprobaciones para las demás plataformas publicitarias.
¿Cómo se prueba la Pinterest Conversions API?
La API tiene un indicador de prueba. Las solicitudes enviadas con test=true van a un entorno de pruebas: Pinterest las trata como datos de prueba y no las usa para informes ni para la optimización.
- Activa el modo de prueba
En ROASaurus, edita el píxel de Pinterest en Tracking & platforms y marca Test mode (events show under Test events, max 20). Cada evento del servidor se envía entonces con test=true. Pinterest procesa como máximo 20 eventos de prueba por lote.
- Haz un pedido de prueba
Visita tu tienda, mira un producto, añádelo al carrito y completa un pedido.
- Lee el resultado
Abre el Event log. Pinterest puede responder HTTP 200 aunque falle un evento de la solicitud, así que ROASaurus comprueba el estado de cada evento y muestra ahí los fallos.
- Desactiva el modo de prueba
Desmarca el modo de prueba, para que los eventos cuenten en los informes y en la optimización.
- Revisa el Events Overview
En Pinterest Ads Manager, abre la página Events Overview. Muestra los eventos que llegan y las conversiones deduplicadas. Pinterest recomienda aspirar a un Good Event Quality Score.
Cómo configurar la Pinterest Conversions API en Shopify con ROASaurus
Necesitas una tienda de Shopify con la app de ROASaurus y acceso a Pinterest Ads Manager. La página de la integración con Pinterest enumera todos los campos que envía ROASaurus.
- Conecta tu tienda de Shopify
Ve a Add a store › Shopify, haz clic en Install app y activa el app embed de ROASaurus en el editor de temas. Captura epik y la cookie _epik en cada página. La guía de configuración de Shopify muestra cada paso.
- Crea un token de acceso de conversiones
En Pinterest Ads Manager, ve a Conversions y crea un token de acceso de conversiones. Anota el ID de tu cuenta publicitaria.
- Añade el píxel de Pinterest en ROASaurus
Ve a Tracking & platforms, haz clic en Add pixel en la tarjeta de Pinterest y rellena Ad account ID y Conversion access token.
- Añade tu Tag ID
Para deduplicar con la Tag, rellena Pinterest Tag ID y deja marcado Also load the browser tag. Sin un Tag ID, ROASaurus envía solo eventos del servidor y no carga la Tag.
- Añade el píxel del checkout
En Shopify admin › Settings › Customer events, añade un píxel personalizado llamado ROASaurus y pega el fragmento de tu página Tracking & platforms. Dispara el evento checkout de la Tag en el checkout de Shopify, con el id del pedido como event_id.
- Elige los eventos del servidor y prueba
Elige los eventos del servidor que quieras y prueba con el modo de prueba antes de salir en directo.
Con Respect visitor consent activado, que es lo predeterminado, ROASaurus sigue la elección del comprador en el banner de cookies de Shopify. Cuando un comprador rechaza las cookies de marketing, ROASaurus no carga la Pinterest Tag para él, no asigna ningún id de visitante, así que sus clics no se le asocian, y no envía sus eventos de navegación a Pinterest. Su pedido pagado se sigue enviando a la Conversions API desde el servidor, con los datos del pedido con hash y con la dirección IP y el user agent del pedido, pero sin click id. La guía de consentimiento y privacidad explica qué se almacena y qué se envía.
Conecta tu cuenta publicitaria de Pinterest en Setup › Ad spend y ROASaurus importa el gasto de campañas cada hora, para que veas el ROAS de Pinterest y el beneficio tras los anuncios en la analítica de beneficios. La guía de la TikTok Events API cubre la misma configuración para TikTok, donde se deduplican todos los eventos que van por las dos vías.
Fuentes
- Pinterest Developers: Track conversion events in the API
- Pinterest Business help: The Pinterest Conversions API
- Pinterest Developers: Track conversions with Pinterest Tag