Fazendo solicitações autenticadas

Para acessar os endpoints da X Ads API, seu App deve enviar solicitações web autenticadas com segurança via TLS para https://ads-api.x.com.

As seções a seguir trazem uma visão geral sobre como fazer solicitações autenticadas à API, configurar o Twurl para interagir com a API e ampliar seu App para dar suporte a OAuth 1.0a e fazer solicitações à sua conta de Ads.

​

Requisitos

Antes de fazer solicitações autenticadas à X Ads API, você precisará de:

• uma conta de desenvolvedor aprovada
• uma App que tenha sido aprovada para acesso à X Ads API
• API Key e secret obtidos por meio da UI de gerenciamento da App e
• access tokens para um usuário com acesso a uma conta do X Ads

​

Usando a API

A Ads API é acessada em https://ads-api.x.com. A API REST padrão e a Ads API podem ser usadas juntas com o mesmo App cliente. A Ads API exige HTTPS; portanto, tentativas de acessar um endpoint via HTTP resultarão em uma mensagem de erro.

A X Ads API retorna JSON. Todos os identificadores são strings e todas as strings estão em UTF-8. A Ads API é versionada e a versão é especificada como o primeiro elemento do caminho de qualquer URL de recurso.

https://ads-api.x.com/<version>/accounts

​

Verbos HTTP e códigos de resposta típicos

Há quatro verbos HTTP usados na X Ads API:

• GET recupera dados
• POST cria novos dados, como campanhas
• PUT atualiza dados existentes, como itens de linha
• DELETE remove dados.

Embora as exclusões sejam permanentes, os dados excluídos ainda podem ser exibidos na maioria dos métodos baseados em GET ao incluir explicitamente o parâmetro with_deleted=true ao solicitar o recurso. Caso contrário, registros excluídos retornarão um HTTP 404.

Uma solicitação bem-sucedida retornará uma resposta HTTP da série 200, juntamente com o JSON que representa o objeto ao criar, excluir ou atualizar um recurso.

Ao atualizar dados com HTTP PUT, apenas os fields especificados serão atualizados. Você pode desfazer um valor opcional especificando o parâmetro com uma string vazia. Por exemplo, este conjunto de parâmetros removeria qualquer end_time já especificado: &end_time=&paused=false.

Consulte Error Codes & Responses para mais detalhes sobre respostas de erro.

​

Parâmetros in-line

A maioria das URLs de recursos apresenta um ou mais parâmetros in-line. Muitas URLs também aceitam parâmetros declarados explicitamente na query string ou, para solicitações POST ou PUT, no corpo.

Parâmetros in-line são indicados com dois-pontos (”:”) antepostos na seção Resource Path de cada recurso. Por exemplo, se a conta em que você estivesse trabalhando fosse identificada como "abc1" e você estivesse recuperando as campanhas associadas a uma conta, acessaria essa lista usando a URL https://ads-api.x.com/6/accounts/abc1/campaigns. Ao especificar o parâmetro in-line account_id descrito na URL do recurso (https://ads-api.x.com/6/accounts/:account_id/campaigns), você delimitou o escopo da solicitação a objetos associados somente àquela conta.

​

Usando Access Tokens

A X Ads API usa solicitações HTTPS assinadas para validar a identidade de uma App e também obter as permissões concedidas ao usuário final em nome de quem a App está fazendo a solicitação de API, representadas pelo access token do usuário. Todas as chamadas HTTP para a X Ads API devem incluir um cabeçalho de solicitação Authorization (usando OAuth 1.0a) sobre o protocolo HTTPS.

Você precisará adicionar suporte para gerar cabeçalhos de solicitação Authorization do OAuth 1.0a na sua App para integrar com a X Ads API. No entanto, devido à complexidade de gerar solicitações assinadas, recomendamos fortemente que os parceiros usem uma biblioteca existente que já ofereça suporte à X API ou implemente o tratamento de solicitações OAuth 1.0a — aqui está uma lista de bibliotecas OAuth recomendadas e exemplos de código de autenticação.

