Saltar al contenido principal

​
Configuración de la API de conversiones

​
Requisitos previos 

​
Acceso al Ads API - Nuevas solicitudes

Paso 1: Cuenta de desarrollador
  • Al solicitar una Cuenta de desarrollador, suscríbete a uno de nuestros planes para obtener aprobación instantánea.
  • Nota: Como práctica recomendada, te sugerimos encarecidamente usar el handle oficial de X de tu empresa para crear una cuenta de desarrollador y solicitar acceso al Ads API. Si la cuenta de desarrollador está asociada a un handle de desarrollador, no hay forma de transferir esas credenciales si fuera necesario. Es mejor mantenerla bajo una cuenta de empresa para su gestión continua y utilizar Multi-user login según sea necesario. De lo contrario, como mínimo, la cuenta debe configurarse con ajustes no predeterminados (imagen de encabezado, avatar, descripción y URL de la biografía) y usar autenticación de dos factores.
Paso 2: Solicitud de Ads API
  • Asegúrate de tener listo el App ID correcto para tu solicitud de Ads API. El App ID se puede encontrar en el Portal de desarrolladores, en Projects & Apps. Ejemplo: 16489123
  • Solicita acceso al Ads API contactando a tu representante de X.

​
Acceso al Ads API - Aplicaciones existentes

  • Si ya cuentas con una App del Ads API en uso activo, tanto la App como los tokens de acceso existentes pueden usarse con la Conversion API.

​
Tokens de acceso

  • Los tokens de acceso de usuario para el handle del usuario propietario de la aplicación de Ads API pueden generarse y obtenerse directamente desde el Portal de desarrolladores. Esto se denomina tu “token de acceso personal” porque está destinado a usarse con tu propio handle de X. La información general sobre Autenticación y el Portal de desarrolladores se puede encontrar aquí.
  • Los tokens de acceso de usuario para handles distintos del handle propietario de la aplicación de Ads API deben generarse con un flujo OAuth de 3 patas. Las opciones para generar el token de acceso con OAuth de 3 patas incluyen:
  • Cualquier token de usuario utilizado con la Conversion API debe pertenecer a usuarios con nivel de acceso AD_MANAGER o ACCOUNT_ADMIN, lo cual puede verificarse mediante el endpoint authenticated_user_access.
  • Nota: los propios tokens (después de su creación según lo anterior) pueden compartirse con usuarios sin el nivel de acceso AD_MANAGER o ACCOUNT_ADMIN para su uso.

​
Pasos

​
Creación del evento de la Conversion API

Para usar la Conversion API, debes crear un nuevo evento de conversión en Ads Manager o utilizar un evento existente que ya hayas creado y usado con el Pixel de X. Si quieres realizar la desduplicación entre eventos del Pixel y de la Conversion API, debes utilizar el evento existente que creaste para el Pixel. 
Opción 1: Usar un evento de conversión existente en Ads Manager
Si deseas usar un evento existente que ya utilizas con el píxel de X, es posible y deberás tomar el Event ID de ese evento. Si usas tanto el píxel como la Conversion API para el mismo evento, asegúrate de usar la clave de desduplicación en ambos: el fragmento de código del píxel y la solicitud de la Conversion API (como conversion_id) para desduplicar eventos entre el píxel y la Conversion API para el mismo evento. Consulta la sección d. Pruebas de eventos y desduplicación para obtener más información. 
Opción 2: Crear un nuevo evento de conversión en Ads Manager:
Es importante tener una fuente de eventos creada en Events Manager antes de crear un evento. Para verificar si tienes una fuente de eventos (X Pixel) añadida a tu cuenta, ve a Events Manager y comprueba si tienes X Pixel en el menú de la izquierda. Si aún no tienes una fuente de eventos añadida, sigue los pasos a continuación para crear una.
  1. Ve a ads.x.com
  2. Navega a la sección Tools en la parte superior izquierda y haz clic en Events Manager
  3. Selecciona Add event source en la parte superior derecha para Add an event source si aún no tienes una fuente de eventos de X Pixel en la barra lateral izquierda
    1. El id de la fuente de eventos de X Pixel es tu Pixel ID
