Conversions API

La Conversions API (CAPI) permite que Meta vea conversiones que ocurren fuera del navegador: pedidos confirmados en tu servidor, clientes potenciales cualificados en un CRM o compras en una tienda física. AdWitch aloja la integración: envías eventos, AdWitch los valida, normaliza y aplica SHA-256 a los campos de coincidencia que Meta espera con hash, los deduplica y los reenvía a tu píxel.

Hay dos formas de acceder:

Endpoint de recepción alojado — una URL y una clave por cuenta publicitaria; tu backend o CRM le envía los eventos en el formato de abajo.
Carga desde el chat — «carga estas compras como conversiones offline» con una tabla o CSV; el agente aplica hash a las filas y las envía después de tu confirmación.

Ambas necesitan un píxel predeterminado en la cuenta publicitaria (Cuentas publicitarias en /accounts) y que, en Meta, un administrador de tu negocio haya aceptado los Business Tools Terms.

Tiendas en Shopify, WooCommerce, BigCommerce, Wix o Tilda

Una tienda o un sitio en una de estas plataformas no necesita el endpoint de recepción: la integración oficial de la plataforma ya envía eventos de servidor (Conversions API) a Meta junto al píxel del navegador. La comprobación Señal y evento de optimización de Cuentas publicitarias reconoce estas plataformas por el dominio en el que se dispara el píxel y muestra estos mismos pasos cuando solo llegan eventos de navegador; en Shopify, WooCommerce y BigCommerce, cuyas integraciones también envían datos de clientes, también cuando la coincidencia de clientes es débil.

Shopify: la app gratuita Facebook & Instagram de Meta.

En el panel de control de Shopify, ve a Canales de venta → Facebook & Instagram → Configuración → Configuración de uso compartido de datos.
En la sección Uso compartido de datos del cliente, activa el uso compartido de datos del cliente y elige el nivel Máximo (Conversions API + píxel de Meta).
Conecta el píxel de Meta que está vinculado en AdWitch como píxel predeterminado de la cuenta publicitaria.
Quita otras apps de píxel y el código del píxel de Meta añadido a mano al tema, para que los eventos no se cuenten dos veces.

Más detalles en el artículo de ayuda de Shopify.

WooCommerce: el plugin oficial y gratuito Meta for WooCommerce (antes Facebook for WooCommerce).

Instala y activa el plugin desde el directorio de plugins de WordPress.
Conéctalo a Meta y elige el píxel de Meta vinculado en AdWitch.
Mantén activada la Conversions API (eventos de servidor) del plugin.
Quita otros plugins de píxel y el código del píxel de Meta añadido a mano al tema.

BigCommerce: la integración Meta Pixel incluida, que sin coste adicional también envía eventos de la Conversions API con datos de clientes cifrados con hash (email, teléfono y nombre).

En el panel de control de BigCommerce, ve a Settings › Data Solutions y, en Web analytics, haz clic en Connect junto a Meta Pixel.
Haz clic en Connect with Meta Pixel, inicia sesión en Facebook y elige tu Business Manager, tu página de Facebook y el píxel de Meta vinculado en AdWitch.
En la pantalla What is BigCommerce allowed to do, deja activadas todas las opciones.
Quita otras apps de píxel y el código del píxel de Meta añadido a mano al tema o a los scripts.

Más detalles en el artículo de ayuda de BigCommerce (en inglés).

Wix: la integración incluida Píxel y API de conversiones de Meta, que envía eventos desde los servidores de Wix. Necesita un plan Premium, un dominio conectado y el dominio verificado en Meta.

En el panel de control del sitio, abre Integraciones de marketing y haz clic en Conectar dentro de Píxel y API de conversiones de Meta. Si solo ves una integración antigua de Píxel de Meta, elimínala, actualiza la página y conecta Píxel y API de conversiones de Meta.
Haz clic en Conectar a Facebook, inicia sesión y, cuando te pida el píxel, elige el píxel de Meta vinculado en AdWitch.
Quita el código del píxel de Meta añadido a mano al sitio (código personalizado).

Más detalles en el artículo de ayuda de Wix.

Tilda: la conexión incluida con la Conversions API, que envía a Meta los envíos de formularios (Lead) y los pagos del carrito (Purchase) desde el servidor de Tilda.

