Conversiones web

​

Configuración de Conversion API

​

Requisitos previos

​

Acceso a Ads API - Aplicaciones nuevas

• El requisito principal de Conversion API es contar con una cuenta de desarrollador y con Ads API Access. El proceso se describe en la guía Ads API Getting Started. Ten en cuenta lo siguiente:

Paso 1: Cuenta de desarrollador

• Al solicitar una cuenta de desarrollador, solicita uno de nuestros planes de suscripción para obtener aprobación inmediata. 
• Nota: Como práctica recomendada, te sugerimos encarecidamente usar el usuario oficial de X de tu empresa para crear una cuenta de desarrollador y solicitar acceso a la Ads API. Si la cuenta de desarrollador está asociada con un usuario 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, según sea necesario, el inicio de sesión multiusuario. De lo contrario, como mínimo, la cuenta debe configurarse con ajustes no predeterminados (imagen de encabezado, avatar, descripción de la biografía 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 la Consola de desarrollador en la sección Projects & Apps. Ejemplo: 16489123
• Solicita acceso a la Ads API poniéndote en contacto con tu representante de X.

​

Acceso a la Ads API - Aplicaciones existentes

• Si ya tienes una aplicación de Ads API que usas activamente, tanto la aplicación como los tokens de acceso existentes se pueden utilizar para la Conversion API.

​

Tokens de acceso

• Los tokens de acceso de usuario para la cuenta que es propietaria de la aplicación de Ads API se pueden generar y obtener directamente desde la Consola de desarrollador. Esto se denomina tu “token de acceso personal” porque está pensado para usarse con tu propia cuenta de X. Puedes encontrar información general sobre autenticación y la Consola de desarrollador aquí.
• Los tokens de acceso de usuario para cuentas distintas de la que es propietaria de la aplicación de Ads API deben generarse con un flujo OAuth de 3 partes (3-legged OAuth). Las opciones para generar el token de acceso con OAuth de 3 partes incluyen:
  • Línea de comandos con autorización basada en la web mediante la utilidad twurl
  • Línea de comandos con autorización basada en PIN
  • Flujo web personalizado que implemente el patrón OAuth de 3 partes
• Cualquier token de usuario utilizado con la Conversion API debe pertenecer a usuarios con nivel de acceso AD_MANAGER o ACCOUNT_ADMIN, lo cual se puede comprobar mediante el endpoint authenticated_user_access.
• Nota: los propios tokens (después de su creación según lo anterior) pueden compartirse con usuarios que no tengan el nivel de acceso AD_MANAGER o ACCOUNT_ADMIN para su uso.

​

Pasos

​

Creación del evento de Conversion API

Para usar Conversion API, debes crear un nuevo evento de conversión en Ads Manager o utilizar un evento existente que ya se haya creado y usado con X Pixel. Si quieres hacer deduplicación entre los eventos del píxel y de Conversion API, debes usar el evento existente que creaste para Pixel. 

Opción 1: Usar un evento de conversión existente en Ads Manager

Si deseas usar un evento existente que ya estás utilizando con el pixel de X, es posible hacerlo y solo necesitas obtener el Event ID de ese evento. Si usas tanto el pixel como Conversion API para el mismo evento, asegúrate de usar la clave de deduplicación tanto en el fragmento de código del pixel como en la solicitud de Conversion API (como conversion_id) para deduplicar eventos entre el pixel y Conversion API para el mismo evento. Consulta la sección d. Testing Events and Deduplication para más información. 

Opción 2: Crear un nuevo evento de conversión en Ads Manager:

Es importante tener un Event Source creado en Events Manager antes de crear un evento. Para verificar si tienes un Event Source (X Pixel) añadido a tu cuenta, ve a Events Manager y comprueba si tienes X Pixel en el menú de la izquierda. 

Si aún no tienes un Event Source añadido, sigue los pasos a continuación para crear un Event Source.

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 todavía no tienes un X Pixel event source en la barra lateral izquierda
   1. El ID del X Pixel event source es tu Pixel ID

Ahora tienes un Event Source y un Pixel ID. Debes crear un evento dentro del Event Source para los eventos de conversión que deseas registrar:

1. Dentro del X Pixel event source, 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 usarse

​

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 obtener una coincidencia de conversión adecuada.

Enviar más identificadores generará una tasa de coincidencia de conversión más alta.

Campo de coincidencia del cliente	Formato	¿Se requiere hash?
X Click ID	Generado por X (más información)	No
Dirección de correo electrónico	Eliminar espacios iniciales y finales	Requerido (SHA256)
Número de teléfono	Estándar E.164	Requerido (SHA256)

Dirección IP	Eliminar espacios iniciales y finales	No
Agente de usuario	Eliminar espacios iniciales y finales	No

​

1. Preparar el identificador de 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 cadena de consulta twclid cuando esté disponible después de que el usuario navegue al sitio web de destino. 

Ejemplo básico de código JavaScript:

var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Próximos pasos recomendados: Registro, insertar en el 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 relevantes o la información del evento de conversión.

Vincular el Click ID a eventos de conversión y a la información del flujo de trabajo permite casos de uso como el procesamiento por lotes, algoritmos para analizar y crear eventos de conversión basados en múltiples flujos de navegación del sitio web y cargas masivas.

La URL de origen del evento debe estar codificada en formato URL y está pensada para representar la página web que desencadenó el evento.

​

2. Preparar identificador de correo electrónico

Los campos admitidos para la coincidencia de clientes se pueden enviar, pero deben normalizarse y, cuando sea necesario, convertirse en un hash para proteger la privacidad.

La información debe convertirse en un hash usando SHA256, sin salt. 

Por ejemplo, una dirección de correo electrónico [e-mail] debe enviarse en formato de hash: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

​

3. Preparar el identificador de teléfono

El número de teléfono debe pasarse utilizando el estándar E.164 y la información debe someterse a un hash SHA256, sin usar salt. 

Por ejemplo, para un número de teléfono de EE. UU.: [phone], se debe enviar en formato hash: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

​

4. Preparar el identificador de dirección IP

Es obligatorio enviar la dirección IP 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 expresa en notación decimal punteada, 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

El User Agent debe incluirse 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 identifique la aplicación, el sistema operativo, el proveedor y/o la versión del User Agent que realiza la solicitud. Por ejemplo, este valor se puede enviar como Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, como 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 de la solicitud POST, consulta la sección de Referencia de la API. 

​

Ejemplo de solicitud (con formato 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":"Pet supply purchases",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "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 frecuencia

El límite de frecuencia 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, entre otras cosas:

1. Instrumentar las acciones de los usuarios (registro/logging) para poder enviar los datos de conversión correctos por evento

2. Cualquier lógica necesaria para filtrar eventos de conversión de usuarios que hayan ejercido opciones de privacidad relevantes; 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. Integración con disparadores de eventos y páginas a fin de capturar eventos y enviar conversiones

​

Pruebas de eventos y eliminación de duplicados

​

Pruebas de eventos

Cuando tu evento haya recibido correctamente eventos de conversión, en un plazo de 12 a 24 horas el estado de la “Single event web tag” debería mostrar TRACKING en la página Conversion Tracking de Ads Manager. Enviar conversiones mediante la Conversion API no afectará a las campañas en curso.

También puedes comprobar los resultados de tu evento de conversión por ID de etiqueta mediante:

• Exportación de datos desde Ads Manager (página de ayuda Analytics for Website Conversion Tracking)

• Exportación de datos mediante la Ads API (segmentation_type=CONVERSION_TAGS) 

​

Duplicación entre Pixel y Conversion API

Si deseas deduplicar conversiones entre las solicitudes de Pixel y Conversion API, disponemos de conversion_id como clave de deduplicación. La deduplicación solo se realiza a nivel de evento. En otras palabras, para deduplicar entre solicitudes de Pixel y de CAPI, un anunciante debe usar el mismo evento tanto en las solicitudes de Pixel como en las de CAPI, además de utilizar el mismo conversion_id. La deduplicación solo puede aplicarse a eventos que se reciben dentro de un periodo de 48 horas.

​

Seguimiento de conversiones (Descripción general)

​

Resumen

El seguimiento de conversiones permite medir la cantidad de usuarios de X que realizan una acción deseada después de ver e interactuar con anuncios en X. También permite determinar qué campañas generan acciones como visitas al sitio, registros y compras. Esto proporciona a los anunciantes capacidades de medición fuera de X para comprender el rendimiento de sus anuncios de respuesta directa y así poder adquirir clientes de forma rentable.

Mediante una etiqueta de conversión, los anunciantes pueden rastrear las conversiones de los usuarios y vincularlas a las campañas publicitarias en X. Esto les da la visibilidad necesaria para optimizar sus campañas y cumplir sus objetivos de costo por adquisición (CPA).

Hay una variedad de acciones en sitios web que un anunciante puede medir con el seguimiento de conversiones. Puede seleccionar una o más, de acuerdo con la(s) acción(es) que busca 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 o un paquete de software, desde el sitio del anunciante
• Registro: el usuario se registra en el servicio, boletín o comunicaciones por correo electrónico del anunciante
• Personalizada: esta es una categoría general para una acción personalizada que no entra en alguna 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 los sistemas de medición de terceros que los clientes pueden haber estado utilizando en lugar de la capacidad de seguimiento de conversiones propia de X, como URL de clic únicas combinadas con etiquetas de seguimiento de terceros, la etiqueta de conversión de X ofrece a los anunciantes la posibilidad de rastrear conversiones atribuidas a interacciones de mitad y parte superior del embudo, como expansiones de Tweets, Retweets, favoritos, respuestas y follows, así como impresiones.

​

Preguntas frecuentes

¿Cómo funciona la etiqueta de seguimiento de conversiones?

En primer lugar, 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 ya está lista para medir la conversión cuando un usuario completa la acción indicada.

Luego, 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 este ha etiquetado. Si el usuario completa esa acción durante la(s) ventana(s) de atribución especificada(s) por el anunciante durante la configuración de la etiqueta, la etiqueta reconoce que el usuario ha interactuado previamente con un anuncio de X. La etiqueta entonces se “activa” o envía una notificación a los servidores de X para que la conversión pueda atribuirse al anuncio que generó la conversión.

¿Existe alguna forma en el proceso de configuración de la campaña que permita al usuario seleccionar qué píxeles de seguimiento son relevantes para esa campaña?

No, nuestro producto no está configurado para adjuntar etiquetas de conversión específicas a campañas específicas. En cambio, una vez que se configura una etiqueta, el sistema realiza automáticamente el seguimiento de qué anuncio generó conversiones en una determinada etiqueta.

¿Cuáles son nuestras configuraciones predeterminadas de ventana de atribución para las etiquetas de conversión?

Ventana de atribución predeterminada post-impresión: 1 día

Atribución predeterminada post-interacción: 14 días

Estos valores predeterminados se pueden cambiar durante la configuración de la etiqueta de conversión o en cualquier momento después de que se haya creado la etiqueta. Las opciones para las ventanas de atribución post-interacción son 1, 7, 14, 30, 60 y 90 días. Las opciones para las ventanas de atribución post-impresión son ninguna, 1, 7, 14, 30, 60 y 90 días.

¿Cuáles son algunas ideas para creatividades y estrategias de DR eficaces que impulsen conversiones de forma efectiva?

Si bien los objetivos, la situación y las estrategias de cada cliente son diferentes, aquí hay algunas ideas que han funcionado para clientes que participaron en la fase alfa o beta de seguimiento de conversiones:

Creatividad:

• Ofertas: Combinar un descuento, una promoción o una oferta de envío gratuito 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
• Experimentación con el texto del Tweet: Probar mayúsculas frente a minúsculas (FREE vs free o NOW vs now)
• Plazos: Ofrecer una fecha límite para incentivar a las personas a tomar medidas inmediatas (¡La oferta vence el 12 de diciembre!)
• Agregar fotos atractivas: 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ía de interés: Una alineación estrecha 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, el uso de palabras clave relacionadas con el artista o músico (por ejemplo, su nombre) resultó eficaz.
• Audiencias personalizadas: Los clientes que utilizaron TA web y seguimiento de conversiones juntos lograron CPAs más bajos que los grupos de control que usaban otros tipos de segmentación

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 Conversion API

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

​

Gestión y explicación de errores

Una solicitud solo se considerará correcta cuando no haya ningún error 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 aplicables.

​

Descripción general de los códigos de error de la X Ads API

A continuación se muestra una lista completa de los códigos de error en la Ads API:

https://developer.x.com/en/docs/twitter-ads-api/response-codes

Las respuestas satisfactorias de Conversion API se indican con un código HTTP de la serie 200 y un cuerpo en formato JSON que contiene el objeto solicitado.

​

Cuando recibes un código HTTP de la serie 500, está relacionado con un problema del servidor en lugar de con tu solicitud o la configuración de tu cuenta. Consulta la página de estado de X API o el foro de la comunidad de desarrolladores para comprobar si otras personas están teniendo problemas similares.

​

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

• 400 Bad Request (la solicitud no cumple con los estándares)

• 401 Unauthorized (problemas de autenticación)

• 403 Forbidden (problemas de acceso a la API asociados con esa cuenta de desarrollador)

• 404 Not Found (es posible que la URL o los parámetros no sean correctos para el endpoint)

​

Códigos de error de la Conversion API

​

Escenarios de error 400 Bad Request

Motivo	Tipo	Mensaje de error
Error por identificador ausente (actualmente correo electrónico con hash o X click ID - twclid)	400 Bad Request	Se debe proporcionar al menos un identificador de usuario
Correo electrónico con hash no válido	400 Bad Request	Hashed_email no es un hash SHA-256 válido
El type de event_id no es una etiqueta de evento única (SET)	400 Bad Request	Event_id (<event_id>) no es una etiqueta de evento única (SET)
Los eventos de conversión solicitados exceden el límite (actualmente 500 eventos por solicitud)	400 Bad Request	El límite de conversiones es 500
Event ID ausente	400 Bad Request	No se encontró el Event ID

​

Ejemplo de código de error en JSON

Solicitud:

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

​

Mensaje de error:

{"errors":[{"code":"INVALID_PARAMETER","message":"event_id (o6dkt) is not a single event tag (SET)","parameter":"event_id"}],"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_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json'

​

Mensaje de error:

{"errors":[{"code":"INVALID_PARAMETER","message":"At least one user identifier must be provided","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_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":"Expected Time in yyyy-MM-ddTHH:mm:ss.SSSZ, got \"2022-06-16T01:14:00.603\" for conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​

401 No autorizado

Motivo: Faltan las credenciales de autenticación o son incorrectas 

Solución: Sigue los pasos de autenticación en la documentación de configuración usando uno de los 3 métodos de autenticación:

Los tokens de acceso de usuario (User Access Tokens) para identificadores de usuario distintos del identificador propietario de la aplicación de Ads API deben generarse con un flujo OAuth de 3 participantes (3-legged OAuth). Las opciones para generar el token de acceso con 3-legged OAuth incluyen:

• Línea de comandos con autorización basada en web mediante la utilidad twurl

• Línea de comandos con autorización basada en PIN

• Flujo web personalizado que implemente el patrón de 3-legged OAuth

Cualquier token de usuario utilizado con Conversion API debe corresponder a usuarios con nivel de acceso AD_MANAGER o ACCOUNT_ADMIN*, lo que se puede verificar mediante el endpoint authenticated_user_access.

​

403 Acceso prohibido

Motivo	Tipo	Mensaje de error
La cuenta de desarrollador que estás usando no tiene acceso a X Ads API. Solicita acceso aquí.	403 Cliente no autorizado	La 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 usas.

​

404 No encontrado

Motivo	Tipo	Mensaje de error
La URL de la solicitud o los parámetros no son correctos para este endpoint	404 Route Not Found	El recurso solicitado no se pudo encontrar
No tienes acceso a la cuenta que es propietaria de pixel_id/Universal Website Tag	404 Not Found	El 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 que estás usando.
El id del evento no pertenece a la cuenta proporcionada asociada al pixel ID (UWT ID)	404 Not Found	event_id <event_id> no pertenece a la cuenta proporcionada

​

Ejemplo de código de error en JSON

​

Solicitud:

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

Mensaje de error:

{"errors":[{"code":"NOT_FOUND","message":"event_id (abc) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

​

Índice de la referencia de la API

Selecciona un endpoint de la lista para ver la referencia completa de la API:

​

Conversiones web

API de conversiones	measurement/conversions/:pixel_id
Etiqueta de evento web	accounts/:account_id/web_event_tags

​

Conversiones web

POST version/measurement/conversions/:pixel_id

Envía eventos de conversión del sitio web para un único ID de etiqueta de evento.

Se debe comprobar el código de respuesta para verificar que la operación se haya realizado correctamente (HTTP 200 OK). Se recomienda contar con un mecanismo de reintentos y un sistema de registro básico en caso de que se devuelvan códigos de error.

El límite de frecuencia será de 100.000 solicitudes por intervalo de 15 minutos por cuenta (cada solicitud permite 500 eventos).

URL del recurso

https://ads-api.x.com/12/measurement/conversions/:pixel_id

Parámetros de URL de la solicitud

Nombre	Descripción
pixel_id obligatorio	El ID de etiqueta base de una cuenta de anuncios. Representa el valor codificado en base 36 del ID de etiqueta base de una cuenta de anuncios. Tipo: string Ejemplo: o8z6j
conversions obligatorio	El objeto incluido 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. Consulte la tabla siguiente para conocer los campos admitidos. Tipo: array Ejemplo: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]

conversions object

Name	Description
conversion_time required	La hora, expresada en ISO 8601. Type: string Example: 2017-10-05T00:00:00Z
event_id required	El ID en base 36 de un evento específico. Coincide con un evento preconfigurado incluido en esta cuenta publicitaria. Esto se denomina ID en el evento correspondiente en Events Manager. Type: string Example: o87ne o tw-o8z6j-o87ne (tw-pixel_id-event-id), ambos son válidos
identifiers required	Una lista de objetos de identificador 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 de identificador. Si se utiliza una dirección IP o un user agent (agente de usuario), se debe enviar un segundo identificador para una correcta asignación de la conversión. Type: array Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items optional	El número de artículos que se compran en el evento. Debe ser un número positivo mayor que cero. Type: integer Example: 4
price_currency optional	La moneda de los artículos que se compran en el evento, expresada en ISO-4217. Consulta Currency para obtener información detallada. Type: string Default: USD Example: JPY
value optional	El precio de los artículos que se compran en el evento, expresado en la moneda de price_currency. Type: double Example: 100.00
conversion_id optional	Para la deduplicación entre conversiones de píxel y de Conversion API. Un identificador de un evento de conversión que se puede utilizar para la deduplicación entre conversiones de 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. Type: string Example: 23294827
description optional	Descripción con cualquier información adicional sobre las conversiones. Type: string Example: test conversion
contents optional	Lista de detalles relacionados con un producto o contenido específico para proporcionar información granular. Consulta la tabla a continuación para ver los campos admitidos. Type: array Example: contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]

identifiers object

Name	Description
twclid sometimes required	ID de clic obtenido a partir de la URL de click-through. Es obligatorio si no se agrega ningún otro identificador. Type: string Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email sometimes required	Una dirección de correo electrónico con hash mediante SHA256. El texto debe estar en minúsculas y sin espacios al principio ni al final antes de aplicar el hash. Es obligatorio si no se agrega ningún otro identificador. Type: string Example: Para [e-mail] = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number sometimes required	Un número de teléfono en formato E164 y con hash mediante SHA256. El número de teléfono debe estar en formato E164 antes de aplicar el hash. Es obligatorio si no se agrega ningún otro identificador. Type: string Example: Para [phone] = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231
ip_address sometimes required	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). Type: string Example: 8.25.197.25
**user_agent ** sometimes required	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). Type: string Example: 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

Name	Description
content_id optional	SKU o GTIN; identificador que representa el contenido. Type: string Example: jhp
content_group_id optional	ID asociada con un grupo de variantes de producto. Type: integer Example: group 1
content_name optional	Nombre del producto o servicio. Type: string Example: radio flyer
content_price optional	Precio del producto o servicio. Type: double Example: 5.00
content_type optional	Categoría del producto que se compró. Type: string Example: clothes
num_items optional	Número de productos comprados. Type: integer Example: 1

Parámetros de la respuesta

Nombre	Descripción
conversions_processed	Número de conversiones procesadas correctamente Tipo: integer Ejemplo: 1
debug_id	Un UUID de depuración que se puede usar para investigaciones posteriores Tipo: string Ejemplo: ff02e052-36e4-47d6-bdf0-6d8986446562

Ejemplo de solicitud

    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 suministros para mascotas",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "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/:account_id/web_event_tags

Obtiene 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/:account_id/web_event_tags

​

Parámetros

Nombre	Descripción
account_id required	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 para GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica el número de registros que se intenta recuperar por cada solicitud individual. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica un cursor para obtener la siguiente página de resultados. Consulta Pagination para más información. Type: string Example: 8x7v00oow
sort_by optional	Ordena por un atributo admitido en orden ascendente o descendente. Consulta Sorting para más información. Type: string Example: created_at-asc
web_event_tag_ids optional	Restringe la respuesta únicamente a las etiquetas de eventos web deseadas especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 200 id. Type: string Example: o3bk1
with_deleted optional	Incluye en tu solicitud los resultados eliminados. Type: boolean Default: false Possible values: true, false
with_total_count optional	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 tasa más bajos, actualmente establecidos en 200 por cada 15 minutos. Type: boolean Default: false Possible values: 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/:account_id/web_event_tags/:web_event_tag_id

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

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

Parameters

Name	Description
account_id required	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. Type: string Example: 18ce54d4x5t
web_event_tag_id required	Una referencia a la etiqueta de evento web que se utiliza en la solicitud. Type: string Example: o3bk1
with_deleted optional	Incluye los resultados eliminados en la solicitud. Type: boolean Default: false Possible values: 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": "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
      }
    }

​

POST accounts/:account_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/:account_id/web_event_tags

​

Parámetros

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece dentro de 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. Type: string Example: 18ce54d4x5t
click_window required	La ventana de atribución por clic para esta etiqueta web. Nota: Solo se aceptan los valores posibles que se indican a continuación. Type: int Possible values: 1, 7, 14, 30
name required	El nombre de la etiqueta web. Type: string Example: Sample single conversion event
retargeting_enabled required	Indica si se debe habilitar el retargeting para esta etiqueta web. Type: boolean Possible values: true, false
type required	El tipo de etiqueta web. Type: enum Possible values: 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 de usuario, SITE_VISIT se muestra como “Page view” y SIGN_UP se muestra como “Lead”)
view_through_window required	La ventana de atribución por 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 posibles que se indican a continuación. Type: int Possible values: 0, 1, 7, 14, 30

Ejemplo de solicitud

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7

​

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": null,
        "status": "UNVERIFIED",
        "type": "SITE_VISIT",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "web event tag",
          "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_id/web_event_tags/:web_event_tag_id

​

Parameters

Name	Description
account_id required	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. Type: string Example: 18ce54d4x5t
web_event_tag_id required	El identificador de una etiqueta web en la cuenta actual. Type: string Example: o3bk1
click_window optional	La ventana de clic para esta etiqueta web. Nota: Solo se aceptan los valores posibles que se indican a continuación. Type: int Valores posibles: 1, 7, 14, 30
name optional	El nombre de la etiqueta web. Type: string Example: Sample single conversion event
retargeting_enabled optional	Indica si se debe habilitar el retargeting para esta etiqueta web. Type: boolean Valores posibles: true, false
type optional	El tipo de etiqueta web. Type: 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 de usuario, 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 posibles que se indican a continuación. Type: int Valores posibles: 0, 1, 7, 14, 30

​

Ejemplo de solicitud

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD

​

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": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DOWNLOAD",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

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

​

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

Parámetros

Nombre	Descripción
account_id required	El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes a 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 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"
        }
      }
    }