Ahora tienes una fuente de eventos y un Pixel ID. Necesitas crear un evento dentro de la fuente de eventos para los eventos de conversión que deseas medir:
  1. Dentro de la fuente de eventos de X Pixel, selecciona Add events en el lado derecho
  2. Selecciona Install with Conversion API
  3. Verás el Pixel ID y el Event ID de este evento que se utilizarán en la API
    1. El id del evento es tu Event ID
  4. Haz clic en Save y tu evento de conversión quedará creado y listo para usar

​
Preparación de identificadores para eventos de conversión 

Actualmente necesitamos que se envíe al menos un identificador, como el Click ID (twclid), la dirección de correo electrónico o el número de teléfono. Si se utiliza la dirección IP o el agente de usuario, se debe enviar un segundo identificador para lograr una coincidencia de conversión adecuada. Proporcionar más identificadores dará como resultado una mayor tasa de coincidencia de conversión.
Campo de coincidencia del clienteFormato¿Se requiere hashing?
X Click IDGenerado por X (más información)No
Dirección de correo electrónicoEliminar espacios iniciales y finalesRequerido (SHA256)
Número de teléfonoEstándar E.164Requerido (SHA256)
Dirección IPEliminar espacios iniciales y finalesNo
Agente de usuarioEliminar espacios iniciales y finalesNo

​
1. Preparar el identificador X Click ID 

Se recomienda incluir siempre el Click ID en la solicitud de conversión. El Click ID debe extraerse del parámetro de la cadena de consulta twclid cuando esté disponible, después de que el usuario navegue al sitio web de destino.  Ejemplo de código JavaScript básico: 
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Pasos recomendados: Registrar e insertar en almacenamiento local
}
Se recomienda:
  1. Analizar siempre el valor de twclid cuando esté presente en los parámetros de consulta de la URL.
  2. Almacenar los datos junto con los campos de formulario pertinentes o la información del evento de conversión.
Vincular el Click ID a los eventos de conversión y a la información del flujo de trabajo permite escenarios como el procesamiento por lotes, el uso de algoritmos para analizar y crear eventos de conversión basados en múltiples flujos de navegación del sitio web y las cargas masivas. La URL de origen del evento debe estar codificada por porcentaje y está pensada para representar la página web que desencadenó el evento.

​
2. Preparar el identificador de correo electrónico 

Se pueden enviar los campos admitidos para la coincidencia de clientes, pero deben normalizarse y, cuando corresponda, cifrarse mediante hash para proteger la privacidad. La información debe hashificarse con SHA-256, sin sal.  Por ejemplo, para la dirección de correo electrónico test@x.com, debería enviarse en formato con hash: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

​
3. Preparar el identificador de teléfono 

El número de teléfono debe pasarse usando el estándar E.164 y la información debe convertirse a hash con SHA-256, sin sal.  Por ejemplo, para un número de teléfono de EE. UU.: +11234567890, debe enviarse a nosotros en formato con hash: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

​
4. Preparar el identificador de dirección IP

La dirección IP debe enviarse junto con otro identificador (twclid, dirección de correo electrónico, número de teléfono o agente de usuario). No es necesario aplicar hashing a este identificador. Este valor se escribe en notación decimal con puntos, con cuatro números separados por puntos. Por ejemplo, la dirección IP de un usuario puede ser 8.25.197.25.

​
5. Preparar el identificador de User Agent

Se debe enviar el User Agent junto con otro identificador (twclid, dirección de correo electrónico, número de teléfono o dirección IP). No es necesario aplicar hashing a este identificador. Este identificador permite que el servidor reconozca la aplicación, el sistema operativo, el proveedor y/o la versión del user agent que realiza la solicitud. Por ejemplo, este valor puede enviarse como Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.

​
Creación de la solicitud de evento de conversión

POST: version/measurement/conversions/:pixel_id Envía eventos de conversión para una cuenta publicitaria específica. Se debe verificar el código de respuesta para confirmar que la operación fue exitosa (HTTP 200 OK). Se recomienda contar con un mecanismo de reintento y un registro básico en caso de que se devuelvan códigos de error. Para obtener información detallada sobre la URL del endpoint y los parámetros del cuerpo del POST, consulta la sección de Referencia de la API. 

​
Solicitud de ejemplo (formateada para facilitar la lectura)


    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Compras de artículos para mascotas",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Mantas",
                  "content_type":"Artículos para mascotas",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

​
Ejemplo de respuesta

{"request": {
 "params": {
     "account_id":"18ce552mlaq"}
 },
 "data": {
    "conversions_processed":1,
     "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"}
}

​
Límite de tasa

