Guia de integração

Esta página contém informações sobre várias ferramentas e conceitos essenciais que você deve conhecer ao integrar os endpoints de consulta de users ao seu sistema. Dividimos a página em algumas seções:

• Ferramentas úteis
• Conceitos essenciais
• Autenticação
• Portal do desenvolvedor, Projetos e Apps
• Limites de requisições
• fields e expansions
• Casos extremos

​

Ferramentas úteis

Antes de abordarmos alguns conceitos essenciais que ajudarão você a integrar este endpoint, recomendamos que você se familiarize com:

​

Postman

O Postman é uma excelente ferramenta para testar um endpoint. Cada requisição no Postman inclui todos os parâmetros de caminho e de corpo para ajudar você a entender rapidamente o que está disponível. Para saber mais sobre nossas coleções do Postman, visite a página “Using Postman”. 

​

Exemplos de código

Quer configurar este endpoint com código na sua linguagem de programação preferida? Temos vários exemplos de código disponíveis que você pode usar como ponto de partida na nossa página no GitHub.

​

Bibliotecas de terceiros

Aproveite uma das bibliotecas de terceiros da nossa comunidade para começar. Você pode encontrar uma biblioteca compatível com os endpoints v2 procurando pela tag de versão correspondente.

​

Conceitos-chave

​

Autenticação

Todos os endpoints da X API v2 exigem que as solicitações sejam autenticadas com um conjunto de credenciais, também conhecidas como chaves e tokens. Você pode usar OAuth 1.0a User Context, App only ou OAuth 2.0 Authorization Code com PKCE para autenticar solicitações a esses endpoints.

OAuth 1.0a User Context exige que você utilize suas API Keys, Access Tokens de usuário e alguns outros parâmetros para criar um cabeçalho de autorização, que você então enviará com sua solicitação. Os Access Tokens devem estar associados ao usuário em cujo nome você está fazendo a solicitação. Se você deseja gerar um conjunto de Access Tokens para outro usuário, ele deve autorizar sua App usando o fluxo OAuth de 3 etapas.

Observe que o OAuth 1.0a pode ser difícil de usar. Se você não estiver familiarizado com esse método de autenticação, recomendamos usar uma biblioteca, usar uma ferramenta como o Postman ou usar OAuth 2.0 para autenticar suas solicitações. Se você deseja solicitar um Post ou metrics privadas desses endpoints, será necessário usar OAuth 1.0a User Context ou OAuth 2.0 Authorization Code com PKCE, o que garantirá que você tenha as permissões adequadas do usuário proprietário desse conteúdo.

App only requer apenas que você envie um App only Access Token com sua solicitação. Você pode gerar um App only Access Token diretamente em uma App de desenvolvedor ou gerar um usando o endpoint POST oauth2/token.

OAuth 2.0 Authorization Code com PKCE permite maior controle sobre o escopo de uma aplicação e fluxos de autorização em vários dispositivos. O OAuth 2.0 permite escolher escopos específicos e granulares que concedem permissões específicas em nome de um usuário.

Para habilitar o OAuth 2.0 na sua App, você deve ativá-lo nas configurações de autenticação da sua App, encontradas na seção de configurações da App no portal do desenvolvedor.

Observação

Se você estiver solicitando os seguintes fields, é necessário OAuth 1.0a User Context ou OAuth 2.0 Authorization Code:

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics

​

Portal do desenvolvedor, Projetos e Apps de desenvolvedor

Para obter um conjunto de credenciais de autenticação que funcione com os endpoints da X API v2, você deve se inscrever em uma conta de desenvolvedor, configurar um Projeto nessa conta e criar um App de desenvolvedor dentro desse Projeto. Em seguida, você poderá encontrar suas chaves e tokens no seu App de desenvolvedor.   

​

Limites de requisições

Todos os dias, muitos milhares de desenvolvedores fazem requisições à X API. Para ajudar a gerenciar o grande volume dessas requisições, limites de taxa são aplicados a cada endpoint, restringindo o número de requisições que você pode fazer em nome da sua App ou de um usuário autenticado. 

Os endpoints de consulta de usuários têm limites de requisições tanto no nível da App quanto no nível do usuário. No entanto, o endpoint de consulta do usuário autenticado tem limite de requisições apenas no nível do usuário.

O limite de requisições no nível da App significa que você, desenvolvedor, só pode fazer um certo número de requisições a esse endpoint em um determinado período, a partir de qualquer App (identificada pelas chaves e tokens que você está usando). O limite de requisições no nível do usuário significa que o usuário autenticado em nome de quem você está fazendo a requisição só pode realizar um certo número de requisições em qualquer App de desenvolvedor.

A tabela abaixo mostra os limites de requisições para cada endpoint.

Endpoint	método HTTP	Limite de taxa / Nível
/2/users	GET	900 requests por 15 minutos / App e Usuário
/2/users/:id	GET	900 requests por 15 minutos / App e Usuário
/2/users/by	GET	900 requests por 15 minutos / App e Usuário
/2/users/by/username/:username	GET	900 requests por 15 minutos / App e Usuário
/2/users/me	GET	75 requests por 15 minutos / Usuário

​

Campos e expansions

A X API v2 permite que os usuários selecionem exatamente quais dados desejam retornar da API usando um conjunto de ferramentas chamado fields e expansions. O parâmetro expansion permite incluir (expandir) objetos referenciados no payload. Por exemplo, este endpoint permite usar a expansion pinned_tweet_id.

O parâmetro fields permite selecionar exatamente quais fields dentro dos diferentes objetos de dados você deseja receber. Esses endpoints retornam principalmente objetos de usuário. Por padrão, o objeto de usuário retorna os campos id, name e username. Para receber campos adicionais, como user.created_at ou user.location, você precisará solicitá-los especificamente usando um parâmetro fields. Alguns campos importantes que você pode considerar na sua integração são os dados de enquete de Post, metrics, annotations e os campos de ID de conversa.

Adicionamos um guia sobre como usar fields e expansions em nosso dicionário de dados da X API v2.

​

Casos especiais

• O texto do Post é truncado em Retweets. A solução temporária é expandir o Post referenciado e obter o texto completo a partir da expansão. Este é um bug que corrigiremos no futuro.