En el Administrador de eventos de Meta, abre el píxel de Meta vinculado en AdWitch, ve a su configuración y, en la sección Conversions API, haz clic en Generar token de acceso.
En Tilda, ve a Configuración del sitio → Formularios → API de conversión de Facebook, pega el ID de píxel y el token, y guarda.
En el Contenido de cada formulario cuyos envíos deban llegar a Meta, incluido el carrito, marca el receptor de datos API de conversión de Facebook y vuelve a publicar esas páginas.
Quita cualquier otro código del píxel de Meta añadido a mano al sitio.

Más detalles en el artículo de ayuda de Tilda.

¿Envías las mismas compras también por el endpoint de recepción? Se contarán dos veces salvo que ambas rutas envíen el mismo event_id (con el mismo event_name) para el mismo pedido.

Los webhooks de estas plataformas dirigidos al endpoint de recepción no funcionan: no están en el formato de eventos de servidor de Meta, así que el endpoint responde 400 DATA_REQUIRED (o 401 si la solicitud no lleva clave) y no registra nada. Si esas solicitudes llevan tu clave de ingesta, la nota Último problema en Conversions API de la tarjeta de la cuenta lo indica —con el nombre de la plataforma cuando la solicitud lo revela— y enlaza a esta sección. Elimina esos webhooks en la propia plataforma y usa su integración oficial descrita arriba.

Configurar el endpoint de recepción

Abre Cuentas publicitarias (/accounts) y despliega Conversions API en la tarjeta de la cuenta.
Haz clic en Crear clave de recepción. La clave (capi_<id>_<secret>, con un ID hexadecimal de 12 caracteres y un secreto hexadecimal de 48) se muestra una sola vez; guárdala ahora en tu backend. AdWitch solo conserva un hash. ¿La has perdido? Rotar clave emite una nueva e invalida la anterior inmediatamente.
Opcionalmente establece un código de evento de prueba (Administrador de eventos → Eventos de prueba). Mientras esté establecido, cada lote aparece en la pestaña Eventos de prueba en vez de los informes de producción; bórralo cuando pases a producción.
Copia el ejemplo de curl o Webhook JSON y envía tu primer evento.

La sección también muestra los contadores de las últimas 24 horas (recibidos, reenviados, rechazados por validación, duplicados y rechazados por Meta), los lotes recientes y el último problema, si lo hay. Aceptar eventos pausa el endpoint sin revocar la clave (los emisores reciben 403 CAPI_DISABLED); Revocar clave lo detiene definitivamente (401 KEY_REVOKED).

Solo los propietarios y administradores del equipo gestionan las claves; los demás miembros ven el estado.

Contrato de recepción

POST https://api.adwitch.ai/api/capi/v1/events
Authorization: Bearer capi_<id>_<secret>      (or X-Capi-Key: …)
Content-Type: application/json

El cuerpo tiene el formato estándar de evento de servidor de Meta: data[] de eventos (también se acepta un array simple), además de un test_event_code opcional a nivel de solicitud que sustituye al guardado en la configuración:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1757600000,
      "action_source": "website",
      "event_source_url": "https://shop.example.com/checkout/thank-you",
      "event_id": "order-10045",
      "user_data": {
        "em": "customer@example.com",
        "ph": "+34600000000",
        "client_ip_address": "203.0.113.5",
        "client_user_agent": "Mozilla/5.0",
        "fbp": "fb.1.1700000000000.123456789"
      },
      "custom_data": { "value": 49.9, "currency": "EUR", "order_id": "10045" }
    }
  ],
  "test_event_code": "TEST12345"
}

Reglas aplicadas a cada evento:

Campo	Regla
`event_name`	Obligatorio. Nombres estándar (`Purchase`, `Lead`, `CompleteRegistration`, …) o uno personalizado.
`event_time`	Segundos Unix (se aceptan milisegundos y fechas ISO). Como máximo 7 días de antigüedad y 10 minutos en el futuro.
`action_source`	`website`, `email`, `app`, `phone_call`, `chat`, `physical_store`, `system_generated`, `other`. `website` también necesita `event_source_url`; `app` necesita `app_data` (`advertiser_tracking_enabled` 0 o 1 y `extinfo` con la plataforma `a2`/`i2` y la versión del sistema operativo) y solo cuenta si el píxel de la cuenta es el conjunto de datos vinculado a la app. `business_messaging` se rechaza aquí (`business_messaging_not_accepted`): esos eventos van al conjunto de datos de una Página, una cuenta de WhatsApp Business o una cuenta de Instagram, no al píxel; envíalos desde el chat (ver abajo).
`event_id`	Recomendado: es tu clave de idempotencia. Si falta, se deriva un ID determinista del evento para que una solicitud repetida no cuente dos veces.
`user_data`	Al menos un identificador coincidente (`em`, `ph`, `external_id`, `fbp`/`fbc`, `lead_id`, IP + agente de usuario o nombre + ciudad/código postal/fecha de nacimiento). Se entienden alias largos (`email`, `phone`, `first_name`, …).
`custom_data`	`Purchase` necesita `value` y `currency` (si falta, se completa la moneda de la cuenta publicitaria).