El límite de tasa será de 60.000 eventos por cuenta, por intervalo de 15 minutos. Ten en cuenta que es posible que el código de tu servidor deba implementar lógica fuera de esta llamada, incluyendo:
  1. Instrumentar las acciones de los usuarios (registro de eventos) para poder enviar los datos de conversión correctos por evento
  2. La lógica necesaria para filtrar eventos de conversión de usuarios que hayan ejercido opciones de privacidad pertinentes; por ejemplo, si han optado por no ser rastreados o por no permitir la venta de su información personal en el sitio web del anunciante
  3. La integración con disparadores de eventos y páginas para capturar eventos y enviar conversiones

​
Pruebas de eventos y desduplicación

​
Prueba de eventos

Cuando tu evento haya recibido conversiones correctamente, dentro de 12 a 24 horas el estado de la «Single event web tag» debería mostrar TRACKING en la página de Conversion Tracking del Ads Manager. Enviar conversiones a través de la Conversion API no afectará a las campañas en curso. También puedes consultar los resultados de analítica de tu evento de conversión por id de etiqueta mediante:

​
Duplicación entre Pixel y Conversion API

Si deseas deduplicar conversiones entre solicitudes de Pixel y Conversion API, contamos con conversion_id como clave de deduplicación. La deduplicación solo se aplica a nivel de evento. En otras palabras, para deduplicar entre solicitudes de Pixel y CAPI, el anunciante debe usar el mismo evento en ambas solicitudes de Pixel y CAPI, además de utilizar el mismo conversion_id. La deduplicación solo puede aplicarse a eventos recibidos dentro de un período de 48 horas

​
Seguimiento de conversiones (Descripción general)

​
Resumen

El seguimiento de conversiones te permite medir cuántos usuarios de X realizan una acción deseada después de ver e interactuar con tus anuncios en X. Te permite evaluar qué campañas impulsan acciones como visitas al sitio, registros y compras. Esto ofrece a los anunciantes capacidades de medición fuera de X para comprender el rendimiento de sus anuncios de respuesta directa y adquirir clientes de manera rentable. Mediante una etiqueta de conversión, los anunciantes pueden hacer un seguimiento de las conversiones de los usuarios y atribuirlas a campañas publicitarias en X. Esto les brinda la visibilidad necesaria para optimizar sus campañas y alcanzar sus objetivos de costo por adquisición (CPA). Existen diversas acciones en sitios web que un anunciante puede medir con el seguimiento de conversiones. Pueden seleccionar una o varias, según la(s) acción(es) que buscan impulsar con su campaña publicitaria:
  • Visita al sitio: El usuario visita una página de destino en el sitio del anunciante
  • Compra: El usuario completa la compra de un producto o servicio en el sitio del anunciante
  • Descarga: El usuario descarga un archivo, como un documento técnico (white paper) o un paquete de software, desde el sitio del anunciante
  • Registro: El usuario se registra en el servicio, boletín o comunicaciones por correo del anunciante
  • Personalizada: Categoría general para una acción personalizada que no encaja en una de las categorías anteriores
El seguimiento de conversiones de X ofrece a los anunciantes una visión completa de la atribución de conversiones. En comparación con sistemas de medición de terceros que los clientes pueden haber usado en lugar de la solución propia de X, como URL de clic únicas combinadas con etiquetas de seguimiento de terceros, la etiqueta de conversión de X permite a los anunciantes hacer un seguimiento de conversiones atribuidas a interacciones de la mitad y la parte alta del embudo, como expansiones de Tweets, Retweets, favoritos, respuestas y follows, así como impresiones.

​
Preguntas frecuentes

Primero, un anunciante crea una etiqueta de conversión, que es un fragmento de código proporcionado por X, y la coloca en su sitio web. La etiqueta queda lista para medir la conversión cuando un usuario completa la acción indicada.Después, los usuarios ven el anuncio del anunciante en el cliente de X, lo que los lleva al sitio web del anunciante y a la acción que han etiquetado. Si el usuario completa esa acción durante la(s) ventana(s) de atribución especificada(s) por los anunciantes al configurar la etiqueta, esta reconoce que el usuario ha interactuado previamente con un anuncio de X. Luego, la etiqueta “se activa” o envía una notificación a los servidores de X para que la conversión pueda atribuirse al anuncio que la generó.
No, nuestro producto no está configurado para asociar etiquetas de conversión específicas a campañas específicas. En su lugar, una vez que se configura una etiqueta, el sistema realiza automáticamente el seguimiento de qué anuncio generó conversiones en una etiqueta determinada.
Ventana predeterminada de atribución post‑impresión: 1 díaAtribución predeterminada post‑interacción: 14 díasEstos valores predeterminados pueden cambiarse durante la configuración de la etiqueta de conversión o en cualquier momento después de creada la etiqueta. Las opciones para ventanas de atribución post‑interacción son 1, 7, 14, 30, 60 y 90 días. Las opciones para ventanas de atribución post‑impresión son ninguna, 1, 7, 14, 30, 60 y 90 días.
Si bien los objetivos, la situación y las estrategias de cada cliente son diferentes, aquí tienes algunas ideas que han funcionado para clientes que participaron en las fases alfa o beta del seguimiento de conversiones:Creatividades:
  • Ofertas: Combina un descuento, una promoción o envío gratis con el Tweet Promocionado para generar más interés en la acción
  • Sorteos y concursos: Especialmente para marcas reconocidas, los sorteos y concursos impulsaron conversiones
  • Pruebas de texto del Tweet: Probar mayúsculas vs. minúsculas (GRATIS vs. gratis o AHORA vs. ahora)
  • Fechas límite: Ofrece una fecha límite para incentivar a las personas a actuar de inmediato (¡La oferta vence el 12 de diciembre!)
  • Agregar fotos llamativas: Vale la pena probar si las fotos visualmente atractivas en la creatividad del Tweet son eficaces para impulsar conversiones; los resultados pueden variar o ser específicos de la oferta del cliente.
Segmentación:
  • Segmentación por @handle y por categorías de interés: Una estrecha alineación entre el texto del Tweet y los @handles con la audiencia prevista del Tweet impulsó conversiones
  • Uso de palabras clave de nicho pero de alto volumen: En el ámbito de los conciertos, usar palabras clave relacionadas con el artista/músico (p. ej., su nombre) resultó eficaz.
  • Audiencias personalizadas: Los clientes que usan TA web y seguimiento de conversiones juntos lograron CPAs más bajos que los grupos de control que usan otras segmentaciones
Cuanto más granular sea la segmentación de tu campaña, más accionables serán los resultados de conversión reportados. Por ejemplo, es mucho más fácil optimizar una campaña con 4 palabras clave que optimizar una campaña con 50.

​
Solución de problemas y soporte para la Conversion API

Si tienes preguntas sobre los códigos de error tras llamar a la API, consulta la sección siguiente. Para cualquier otra consulta, no dudes en ponerte en contacto con tu representante de Twitter; trabajaremos para resolverla lo antes posible. 

​
Gestión y explicación de errores

Una única solicitud solo se considerará correcta cuando no haya errores en ninguna de las conversiones que contiene. Si se produce algún error en una conversión individual, el endpoint devolverá una lista de todos los errores correspondientes.

​
Información general sobre los códigos de error de la X Ads API

A continuación, encontrarás una lista completa de los códigos de error de la Ads API: https://developer.x.com/en/docs/twitter-ads-api/response-codes Las respuestas correctas de la Conversion API se indican con un código HTTP de la serie 200 y una carga útil en formato JSON que contiene el objeto solicitado.

​
Cuando se devuelve un código HTTP de la serie 500, suele deberse a un problema del servidor, no a tu solicitud ni a la configuración de tu cuenta. Consulta la página de estado de X API o el foro de la comunidad de desarrolladores para ver si otras personas están experimentando problemas similares.

​
Cuando se produce un código HTTP de la serie 400, los casos comunes son

  • 400 Bad Request (la solicitud no cumple los estándares)
  • 401 Unauthorized (problemas de autenticación)
  • 403 Forbidden (problemas de acceso a la API asociados con esa developer account)
  • 404 Not Found (la URL o los parámetros podrían no ser correctos para el endpoint)

​
Códigos de error de la API de conversiones

​
400 Escenarios de Solicitud incorrecta

MotivoTipoMensaje de error
Falta un identificador (actualmente correo electrónico con hash o X click ID - twclid)400 Solicitud incorrectaSe debe proporcionar al menos un identificador de usuario
Correo electrónico con hash no válido400 Solicitud incorrectaHashed_email no es un hash SHA-256 válido
El tipo de event_id no es una etiqueta de evento única (SET)400 Solicitud incorrectaEvent_id (<event_id>) no es una etiqueta de evento única (SET)
Los eventos de conversión solicitados superan el límite (actualmente 500 eventos por solicitud)400 Solicitud incorrectaEl límite de la cuenta de conversiones es 500
Falta el ID del evento400 Solicitud incorrectaNo se encontró el ID del evento

