Saltar al contenido principal

​
Configuración de la API de conversiones

​
Requisitos 

​
Acceso a la Ads API - Solicitudes nuevas

Paso 1: Cuenta de desarrollador
  • Al solicitar una cuenta de desarrollador, suscríbase a uno de nuestros planes para obtener aprobación instantánea.
  • Nota: Como práctica recomendada, sugerimos encarecidamente usar el handle oficial de X de su empresa para crear la cuenta de desarrollador y solicitar acceso a la Ads API. Si la cuenta de desarrollador está asociada a un handle de desarrollador, no habrá forma de transferir esas credenciales si fuera necesario. Es preferible 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 la autenticación de dos factores.
Paso 2: Solicitud de Ads API
  • Asegúrese de tener listo el App ID correcto para su solicitud de Ads API. El App ID se puede encontrar en el portal de desarrolladores en Projects & Apps. Ejemplo: 16489123
  • Solicite acceso a la Ads API poniéndose en contacto con su representante de X.

​
Acceso a X Ads API - Aplicaciones existentes

  • Si ya cuenta con una aplicación de X Ads API en uso activo, tanto la App como los access tokens existentes pueden utilizarse para la Conversion API.

​
Access Tokens

  • Los User Access Tokens para el handle del usuario propietario de la aplicación de X Ads API pueden generarse y obtenerse directamente desde el portal de desarrolladores. Se denomina “personal access token” porque está pensado para usarse con tu propio handle de X. Puedes encontrar información general sobre autenticación y el portal de desarrolladores aquí.
  • Los User Access Tokens para handles de usuario distintos del handle propietario de la aplicación de X Ads API deben generarse con un flujo de OAuth de 3 fases. Las opciones para generar el Access Token con OAuth de 3 fases 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 puede verificarse mediante el endpoint authenticated_user_access.
  • Nota: los tokens en sí (después de su creación como se indicó arriba) 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 la Conversion API

Para usar la Conversion API, debes crear un nuevo evento de conversión en Ads Manager o usar un evento existente que ya hayas creado y utilizado con X Pixel. Si quieres realizar la desduplicación entre los eventos del píxel y de la Conversion API, debes usar el evento existente que creaste para el píxel. 
Opción 1: Usar un evento de conversión existente en Ads Manager
Si deseas usar un evento existente que ya empleas con el píxel de X, es posible; deberás tomar el Event ID de ese evento. Si utilizas tanto el píxel como la Conversion API para el mismo evento, asegúrate de usar la clave de desduplicación tanto en el fragmento de código del píxel como en la solicitud de la Conversion API (como conversion_id) para desduplicar los eventos entre el píxel y la Conversion API para ese mismo evento. Consulta la sección d. Testing Events and Deduplication 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) agregada a tu cuenta, ve a Events Manager y comprueba si aparece X Pixel en el menú de la izquierda. Si aún no tienes una fuente de eventos agregada, sigue los pasos a continuación para crear una fuente de eventos.
  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 un X Pixel event source en la barra lateral izquierda
    1. El ID del X Pixel event source 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 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 tendrás tu evento de conversión 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), una dirección de correo electrónico o un número de teléfono. Si se utiliza la dirección IP o el agente de usuario, se debe enviar un segundo identificador para realizar una coincidencia de conversión adecuada. Enviar más identificadores aumentará la tasa de coincidencia de conversión.
Campo de coincidencia de clientesFormato¿Se requiere hashing?
X Click IDGenerado por X (más información)No
Dirección de correo electrónicoQuitar espacios iniciales y finalesRequerido (SHA256)
Número de teléfonoEstándar E.164Requerido (SHA256)
Dirección IPQuitar espacios iniciales y finalesNo
Agente de usuarioQuitar 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 query 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');
  // Pasos recomendados a continuación: registrar en logs, insertar en el almacenamiento local
}
Se recomienda:
  1. Analizar siempre el valor de twclid cuando esté presente en los parámetros query de la URL.
  2. Almacenar los data junto con los campos relevantes del formulario 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 habilita 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 Event Source URL debe estar codificada en formato URL y está pensada para representar la página web que originó 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, aplicarles un hash para proteger la privacidad. La información debe hashearse usando SHA256, sin sal.  Por ejemplo, para la dirección de correo electrónico test@x.com, debe enviarse en formato hasheado: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

​
3. Preparar el identificador de teléfono 

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

​
4. Preparar el identificador de dirección IP

La dirección IP debe pasarse junto con otro identificador (twclid, dirección de correo electrónico, número de teléfono o agente de usuario). No se requiere hashing para 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 hash a este identificador. Este identificador permite al servidor reconocer la aplicación, el sistema operativo, el proveedor y/o la versión del agente de usuario 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 fue correcto (HTTP 200 OK). Se recomienda implementar 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 API Reference. 

