Skip to main content
Acessar os endpoints da X Ads API requer que sua aplicação envie requisições web autenticadas com segurança usando TLS para https://ads-api.x.com. As seções a seguir fornecerão uma visão geral de como fazer requisições autenticadas à API, configurar o Twurl para interagir com a API e estender sua aplicação para suportar OAuth 1.0a e fazer requisições à sua conta Ads.

​
Requisitos

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

​
Usando a API

A Advertising API é acessada em https://ads-api.x.com. A REST API padrão e a Advertising API podem ser usadas juntas com o mesmo app cliente. A Advertising API impõe HTTPS, portanto, tentativas de acessar um endpoint com HTTP resultarão em uma mensagem de erro. A Ads API retorna JSON. Todos os identificadores são strings e todas as strings são UTF-8. A Advertising API é versionada e a versão é especificada como o primeiro elemento do path de qualquer URL de recurso. https://ads-api.x.com/<version>/accounts

​
Verbos HTTP e códigos de resposta típicos

Existem quatro verbos HTTP usados na Ads API:
  • GET recupera dados
  • POST cria novos dados, como campanhas
  • PUT atualiza dados existentes, como line items
  • DELETE remove dados.
Enquanto as exclusões são permanentes, os dados excluídos ainda podem ser visualizados a partir da maioria dos métodos baseados em GET, incluindo um parâmetro explícito with_deleted=true ao solicitar o recurso. Caso contrário, registros excluídos retornarão um HTTP 404. Uma requisição bem-sucedida retornará uma resposta HTTP na faixa 200 junto com a resposta JSON representando o objeto ao criar, excluir ou atualizar um recurso. Ao atualizar dados com HTTP PUT, apenas os campos especificados serão atualizados. Você pode remover um valor opcional especificando o parâmetro com uma string vazia. Como exemplo, este grupo de parâmetros removeria qualquer end_time já especificado: &end_time=&paused=false. Consulte Códigos de Erro e Respostas para mais detalhes sobre respostas de erro.

​
Parâmetros in-line

A maioria das URLs de recursos possui um ou mais parâmetros in-line. Muitas URLs também aceitam parâmetros declarados explicitamente na query string ou, para requisições POST ou PUT, no body. Parâmetros in-line são indicados por dois pontos ”:” prefixados na seção Resource Path de cada recurso. Por exemplo, se a conta em que você estava trabalhando fosse identificada como "abc1" e você estivesse recuperando as campanhas associadas a uma conta, você 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ê restringiu a requisição a objetos associados apenas a essa conta.

​
Usando access tokens

A X Ads API usa requisições HTTPS assinadas para validar a identidade de uma aplicação e também obter as permissões concedidas ao usuário final em nome do qual a aplicação está fazendo a requisição à API, representado pelo access token do usuário. Todas as chamadas HTTP à Ads API devem incluir um header de Authorization (usando OAuth 1.0a) sobre o protocolo HTTPS. Você precisará adicionar suporte para gerar headers de Authorization OAuth 1.0a à sua aplicação para se integrar à X Ads API. No entanto, devido à complexidade de gerar requisições assinadas, recomendamos fortemente que os parceiros usem uma biblioteca existente que suporte a X API ou implemente o tratamento de requisiçõ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 encontrarem erros de autenticação ao usar uma biblioteca conhecida, mas não podemos oferecer suporte a implementações OAuth personalizadas.

​
HTTP e OAuth

Como a X REST API v1.1, a Advertising API requer o uso de OAuth 1.0A e HTTPS. As API keys podem ser obtidas através do console de gerenciamento de apps. Access tokens também devem ser usados para representar o “current user”. O current user é uma conta X com capacidades de publicidade. Recomendamos fortemente que os parceiros usem uma biblioteca OAuth em vez de escrever a própria. Podemos oferecer suporte à depuração ao usar uma biblioteca conhecida, mas não se você criar sua própria implementação OAuth. Consulte as bibliotecas que você pode usar. A API é rigorosa com HTTP 1.1 e OAuth. Certifique-se de estar codificando caracteres reservados apropriadamente dentro de URLs e bodies POST antes de preparar strings de base de assinatura OAuth. A Advertising API em particular usa caracteres ”:” ao especificar tempo e caracteres ”,” ao fornecer uma coleção de opções. Ambos os caracteres estão entre este conjunto reservado:

​
Fazendo sua primeira requisição à API com Twurl

O X ajuda a manter uma ferramenta de linha de comando, Twurl, que suporta headers de autorização OAuth 1.0a como alternativa ao cURL. O Twurl fornece uma forma simples de fazer requisições autenticadas à API e explorar a Ads API antes de adicionar autenticação à sua aplicação. Depois de instalar e autorizar o Twurl, você pode gerar rapidamente access tokens e fazer requisições autenticadas à Ads API.
Reserve um tempo para se familiarizar com o Twurl e a API seguindo este tutorial passo a passo para criar uma campanha através da API.

​
Testando com Postman

Para aqueles que não estão familiarizados com uma ferramenta de linha de comando, também fornecemos uma coleção Postman para os endpoints da X Ads API. Postman é uma das ferramentas de desenvolvimento de API mais populares que existem atualmente na indústria. É um cliente HTTP com uma ótima interface de usuário que facilita fazer uma requisição de API complexa e aumenta a produtividade. Para instalar o Postman e começar a usar a coleção Postman da Ads API, consulte nosso guia de configuração.

​
Estendendo sua aplicação para fazer requisições autenticadas

Depois de se familiarizar com fazer requisições à Ads API usando o Twurl, é hora de adicionar suporte para criar headers de autenticação OAuth 1.0a à sua aplicação. Os headers de autenticação OAuth 1.0a incluem informações que verificam tanto a identidade da aplicação quanto do usuário e também previnem adulteração da requisição. Sua aplicação precisará criar um novo header de Authorization para cada requisição à API. Muitas linguagens têm bibliotecas open source que suportam a criação desse header de autorização para fazer requisições à API do X. Aqui estão alguns exemplos usando C#, PHP, Ruby e Python - exemplos de código.

​
Implementação personalizada

Existem alguns cenários que exigem implementar autenticação OAuth 1.0a sem o suporte de uma biblioteca open-source. Autorizando uma requisição fornece instruções detalhadas para implementar suporte para criar o header de Authorization. Recomendamos fortemente usar uma biblioteca suportada pela comunidade. Esboço geral:
  1. Colete 7 pares chave/valor para o header - começando com oauth_
  2. Gere uma assinatura OAuth 1.0a HMAC-SHA1 usando esses pares chave/valor
  3. Construa o header de Authorization usando os valores acima