Guia de integração

Este guia cobre os conceitos-chave que você precisa para integrar os endpoints de Post lookup à sua aplicação.

Autenticação

Todos os endpoints da X API v2 exigem autenticação. Escolha o método que 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 com PKCE	Apps voltados para o usuário	Sim (para Posts do usuário autorizado)
OAuth 1.0a User Context	Integrações legadas	Sim (para Posts do usuário autorizado)

Autenticação App-Only

Para dados públicos de Post, use um Bearer Token:

cURL

curl "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obter um único Post por ID
response = client.posts.get("1234567890")
print(response.data)

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

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

const response = await client.posts.get("1234567890");
console.log(response.data);

Autenticação User Context

Para acessar métricas privadas, autentique em nome do autor do Post:

Os seguintes fields exigem autenticação User Context:

tweet.fields.non_public_metrics
tweet.fields.promoted_metrics
tweet.fields.organic_metrics
media.fields.non_public_metrics
media.fields.promoted_metrics
media.fields.organic_metrics

Fields e expansions

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

Resposta padrão

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"]
  }
}

Fields disponíveis

tweet.fields

Field	Descrição
`created_at`	Timestamp de criação do Post
`author_id`	ID de usuário do autor
`public_metrics`	Contagens de like, retweet, reply, quote
`entities`	Hashtags, menções, URLs, cashtags
`attachments`	Media keys, IDs de poll
`conversation_id`	Identificador do thread
`context_annotations`	Classificações de tópico/entity
`in_reply_to_user_id`	Usuário sendo respondido
`lang`	Idioma detectado
`source`	Cliente de postagem
`possibly_sensitive`	Sinalizador de conteúdo sensível
`reply_settings`	Quem pode responder

user.fields (requer expansion author_id)

Field	Descrição
`username`	@handle
`name`	Nome de exibição
`profile_image_url`	URL do avatar
`verified`	Status de verificação
`description`	Bio
`public_metrics`	Contagens de seguidores/seguindo
`created_at`	Data de criação da conta

media.fields (requer expansion attachments.media_keys)

Field	Descrição
`url`	URL da mídia
`preview_image_url`	URL da miniatura
`type`	photo, video, animated_gif
`duration_ms`	Duração do vídeo
`height`, `width`	Dimensões
`alt_text`	Texto de acessibilidade

Exemplo com fields

cURL

curl "https://api.x.com/2/tweets/1234567890?\
tweet.fields=created_at,public_metrics,entities&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obter um Post com fields e expansions adicionais
response = client.posts.get(
    "1234567890",
    tweet_fields=["created_at", "public_metrics", "entities"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"]
)

print(response.data)
print(response.includes)  # Contém objetos user e media expandidos

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

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

const response = await client.posts.get("1234567890", {
  tweetFields: ["created_at", "public_metrics", "entities"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
});

console.log(response.data);
console.log(response.includes); // Contém objetos user e media expandidos

Edições de Post

Posts podem ser editados até 5 vezes dentro de 30 minutos após a criação.

Como funciona

Cada edição cria um novo Post ID
edit_history_tweet_ids contém todas as versões (mais antigas primeiro)
O endpoint sempre retorna a versão mais recente

Exemplo de resposta

{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited twice)",
    "edit_history_tweet_ids": [
      "1234567890",
      "1234567891",
      "1234567893"
    ]
  }
}

Posts recuperados após a janela de edição de 30 minutos representam a versão final. Para casos de uso em tempo real, esteja ciente de que Posts publicados recentemente ainda podem ser editados.

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	Post excluído ou inexistente
429	Muitas requisições	Aguarde e tente novamente (veja rate limits)

Posts excluídos ou protegidos

Se um Post foi excluído ou é de uma conta protegida que você não segue:

A consulta de um único Post retorna 404
A consulta de múltiplos Posts omite o Post dos resultados com um array errors

Exemplo de resposta

{
  "data": [
    { "id": "1234567890", "text": "Available post" }
  ],
  "errors": [
    {
      "resource_id": "1234567891",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [1234567891]."
    }
  ]
}

Melhores práticas

Requisições em lote

Use o endpoint de múltiplos Posts para buscar até 100 Posts de uma vez, reduzindo as chamadas de API.

Solicite apenas os fields necessários

Especifique apenas os fields que você precisa para minimizar o tamanho da resposta e o tempo de processamento.

Faça cache das respostas

Armazene os dados dos Posts localmente para reduzir requisições repetidas ao mesmo conteúdo.

Trate edições

Para apps em tempo real, considere buscar Posts novamente após a janela de edição de 30 minutos.

Próximos passos

Referência da API

Documentação completa do endpoint

Data dictionary

Todos os objetos e fields disponíveis

Código de exemplo

Exemplos de código funcionais

Tratamento de erros

Trate erros de forma elegante

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

Edições de Post

Como funciona

Exemplo de resposta

Tratamento de erros

Erros comuns

Posts excluídos ou protegidos

Melhores práticas

Requisições em lote

Solicite apenas os fields necessários

Faça cache das respostas

Trate edições

Próximos passos

Referência da API

Data dictionary

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

​Edições de Post

​Como funciona

​Exemplo de resposta

​Tratamento de erros

​Erros comuns

​Posts excluídos ou protegidos

​Melhores práticas

Requisições em lote

Solicite apenas os fields necessários

Faça cache das respostas

Trate edições

​Próximos passos

Referência da API

Data dictionary

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

Edições de Post

Como funciona

Exemplo de resposta

Tratamento de erros

Erros comuns

Posts excluídos ou protegidos

Melhores práticas

Próximos passos