Instalar la API de Conversiones de Meta es conectar tu tienda, tu servidor o tu CRM para que las compras y los leads lleguen a Meta sin depender solo del navegador. En esta guía elegís el método que te conviene, lo configurás, deduplicás con el píxel y lo probás. Cuánto lleva depende de tu plataforma.
Si todavía no tenés claro qué es y para qué sirve, arrancá por la guía de qué es la API de Conversiones. Acá vamos directo al cómo, con lo que dice la documentación oficial de Meta.
Antes de empezar
- Un píxel de Meta activo: la API usa el mismo ID que el píxel de Meta. Si ya tenés uno, no crees otro: navegador y servidor van al mismo conjunto de datos.
- Acceso al portafolio comercial: necesitás permisos sobre el píxel dentro de tu Meta Business Manager. El enlace para generar el token de acceso solo lo ven los usuarios con privilegios de desarrollador en el negocio.
- Dominio verificado: plataformas como Tiendanube lo piden como parte de la conexión.
- Saber qué eventos importan: compra, inicio de pago, lead, registro. Definilos antes de tocar nada.
- Consentimiento resuelto: mandás datos de clientes, así que tu sitio tiene que pedir y registrar el consentimiento. Si además usás Google, mirá cómo configurar Consent Mode v2.
Paso 1: Elegí el método de instalación
Hay cinco caminos reales. La regla de Meta es simple: si tu tienda ya trabaja con una plataforma que soporta la API de Conversiones, usá esa integración antes que cualquier otra cosa.
| Método | Para quién | Esfuerzo técnico | Qué tener en cuenta |
|---|---|---|---|
| Integración de socio (Tiendanube, Shopify, WooCommerce) | Tiendas en plataformas con conexión oficial | Bajo | Se activa desde el panel de la plataforma; controlás menos qué se envía |
| Conversions API Gateway | Sitios con píxel que no tienen integración de socio | Bajo, sin código | Requiere una cuenta en un proveedor de nube (por ejemplo, AWS) y replica los eventos del píxel |
| Configuración manual desde el Administrador de eventos | Equipos con un desarrollador disponible | Medio | Meta arma instrucciones personalizadas que podés seguir vos o mandarle al desarrollador |
| GTM del lado del servidor | Sitios que ya miden todo con Google Tag Manager | Medio a alto | Necesitás un contenedor de servidor alojado y mantenerlo |
| API directa | Negocios con backend propio o eventos de CRM | Alto | Control total de qué mandás, incluidas ventas offline |
Paso 2: Activala con la integración de tu plataforma
Tiendanube tiene integración oficial. Según su centro de ayuda, la API de Conversiones se activa sola cuando conectás tu portafolio de Meta:
- En el administrador de Tiendanube, entrá a la sección Instagram y Facebook.
- Hacé clic en Conectar con Meta, o en Editar conexión si ya estaba conectada.
- Elegí Continuar como y seleccioná catálogo, página de Facebook, cuenta publicitaria, píxel y cuenta comercial.
- Dejá activo el permiso de acceso a tus anuncios y estadísticas.
- Verificá tu dominio en el portafolio comercial.
Un detalle que Tiendanube marca con claridad: su integración nativa no es compatible con el Conversions API Gateway. Si tenés los dos activos, el Gateway puede bloquear o contaminar los datos. Elegí uno.
En Shopify y WooCommerce el camino es el mismo en concepto: conectás la integración oficial de Meta para la plataforma y elegís el nivel de datos compartidos. Antes de sumar otra cosa, fijate si esa conexión ya está enviando eventos de servidor.
Paso 3: Si no tenés socio, usá el Gateway o la configuración manual
El Conversions API Gateway es una opción de autoservicio dentro del Administrador de eventos. Recibe los eventos del navegador y los manda a la API de Conversiones: cada vez que el píxel dispara, el evento viaja a Meta y también al Gateway por HTTPS. No requiere programar, pero sí una cuenta en un proveedor de nube externo a Meta donde se despliega la infraestructura. Meta lo recomienda si ya usás el píxel, todavía no mandás eventos web por la API y no trabajás con un socio de ecommerce.
La configuración manual está en el Administrador de eventos: elegís tu píxel, vas a Configuración, buscás la sección API de conversiones y elegís configurarla manualmente. Meta te arma instrucciones personalizadas para el píxel, la API y los eventos, y en la última pantalla podés seguirlas vos o mandárselas a un desarrollador.
Paso 4: Con GTM del lado del servidor o con la API directa, generá el token
Tanto la integración directa como GTM server-side necesitan un token de acceso. Se genera así:
- Abrí el Administrador de eventos y elegí tu píxel.
- Entrá a la pestaña Configuración.
- En la sección API de conversiones, hacé clic en Generar token de acceso.
El token va siempre en el servidor, nunca en el código del sitio. Si lo pegás en un script del navegador, cualquiera puede verlo y mandar eventos falsos a tu píxel.
Con GTM del lado del servidor, el contenedor web manda los eventos a tu contenedor de servidor y ahí una etiqueta de la API de Conversiones los reenvía a Meta con el token. Necesitás alojar ese contenedor y mantenerlo, igual que cualquier servidor.
Paso 5: Armá el payload mínimo
Si vas por la API directa, cada envío es un POST al endpoint de eventos de tu píxel. Este es el mínimo que conviene mandar en una compra web, basado en el ejemplo de la guía Using the API (los hashes de em y ph son los de ejemplo de esa documentación):
POST https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}
{
"data": [
{
"event_name": "Purchase",
"event_time": 1633552688,
"event_id": "pedido-10482",
"action_source": "website",
"event_source_url": "https://tutienda.com/gracias",
"user_data": {
"em": ["309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"],
"ph": ["254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4"],
"client_ip_address": "203.0.113.10",
"client_user_agent": "Mozilla/5.0 (...)",
"fbp": "fb.1.1596403881668.1116446470"
},
"custom_data": {
"currency": "ARS",
"value": 45000
}
}
],
"test_event_code": "TEST12345"
}Qué hace cada parte:
- event_name: el nombre del evento, igual al que usa el píxel (Purchase, Lead, InitiateCheckout).
- event_time: marca de tiempo Unix en segundos. Puede ser de hasta 7 días antes del envío.
- event_id: el identificador que usás para deduplicar. Un número de pedido funciona bien.
- action_source: dónde pasó la conversión. Para tu sitio, website.
- user_data: los datos del cliente. Según la página de parámetros de información del cliente, email, teléfono, nombre, apellido, ciudad, código postal, país y external_id van con hash SHA-256. La IP, el user agent, fbp y fbc van sin hash. Para eventos web, client_user_agent es obligatorio.
- custom_data: valor y moneda de la compra.
- test_event_code: solo para pruebas. Lo sacás en producción.
Antes de hashear, normalizá: el email sin espacios al principio y al final y en minúsculas; el teléfono solo con números, sin símbolos ni ceros iniciales y con código de país adelante. Un dato mal normalizado genera un hash que no coincide con nada. Podés mandar hasta 1.000 eventos por solicitud en el arreglo data.
Paso 6: Configurá la deduplicación con event_id
Si el píxel y la API mandan la misma compra, Meta tiene que saber que es una sola. Para eso el eventID del píxel tiene que ser igual al event_id de la API, y el nombre del evento tiene que coincidir. En el navegador queda así:
fbq('track', 'Purchase', {value: 45000, currency: 'ARS'}, {eventID: 'pedido-10482'});Y en el servidor mandás Purchase con event_id pedido-10482. Meta deduplica los eventos que llegan dentro de las 48 horas desde que recibe el primero. El identificador tiene que ser único por conversión: si usás el mismo valor fijo para todas, Meta va a descartar compras reales.
Paso 7: Probá con la herramienta Probar eventos
En el Administrador de eventos, dentro de tu píxel, abrí Probar eventos. La herramienta te da un código de prueba que mandás como test_event_code. Según la ayuda de Meta, los eventos de prueba deberían aparecer en unos 30 segundos. Ahí revisás tres cosas:
- Que lleguen los eventos del servidor con los parámetros correctos.
- Que la deduplicación funcione: la herramienta muestra qué eventos se procesaron y cuáles se deduplicaron.
- Que no haya actividad rara, como eventos repetidos o valores en cero.
Ojo con algo que Meta aclara: los eventos enviados con test_event_code no se descartan. Entran al Administrador de eventos y se usan para segmentación y medición. Por eso, probá con datos reales de una compra de prueba y sacá el código apenas termines.
Paso 8: Revisá la calidad de coincidencia
La calidad de coincidencia de eventos es una puntuación sobre 10 que ves en el Administrador de eventos para cada evento enviado por la API. Indica qué tan bien Meta puede asociar ese evento con una cuenta. Meta la calcula según qué parámetros de cliente mandás, su calidad y el porcentaje de eventos que logran coincidir. Si está baja, revisá qué te falta: email y teléfono normalizados, external_id, fbp y fbc cuando existen. Eso alimenta mejor a las campañas de Advantage+ y a las audiencias de remarketing.
Todo esto es first-party data: mandá solo lo que tengas autorizado.
Errores comunes
- Dos integraciones a la vez: la de la plataforma más el Gateway, o el plugin más GTM server-side. Resultado: compras duplicadas o datos contaminados.
- event_id distinto en cada lado: el píxel manda un ID y el servidor otro. Meta cuenta dos conversiones.
- Hashear lo que no va: la IP, el user agent, fbp y fbc se mandan sin hash.
- No normalizar antes de hashear: un email con mayúsculas o un teléfono con guiones da un hash inútil.
- Dejar test_event_code en producción.
- Token en el navegador: el token de acceso vive solo en el servidor.
- event_time viejo o en milisegundos: tiene que estar en segundos y dentro de los 7 días.
Checklist final
- Un solo método de envío de servidor activo.
- Píxel y API apuntando al mismo ID.
- Mismo event_name y mismo event_id en navegador y servidor.
- Datos de cliente normalizados y con hash SHA-256; IP, user agent, fbp y fbc sin hash.
- client_user_agent presente en eventos web.
- Eventos verificados en Probar eventos y test_event_code removido.
- Calidad de coincidencia revisada por evento.
- Consentimiento del usuario registrado.
Preguntas frecuentes
¿Necesito un desarrollador para instalar la API de Conversiones?
No siempre. Si tu tienda está en una plataforma con integración oficial, como Tiendanube, Shopify o WooCommerce, la activás desde el panel. El Conversions API Gateway también se instala sin código, aunque pide una cuenta en un proveedor de nube. La integración directa y GTM del lado del servidor sí requieren a alguien técnico.
¿La API de Conversiones reemplaza al píxel de Meta?
No. Meta recomienda usarlos juntos: el píxel mide desde el navegador y la API desde tu servidor o plataforma. Para que no se cuenten dos veces los mismos eventos, tenés que mandar el mismo event_id desde los dos lados.
¿Cuánto tiempo tengo para enviar un evento por la API?
Según la documentación de Meta, el event_time puede ser de hasta 7 días antes del momento en que mandás el evento. Para conversiones en tienda física el plazo es de 62 días. Lo ideal para eventos web es enviarlos en el momento en que ocurren.
¿Qué datos del cliente tengo que hashear?
Email, teléfono, nombre, apellido, fecha de nacimiento, género, ciudad, provincia, código postal, país y external_id van con hash SHA-256, después de normalizarlos. La IP, el user agent, fbp y fbc se mandan sin hash.
¿Puedo usar el Gateway si tengo Tiendanube?
Tiendanube aclara en su centro de ayuda que su integración nativa no es compatible con el Conversions API Gateway de Meta y que tener los dos activos puede bloquear o contaminar los datos. Si usás la integración de Tiendanube, desactivá el Gateway.
Si querés que revisemos tu instalación, el equipo de Meta Ads de Go For audita píxel, API de Conversiones y deduplicación. También podés empezar por una auditoría con IA de tu cuenta.