Hashing. AdWitch normaliza (em, ph, fn, ln, ge, db, ct, st, zp, country y external_id) —minúsculas, espacios recortados, solo dígitos telefónicos con prefijo de país, etc.— y les aplica SHA-256. Un valor que ya sea un resumen SHA-256 hexadecimal de 64 caracteres se reenvía tal cual. client_ip_address, client_user_agent, fbp, fbc, lead_id y los demás identificadores que Meta espera sin hash se reenvían sin hash.

Deduplicación. El mismo event_name + event_id dentro de 48 horas en la misma cuenta se descarta y se informa en duplicates; esto cubre los reintentos y el caso en que los mismos pedidos llegan por el endpoint y por carga del chat.

Límites. Hasta 1000 eventos y 1 MB por solicitud; 600 solicitudes por minuto y clave y 1200 por minuto y dirección IP. Para volúmenes mayores, divide el lote.

Respuestas

202 Accepted — se puso algo en cola para Meta; 200 OK — no hay nada que reenviar (todas las filas fueron rechazadas o duplicadas). Ambas respuestas contienen:

{
  "status": "queued",
  "batch_id": 812,
  "pixel_id": "555000111",
  "received": 4,
  "accepted": 2,
  "rejected": [{ "index": 2, "reason": "event_time_invalid", "field": "event_time", "message": "…" }],
  "duplicates": [{ "index": 3, "reason": "duplicate_event_id", "field": "event_id", "message": "an event with the same event_name and event_id was already accepted in the last 48 hours" }],
  "accepted_event_ids": [{ "index": 0, "event_id": "order-10045" }, { "index": 1, "event_id": "order-10046" }],
  "hashed_user_data_keys": ["em", "ph"],
  "test_event_code": "TEST12345"
}

Las filas rechazadas y duplicadas incluyen índice, motivo y mensaje, y el campo cuando corresponde, pero nunca el valor personal. Si no se puso nada en cola, status es nothing_to_forward y batch_id es null. test_event_code aparece solo cuando está establecido.

Estado	`reason`	Significado
401	`KEY_MISSING` / `KEY_INVALID`	No hay clave, la clave es desconocida o el secreto es incorrecto.
401	`KEY_REVOKED`	La clave se revocó en la configuración; crea una nueva.
403	`CAPI_DISABLED`	Aceptar eventos está desactivado para esta cuenta.
409	`PIXEL_NOT_BOUND`	La cuenta ya no tiene un píxel predeterminado.
409	`FB_NOT_CONNECTED`	La conexión de Meta de la cuenta ha desaparecido; vuelve a conectarla.
400	`DATA_REQUIRED` / `TOO_MANY_EVENTS`	Falta `data[]` o hay más de 1000 eventos. Si el cuerpo no tiene el formato de Meta, la respuesta incluye `hint` y `docs`, y además `platform` y `topic` cuando es un webhook de una de las plataformas de arriba.
429	`RATE_LIMITED`	Reduce la velocidad; `Retry-After` indica cuándo.

El reenvío es asíncrono: el estado del lote (forwarded, partial, failed, terms_required) y las advertencias de Meta por evento aparecen en los Lotes recientes de la cuenta. Si Meta rechaza los eventos porque no se aceptaron los Business Tools Terms, la sección muestra el aviso con el enlace del negocio; no se reintenta nada hasta que un administrador los acepte.

Cargar conversiones desde el chat

Pide al agente, por ejemplo: «Carga estas compras como conversiones offline» y pega una tabla o adjunta un CSV con columnas como email, phone, order_id, value, currency, date (se reconocen encabezados en inglés, ruso y español). El agente:

normaliza y aplica hash localmente a las filas e informa de lo que se enviaría (dry_run): cuántas filas, qué identificadores se han convertido, y qué filas se rechazan y por qué;
solicita tu confirmación explícita: los datos de clientes (como hashes) salen de la plataforma;
envía lotes de hasta 1000 eventos por llamada a Graph e informa de events_received y de las advertencias de Meta;
te dirige a Administrador de eventos → Eventos de prueba (con un código de evento de prueba) o Información general; get_pixel_diagnostics muestra los eventos que llegan.

