Requisitos
Antes de realizar solicitudes autenticadas a la X Ads API, necesitarás:- una cuenta de desarrollador aprobada
- una aplicación que haya sido aprobada para acceder a la Ads API
- la API key y el secret obtenidos a través de la interfaz de gestión de apps y
- access tokens para un usuario con acceso a una cuenta de X Ads
Uso de la API
La Advertising API se accede en https://ads-api.x.com. La REST API estándar y la Advertising API pueden usarse conjuntamente con la misma aplicación cliente. La Advertising API exige HTTPS; por tanto, los intentos de acceder a un endpoint con HTTP darán como resultado un mensaje de error. La Ads API devuelve JSON. Todos los identificadores son cadenas y todas las cadenas están en UTF-8. La Advertising API 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 habituales
Existen cuatro verbos HTTP utilizados en la Ads API:- GET recupera datos
- POST crea datos nuevos, como campañas
- PUT actualiza datos existentes, como line items
- DELETE elimina datos.
with_deleted=true al solicitar el recurso. De lo contrario, los registros eliminados devolverán un HTTP 404.
Una solicitud exitosa 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 desestablecer un valor opcional especificando el parámetro con una cadena vacía. Como ejemplo, este grupo de parámetros desestablecería cualquier end_time ya especificado: &end_time=&paused=false.
Consulta Códigos de error y respuestas para más detalles sobre las respuestas de error.
Parámetros en línea
La mayoría de las URLs de recursos contienen uno o más parámetros en línea. Muchas URLs 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 (”:”) antepuestos en la sección Ruta del recurso de cada recurso. Por ejemplo, si la cuenta con la que estás trabajando estuviera identificada como"abc1" y estuvieras recuperando las campañas asociadas a 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 solo con esa cuenta.
Uso de access tokens
La X Ads API utiliza solicitudes HTTPS firmadas para validar la identidad de la aplicación y también para obtener los permisos concedidos al usuario final en cuyo nombre la aplicación realiza la solicitud API, representados por el access token del usuario. Todas las llamadas HTTP a la Ads API deben incluir una cabecera Authorization (usando OAuth 1.0a) sobre el protocolo HTTPS. Deberás añadir soporte a tu aplicación para generar cabeceras Authorization OAuth 1.0a para integrarte con la X Ads API. Sin embargo, debido a la complejidad de generar solicitudes firmadas, se recomienda encarecidamente que los partners utilicen una biblioteca existente que admita la X API o que implemente el manejo de solicitudes OAuth 1.0a. Aquí tienes una lista de bibliotecas OAuth recomendadas y ejemplos de código de autenticación. Ten en cuenta que podemos ayudar a los partners que encuentren errores de autenticación cuando usen una biblioteca conocida, pero no podemos dar soporte a implementaciones personalizadas de OAuth.HTTP y OAuth
Al igual que la X REST API v1.1, la Advertising API requiere el uso de OAuth 1.0A y HTTPS. Las API keys pueden obtenerse a través de la consola de gestión de apps. Los access tokens también deben usarse para representar al “usuario actual”. El usuario actual es una cuenta de X con capacidades publicitarias. Se recomienda encarecidamente que los partners utilicen una biblioteca OAuth en lugar de escribir la suya propia. Podemos ayudar con la depuración cuando se utilice una biblioteca conocida, pero no si desarrollas tu propia implementació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 adecuadamente dentro de las URLs y los cuerpos POST antes de preparar las cadenas base de firma OAuth. La Advertising API en particular utiliza caracteres ”:” al especificar tiempo y caracteres ”,” al proporcionar una colección de opciones. Ambos caracteres están entre este conjunto reservado:Realizar tu primera solicitud a la API con Twurl
X ayuda a mantener una herramienta de línea de comandos, Twurl, que admite cabeceras de autorización OAuth 1.0a como alternativa a cURL. Twurl proporciona una manera sencilla de realizar solicitudes autenticadas a la API y de 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 access tokens y realizar solicitudes autenticadas a la Ads 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 APIs más populares que existen en la industria hoy en día. Es un cliente HTTP con una gran interfaz de usuario que te permite realizar solicitudes API complejas más fácilmente y aumenta la productividad. Para instalar Postman y empezar a usar la colección Postman de la Ads API, consulta nuestra guía de configuración.Extender tu aplicación para realizar solicitudes autenticadas
Después de familiarizarte con la realización de solicitudes a la Ads API usando Twurl, es momento de añadir soporte para crear cabeceras de autenticación OAuth 1.0a en tu aplicación. Las cabeceras de autenticación OAuth 1.0a incluyen información que verifica la identidad tanto de la aplicación como del usuario y previene la manipulación de la solicitud. Tu aplicación necesitará crear una nueva cabecera Authorization para cada solicitud a la API. Muchos lenguajes tienen bibliotecas de código abierto que dan soporte a la creación de esta cabecera de autorización para realizar solicitudes API a X. Aquí tienes algunos ejemplos usando 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 el soporte de creación de la cabecera Authorization. Se recomienda encarecidamente usar una biblioteca respaldada por la comunidad. Esquema general:- Recopila 7 pares clave/valor para la cabecera, comenzando con oauth_
- Genera una firma OAuth 1.0a HMAC-SHA1 usando esos pares clave/valor
- Construye la cabecera Authorization usando los valores anteriores