Cómo configurar la Meta CAPI paso a paso

Pre-requisitos

Antes de empezar, asegúrate de tener:

• Cuenta de Meta Business Manager (business.facebook.com);
• Pixel de Facebook ya creado y funcionando en el sitio (con al menos PageView disparando);
• Acceso de admin en el pixel;
• Servidor backend donde correr el código (PHP, Node, Python, Ruby — cualquiera sirve);
• Capacidad de hacer requests HTTPS de salida (firewall permitiendo graph.facebook.com).

Paso 1 — Generar el access token

1. Abre Events Manager;
2. Selecciona el pixel que quieres usar;
3. Ve a Settings → desplázate hasta Conversions API;
4. Haz clic en Generate access token;
5. Copia el token. No podrás verlo de nuevo después. Guárdalo con cuidado.

Paso 2 — Copiar el Pixel ID

Aún en Events Manager, en la parte superior de la página del pixel verás el Pixel ID (15 dígitos). Cópialo. Va junto con el access token.

Paso 3 — Armar el payload

Estructura mínima del payload de un evento Purchase:

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1716640000,
    "event_id": "order_10042_purchase",
    "action_source": "website",
    "event_source_url": "https://tutienda.com/checkout/success",
    "user_data": {
      "em": ["a3f2b9c8d4e5f6a1..."],
      "ph": ["b4e5f6a2c3d9..."],
      "client_ip_address": "200.123.45.67",
      "client_user_agent": "Mozilla/5.0...",
      "fbp": "fb.1.1716640000.123456789",
      "fbc": "fb.1.1716640000.IwAR..."
    },
    "custom_data": {
      "value": 99.90,
      "currency": "USD",
      "content_ids": ["SKU-001"],
      "content_type": "product"
    }
  }],
  "test_event_code": "TEST12345"
}

Campos obligatorios:

• event_name: nombre estándar de Meta — Purchase, Lead, CompleteRegistration, AddToCart, etc.
• event_time: Unix timestamp en segundos, no milisegundos. Error común.
• action_source: "website", "app", "phone_call", etc.
• event_id: para deduplicación con pixel client (ver guía de dedupe).
• user_data: identificadores del usuario (email, teléfono, IP). Cuantos más campos, mayor el Match Quality.

Paso 4 — Enviar vía cURL (o tu HTTP client favorito)

curl -X POST "https://graph.facebook.com/v19.0/{PIXEL_ID}/events" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [...],
    "access_token": "EAAxx..."
  }'

En PHP:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://graph.facebook.com/v19.0/{$pixel_id}/events");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'data' => [$event_payload],
    'access_token' => $access_token
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

Respuesta de éxito (HTTP 200):

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": "AbcDefGhi..."
}

Paso 5 — Compartir event_id con el pixel para deduplicación

En el frontend, al disparar el pixel:

fbq('track', 'Purchase', {
  value: 99.90,
  currency: 'USD'
}, {
  eventID: 'order_10042_purchase'  // ← mismo del CAPI
});

Lo detallamos en la guía completa de deduplicación.

Paso 6 — Hashear PII con SHA-256

Email y teléfono nunca pueden ir en plaintext. Normaliza antes del hash:

// PHP
function hashEmail($email) {
    return hash('sha256', strtolower(trim($email)));
}

function hashPhone($phone) {
    // Normaliza a E.164: +5491199998888 (Argentina) o +5215555555555 (México)
    $digits = preg_replace('/[^0-9]/', '', $phone);
    return hash('sha256', '+' . $digits);
}

$user_data = [
    'em' => [hashEmail($order->customer_email)],
    'ph' => [hashPhone($order->customer_phone)],
    'fn' => [hash('sha256', strtolower(trim($order->customer_first_name)))],
    'ln' => [hash('sha256', strtolower(trim($order->customer_last_name)))],
    'ct' => [hash('sha256', strtolower($order->city))],
    'st' => [hash('sha256', strtolower($order->state))],
    'zp' => [hash('sha256', preg_replace('/[^0-9]/', '', $order->zip))],
    'country' => [hash('sha256', 'ar')],  // o 'mx', 'co', 'es', etc.
    'client_ip_address' => $_SERVER['REMOTE_ADDR'],
    'client_user_agent' => $_SERVER['HTTP_USER_AGENT'],
    'fbp' => $_COOKIE['_fbp'] ?? null,
    'fbc' => $_COOKIE['_fbc'] ?? null,
];

Paso 7 — Testear en Events Manager

Antes de subir a producción, testea con test_event_code:

1. Events Manager → tu pixel → pestaña Test Events;
2. Copia el código de prueba (formato: TEST12345);
3. Inclúyelo en el payload: "test_event_code": "TEST12345";
4. Dispara el evento. En segundos aparece en Events Manager con el label "Test event";
5. Verifica: ¿campos del user_data hasheados? ¿event_id coincidiendo con el pixel?

Paso 8 — Validar en producción

Después de testear, remueve el test_event_code del payload de producción. Si no, Meta lo marca como prueba y no cuenta en la optimización.

Monitorea en Events Manager:

• Event Activity: cuántos eventos llegando por hora;
• Diagnostics: avisos de problemas (deduplicación fallida, campos malformados);
• Event Match Quality: score 1-10 por evento — meta 7+.

Troubleshooting común

"Event time in the past" o "in the future"

Estás enviando timestamp en milisegundos. Meta espera segundos. Divide por 1000.

EMQ trabado en 0

Probablemente el email/teléfono no se está hasheando, o se está hasheando mal (sin lowercase/trim antes). Compara tu hash con echo -n "[email protected]" | shasum -a 256.

Eventos duplicados (Meta avisa)

event_id del pixel ≠ event_id del CAPI. Garantizar que sea la MISMA string. Ver guía de dedupe.

"Invalid OAuth access token"

El token expiró o fue revocado. Genera otro en Events Manager.

FAQ

¿Necesito un programador para configurar CAPI?

Depende. Setup vía Shopify, Tiendanube o CMS con integración nativa lleva 5-15 minutos sin código. Setup vía webhook o directo en la API requiere dev por unas 2-4 horas. Setup vía SaaS (Trakvo, Stape) requiere 0 código — solo conectar OAuth.

¿Cuánto tiempo hasta ver mejora en el Match Quality?

EMQ se actualiza en hasta 48h después de que los eventos empiecen a llegar. Para subir de 5 → 8+ necesitas al menos 7 días de eventos consistentes con PII enriquecido (email + teléfono + click IDs).

¿Meta cobra por usar la CAPI?

No. CAPI es gratuita. Solo pagas tu infraestructura (servidor) o el SaaS que se encarga de eso por ti.

¿Puedo configurar CAPI sin el pixel?

Técnicamente sí, pero Meta NO lo recomienda. Pixel toma eventos rápidos en el cliente (PageView, AddToCart) con baja latencia. CAPI cubre conversiones críticas con privacidad. Corriendo ambos juntos = mejor escenario.

¿Qué es el access token de CAPI y dónde lo genero?

Access token es una llave secreta que autoriza a tu servidor a enviar eventos a Meta. Se genera en Meta Events Manager → Settings → Conversions API → Generate Access Token. Trátalo como contraseña — nunca exponerlo en el frontend.