​
Ejemplo de código de error de JSON

Solicitud:
POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event&#95;id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json

​
Mensaje de error:

{"errors":[{"code":"INVALID_PARAMETER","message":"event&#95;id (o6dkt) no es una etiqueta de evento única (SET)","parameter":"event&#95;id"}],"request":{"params":{"account&#95;id":"18ce552mlaq"}}}

​
Solicitud:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event&#95;id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json'

​
Mensaje de error:

{"errors":[{"code":"INVALID_PARAMETER","message":"Se debe proporcionar al menos un identificador de usuario","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Solicitud:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event&#95;id":"o6dl3", "identifiers": [{"hashed_email": "abc"}]}]}' --header 'Content-Type: application/json'

​
Mensaje de error:

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) is not a valid SHA-256 hash","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Solicitud:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

​
Mensaje de error:

{"errors":[{"code":"INVALID_PARAMETER","message":"Se esperaba una hora en el formato yyyy-MM-ddTHH:mm:ss.SSSZ, se obtuvo \"2022-06-16T01:14:00.603\" para conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
401 No autorizado

Motivo: Falta de credenciales de Autenticación o credenciales incorrectas  Solución: Sigue los pasos de Autenticación en la documentación de configuración utilizando uno de los 3 métodos de Autenticación: Los tokens de acceso de usuario para cuentas distintas de la que es propietaria de la App de Ads API deben generarse con un flujo OAuth de 3 patas. Las opciones para generar el token de acceso con OAuth de 3 patas incluyen: Cualquier token de usuario utilizado con la Conversion API debe corresponder a usuarios con nivel de acceso AD_MANAGER o ACCOUNT_ADMIN*, lo cual se puede verificar mediante el endpoint authenticated_user_access.

​
403 Acceso prohibido 

MotivoTipoMensaje de error
La cuenta de desarrollador que estás usando no tiene acceso a Ads API. Solicita acceso aquí.403 Cliente no autorizadoLa aplicación cliente con id <> que realiza esta solicitud no tiene acceso a X Ads API. Asegúrate de que tu aplicación tenga acceso a advertiser-api. Usa ‘twurl accounts’ y ‘twurl set default <username> <key>’ para cambiar la aplicación que estás usando.

​
404 No encontrado 

MotivoTipoMensaje de error
La URL de la solicitud o los parámetros no son correctos para el endpoint404 Ruta no encontradaNo se encontró el recurso solicitado
No tienes acceso a la cuenta propietaria del pixel_id/Etiqueta universal del sitio web404 No encontradoEl usuario <user_id> no tiene acceso a la cuenta <account_id>. Escribe ‘sn <user_id>’ para obtener el handle del usuario. Usa ‘twurl accounts’ y ‘twurl set default \u003Cusername\u003E’ para cambiar el usuario con el que estás operando.
El id del evento no pertenece a la cuenta proporcionada asociada con el pixel ID (UWT ID)404 No encontradoevent_id <event_id> no pertenece a la cuenta proporcionada

​
Ejemplo de código de error de JSON

​
Solicitud:

twurl_ads -X POST '/11/measurement/conversions/o8z6j' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event&#95;id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json' Mensaje de error: {"errors":[{"code":"NOT_FOUND","message":"event_id (abc) no pertenece a la cuenta proporcionada","parameter":"event&#95;id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) no es una etiqueta de evento única (SET)","parameter":"event&#95;id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

​
Índice de referencia de la API

Para consultar la referencia completa de la API, selecciona un punto de conexión de la lista:

​
Conversiones web

API de Conversionesmeasurement/conversions/:pixel_id
Etiqueta de evento webaccounts/:account_id/web_event_tags

​
Conversiones web

POST version/measurement/conversions/:pixel&#95;id Envía eventos de conversión del sitio web para un único ID de etiqueta de evento. Se debe verificar el código de respuesta para confirmar que fue correcto (HTTP 200 OK). Se recomienda contar con un mecanismo de reintento y un registro básico en caso de que se devuelvan códigos de error. El límite de solicitudes será de 100,000 por intervalo de 15 minutos por cuenta (cada solicitud permite 500 eventos).
URL del recurso
https://ads-api.x.com/12/measurement/conversions/:pixel&#95;id
Parámetros de la URL de la solicitud
NombreDescripción
pixel_id
obligatorio		El ID de etiqueta base de una cuenta publicitaria. Es el valor codificado en base36 del ID de etiqueta base de una cuenta publicitaria.

Tipo: string

Ejemplo: o8z6j
conversions
obligatorio		El objeto en el cuerpo POST de la solicitud de la API. Lista de eventos de conversión. Se pueden proporcionar hasta 500 eventos de conversión. Consulta la tabla a continuación para ver los fields admitidos.

Tipo: array

Ejemplo: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion&#95;id": "23294827"}]
objeto conversions
NombreDescripción
conversion_time
obligatorio		La hora, expresada en ISO 8601.

Tipo: string

Ejemplo: 2017-10-05T00:00:00Z
event_id
obligatorio		El ID en base 36 de un evento específico. Coincide con un evento preconfigurado incluido en esta cuenta publicitaria. En el evento correspondiente en Events Manager se denomina ID.

Tipo: string

Ejemplo: o87ne o tw-o8z6j-o87ne (tw-pixel&#95;id-event-id), ambos aceptados
identifiers
obligatorio		Una lista de objetos identificadores para hacer coincidir el evento de conversión. Los campos admitidos se enumeran en una tabla a continuación. Se requiere al menos uno de los objetos identificadores.

Si se utiliza dirección IP o user agent, se debe enviar un segundo identificador para una concordancia de conversión adecuada.

Tipo: array

Ejemplo: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
opcional		La cantidad de artículos que se compran en el evento. Debe ser un número positivo mayor que cero.

Tipo: integer

Ejemplo: 4
price_currency
opcional		La moneda de los artículos que se compran en el evento, expresada en ISO-4217. Consulta Currency para obtener información detallada.

Tipo: string

Predeterminado: USD

Ejemplo: JPY
value
opcional		El valor de los artículos que se compran en el evento, expresado en la moneda de price_currency.

Tipo: double

Ejemplo: 100.00
conversion_id
opcional		Para la deduplicación entre conversiones de píxel y de Conversion API. Un identificador de un evento de conversión que se puede usar para la deduplicación entre Web Pixel y Conversion API en la misma etiqueta de evento. Consulta la sección Testing Events and Deduplication de la Conversions Guide para obtener más información.

Tipo: string

Ejemplo: 23294827
description
opcional		Descripción con cualquier información adicional sobre las conversiones.

Tipo: string

Ejemplo: test conversion
contents
opcional		Lista de detalles relacionados con un producto/contenido específico para proporcionar información detallada. Consulta la tabla a continuación para los campos admitidos.

Tipo: array

Ejemplo: contents": [{"content&#95;id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content&#95;id": "2"}]
objeto identifiers
NombreDescripción
twclid
a veces obligatorio		ID de clic extraído de la URL de redirección (click-through). Es obligatorio si no se añade ningún otro identificador.

Tipo: string

Ejemplo: 26l6412g5p4iyj65a2oic2ayg2
hashed_email
a veces obligatorio		Dirección de correo electrónico con hash usando SHA256. El texto debe estar en minúsculas y se deben eliminar los espacios iniciales y finales antes de aplicar el hash. Es obligatorio si no se añade ningún otro identificador.

Tipo: string

Ejemplo: Para test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
a veces obligatorio		Número de teléfono en formato E164 y con hash usando SHA256. El número debe estar en formato E164 antes de aplicar el hash. Es obligatorio si no se añade ningún otro identificador.

Tipo: string

Ejemplo: Para +11234567890 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231
ip_address
a veces obligatorio		Este valor se escribe en notación decimal con puntos, con cuatro números separados por puntos.

La dirección IP debe enviarse junto con otro identificador (twclid, dirección de correo electrónico, número de teléfono o agente de usuario).

Tipo: string

Ejemplo: 8.25.197.25
user_agent
a veces obligatorio		Este identificador permite que el servidor identifique la aplicación, el sistema operativo, el proveedor y/o la versión del agente de usuario que realiza la solicitud.

El agente de usuario debe enviarse junto con otro identificador (twclid, dirección de correo electrónico, número de teléfono o dirección IP).

Tipo: string

Ejemplo: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.
objeto contents
NombreDescripción
content_id
opcional		SKU o GTIN; identificador que representa el contenido.

Tipo: string

Ejemplo: jhp
content_group_id
opcional		id asociado con un grupo de variantes de producto.

Tipo: integer

Ejemplo: group 1
content_name
opcional		Nombre del producto o servicio.

Tipo: string

Ejemplo: radio flyer
content_price
opcional		Precio del producto o servicio.

Tipo: double

Ejemplo: 5.00
content_type
opcional		Categoría del producto adquirido.

Tipo: string

Ejemplo: clothes
num_items
opcional		Número de productos comprados.

Tipo: integer

Ejemplo: 1
Parámetros de la respuesta
NombreDescripción
conversions_processedNúmero de conversiones procesadas correctamente

Tipo: entero

Ejemplo: 1
debug_idUn UUID de depuración que puede usarse para investigaciones posteriores

Tipo: cadena

Ejemplo: ff02e052-36e4-47d6-bdf0-6d8986446562
Ejemplo de petición
    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Compras de artículos para mascotas",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Mantas",
                  "content_type":"Artículos para mascotas",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'
Ejemplo de solicitud
    {
       "request":{
          "params":{
             "account_id":"18ce552mlaq"
          }
       },
       "data":{
          "conversions_processed":1,
          "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
       }
    }

​
Etiquetas de eventos web

GET accounts/&#95;id/web&#95;event&#95;tags Obtén los detalles de algunas o todas las etiquetas de eventos web asociadas a la cuenta actual.

​
URL del recurso

https://ads-api.x.com/12/accounts/&#95;id/web&#95;event&#95;tags

​
Parámetros

NombreDescripción
account_id
obligatorio		El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado.

Tipo: string

Ejemplo: 18ce54d4x5t
count
opcional		Especifica la cantidad de registros que se intentará recuperar por cada solicitud.

Tipo: int

Predeterminado: 200
Mín., máx.: 1, 1000
cursor
opcional		Especifica un cursor para obtener la página siguiente de resultados. Consulta Pagination para más información.

Tipo: string

Ejemplo: 8x7v00oow
sort_by
opcional		Ordena por un atributo compatible en orden ascendente o descendente. Consulta Sorting para más información.

Tipo: string

Ejemplo: created_at-asc
web_event_tag_ids
opcional		Restringe la respuesta solo a las etiquetas de eventos web deseadas especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 IDs.

Tipo: string

Ejemplo: o3bk1
with_deleted
opcional		Incluye resultados eliminados en tu solicitud.

Tipo: boolean

Predeterminado: false
Valores posibles: true, false
with_total_count
opcional		Incluye el atributo de respuesta total_count.

Nota: Este parámetro y cursor son excluyentes.

Nota: Las solicitudes que incluyan total_count tendrán límites de frecuencia más bajos, actualmente de 200 por 15 minutos.

Tipo: boolean

Predeterminado: false
Valores posibles: true, false

​
Ejemplo de solicitud

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?web_event_tag_ids=o3bk1

​
Ejemplo de respuesta

    {
      "request": {
        "params": {
          "web_event_tag_ids": [
            "o3bk1"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "web event tag",
          "view_through_window": 7,
          "click_window": 7,
          "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
          "id": "o3bk1",
          "retargeting_enabled": false,
          "last_tracked_at": "2021-05-22T17:00:04Z",
          "status": "TRACKING",
          "type": "DOWNLOAD",
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

​
GET accounts/_id/web_event_tags/_id

Recupera una etiqueta de evento web específica asociada con la cuenta actual.
URL del recurso
https://ads-api.x.com/12/accounts/:account&#95;id/web&#95;event&#95;tags/:web&#95;event&#95;tag&#95;id
Parámetros
NombreDescripción
account_id
obligatorio		El identificador de la cuenta apalancada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado.

Tipo: string

Ejemplo: 18ce54d4x5t
web_event_tag_id
obligatorio		Una referencia a la etiqueta de evento web con la que operas en la solicitud.

Tipo: string

Ejemplo: o3bk1
with_deleted
opcional		Incluye los resultados eliminados en tu solicitud.

Tipo: boolean

Predeterminado: false
Valores posibles: true, false
Ejemplo de solicitud
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Ejemplo de respuesta
    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "etiqueta de evento web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "EN SEGUIMIENTO",
        "type": "DESCARGA",
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

​
POST accounts/_id/web_event_tags

Crea una nueva etiqueta de evento web asociada a la cuenta actual.

​
URL del recurso

https://ads-api.x.com/12/accounts/&#95;id/web&#95;event&#95;tags

​
Parámetros

NombreDescripción
account_id
obligatorio		El identificador de la cuenta aprovechada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado.

Tipo: string

Ejemplo: 18ce54d4x5t
click_window
obligatorio		La ventana de clic para esta etiqueta web.

Nota: Solo se aceptan los valores que se indican a continuación.

Tipo: int

Valores posibles: 1, 7, 14, 30
name
obligatorio		El nombre de la etiqueta web.

Tipo: string

Ejemplo: Sample single conversion event
retargeting_enabled
obligatorio		Indica si se debe habilitar el retargeting para esta etiqueta web.

Tipo: boolean

Valores posibles: true, false
type
obligatorio		El tipo de etiqueta web.

Tipo: enum

Valores posibles: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(En la interfaz, SITE_VISIT aparece como “Page view” y SIGN_UP aparece como “Lead”)
view_through_window
obligatorio		La ventana de visualización para esta etiqueta web. Este valor siempre debe ser menor o igual que el valor de click_window.

Nota: Solo se aceptan los valores que se indican a continuación.

Tipo: int

Valores posibles: 0, 1, 7, 14, 30
Ejemplo de solicitud
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web&#95;event&#95;tags?click&#95;window=7&name=web event tag&retargeting&#95;enabled=false&type=SITE&#95;VISIT&view&#95;through&#95;window=7

​
Ejemplo de respuesta

    {
      "data": {
        "name": "etiqueta de evento web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": null,
        "status": "NO VERIFICADO",
        "type": "VISITA_EN_EL_SITIO",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "etiqueta de evento web",
          "view_through_window": 7,
          "click_window": 7,
          "retargeting_enabled": false,
          "account_id": "18ce54d4x5t",
          "type": "SITE_VISIT"
        }
      }
    }

​
PUT accounts/:account_id/web_event_tags/:web_event_tag_id

Actualiza una etiqueta de evento web asociada a la cuenta actual.
URL del recurso
https://ads-api.x.com/12/accounts/:account&#95;id/web&#95;event&#95;tags/:web&#95;event&#95;tag&#95;id

​
Parámetros

NombreDescripción
account_id
required		El identificador de la cuenta aprovechada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado.

Tipo: string

Ejemplo: 18ce54d4x5t
web_event_tag_id
required		El identificador de una etiqueta web en la cuenta actual.

Tipo: string

Ejemplo: o3bk1
click_window
optional		La ventana de clics para esta etiqueta web.

Nota: Solo se aceptan los valores indicados a continuación.

Tipo: int

Valores posibles: 1, 7, 14, 30
name
optional		El nombre de la etiqueta web.

Tipo: string

Ejemplo: Sample single conversion event
retargeting_enabled
optional		Indica si se debe habilitar el retargeting para esta etiqueta web.

Tipo: boolean

Valores posibles: true, false
type
optional		El tipo de etiqueta web.

Tipo: enum

Valores posibles: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(En la interfaz, SITE_VISIT se muestra como “Page view” y SIGN_UP se muestra como “Lead”)
view_through_window
optional		La ventana de visualización para esta etiqueta web. Este valor siempre debe ser menor o igual que el valor de click_window.

Nota: Solo se aceptan los valores indicados a continuación.

Tipo: int

Valores posibles: 0, 1, 7, 14, 30

​
Ejemplo de solicitud

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web&#95;event&#95;tags/o3bk1?type=DOWNLOAD

​
Respuesta de ejemplo

    {
      "data": {
        "name": "etiqueta de evento web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "NO VERIFICADO",
        "type": "DESCARGA",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DESCARGA",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​
DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

Elimina una etiqueta de evento web específica asociada con la cuenta actual.

​
URL del recurso

https://ads-api.x.com/12/accounts/:account&#95;id/web&#95;event&#95;tags/:web&#95;event&#95;tag&#95;id
Parámetros
NombreDescripción
account_id
obligatorio		El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Ads API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado.

Tipo: string

Ejemplo: 18ce54d4x5t
web_event_tag_id
obligatorio		El identificador de una etiqueta web de la cuenta actual.

Tipo: string

Ejemplo: o3bk1
Ejemplo de solicitud
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Ejemplo de respuesta
    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }