Saltar al contenido principal
Acceder a los endpoints de la Ads API de X requiere que tu aplicación envíe solicitudes web autenticadas de forma segura mediante TLS a https://ads-api.x.com. Las siguientes secciones ofrecerán una descripción general de cómo realizar solicitudes autenticadas a la API, cómo configurar Twurl para interactuar con la API y cómo ampliar tu aplicación para que admita OAuth 1.0a y pueda realizar solicitudes a tu cuenta de Ads.

Requisitos

Antes de realizar solicitudes autenticadas a la X Ads API, necesitas:

Uso de la API

Se accede a la API de Publicidad en https://ads-api.x.com. La API REST estándar y la API de Publicidad se pueden usar conjuntamente con la misma aplicación cliente. La API de Publicidad exige el uso de HTTPS; por lo tanto, los intentos de acceder a un endpoint con HTTP producirán un mensaje de error. La API de Publicidad devuelve JSON. Todos los identificadores son cadenas y todas las cadenas están en UTF-8. La API de Publicidad está versionada y la versión se especifica como el primer elemento de la ruta de cualquier URL de recurso. https://ads-api.x.com/<version>/accounts

Verbos HTTP y códigos de respuesta típicos

Hay cuatro verbos HTTP utilizados en la Ads API:
  • GET recupera datos 
  • POST crea nuevos datos, como campañas
  • PUT actualiza datos existentes, como líneas de pedido
  • DELETE elimina datos.
Aunque las eliminaciones son permanentes, en la mayoría de los métodos basados en GET aún se pueden ver los datos eliminados si se incluye explícitamente el parámetro with_deleted=true al solicitar el recurso. De lo contrario, los registros eliminados devolverán un código de estado HTTP 404. Una solicitud satisfactoria devolverá una respuesta HTTP de la serie 200 junto con la respuesta JSON que representa el objeto al crear, eliminar o actualizar un recurso. Al actualizar datos con HTTP PUT, solo se actualizarán los campos especificados. Puedes restablecer (dejar sin valor) un valor opcional especificando el parámetro con una cadena vacía. Por ejemplo, este grupo de parámetros restablecería cualquier end_time ya especificado: &end_time=&paused=false. Consulta Códigos de error y respuestas para obtener más detalles sobre las respuestas de error.

Parámetros en línea

La mayoría de las URL de recursos incluyen uno o más parámetros en línea. Muchas URL también aceptan parámetros declarados explícitamente en la cadena de consulta o, para solicitudes POST o PUT, en el cuerpo. Los parámetros en línea se indican con dos puntos (“:”) antepuesto en la sección Resource Path de cada recurso. Por ejemplo, si la cuenta en la que estuvieras trabajando se identificara como "abc1" y recuperaras las campañas asociadas con una cuenta, accederías a esa lista utilizando la URL https://ads-api.x.com/6/accounts/abc1/campaigns. Al especificar el parámetro en línea account_id descrito en la URL del recurso (https://ads-api.x.com/6/accounts/:account_id/campaigns), has limitado el alcance de la solicitud a los objetos asociados únicamente con esa cuenta.

Uso de tokens de acceso

La X Ads API utiliza solicitudes HTTPS firmadas para validar la identidad de una aplicación y también obtener los permisos otorgados al usuario final en cuyo nombre la aplicación realiza la solicitud a la API, representados por el token de acceso del usuario. Todas las llamadas HTTP a la Ads API deben incluir un encabezado de solicitud Authorization (usando OAuth 1.0a) sobre el protocolo HTTPS. Deberás añadir compatibilidad para generar encabezados de solicitud Authorization de OAuth 1.0a en tu aplicación para poder integrarla con la X Ads API. Sin embargo, debido a la complejidad de generar solicitudes firmadas, recomendamos encarecidamente que los socios utilicen una biblioteca existente que admita la X API o implemente el manejo de solicitudes con OAuth 1.0a; aquí encontrarás una lista de bibliotecas OAuth recomendadas y ejemplos de código de autenticación. Ten en cuenta que podemos ayudar a los socios que encuentren errores de autenticación al usar una biblioteca conocida, pero no podemos brindar soporte para implementaciones personalizadas de OAuth.

HTTP y OAuth

Al igual que la X REST API v1.1, la Advertising API requiere el uso tanto de OAuth 1.0A como de HTTPS. Las claves de API se pueden obtener a través de la consola de administración de Apps. También se deben usar tokens de acceso para representar al “usuario actual”. El usuario actual es una cuenta de X con capacidades publicitarias. Se recomienda encarecidamente que los socios usen una biblioteca de OAuth en lugar de escribir una propia. Podemos ayudar con la depuración cuando se usa una biblioteca conocida, pero no si implementas tu propia versión de OAuth. Consulta las bibliotecas que puedes usar. La API es estricta con HTTP 1.1 y OAuth. Asegúrate de codificar los caracteres reservados de forma adecuada en las URL y en los cuerpos de las solicitudes POST antes de preparar las cadenas base de la firma de OAuth. En particular, la Advertising API utiliza caracteres ”:” al especificar la hora y ”,” al proporcionar una colección de opciones. Ambos caracteres forman parte de este conjunto reservado:

Realizar tu primera solicitud a la API con Twurl

X mantiene una herramienta de línea de comandos, Twurl, que admite encabezados de autorización OAuth 1.0a como alternativa a cURL. Twurl ofrece una forma sencilla de realizar solicitudes autenticadas a la API y explorar la Ads API antes de añadir autenticación a tu aplicación. Después de instalar y autorizar Twurl, puedes generar rápidamente tokens de acceso y realizar solicitudes autenticadas a la Ads API.
Dedica algo de tiempo a familiarizarte con Twurl y la API siguiendo este tutorial paso a paso para crear una campaña mediante la API.

Pruebas con Postman

Para quienes no están familiarizados con una herramienta de línea de comandos, también proporcionamos una colección de Postman para los endpoints de la X Ads API. Postman es una de las herramientas de desarrollo de API más populares del sector en la actualidad. Es un cliente HTTP con una excelente interfaz de usuario que te permite realizar solicitudes de API complejas de forma más sencilla y aumentar la productividad. Para instalar Postman y comenzar a usar la colección de Postman para la X Ads API, consulta nuestra guía de configuración.

Ampliar tu aplicación para realizar solicitudes autenticadas

Después de familiarizarte con cómo hacer solicitudes a la Ads API usando Twurl, es momento de agregar compatibilidad en tu aplicación para crear encabezados de autenticación OAuth 1.0a. Los encabezados de autenticación OAuth 1.0a incluyen información que verifica la identidad tanto de la aplicación como del usuario, y además evitan la manipulación de la solicitud. Tu aplicación deberá crear un nuevo encabezado Authorization para cada solicitud a la API. Muchos lenguajes de programación cuentan con bibliotecas de código abierto que permiten crear este encabezado de autorización para hacer solicitudes a la API de X. A continuación se muestran algunos ejemplos en C#, PHP, Ruby y Python: ejemplos de código.

Implementación personalizada

Hay algunos escenarios que requieren implementar la autenticación OAuth 1.0a sin el soporte de una biblioteca de código abierto. Autorizar una solicitud proporciona instrucciones detalladas para implementar la compatibilidad con la creación del encabezado Authorization. Recomendamos encarecidamente usar una biblioteca mantenida por la comunidad. Esquema general:
  1. Recopila 7 pares clave/valor para el encabezado, que comiencen por oauth_
  2. Genera una firma OAuth 1.0a HMAC-SHA1 usando esos pares clave/valor
  3. Crea el encabezado Authorization usando los valores anteriores