Realizar solicitudes autenticadas

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 visió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ás:

• una cuenta de desarrollador aprobada
• una App que haya sido aprobada para el acceso a la Ads API
• clave y secreto de API obtenidos a través de la interfaz de administración del App y
• tokens de acceso para un usuario con acceso a una cuenta de X Ads

​

Uso de la API

Se accede a la Advertising API en https://ads-api.x.com. La API REST estándar y la Advertising API pueden usarse juntas con la misma App de cliente. La Advertising API exige HTTPS; por lo tanto, los intentos de acceder a un endpoint mediante HTTP generarán 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 típicos

Hay cuatro verbos HTTP usados en la 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, aún es posible ver los datos eliminados desde la mayoría de los métodos basados en GET al incluir explícitamente el parámetro with_deleted=true al solicitar el recurso. De lo contrario, los registros eliminados devolverán un HTTP 404.

Una solicitud correcta 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 restablecer (un-set) 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.

Consulte Códigos y respuestas de error 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 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 Resource Path de cada recurso. Por ejemplo, si la cuenta en la que está trabajando estuviera identificada como "abc1" y estuviera obteniendo las campañas asociadas a 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), estará delimitando la solicitud a objetos asociados únicamente a esa cuenta.

​

Uso de tokens de acceso

La X Ads API utiliza solicitudes HTTPS firmadas para validar la identidad de una App y obtener los permisos otorgados al usuario final en cuyo nombre la App realiza solicitudes 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 (con OAuth 1.0a) sobre el protocolo HTTPS.

Deberá incorporar compatibilidad para generar encabezados de solicitud Authorization de OAuth 1.0a en su App para integrarse 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 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 socios que encuentren errores de Autenticación al usar una biblioteca conocida, pero no podemos ofrecer soporte para implementaciones personalizadas de OAuth.

​

HTTP y OAuth

Al igual que X REST API v1.1, la Advertising API requiere el uso de OAuth 1.0A y HTTPS. Las claves de API pueden obtenerse a través de la consola de administración de App. También se deben usar tokens de acceso para representar al “usuario actual”. El usuario actual es una cuenta de X con funciones publicitarias.

Se recomienda encarecidamente que los partners usen una biblioteca de OAuth en lugar de desarrollar la suya propia. Podemos ayudar con la depuración cuando se utiliza una biblioteca conocida, pero no si implementa su propia versión de OAuth. Consulte las bibliotecas disponibles.

La API es estricta con HTTP/1.1 y OAuth. Asegúrese de codificar los caracteres reservados adecuadamente 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 los caracteres “:” al especificar la hora y “,” al proporcionar un conjunto de opciones. Ambos caracteres forman parte de este conjunto reservado:

Símbolo	Codificado en 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 explorar la Ads API antes de añadir Autenticación a tu App.

Después de instalar y autorizar Twurl, puedes generar rápidamente tokens de acceso y realizar solicitudes autenticadas a la Ads API.

twurl -H "ads-api.x.com" "/5/accounts/"

Dedica un 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 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 del sector en la actualidad. Es un cliente HTTP con una excelente interfaz de usuario que facilita la realización de solicitudes de API complejas y aumenta 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.

​

Ampliar tu aplicación para realizar solicitudes autenticadas

Después de familiarizarte con el uso de Twurl para hacer solicitudes a la 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 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 cuentan con bibliotecas de código abierto que permiten crear este encabezado de autorización para realizar solicitudes a la API de X.

Aquí tienes algunos ejemplos en C#, PHP, Ruby y Python: ejemplos de código.

​

Implementación personalizada

Hay escenarios que requieren implementar la Autenticación OAuth 1.0a sin usar una biblioteca de código abierto. Autorizar una solicitud ofrece instrucciones detalladas para implementar la creación del encabezado Authorization. Recomendamos encarecidamente utilizar una biblioteca mantenida por la comunidad.

Esquema general:

1. Recopilar 7 pares clave/valor para el encabezado, empezando por oauth_
2. Generar una firma HMAC-SHA1 de OAuth 1.0a con esos pares clave/valor
3. Crear el encabezado Authorization usando los valores anteriores