Guía
API de conversiones de OpenAI en WooCommerce: compras server-side
La OpenAI Conversions API (la API de conversiones de OpenAI) permite que una tienda WooCommerce envíe las conversiones de ChatGPT Ads desde su propio servidor en lugar de hacerlo desde el navegador del comprador. En una tienda, la conversión que más importa es la compra: en cuanto WooCommerce marca un pedido como pagado, el pedido existe, lo haya notificado o no un script del navegador. Esta guía explica cómo funciona el seguimiento server-side (del lado del servidor) de la compra, qué tiene que resolver una implementación correcta y qué no puede arreglar.
Actualizado
En esta página
En un párrafo: envía order_created desde WooCommerce cuando el pedido pase a un estado pagado, con el mismo event ID que usó el píxel del navegador para ese pedido, con la hora original de la compra y con tu clave de API guardada en el servidor. Reintenta los fallos temporales con el mismo ID y guarda un registro de lo que pasó con cada pedido.
Arquitectura
El seguimiento server-side de la compra, de un vistazo
De la tienda salen dos vías. La del navegador lleva todo el recorrido de compra; la del servidor lleva el pedido pagado.
En el navegador, el Measurement Pixel envía las vistas de producto, los añadidos al carrito, los inicios de pago y la compra. Cuando WooCommerce confirma un pedido pagado, la compra también se envía desde tu servidor a través de la OpenAI Conversions API, con el mismo event ID, para que OpenAI la cuente una sola vez.
Navegador del cliente
Ve productos, añade al carrito, finaliza la compra
Tienda WooCommerce
Productos, carrito, pago y pedidos
En el navegador
Measurement Pixel
contents_viewed, items_added, checkout_started, order_created
OpenAI
Recibe los eventos del navegador
En tu servidor
Pedido marcado como pagado
Cambio de estado en WooCommerce
El plugin envía order_created
Mismo event ID · reintentos · diagnóstico
Conversions API
Autenticada con tu clave de API
Una sola compra contabilizada
OpenAI cruza el Pixel ID, el nombre del evento y el event ID, y descarta el duplicado que llega después.
Lo que se le escapa a la medición en el navegador
El Measurement Pixel se ejecuta en el navegador del comprador. Es el único sitio desde el que se ven las vistas de producto y la actividad del carrito, pero también significa que un evento se pierde cada vez que la página o el script no llegan a ejecutarse del todo:
- Los bloqueadores de contenido o las herramientas de privacidad impiden que se cargue el script del píxel.
- El cliente cierra la pestaña después de pagar, antes de que cargue la página de pedido recibido.
- El pago se confirma más tarde (transferencia bancaria, algunas pasarelas con redirección), cuando el cliente ya no está en la web.
- Una página lenta o que no termina de cargar pierde la petición.
En todos estos casos WooCommerce registra el pedido igualmente. Un evento de compra server-side parte de ese pedido, así que ninguno de ellos impide que se envíe.
Cómo funciona la Conversions API
Tu servidor hace una petición HTTPS autenticada a OpenAI con uno o varios eventos. La petición va dirigida a tu Pixel ID y se autoriza con una clave de la Conversions API; los dos se generan en la pestaña de conversiones de Ads Manager (documentación de la OpenAI Conversions API, en inglés, como el resto de la documentación de OpenAI que enlaza esta guía).
| Campo | Qué contiene en una compra de WooCommerce |
|---|---|
event_name | order_created: una compra completada |
id | El event ID. Tiene que coincidir con el del evento del navegador para ese mismo pedido. |
timestamp_ms | Cuándo se hizo la compra, en milisegundos. |
action_source | web para una tienda online |
Solo desde el servidor
OpenAI indica que los eventos de la Conversions API deben enviarse únicamente desde tu servidor, y la documentación del píxel añade que la API de servidor no se debe llamar directamente desde el código de la página. La clave de API nunca debe llegar al navegador.
Cuándo enviar la compra
Envíala cuando WooCommerce pase el pedido a un estado pagado, no cuando se muestre la página de pedido recibido. Vincular el evento al estado del pedido, y no a una vista de página, significa que:
- Se dispara una vez por pedido, aunque la página de agradecimiento se recargue muchas veces.
- Con los métodos de pago diferido, la compra se envía cuando el pago se confirma de verdad.
- Los pedidos sin pagar, fallidos o abandonados no se notifican como compras.
Compra finalizada
Pedido creado en WooCommerce
Pago confirmado
El pedido pasa a un estado pagado
Compra enviada
order_created desde tu servidor
Resultado registrado
Aceptada, reintentada o fallida
Event ID y deduplicación
Si una compra se envía desde el navegador y desde el servidor, OpenAI necesita saber que es una sola compra. Según la documentación de OpenAI, para deduplicar se usan tu Pixel ID, el nombre del evento (event_name) y su ID; OpenAI se queda con el primer evento que recibe con esa combinación y descarta los duplicados que lleguen después.
Por eso el event ID tiene que ser idéntico en las dos vías. En WooCommerce, la forma fiable de conseguirlo es derivarlo del pedido, que conocen tanto la página de pedido recibido como el servidor, en lugar de generar en el navegador un ID aleatorio que el servidor nunca llega a ver. La guía sobre el píxel frente a la API de conversiones explica cómo encajan las dos vías.
Navegador · Píxel
Compra
Event ID compartido, generado a partir del pedido de WooCommerce
Servidor · Conversions API
Compra
Event ID compartido, generado a partir del pedido de WooCommerce
Una sola conversión
Mismo Pixel ID, mismo nombre de evento y mismo ID: OpenAI se queda con el primero y descarta el duplicado.
La regla de los 7 días
OpenAI rechaza los eventos que quedan fuera de una ventana de tiempo: la marca de tiempo tiene que estar dentro de los últimos 7 días y no más de 10 minutos en el futuro. Para una tienda, esto tiene dos consecuencias:
7 días
antigüedad máxima de la compra
10 minutos
margen máximo hacia el futuro
- Envía la hora original de la compra, no la del intento: si no, un evento reintentado indicaría que la compra se hizo más tarde de lo que realmente se hizo.
- Corrige pronto los envíos fallidos. Un pedido cuya hora de compra tiene más de 7 días ya no se puede enviar.
La API también admite lotes de hasta 1.000 eventos y, si falla un evento del lote, falla el lote entero: un solo pedido mal formado puede bloquear a otros si una implementación agrupa los eventos sin cuidado.
Reintentos y fallos
La documentación de OpenAI pide reutilizar el mismo ID al reintentar o al enviar la misma conversión por otra integración. No publica un calendario de reintentos, así que la política depende de cada implementación. Una política razonable distingue entre:
| Fallo | Ejemplo | Tratamiento |
|---|---|---|
| Temporal | Tiempo de espera agotado, límite de peticiones (429), error del servidor (5xx) | Reintentar automáticamente con el mismo ID |
| De configuración | Clave de API rechazada (401) | Corregir el ajuste y reenviar |
| De red | El servidor no llega a la API | Corregir las peticiones HTTPS salientes o las reglas del cortafuegos |
Sea cual sea la política, un fallo tiene que verse en algún sitio. Sin un registro por pedido, una integración rota se confunde con una semana floja de ventas.
Consentimiento
El envío server-side no sirve para saltarse el consentimiento. El propio píxel no envía señales de medición cuando el consentimiento vale false (documentación del Measurement Pixel), y una compra server-side debe respetar el estado de consentimiento registrado para ese pedido. En WordPress, la WordPress Consent API es la forma habitual de que un banner de cookies comparta ese estado con otros plugins.
Cómo lo implementa Pixel for ChatGPT Ads
Pixel for ChatGPT Ads es un plugin de WooCommerce que solo envía server-side la compra. Esto es lo que hace en cada uno de los puntos anteriores:
| Aspecto | Comportamiento |
|---|---|
| Evento enviado server-side | Solo order_created |
| Disparador | El pedido pasa a un estado pagado en WooCommerce |
| Event ID | Derivado del pedido; el mismo ID que la compra del navegador |
| Hora de la compra | Se envía la hora original de la compra |
| Fallos temporales | Se reintentan automáticamente |
| Visibilidad | Estado de envío, intentos y código HTTP por pedido |
| Reenvío manual | Disponible para los pedidos que cumplen los requisitos, una vez corregida la causa |
| Clave de API | Guardada para uso server-side; nunca se imprime en la página |
| Consentimiento | Usa el estado de consentimiento registrado para el pedido (WordPress Consent API) |
| Almacenamiento de pedidos | Compatible con HPOS y con el almacenamiento de pedidos antiguo |
La vía server-side de la compra, tal como la implementa el plugin (rótulos en inglés).
- 1El punto de partida es el pedido pagado de WooCommerce, no el navegador del comprador.
- 2La compra viaja desde tu tienda hasta la OpenAI Conversions API.
- 3Los scripts bloqueados, las pestañas cerradas y los bloqueadores de contenido no frenan esta vía.
Las vistas de producto, los añadidos al carrito y los inicios de pago siguen siendo eventos del navegador. La página del píxel de ChatGPT Ads para WooCommerce enumera todos los eventos y desde dónde se envía cada uno.
Expectativas
En qué ayuda el seguimiento server-side y qué no resuelve
El envío server-side hace más fiable la compra. No lo arregla todo.
En qué ayuda el seguimiento server-side
- Compras cuyo evento del navegador bloqueó un bloqueador de contenido.
- Clientes que cierran la pestaña después de pagar.
- Pagos que se confirman más tarde, cuando el cliente ya se ha ido de la web.
- Ver, reintentar y reenviar pedido a pedido los envíos fallidos.
Lo que no resuelve
- No decide la atribución. Si una compra se atribuye a un anuncio de ChatGPT, lo determina OpenAI, no la forma en que se envió el evento.
- No recupera los eventos exclusivos del navegador. Las vistas de producto y la actividad del carrito siguen necesitando el navegador.
- No se salta el consentimiento. Los pedidos sin consentimiento de marketing no se envían.
- No arregla un segundo píxel sin control. Las copias duplicadas sin ID compartidos siguen contando dos veces.
- No garantiza todas las conversiones. Lo que hace es que la compra deje de depender únicamente del navegador.
Preguntas
¿Es obligatoria la Conversions API para ChatGPT Ads?
OpenAI admite medir conversiones con el píxel, con la Conversions API o con los dos (resumen del seguimiento de conversiones). En una tienda, enviar la compra por las dos vías con un ID compartido le da a la compra una vía que no depende del navegador.
¿Puedo llamar a la Conversions API con JavaScript desde la página de agradecimiento?
No. Expondrías tu clave de API y seguirías dependiendo del navegador. OpenAI indica que se use el píxel en el navegador y la Conversions API desde el servidor.
¿El seguimiento server-side necesita contenedores de servidor de Google Tag Manager?
No. WooCommerce ya se ejecuta en un servidor; un plugin puede enviar la compra directamente desde WordPress.
¿Este plugin envía server-side el evento de añadir al carrito?
No. Solo la compra se envía server-side. Los otros tres eventos son del navegador.
Compras server-side sin tener que desarrollar la integración
Pixel for ChatGPT Ads se encarga en WooCommerce del disparador, los event ID, los reintentos y el diagnóstico por pedido. Mismas funciones en todos los planes.
Guías relacionadas
- Píxel de ChatGPT Ads para WooCommerceQué envía el plugin a ChatGPT Ads desde una tienda WooCommerce, cómo se configura y qué no hace.
- Píxel de ChatGPT Ads o API de conversiones: diferencias y cuál usarComparativa entre la medición en el navegador y en el servidor para ChatGPT Ads, y por qué una tienda usa las dos.
- Cómo instalar el píxel de ChatGPT Ads en WooCommerce, paso a pasoRequisitos, de dónde salen el Pixel ID y la clave de API, la configuración y cómo comprobar el primer pedido.