APIs de conversiones

Estas guías explican cómo conectar y configurar el envío de conversiones desde Referrer Tracker a las plataformas publicitarias.

Sync Conversiones

Sync Conversiones agrupa las integraciones que permiten enviar conversiones desde Referrer Tracker a plataformas publicitarias (Meta hoy; en el futuro Google Ads, etc.).

Meta (Conversions API)

La sección Meta del dashboard te permite conectar tu cuenta de Meta mediante OAuth, seleccionar el Pixel o Dataset donde se enviarán los eventos, y definir el mapeo de conversiones que quieres sincronizar.

Objetivo

Enviar conversiones (leads, leads cualificados, ventas, etc.) a Meta con un event_name correcto para mejorar atribución y optimización de campañas.

Flujo en el dashboard

  1. Conectar Meta: el usuario autoriza la app y el servidor guarda un access_token (no se guarda contraseña).
  2. Seleccionar activos: se listan Businesses y sus Pixels/Datasets para elegir el destino.
  3. Configurar conversiones: se define el mapeo de “tipo de conversión” a “evento Meta” y opcionalmente el valor/moneda.

Selección de destino (Business / Pixel / Dataset)

Para enviar eventos, Meta necesita un destino. Dependiendo de tu caso, usarás:

Importante: Debes seleccionar al menos Pixel o Dataset (uno de los dos).

Cómo crear un Dataset en Meta (Events Manager)

Si no tienes Dataset (o prefieres usar Conversions API), puedes crearlo desde Events Manager. La interfaz puede cambiar, pero el flujo es parecido:

  1. Entra en Events Manager (Administrador de eventos) con el Business correcto.
  2. Haz click en Conectar fuente de datos (o Connect data sources).
  3. Elige Web.
  4. Selecciona Conversions API y sigue el asistente para crear un Dataset (nombre, Business, etc.).
  5. Una vez creado, ve a la sección de Configuración del dataset/pixel y copia el Dataset ID.

En Referrer Tracker, ese Dataset ID es el valor que seleccionarás en el desplegable “Dataset (opcional)”.

Enlaces oficiales (Meta)

Guía de Meta (access token / endpoint) vs Referrer Tracker

La guía de Meta suele indicar que debes generar un identificador de acceso (access token) y enviar eventos directamente a:

https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}

En Referrer Tracker, este paso se gestiona desde el dashboard:

Payload que envía Referrer Tracker a Meta

Meta muestra un listado amplio de parámetros posibles por tipo de evento (Lead, Purchase, etc.). Referrer Tracker envía un subconjunto estable:

Nota: Actualmente Referrer Tracker no envía algunos campos opcionales que Meta sugiere en su asistente, como event_source_url (URL), client_user_agent (User-Agent) o detalles de contenido (content_ids, content_type). Si necesitas mejorar el match quality, podemos ampliarlo en una iteración.

Configuración de conversiones

La tabla de conversiones define cómo se transforman tus conversiones internas en eventos que recibirá Meta.

Meta (web / server-side genérico)

Para conversiones Meta que no vienen de un formulario nativo de Meta Lead Ads, lo normal es enviar a Referrer Tracker un evento genérico con buenos identificadores de matching. Después, Referrer Tracker aplicará el mapping del dashboard y construirá el payload final para Meta Conversions API.

Ejemplo exacto (cURL) - Meta web / server-side

curl -X POST https://www.referrertracker.com/api/conversions/ingest \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "meta",
    "conversion_type": "LeadQualified",
    "event_time": "2026-03-08T14:42:00Z",
    "external_id": "crm-deal-93811",
    "data": {
      "lead_id": "lead-93811",
      "email": "cliente@ejemplo.com",
      "phone": "+34600111222",
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "fbclid": "fb.1.1710000000000.AbCdEfGhIjKlMnOpQr",
      "fbc": "fb.1.1710000000000.AbCdEfGhIjKlMnOpQr",
      "fbp": "fb.1.1710000000000.1234567890"
    }
  }'

En este caso, Referrer Tracker tratará la conversión como un evento Meta genérico y construirá el payload final con los identificadores de matching disponibles.

Meta Lead Forms: flujo correcto vía CRM

Si el lead original viene de un formulario nativo de Meta Lead Ads, Referrer Tracker no debe capturarlo directamente desde Meta. El flujo correcto es:

  1. El usuario capta el lead en Meta Lead Ads.
  2. Ese lead entra primero en su CRM o automatización.
  3. Cuando el usuario decide que ese lead debe contarse como Lead, LeadQualified, Purchase, etc., su CRM envía la conversión a /api/conversions/ingest.
  4. Referrer Tracker usa el mapping del dashboard y lo envía a Meta Conversions API.

Importante: el nombre final del evento que se envía a Meta no depende del formulario. Depende del conversion_type / event_name que tu CRM nos envía y del mapping que hayas configurado en el dashboard.

Qué datos debes guardar del lead en tu CRM

Si el origen es un formulario nativo de Meta, recomendamos guardar como mínimo estos campos para poder reenviarnos la conversión más tarde:

Contrato recomendado para enviar una conversión de Meta Lead Forms a Referrer Tracker

