> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Guia de integração
> Este guia cobre os principais conceitos necessários para integrar os endpoints de consulta de usuário ao seu. Referência para o nível standard da X API v2 sobre lookup.
export const Button = ({href, children}) => {
return ;
};
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](/resources/fundamentals/authentication#oauth-2-0) | Server-to-server, dados públicos | Não |
| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Apps voltados ao usuário | Sim (para dados do usuário autorizado) |
| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | 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:
```bash cURL theme={null}
curl "https://api.x.com/2/users/by/username/XDevelopers" \
-H "Authorization: Bearer $BEARER_TOKEN"
```
```python Python SDK theme={null}
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)
```
```javascript JavaScript SDK theme={null}
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`):
```bash cURL theme={null}
curl "https://api.x.com/2/users/me" \
-H "Authorization: Bearer $USER_ACCESS_TOKEN"
```
```python Python SDK theme={null}
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)
```
```javascript JavaScript SDK theme={null}
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
```json theme={null}
{
"data": {
"id": "2244994945",
"name": "X Developers",
"username": "XDevelopers"
}
}
```
### Fields disponíveis
| 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 |
| 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
```bash cURL theme={null}
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"
```
```python title="Python SDK" lines wrap icon="python" theme={null}
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
```
```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
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
```json title="Exemplo de resposta" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
"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"
}
]
}
}
```
Saiba mais sobre como personalizar as respostas
***
## Consultas em lote
Consulte vários usuários em uma única requisição:
```bash cURL (by IDs) theme={null}
curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
user.fields=username,verified" \
-H "Authorization: Bearer $BEARER_TOKEN"
```
```bash cURL (by usernames) theme={null}
curl "https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&\
user.fields=username,verified" \
-H "Authorization: Bearer $BEARER_TOKEN"
```
```python title="Python SDK" lines wrap icon="python" theme={null}
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}")
```
```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
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`
```json title="Exemplo de resposta" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
"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
Use endpoints de múltiplos usuários para buscar até 100 usuários de uma vez, reduzindo chamadas à API.
Especifique apenas os fields de que precisa para minimizar o tamanho da resposta.
Armazene perfis de usuário em cache localmente para reduzir requisições repetidas.
Verifique erros parciais em respostas em lote.
***
## Próximos passos
Documentação completa do endpoint
Todos os objetos e fields disponíveis
Exemplos de código funcionais
Trate erros com elegância