​
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":"Compra 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. Tenga en cuenta que es posible que el código de su servidor deba implementar lógica fuera de esta llamada, incluida:
  1. Instrumentación de acciones de los usuarios (registro) para poder enviar 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 relevantes; por ejemplo, si han optado por excluirse del seguimiento o de la venta de su información personal en el sitio web del anunciante
  3. Integración con activadores de eventos y páginas para capturar eventos y enviar conversiones

​
Pruebas de eventos y desduplicación

​
Pruebas de eventos

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

​
Duplicación entre Pixel y Conversion API

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

​
Seguimiento de conversiones (Visión general)

​
Resumen

El seguimiento de conversiones le permite medir cuántos usuarios de X realizan una acción deseada después de ver e interactuar con sus anuncios en X. Le brinda la capacidad de medir qué campañas impulsan acciones como visitas al sitio, registros y compras. Esto proporciona a los anunciantes capacidades de medición fuera de X para entender el rendimiento de sus anuncios de respuesta directa y adquirir clientes de forma rentable. Con una etiqueta de conversión, los anunciantes pueden rastrear las conversiones de los usuarios y asociarlas a 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). Existe una variedad de acciones en sitios web que un anunciante puede medir con el seguimiento de conversiones. Pueden seleccionar una o varias, según las acciones que busquen 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 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 electrónico del anunciante
  • Personalizada: categoría comodín para una acción personalizada que no encaja en ninguna 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 podrían haber utilizado en lugar de la función de seguimiento de conversiones 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 rastrear conversiones atribuidas a interacciones de las etapas media y 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.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 han etiquetado. Si el usuario completa esa acción dentro de la(s) ventana(s) de atribución especificada(s) por los anunciantes durante la configuración de la etiqueta, esta reconoce que el usuario interactuó previamente con un anuncio de X. La etiqueta luego “se activa” y 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á diseñado para adjuntar 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 determinada etiqueta.
Ventana de atribución posvisualización predeterminada: 1 díaAtribución posinteracción predeterminada: 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 posinteracción son 1, 7, 14, 30, 60 y 90 días. Las opciones para ventanas de atribución posvisualizació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í hay 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 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 copy del Tweet: Probar mayúsculas vs minúsculas (FREE vs free o NOW vs now)
  • Plazos: Ofrece 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ías de interés: Una alineación estrecha entre el copy 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 CPA más bajos que los grupos de control que usaban otras segmentaciones
Cuanto más granular sea la segmentación de tu campaña, más accionables serán los resultados de conversión informados. 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 tiene preguntas sobre códigos de error tras llamar a la API, consulte la sección siguiente. Para cualquier otra consulta, no dude en ponerse en contacto con su representante de Twitter; trabajaremos para resolverla lo antes posible. 

​
Gestión y explicación de errores

Una solicitud solo se considerará exitosa cuando no haya errores en ninguna de las conversiones que incluye. Si se produce algún error en una conversión individual, el endpoint emitirá una lista con todos los errores aplicables.

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

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

​
Cuando se recibe un código HTTP de la serie 500, se debe 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 verificar si otras personas están experimentando problemas similares.

​
Cuando se devuelve 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 cuenta de desarrollador)
  • 404 Not Found (la URL o los parámetros pueden no ser correctos para el endpoint)

​
Códigos de error de la API de Conversiones

​
400 Escenarios de solicitud incorrecta

MotivoTipoMensaje de error
Falta 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 type 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 cantidad de conversiones es 500
Falta el Event ID400 Solicitud incorrectaNo 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) no es una etiqueta de evento única (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":"Debe proporcionarse 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_id":"o6dl3", "identifiers": [{"hashed_email": "abc"}]}]}' --header 'Content-Type: application/json'

​
Mensaje de error:

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) no es un hash SHA-256 válido","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: Credenciales de autenticación faltantes o incorrectas Solución: Siga los pasos de autenticación en la documentación de configuración utilizando uno de los 3 métodos de autenticación: Los Access Tokens de usuario para cuentas distintas de la que es propietaria de la aplicación de X Ads API deben generarse con un flujo de OAuth de 3 fases. Las opciones para generar el Access Token con OAuth de 3 fases 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 puede verificarse mediante el endpoint authenticated_user_access.

​
403 Acceso prohibido 