Las cargas del chat comparten la ventana de deduplicación de 48 horas con el endpoint de recepción.

Ventas cerradas en chats de Messenger, WhatsApp o Instagram

Las compras y los clientes potenciales cualificados conseguidos en una conversación iniciada por un anuncio de clic a mensaje se envían con la Conversions API for Business Messaging de Meta. Así Meta puede optimizar los anuncios de clic a Messenger y clic a WhatsApp para compras en chats (el objetivo de compras en mensajes); los eventos de Instagram solo sirven para medir. Cada fila necesita messaging_channel (whatsapp, messenger o instagram) y el par de identificadores de ese chat:

Canal	Cuenta	Persona en el chat
`whatsapp`	`whatsapp_business_account_id`	`ctwa_clid` (del webhook del anuncio de clic a WhatsApp)
`messenger`	`page_id`	`page_scoped_user_id` (PSID)
`instagram`	`ig_account_id`	`ig_sid` (IGSID)

Eventos admitidos: Purchase, LeadSubmitted, QualifiedLead, InitiateCheckout, AddToCart, ViewContent, OrderCreated, OrderShipped, OrderDelivered, OrderCanceled, OrderReturned, CartAbandoned, RatingProvided, ReviewProvided. Una carga cubre un canal y una cuenta. Los eventos van al conjunto de datos de esa Página, cuenta de WhatsApp Business o cuenta de Instagram (se crea si no existe), nunca al píxel. Una fila sin canal, con un canal desconocido o con un identificador ausente o de otro canal se rechaza con su código de motivo. Antes del primer envío, el agente enumera los permisos adicionales de Meta (page_events para Messenger; whatsapp_business_management y whatsapp_business_manage_events para WhatsApp; instagram_manage_events para Instagram) con su estado y no envía nada mientras se sepa que falta alguno. Meta no deduplica estos eventos, así que sube cada venta una sola vez.

Etapas de venta desde un CRM

El objetivo de optimización Clientes potenciales de conversión (QUALITY_LEAD) aprende de las etapas que tu CRM registra para cada cliente potencial. Envíalas al endpoint de recepción en el formato CRM de Meta: un evento por cada cambio de etapa, con el nombre de la etapa:

event_name: la etapa tal como la nombra tu CRM (Lead, Qualified, Opportunity, Closed Won, …), incluida la primera, el propio cliente potencial.
action_source: system_generated.
user_data.lead_id: el ID de cliente potencial de Meta de un formulario instantáneo (el leadgen_id de Meta), como cadena y tal cual lo dio Meta; se reenvía sin hash. Si no hay ID de cliente potencial, envía el email o el teléfono usados para la coincidencia; AdWitch les aplica hash.
custom_data.event_source: crm; custom_data.lead_event_source: el nombre de tu CRM (HubSpot, Salesforce, In-house CRM, …).
event_time: la hora del cambio de etapa, con 7 días de antigüedad como máximo y posterior al cliente potencial.

{
  "data": [
    {
      "event_name": "Qualified",
      "event_time": 1757600000,
      "action_source": "system_generated",
      "event_id": "hubspot-1234567890123456-qualified",
      "user_data": { "lead_id": "1234567890123456" },
      "custom_data": {
        "event_source": "crm",
        "lead_event_source": "HubSpot"
      }
    }
  ]
}

Pon los ID entre comillas: un ID de cliente potencial de 15 a 17 dígitos escrito como número JSON puede quedar redondeado por las herramientas por las que pasa y apuntar entonces a otro cliente potencial.

La regla de los 7 días. Meta solo acepta una etapa si su event_time tiene 7 días de antigüedad como máximo, así que AdWitch rechaza las más antiguas con event_time_too_old: una exportación mensual del CRM pierde la mayoría de sus etapas. Sube los cambios de etapa al menos una vez al día: primero con un código de evento de prueba (Administrador de eventos → Eventos de prueba) y después sin él.

En el chat, adjunta las etapas como tabla o CSV con las columnas lead_id, event_name, event_time, event_source y lead_event_source, y pide al agente que las envíe como etapas de CRM (action_source system_generated).

Lo que no está incluido

Alojar el fragmento del píxel del navegador o un SDK de JavaScript.
La App Events API del SDK (los eventos de app desde tu propio servidor usan action_source app, arriba), feeds de catálogos y la API de conversiones offline heredada (conjuntos de eventos offline).
Una app o plugin propio para Shopify, WooCommerce u otra plataforma de tienda; usa las integraciones oficiales descritas arriba.

Los eventos se contabilizan por equipo en el registro de uso; actualmente no se facturan.