| Versión | Ruta | Fecha de introducción | Fecha de deprecación | Fecha de fin de vida |
|---|---|---|---|---|
| 12.0 | /12/ | 27 de octubre de 2022 | Por definir | Por definir |
| 11.0 | /11/ | 31 de marzo de 2022 | Por definir | Por definir |
| 10.0 | /10/ | 31 de agosto de 2021 | 31 de marzo de 2022 | 27 de octubre de 2022 |
| 9.0 | /9/ | 2 de marzo de 2021 | 31 de agosto de 2021 | 31 de marzo de 2022 |
| 8.0 | /8/ | 8 de septiembre de 2020 | 2 de marzo de 2021 | 31 de agosto de 2021 |
| 7.0 | /7/ | 3 de marzo de 2020 | 1 de septiembre de 2020 | 2 de marzo de 2021 |
| 6.0 | /6/ | 28 de agosto de 2019 | 3 de marzo de 2020 | 1 de septiembre de 2020 |
| 5.0 | /5/ | 28 de febrero de 2019 | 28 de agosto de 2019 | 3 de marzo de 2020 |
| 4.0 | /4/ | 28 de agosto de 2018 | 28 de febrero de 2019 | 28 de agosto de 2019 |
| 3.0 | /3/ | 1 de febrero de 2018 | 28 de agosto de 2018 | 28 de febrero de 2019 |
| 2.0 | /2/ | 10 de julio de 2017 | 1 de febrero de 2018 | 1 de agosto de 2018 |
| 1.0 | /1/ | 31 de marzo de 2016 | 7 de julio de 2017 | 10 de enero de 2018 |
| 0.0 | /0/ | 21 de febrero de 2013 | N/D | 31 de octubre de 2016 |
Descripción general
- Eliminar un parámetro de la solicitud/respuesta de la API
- Modificar el nombre de cualquier parámetro o endpoint
- Cambiar la representación de valores (preview_url → card_uri)
- Cambiar el comportamiento de los endpoints (p. ej., estadísticas async vs. sync)
- Agregar/modificar parámetros opcionales o obligatorios (p. ej., hacer que name sea un campo obligatorio en la solicitud)
Estrategia de versionado
- Todos los cambios con ruptura se agruparán en una versión nueva
- El periodo de desaprobación para las versiones existentes cuando se anuncia una versión nueva es de 6 meses
- En cualquier momento, la API permitirá solicitudes de dos versiones simultáneamente; sin embargo, la más antigua de las dos no contará con soporte
- Para facilitar una adopción más rápida de nuevos productos, estos se lanzarán de forma continua (fuera de la cadencia de versionado)
-
Todas las respuestas de la API incluirán un
x-current-api-version, establecido en la versión actual de la API, además de un encabezadox-api-warnal llamar a cualquier endpoint de la API en desaprobación.
v9
Nota: A partir de esta versión, la versión 7 (v7) de la Ads API ha alcanzado el fin de su vida útil y ya no está disponible.
v8
v7
v6
v5
accounts/:account_id/account_media quedaron obsoletos.
Como en versiones anteriores, habrá un período de transición de 6 meses para migrar a v5. El 2019-08-28, la versión 4 de la X Ads API dejará de estar disponible. Recomendamos a todos los partners migrar a la versión más reciente de la API lo antes posible para evitar interrupciones del servicio. La versión 3 de la X Ads API llegó al final de su vida útil y ya no está disponible.
Novedades
CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE y PROMOTED_TWEET.
Estadísticas de MEDIA_CREATIVE
Los endpoints de analytics de la X Ads API ahora proporcionan metrics para entidades de Media Creative. Los Media Creatives son el mecanismo mediante el cual se promocionan anuncios in-stream o imágenes en la X Audience Platform. La interfaz de X Ads muestra las metrics de Media Creative en las pestañas “In-stream videos” y “Display creatives”. Tanto los endpoints de analytics síncronos como asíncronos ahora admiten el enum de entidad MEDIA_CREATIVE.
Obtener varias cards
Mejorando la versión v3 del endpoint diseñado para recuperar una sola card por su valor de card URI, ahora es posible obtener varias cards mediante el endpoint GET accounts/:account_id/cards/all. Ahora, en lugar de hacer una solicitud por cada card, puede recuperar hasta 200 cards en una sola solicitud.
Dos aspectos a tener en cuenta:
- La ruta de URL ahora es
accounts/:account_id/cards/all. (La ruta anterior ya no está disponible). Esto es para mantener coherencia con el endpoint diseñado para recuperar una card por ID. - El parámetro de solicitud obligatorio ahora se llama card_uris (en plural).
- GET accounts/:account_id/line_item_apps
- GET accounts/:account_id/media_creatives
- GET accounts/:account_id/promoted_accounts
- GET accounts/:account_id/preroll_call_to_actions
Cambiado
draft_only | with_draft | |
Segmentación por duración de activación de la red
La X Ads API ha resuelto un problema de visualización en el que, tras agregar la segmentación de Network Activation Duration, el tipo de segmentación en la respuesta incluía el sufijo _IN_SEC. Hacer referencia a segundos resultaba confuso, ya que Network Activation Duration siempre se representa en meses. Esta corrección unifica la representación y reduce la confusión.
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |
Recuentos totales y cursores
En v5, with_total_count y cursor son excluyentes. Especificar ambos en una solicitud devolverá el código de error EXCLUSIVE_PARAMETERS. Antes de v5, with_total_count se ignoraba cuando se especificaba cursor. Este cambio hace explícita la relación.
Eliminado
- En v4, se anunció que el parámetro de respuesta preview_url para las cards siempre era null. El paso final de esta migración es eliminar preview_url de todas las respuestas de cards.
- El atributo de respuesta account_id se está eliminando para los siguientes recursos, dado que el id de la cuenta de anuncios ya está presente en la URL y en request.params. (Se excluyen intencionalmente los instrumentos de financiación de esta lista, ya que, cuando sea posible, los parent IDs deben estar presentes en los objetos de respuesta, y los account IDs son entidades padre de los instrumentos de financiación).
- Medios de la cuenta
- Proveedores de eventos de App
- Etiquetas de eventos de App
- Campañas
- Cards
- Line items
- Usuarios promocionables
- Criterios de segmentación
- Para las solicitudes GET accounts/:account_id/targeting_criteria, ya no devolvemos el field parent_ids, ya que siempre era un array vacío.
- Nota: Esto no afecta a las image and video app download cards.
- Los assets
AMPLIFY_VIDEOagregados a la Media Library se agregan automáticamente como asset de Account Media con el creative typePREROLL. - Las imágenes con dimensiones específicas agregadas a la Media Library se agregan automáticamente como assets de Account Media. El creative type (p. ej.,
INTERSTITIAL) depende de las dimensiones de la imagen. (Para dimensiones, consulte nuestra página de Enumerations.)
v4
Nuevo
- TON Upload:
- GET accounts/:account_id/tailored_audience_changes
- GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
- POST accounts/:account_id/tailored_audience_changes
- PUT accounts/:accounti_d/tailored_audiences/global_opt_out
- Real Time Audiences:
- POST tailored_audience_memberships
list_type se eliminará de la solicitud y de la respuesta en todos los endpoints de Tailored Audiences en la versión 4.
Settings Endpoints
Ahora permitimos que los administradores de cuenta configuren y actualicen la configuración de usuario, cuenta e impuestos. Los User settings corresponden a las preferencias de contacto específicas del usuario para una cuenta de anuncios determinada. Con el endpoint PUT accounts/:account_id, los anunciantes ahora pueden actualizar el nombre de su cuenta y el sector. Por último, los endpoints de tax settings permiten a los anunciantes en países donde se cobra el impuesto al valor agregado (IVA) actualizar información como el nombre de la empresa, la dirección, el VAT ID y si la cuenta pertenece al anunciante o a una agencia que anuncia en nombre de un anunciante.
Cambiado
lookalike_expansion en los endpoints POST accounts/:account_id/line_items y PUT accounts/:accountit/line_items/:line_item_id.
| v3 | v4 |
|---|---|
NARROW | DEFINED |
BALANCED | EXPANDED |
country_code en todas partes
Como parte de un esfuerzo más amplio por la consistencia en la X Ads API, estamos cambiando el nombre de los parámetros en los siguientes endpoints de app_country_code a country_code.
- POST accounts/:account_id/cards/image_app_download
- PUT accounts/:account_id/cards/image_app_download/:card_id
- POST accounts/:account_id/cards/video_app_download
- PUT accounts/:account_id/cards/video_app_download/:card_id
preview_url siempre null
Como se prometió en el anuncio de v3, todas las tarjetas existentes ahora tienen un card_uri. Como resultado, el valor de preview_url siempre será null.
Como recordatorio, asocia una tarjeta con un Tweet usando su valor card_uri. Consulta la siguiente solicitud de ejemplo.
$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”
Eliminado
-
Endpoint de videos en v3:
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos" -
Endpoint de Media Library en v4 para videos:
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id en la vista de Tweet
El parámetro as_user_id disponible en el endpoint GET accounts/:account_id/tweet/preview/:tweet_id ya no será aceptado. La vista previa siempre se mostrará como el autor del Tweet.
v3
- Dada una audiencia de entrada, recuperar los hashtags, @handles y eventos más relevantes.
- Dada una audiencia de entrada, recuperar información demográfica clave (como edad, género e ingresos del hogar).
- Dada una palabra clave, recuperar la serie temporal del volumen de Tweet.
Otros cambios
- La respuesta del endpoint GET insights/keywords/search ahora incluye el atributo related_keywords con 30 términos relacionados con las palabras clave de entrada.
- El tamaño máximo del lote de criterios de segmentación ahora es de 500.
- Los atributos de respuesta card_uri y preview_url ahora son mutuamente excluyentes. Cuando una tarjeta tenga card_uri, preview_url será null. Cuando una tarjeta no tenga card_uri, solo se devolverá preview_url.
- Todas las tarjetas creadas a partir de 2018-01-29 tendrán card_uri.
- Para la versión 4, todas las tarjetas existentes tendrán card_uri.
- Ya no es posible crear tarjetas con imágenes 5:2. Si bien las tarjetas existentes basadas en imágenes 5:2 seguirán funcionando, recomendamos a los socios cambiar a las relaciones de aspecto de mejor rendimiento 1.91:1 o 1:1 (donde estén disponibles).
- El endpoint PUT accounts/:account_id/targeting_criteria ya no está disponible. Hemos decidido realizar este cambio porque el comportamiento de reemplazo con este endpoint causaba confusión entre los anunciantes y no era coherente con nuestros otros endpoints PUT que actualizan un único recurso a la vez. En su lugar, los socios deben usar el endpoint POST batch/accounts/:account_id/targeting_criteria, que proporciona mayor flexibilidad, incluida la posibilidad de agregar y eliminar segmentaciones en una sola solicitud.
- El atributo de respuesta paused ya no se devuelve para los instrumentos de financiación. En su lugar, consulta el atributo de respuesta entity_status para determinar si un instrumento de financiación está pausado. Además, dado que paused y cancelled corresponden al mismo valor, cancelled tampoco se devuelve en la respuesta.
- Hemos eliminado el parámetro card_id del endpoint GET accounts/:account_id/tweet/preview.
- Debido a que no es posible recuperar Scheduled Tweets eliminados, el parámetro with_deleted ya no es compatible.
- El parámetro draft_only se ha eliminado de los siguientes endpoints, ya que estas entidades nunca pueden estar en estado de borrador:
v2
-
total_countahora es un atributo de respuesta opcional. Solo estará disponible siwith_total_countse establece entrue. -
Los campos
pausedydraft_onlyen los objetos de solicitud y respuestaline_itemsycampaignsse han reemplazado por un único parámetroentity_status. -
El parámetro
statusha pasado a llamarsetexten los endpoints POST accounts/:account_id/tweet y GET accounts/:account_id/tweet/preview. -
Los enums de
location_typedel endpoint GET targeting_criteria/locations ahora están en plural.COUNTRYahora esCOUNTRIES,REGIONahora esREGIONS, y así sucesivamente. La única excepción es que, en v2,CITYahora esMETROS, para reflejar correctamente que el tipo de ubicación se refiere a Designated Market Areas (DMA) o “metros”. -
display_propertiesen los endpoints PUT accounts/:account_id/promoted_tweets. Este valor tampoco se devolverá como parte de la respuesta. -
Como resultado del punto anterior, ya no es posible actualizar (PUT) entidades
promoted_tweets. -
Se ha eliminado el parámetro
line_item_iden el endpoint GET accounts/:account_id/promoted_tweets. - Ya no será posible crear Website Cards 5:2 en los endpoints v2.
-
El atributo de respuesta
data_typeya no se devuelve.
- Cards v2
- Creación y activación de campañas/line items en borrador
- Tweets programados
- Resúmenes de trabajos asíncronos
- Se debe usar el parámetro de solicitud
card_urien lugar de adjuntarpreview_urlal texto del Tweet al asociar una card con un Tweet. - Si el parámetro
card_urino se devuelve en la respuesta (durante el paso de creación de la card), use entoncespreview_url. - Todos los nuevos formatos de card estarán disponibles de forma nativa en la API, aprovechando el parámetro
card_uri.
- Video Website Cards:
- El valor del parámetro
entity_statusen los endpoints POST accounts/:account_id/line_items y POST accounts/:account_id/campaigns se puede establecer enDRAFTpara crear nuevas campañas o partidas (line items) en borrador. - Conjunto de parámetros obligatorios para un borrador recién creado:
| Campaña en borrador | Partida (line item) en borrador |
|---|---|
funding_instrument_id | campaign_id |
name | objective |
start_time | product_type |
placements |
- Las partidas o campañas en borrador solo pueden convertirse de un
entity_statusdeDRAFTaPAUSEDoACTIVE. - Para activar una campaña completa (con múltiples partidas), cada partida de la campaña, así como la propia campaña, debe configurarse con un
entity_statusdeACTIVE. - Para cambiar el
entity_statusde cualquier campaña o partida, use el endpoint PUT correspondiente.
- Los Tweets programados constan de los siguientes endpoints nuevos
- Tweets programados:
- Gestión de campañas:
- Los Tweets recién programados se pueden programar para cualquier fecha futura.
- Actualmente, no es posible previsualizar un Tweet programado.
-
Solo los Tweets programados en el estado
SCHEDULEDpueden editarse o eliminarse. -
Los Tweets programados no se propagan al Firehose de Enterprise ni a ninguna otra API de datos hasta la fecha y hora de
scheduled_at.
v1
- Compatibilidad con control de versiones
- Ya no se admite el objetivo
CUSTOM - Batch endpoints ya están disponibles de forma general
- Cambios en la estimación de alcance:
- Para ofrecer una mejor estimación de alcance, el endpoint ahora tiene en cuenta el presupuesto. Los siguientes parámetros ahora son obligatorios:
- [nuevo]
campaign_daily_budget_amount_local_micro currencybidobjective
- [nuevo]
- El objeto de respuesta ha cambiado y ahora devuelve intervalos para los valores de la respuesta.
infinite_countse ha renombrado ainfinite_bid_countpara evitar confusiones sobre su propósito- Además de
counteinfinite_bid_count, ahora se devolverán estos nuevos datos:impressionsengagementsestimated_daily_spend_local_micro
- Cambio en el tipo de datos para audiencias personalizadas
- El
data_typede Tailored Audiences se ha cambiado detailored_audiencesatailored_audienceen todas nuestras respuestas. - Las audiencias personalizadas compartidas ahora están disponibles como una beta exclusiva de API. Las audiencias personalizadas compartidas permiten usar una sola audiencia en varias cuentas publicitarias. Usa el endpoint POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions (y los relacionados) para gestionar los permisos de una audiencia personalizada que quieras compartir entre cuentas publicitarias.
- Mejoras significativas en la manera de recopilar análisis de rendimiento para cuentas de anunciantes: analytics
- Para alinearnos con nuestras mejores prácticas, a partir de ahora solo permitiremos obtener datos correspondientes a un máximo de 7 días para los endpoints de estadísticas síncronas.
- Para simplificar la obtención de metrics, hemos reemplazado el parámetro
metricspor un nuevo parámetrometric_groups. Los desarrolladores simplemente deben indicar qué grupos de metrics desean que se devuelvan en una solicitud determinada.- Cualquier solicitud de metrics que no sean apropiadas para una entidad determinada se excluirá de la respuesta y se representará como valores
null. Estas metrics no contarán para tu límite de costos de analytics.
- Cualquier solicitud de metrics que no sean apropiadas para una entidad determinada se excluirá de la respuesta y se representará como valores
- La respuesta se ha simplificado significativamente y ahora se alineará más estrechamente con la forma en que las metrics se exponen en nuestra interfaz.
- Anteriormente exponíamos una métrica independiente para cada ubicación de entrega (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). Ahora devolveremos un conjunto estandarizado de metrics para cada una (en lugar de
promoted_tweet_timeline_impressions,promoted_tweet_search_impressions,promoted_tweets_profile_impressions,promoted_tweets_tpn_impressions); estas se expondrán, cuando se soliciten en una de las siguientes categorías, como una única métrica:impressions(esto aplica a todas las metrics): ALL_ON_TWITTERPUBLISHER_NETWORK- Cuando realices una solicitud, obtendrás una única métrica
impressions, lo que simplifica la correspondencia de valores en nuestra UI. - Debes realizar dos consultas para obtener los datos de
ALL_ON_TWITTERyPUBLISHER_NETWORK, ya que no se pueden combinar.
- Anteriormente exponíamos una métrica independiente para cada ubicación de entrega (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). Ahora devolveremos un conjunto estandarizado de metrics para cada una (en lugar de
- Los endpoints de estadísticas asíncronas ya están disponibles, gracias a los comentarios de nuestros desarrolladores.
- Un nuevo conjunto de endpoints para solicitar estadísticas de forma asíncrona, para datos que no necesitas de inmediato o para extracciones de datos históricos.
- Encola un trabajo de estadísticas usando un único endpoint nuevo. Obtendremos los datos que has solicitado según lo permitan los recursos.
- Puedes consultar un endpoint de estado del trabajo para determinar si los datos están disponibles.
- Una vez que los datos estén disponibles, proporcionaremos un id de recogida para que descargues la respuesta JSON, la cual reflejará la respuesta del endpoint síncrono.
- Consulta hasta 90 días de datos sobre hasta 20 entidades en un único trabajo.
- Consulta nuestra guía de migración de analytics v1, que incluye el mapeo de metrics de v0 a metrics de v1
- Mejoras del Sandbox * Ahora puede crear varias cuentas de anuncios de prueba en el entorno de Sandbox. * Ahora puede crear varios instrumentos de financiamiento para una cuenta de anuncios de prueba únicamente en el entorno de Sandbox. Esto le permite probar todos nuestros tipos de instrumentos de financiamiento. Anteriormente, solo había disponible una fuente de financiamiento
CREDIT_CARDpara realizar pruebas. * ¿Desea probar una función beta? Ahora puede activar o desactivar funciones para una cuenta en el entorno de Sandbox, según sus necesidades de prueba.