Observe que podemos ajudar parceiros que encontrem erros de autenticação ao usar uma biblioteca conhecida, mas não podemos oferecer suporte a implementações personalizadas de OAuth.

​

HTTP e OAuth

Assim como a X REST API v1.1, a Advertising API requer o uso de OAuth 1.0a e de HTTPS. As API Keys podem ser obtidas por meio do app management console. Access Tokens também devem ser usados para representar o “usuário atual”. O usuário atual é uma conta da X com recursos de publicidade.

Recomendamos fortemente que os parceiros usem uma biblioteca de OAuth, em vez de escrever a sua própria. Podemos oferecer suporte à depuração ao usar uma biblioteca conhecida, mas não podemos fazê-lo se você implementar sua própria versão de OAuth. Veja as libraries que você pode usar.

A API é estrita quanto ao HTTP 1.1 e ao OAuth. Certifique-se de codificar os caracteres reservados adequadamente em URLs e nos corpos de POST antes de preparar as base strings da assinatura OAuth. A Advertising API, em particular, usa o caractere “:” ao especificar horário e “,” ao fornecer uma coleção de opções. Ambos os caracteres fazem parte deste conjunto reservado:

Symbol	URL Encoded
!	%21
#	%23
$	%24
&	%26
’	%27
(	%28
)	%29
*	%2A
+	%2B
,	%2C
/	%2F
:	%3A
;	%3B
=	%3D
?	%3F
@	%40
[	%5B
]	%5D

​

Fazendo sua primeira chamada à API com Twurl

A X ajuda a manter uma ferramenta de linha de comando, o Twurl, que dá suporte a cabeçalhos de autorização OAuth 1.0a como alternativa ao cURL. O Twurl oferece uma maneira simples de fazer chamadas autenticadas à API e explorar a X Ads API antes de adicionar autenticação ao seu aplicativo.

Depois de instalar e autorizar o Twurl, você pode gerar access tokens rapidamente e fazer chamadas autenticadas à X Ads API.

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

Reserve um tempo para se familiarizar com o Twurl e a API seguindo este tutorial passo a passo para criar uma campanha pela API.

​

Testando com o Postman

Para quem não está familiarizado com ferramentas de linha de comando, também disponibilizamos uma coleção do Postman para os endpoints da X Ads API.

O Postman é uma das ferramentas de desenvolvimento de API mais populares do mercado atualmente. É um cliente HTTP com uma excelente interface que facilita a criação de solicitações de API complexas e aumenta a produtividade.

Para instalar o Postman e começar a usar a coleção do Postman da X Ads API, consulte nosso guia de configuração.

​

Ampliando seu App para fazer solicitações autenticadas

Depois de se familiarizar com as solicitações à X Ads API usando o Twurl, é hora de adicionar suporte para gerar cabeçalhos de autenticação OAuth 1.0a no seu App.

Os cabeçalhos de autenticação OAuth 1.0a incluem informações que verificam a identidade do App e do usuário e também evitam a adulteração da solicitação. Seu App precisará criar um novo cabeçalho Authorization para cada solicitação à API. Muitas linguagens têm bibliotecas open source que dão suporte à criação desse cabeçalho de autorização para fazer solicitações à API do X.

Aqui estão alguns exemplos em C#, PHP, Ruby e Python — amostras de código.

​

Implementação personalizada

Há cenários em que é necessário implementar a autenticação OAuth 1.0a sem o suporte de uma biblioteca open source. Autorizando uma solicitação fornece instruções detalhadas para implementar a criação do cabeçalho Authorization. Recomendamos fortemente o uso de uma biblioteca mantida pela comunidade.

Visão geral:

1. Coletar 7 pares chave-valor para o cabeçalho — iniciando com oauth_
2. Gerar uma assinatura OAuth 1.0a HMAC-SHA1 usando esses pares chave-valor
3. Montar o cabeçalho Authorization usando os valores acima