Ejemplo exacto (cURL) - payload de ingestión a Referrer Tracker para Meta Lead Form

curl -X POST https://www.referrertracker.com/api/conversions/ingest \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "meta",
    "conversion_type": "LeadQualified",
    "event_time": "2026-03-08T14:42:00Z",
    "external_id": "crm-deal-93811",
    "data": {
      "lead_id": "lead-93811",
      "meta_leadgen_id": "12020101010101010",
      "meta_form_id": "673838383838383",
      "meta_page_id": "112233445566778",
      "meta_form_name": "Demo Request ES",
      "meta_page_name": "Mi Marca",
      "email": "cliente@ejemplo.com",
      "phone": "+34600111222",
      "fbclid": "fb.1.1710000000000.AbCdEfGhIjKlMnOpQr",
      "fbc": "fb.1.1710000000000.AbCdEfGhIjKlMnOpQr",
      "fbp": "fb.1.1710000000000.1234567890"
    }
  }'

En este ejemplo, el CRM nos envía LeadQualified. Luego Referrer Tracker buscará en tu configuración de Meta qué Evento Meta corresponde a LeadQualified y construirá el payload final hacia la API de conversiones.

Cuando detectamos un Lead Form nativo por la presencia de meta_leadgen_id y meta_form_id, Referrer Tracker mantiene destination = meta y construye una rama saliente específica para este caso.

Conversiones personalizadas (Meta)

Al crear una conversión personalizada en Meta (Events Manager), Meta obliga a definir:

Para simplificar y estandarizar la configuración, Referrer Tracker envía siempre este campo en custom_data a Meta:

custom_data.rt_source = "referrertracker"

Por tanto, la regla mínima recomendada para tus conversiones personalizadas es:

custom_data.rt_source es igual a "referrertracker"

A partir de ahí, si quieres filtrar más (por ejemplo por event_name o por un valor), puedes añadir reglas adicionales en Meta.

[
  {
    "conversionType": "Lead",
    "metaEventName": "Lead",
    "value": "0",
    "currency": "EUR"
  },
  {
    "conversionType": "LeadQualified",
    "metaEventName": "CompleteRegistration",
    "value": "100",
    "currency": "EUR"
  },
  {
    "conversionType": "Purchase",
    "metaEventName": "Purchase",
    "value": "{{value}}",
    "currency": "EUR"
  }
]

Troubleshooting

Google Ads (Offline + Enhanced Conversions)

La sección Google Ads del dashboard te permite conectar tu cuenta (OAuth), seleccionar la cuenta (Customer ID / MCC si aplica) y mapear tus conversiones internas a Conversion Actions de Google Ads. Una vez configurado, Referrer Tracker enviará conversiones con destino google automáticamente.

Objetivo

Importar conversiones offline (por ejemplo, leads cualificados o ventas cerradas en CRM) a Google Ads usando GCLID/GBRAID/WBRAID, y mejorar el match con Enhanced Conversions cuando haya email/teléfono/nombre.

Flujo en el dashboard

  1. Conectar Google Ads: el usuario autoriza la app y el servidor guarda access_token + refresh_token.
  2. Configurar cuenta: indicar Customer ID (sin guiones) y opcionalmente Manager Customer ID (MCC).
  3. Configurar conversiones: mapear conversionType (evento interno) a conversionAction (acción de conversión en Google Ads) y, opcionalmente, valor/moneda.

Importar conversiones desde tu CRM (API)

Para que Referrer Tracker pueda enviar conversiones a Google Ads, debes enviar los eventos a:

POST /api/conversions/ingest

Autenticación:

Authorization: Bearer TU_API_KEY

Campos principales del payload

Enhanced Conversions (recomendado)

Si envías datos de usuario, Referrer Tracker los normaliza y hashea (SHA-256) para enviarlos como userIdentifiers a Google Ads, mejorando el matching.

Importante: Google Ads rechaza conversiones con fecha futura. Si tu event_time llega muy ajustado (por desfases de reloj), Referrer Tracker lo ajusta automáticamente para evitar errores del tipo LATER_THAN_MAXIMUM_DATE.

Ejemplo (cURL) - Google Ads + Enhanced Conversions

curl -X POST https://www.referrertracker.com/api/conversions/ingest \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "google",
    "conversion_type": "Lead",
    "event_time": "2026-01-05T09:19:00Z",
    "source": "NocoDB",
    "external_id": "14522",
    "data": {
      "lead_id": "14522",
      "email": "sonia.puca@gmail.com",
      "phone": "34607154665",
      "first_name": "Sonia",
      "last_name": "García Fernández",
      "gclid": "CjwKCAiA3-3KBhBiEiwA2x7FdP1cDw1_lqhA2zjFI_fPJK7Dkb8cD08EwQ-f243UXhFB5VCc8RFZpxoCJzAQAvD_BwE",
      "consent": {
        "ad_user_data": "GRANTED",
        "ad_personalization": "DENIED"
      }
    }
  }'

Requisitos y buenas prácticas (Google Ads)

Ver estado y errores

Puedes ver el estado de envíos desde el dashboard de conversiones. El sistema guarda un registro por conversión en conversion_deliveries con: