Saltar al contenido principal
Para acceder a los endpoints de la X Ads API, su App debe enviar solicitudes web autenticadas de forma segura mediante TLS a https://ads-api.x.com. Las siguientes secciones ofrecen una descripción general sobre cómo realizar solicitudes autenticadas a la API, cómo configurar Twurl para interactuar con la API y cómo ampliar su App para admitir OAuth 1.0a y realizar solicitudes a su cuenta de Ads.

​
Requisitos

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

​
Uso de la API

Se accede a la Ads API en https://ads-api.x.com. La API REST estándar y la Ads API pueden usarse conjuntamente con la misma App cliente. La Ads API exige HTTPS; por lo tanto, los intentos de acceder a un endpoint con HTTP darán como resultado un mensaje de error. La X Ads API devuelve JSON. Todos los identificadores son cadenas y todas las cadenas están en UTF-8. La Ads 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 típicos

Hay cuatro verbos HTTP utilizados en la X Ads API:
  • GET recupera datos
  • POST crea nuevos datos, como campañas
  • PUT actualiza datos existentes, como line items
  • DELETE elimina datos.
Si bien las eliminaciones son permanentes, los datos eliminados aún pueden verse en la mayoría de los métodos basados en GET al incluir el parámetro explícito 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 fields especificados. Puede desasignar un valor opcional especificando el parámetro con una cadena vacía. Por ejemplo, este grupo de parámetros desasignaría cualquier end_time ya especificado: &end_time=&paused=false. Consulte Error Codes & Responses para 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 query 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 Resource Path de cada recurso. Por ejemplo, si la cuenta en la que estuviera trabajando se identificara como "abc1" y usted estuviera recuperando las campañas asociadas con una cuenta, accedería a esa lista usando 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), ha acotado la solicitud a los objetos asociados únicamente con esa cuenta.

​
Uso de Access Tokens

La X Ads API utiliza solicitudes HTTPS firmadas para validar la identidad de una aplicación y para obtener los permisos concedidos al usuario final en cuyo nombre la aplicación realiza la solicitud a la API, representados por el access token del usuario. Todas las llamadas HTTP a la Ads API deben incluir un encabezado de solicitud Authorization (mediante OAuth 1.0a) sobre el protocolo HTTPS. Deberá añadir compatibilidad en su aplicación para generar encabezados de solicitud Authorization de OAuth 1.0a a fin de integrarse con la X Ads API. No obstante, debido a la complejidad de generar solicitudes firmadas, recomendamos encarecidamente que los partners utilicen una biblioteca existente que ya sea compatible con la X API o implemente el manejo de solicitudes de OAuth 1.0a; aquí encontrará una lista de bibliotecas OAuth recomendadas y ejemplos de código de autenticación. Tenga en cuenta que podemos ayudar a los partners que encuentren errores de autenticación al utilizar una biblioteca reconocida, 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 de OAuth 1.0a y de HTTPS. Las API Key se pueden obtener a través de la App management console. También se deben usar access tokens para representar al “usuario actual”. El usuario actual es una cuenta de X con capacidades publicitarias. Se recomienda encarecidamente que los partners usen una biblioteca de OAuth en lugar de implementar la suya propia. Podemos ayudar con la depuración cuando se utiliza una biblioteca reconocida, 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 correctamente en las URL y en los cuerpos de las solicitudes POST antes de preparar las cadenas base de firma de OAuth. En particular, la Advertising API utiliza el carácter “:” al especificar la hora y “,” al proporcionar una colección de opciones. Ambos caracteres forman parte de este conjunto reservado:
SímboloCodificación URL
!%21
#%23
$%24
&%26
’%27
(%28
)%29
*%2A
+%2B
,%2C
/%2F
:%3A
;%3B
=%3D
?%3F
@%40
[%5B
]%5D

​
Realiza 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 de explorar la X Ads API antes de añadir autenticación a tu aplicación. Después de instalar y autorizar Twurl, puedes generar access tokens rápidamente y realizar solicitudes autenticadas a la X Ads API. 
twurl -H "ads-api.x.com" "/5/accounts/"
Tómate un tiempo para 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 las herramientas de línea de comandos, también ofrecemos 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 en la industria actualmente. Es un cliente HTTP con una excelente interfaz de usuario que permite simplificar solicitudes de API complejas y aumentar la productividad. Para instalar Postman y empezar a usar la colección de Postman de la X Ads API, consulta nuestra guía de configuración.

​
Ampliación de tu aplicación para realizar solicitudes autenticadas

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

​
Implementación personalizada

Hay algunos escenarios que requieren implementar la autenticación OAuth 1.0a sin el uso de una biblioteca de código abierto. Autorizar una solicitud ofrece instrucciones detalladas para implementar la compatibilidad necesaria para crear el encabezado Authorization. Recomendamos encarecidamente usar una biblioteca mantenida por la comunidad. Esquema general:
  1. Reúne 7 pares clave/valor para el encabezado, que comiencen con oauth_
  2. Genera una firma HMAC-SHA1 de OAuth 1.0a utilizando esos pares clave/valor
  3. Crea el encabezado Authorization con los valores anteriores
⌘I