Guia de integração

Este guia cobre os principais conceitos necessários para integrar os endpoints de consulta de usuário à sua aplicação.

Autenticação

Todos os endpoints da X API v2 exigem autenticação. Escolha o método que melhor se adequa ao seu caso de uso:

Método	Melhor para	Pode acessar métricas privadas?
OAuth 2.0 App-Only	Server-to-server, dados públicos	Não
OAuth 2.0 Authorization Code with PKCE	Apps voltados ao usuário	Sim (para dados do usuário autorizado)
OAuth 1.0a User Context	Integrações legadas	Sim (para dados do usuário autorizado)

Autenticação App-Only

Para dados públicos de usuários, use um Bearer Token:

cURL

curl "https://api.x.com/2/users/by/username/XDevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obter usuário por username
response = client.users.get_by_username("XDevelopers")
print(response.data)

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.users.getByUsername("XDevelopers");
console.log(response.data);

Autenticação User Context

Obrigatória para o endpoint de usuário autenticado (/2/users/me):

cURL

curl "https://api.x.com/2/users/me" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

# Usando user access token do OAuth 2.0
client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Obter perfil do usuário autenticado
response = client.users.get_me()
print(response.data)

import { Client } from "@xdevplatform/xdk";

// Usando user access token do OAuth 2.0
const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const response = await client.users.getMe();
console.log(response.data);

O endpoint /2/users/me só funciona com autenticação User Context. Tokens App-Only retornarão erro.

Fields e expansions

A X API v2 retorna dados mínimos por padrão. Use fields e expansions para solicitar exatamente o que você precisa.

Resposta padrão

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}

Fields disponíveis

user.fields

Field	Descrição
`created_at`	Timestamp de criação da conta
`description`	Bio do usuário
`entities`	URLs analisadas na bio
`location`	Localização definida pelo usuário
`pinned_tweet_id`	ID do Post fixado
`profile_image_url`	URL do avatar
`protected`	Se a conta é protegida
`public_metrics`	Contagens de seguidores/seguindo
`url`	URL do site
`verified`	Status de verificação
`withheld`	Informações de retenção

tweet.fields (requer expansion pinned_tweet_id)

Field	Descrição
`created_at`	Timestamp de criação do Post
`text`	Conteúdo do Post
`public_metrics`	Contagens de engajamento
`entities`	Hashtags, menções, URLs

Exemplo com fields

cURL

curl "https://api.x.com/2/users/by/username/XDevelopers?\
user.fields=created_at,description,public_metrics,verified&\
expansions=pinned_tweet_id&\
tweet.fields=created_at,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obter usuário com fields e expansions adicionais
response = client.users.get_by_username(
    "XDevelopers",
    user_fields=["created_at", "description", "public_metrics", "verified"],
    expansions=["pinned_tweet_id"],
    tweet_fields=["created_at", "public_metrics"]
)

print(response.data)
print(response.includes)  # Contém o pinned tweet expandido

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.users.getByUsername("XDevelopers", {
  userFields: ["created_at", "description", "public_metrics", "verified"],
  expansions: ["pinned_tweet_id"],
  tweetFields: ["created_at", "public_metrics"],
});

console.log(response.data);
console.log(response.includes); // Contém o pinned tweet expandido

Resposta com expansions

Exemplo de resposta

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "verified": true,
    "pinned_tweet_id": "1234567890",
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052
    }
  },
  "includes": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "Welcome to the X Developer Platform!",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

Guia de fields e expansions

Saiba mais sobre como personalizar as respostas

Consultas em lote

Consulte vários usuários em uma única requisição:

cURL (by IDs)

curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

curl "https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obter vários usuários por IDs
response = client.users.get_users(
    ids=["2244994945", "783214", "6253282"],
    user_fields=["username", "verified"]
)
for user in response.data:
    print(f"{user.username}: {user.verified}")

# Obter vários usuários por usernames
response = client.users.get_users_by_usernames(
    usernames=["XDevelopers", "X", "XAPI"],
    user_fields=["username", "verified"]
)
for user in response.data:
    print(f"{user.username}: {user.verified}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Obter vários usuários por IDs
const byIds = await client.users.getUsers({
  ids: ["2244994945", "783214", "6253282"],
  userFields: ["username", "verified"],
});
byIds.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

// Obter vários usuários por usernames
const byUsernames = await client.users.getUsersByUsernames({
  usernames: ["XDevelopers", "X", "XAPI"],
  userFields: ["username", "verified"],
});
byUsernames.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

Requisições em lote são limitadas a 100 usuários. Use várias requisições para conjuntos maiores.

Tratamento de erros

Erros comuns

Status	Erro	Solução
400	Requisição inválida	Verifique a formatação dos parâmetros
401	Não autorizado	Verifique as credenciais de autenticação
403	Proibido	Verifique as permissões do App
404	Não encontrado	Usuário não existe ou foi suspenso
429	Muitas requisições	Aguarde e tente novamente (veja rate limits)

Usuários suspensos ou excluídos

Se um usuário for suspenso ou excluído:

A consulta de um único usuário retorna 404
A consulta de múltiplos usuários omite o usuário dos resultados com um array errors

Exemplo de resposta

{
  "data": [
    { "id": "2244994945", "username": "XDevelopers" }
  ],
  "errors": [
    {
      "resource_id": "1234567890",
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with id: [1234567890]."
    }
  ]
}

Usuários protegidos

Para contas protegidas que você não segue:

Informações básicas (id, name, username) estão disponíveis
Conteúdo protegido (Post fixado) pode estar restrito
protected: true indica o status da conta

Melhores práticas

Requisições em lote

Use endpoints de múltiplos usuários para buscar até 100 usuários de uma vez, reduzindo chamadas à API.

Solicite apenas os fields necessários

Especifique apenas os fields de que precisa para minimizar o tamanho da resposta.

Faça cache dos dados de usuário

Armazene perfis de usuário em cache localmente para reduzir requisições repetidas.

Trate erros com elegância

Verifique erros parciais em respostas em lote.

Próximos passos

Referência da API

Documentação completa do endpoint

Dicionário de dados

Todos os objetos e fields disponíveis

Código de exemplo

Exemplos de código funcionais

Tratamento de erros

Trate erros com elegância

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Guia de integração

Autenticação

Autenticação App-Only

Autenticação User Context

Fields e expansions

Resposta padrão

Fields disponíveis

Exemplo com fields

Resposta com expansions

Guia de fields e expansions

Consultas em lote

Tratamento de erros

Erros comuns

Usuários suspensos ou excluídos

Usuários protegidos

Melhores práticas

Requisições em lote

Solicite apenas os fields necessários

Faça cache dos dados de usuário

Trate erros com elegância

Próximos passos

Referência da API

Dicionário de dados

Código de exemplo

Tratamento de erros

​Autenticação

​Autenticação App-Only

​Autenticação User Context

​Fields e expansions

​Resposta padrão

​Fields disponíveis

​Exemplo com fields

​Resposta com expansions

Guia de fields e expansions

​Consultas em lote

​Tratamento de erros

​Erros comuns

​Usuários suspensos ou excluídos

​Usuários protegidos

​Melhores práticas

Requisições em lote

Solicite apenas os fields necessários

Faça cache dos dados de usuário

Trate erros com elegância

​Próximos passos

Referência da API

Dicionário de dados

Código de exemplo

Tratamento de erros

Autenticação

Autenticação App-Only

Autenticação User Context

Fields e expansions

Resposta padrão

Fields disponíveis

Exemplo com fields

Resposta com expansions

Consultas em lote

Tratamento de erros

Erros comuns

Usuários suspensos ou excluídos

Usuários protegidos

Melhores práticas

Próximos passos