MotivoTipoMensaje de error
La cuenta de desarrollador que estás usando no tiene acceso a X 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 pudo encontrar el recurso solicitado
No tiene acceso a la cuenta propietaria de pixel_id/Etiqueta universal del sitio web404 No encontradoEl usuario <user_id> no tiene acceso a la cuenta <account_id>. Escriba ‘sn <user_id>’ para obtener el handle del usuario. Use ‘twurl accounts’ y ‘twurl set default \u003Cusername\u003E’ para cambiar el usuario en uso.
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_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_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) no es una etiqueta de evento única (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

​
Índice de referencia de la API

Para consultar la referencia completa de la API, selecciona un endpoint de la lista:

​
Conversiones web

API de conversionesmeasurement/conversions/:pixel_id
Etiqueta de eventos webaccounts/: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 confirmar que fue correcto (HTTP 200 OK). Se recomienda implementar un mecanismo de reintentos y un registro básico en caso de que se devuelvan códigos de error. El límite de tasa 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 la URL de la solicitud
NombreDescripción
pixel_id
obligatorio		El Base Tag ID de una cuenta publicitaria. Representa el valor codificado en base36 del Base Tag ID de una cuenta publicitaria.

Type: string

Example: o8z6j
conversions
obligatorio		Objeto en el cuerpo de la solicitud POST de la API. Lista de eventos de conversión. Se pueden proporcionar hasta 500 eventos de conversión. Consulte la tabla a continuación para los fields admitidos.

Type: array

Example: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]
objeto conversions
NameDescription
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. En el evento correspondiente en Events Manager se denomina ID.

Type: string

Example: o87ne o tw-o8z6j-o87ne (tw-pixel_id-event-id), ambos aceptados
identifiers
required		Una lista de objetos identificadores para asociar el evento de conversión. Los fields compatibles se enumeran en la tabla más abajo. Se requiere al menos uno de los objetos identificadores.

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

Type: array

Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
optional		La cantidad 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 comprados en el evento, representado en la moneda de price_currency.

Type: double

Example: 100.00
conversion_id
optional		Para la desduplicación entre conversiones del píxel y de la Conversion API. Identificador de un evento de conversión que puede usarse para la desduplicación entre conversiones del Web Pixel y de la Conversion API en la misma etiqueta de evento. Consulta la sección Testing Events and Deduplication de la Conversions Guide para más información.

Type: string

Example: 23294827
description
optional		Descripción con información adicional sobre las conversiones.

Type: string

Example: test conversion
contents
optional		Lista de detalles relacionados con un producto/contenido específico para proporcionar información granular. Consulta la tabla a continuación para los fields compatibles.

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"}]
objeto identifiers
NameDescription
twclid
a veces obligatorio		ID de clic extraído de la URL de redirección. Es obligatorio si no se añade ningún otro identificador.

Type: string

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

Type: string

Example: Para test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
a veces obligatorio		Un número de teléfono con 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 añade ningún otro identificador.

Type: string

Example: 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).

Type: string

Example: 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).

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
NombreDescripción
content_id
opcional		SKU o GTIN; identificador que representa el contenido.

Tipo: string

Ejemplo: jhp
content_group_id
opcional		ID asociado a 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 adquiridos.

Tipo: integer

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

Tipo: integer

Ejemplo: 1
debug_idUUID de depuración que puede usarse 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 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 petición
    {
       "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 con la cuenta actual.

​
URL del recurso

https://ads-api.x.com/12/accounts/:account_id/web_event_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 intentar recuperar por cada solicitud.

Tipo: int

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

Tipo: string

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

Tipo: string

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

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 tasa más bajos, actualmente establecidos en 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": "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": "TRACKING",
          "type": "DOWNLOAD"
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

​
GET accounts/:account_id/web_event_tags/:web_event_tag_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_id/web_event_tags/:web_event_tag_id
Parámetros
NombreDescripción
account_id
obligatorio		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 al usuario autenticado.

Type: string

Example: 18ce54d4x5t
web_event_tag_id
obligatorio		Referencia a la etiqueta de evento web con la que se opera en la solicitud.

Type: string

Example: o3bk1
with_deleted
opcional		Incluye 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
Respuesta de ejemplo
    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "tag 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": "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

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.

Type: string

Example: 18ce54d4x5t
click_window
required		La ventana de clic para esta etiqueta web.

Nota: Solo se aceptan los valores posibles que se enumeran 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, SITE_VISIT se muestra como “Page view” y SIGN_UP se muestra como “Lead”)
view_through_window
required		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 enumeran 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": "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": "UNVERIFIED",
        "type": "SITE_VISIT",
        "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_id/web_event_tags/:web_event_tag_id

​
Parámetros

NombreDescripción
account_id
obligatorio		El identificador de la cuenta usada. 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
obligatorio		El identificador de una etiqueta web en la cuenta actual.

Type: string

Example: o3bk1
click_window
opcional		La ventana de atribución por clic para esta etiqueta web.

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

Type: int

Possible values: 1, 7, 14, 30
name
opcional		El nombre de la etiqueta web.

Type: string

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

Type: boolean

Possible values: true, false
type
opcional		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 IU, SITE_VISIT se muestra como “Page view” y SIGN_UP se muestra como “Lead”)
view_through_window
opcional		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 que se indican a continuación.

Type: int

Possible values: 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": "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": "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 con la cuenta actual.

​
URL del recurso

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_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 Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado.

Type: string

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

Type: string

Example: o3bk1
Ejemplo de solicitud
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
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": "2021-05-22T17:00:04Z",
        "status": "NO VERIFICADO",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }
⌘I