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.

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: