Migrar da API oficial do X v2 para a Sorsa API v3
Esta referência cobre autenticação, mapeamento de endpoints, estruturas de resposta, paginação, métodos HTTP, sintaxe de busca, erros e exemplos em cURL, Python e JavaScript. A Sorsa é somente de leitura. Se sua integração publica, envia mensagens, curte ou segue contas, mantenha a API oficial para essas operações e migre apenas as leituras. As 100 requisições gratuitas, sem cartão, permitem validar os endpoints antes de transferir tráfego de produção.Veja comparações de custo e exemplos passo a passo no guia completo de migração.
Resumo das mudanças
Autenticação
A API oficial usa OAuth 2.0 Bearer para chamadas da aplicação e OAuth 1.0a User Context para chamadas no contexto do usuário.ApiKey. Gere chaves no painel.
Mapeamento de endpoints
Usuários
GET /info-batchaceita até 100 nomes ou IDs. Repita o parâmetro:?usernames=a&usernames=b.GET /followerseGET /followsretornam até 200 perfis completos por página, com bio, contadores e verificação.
Publicações
tweet_linkaceita URL, comohttps://x.com/user/status/123, ou ID string, como"123".POST /tweet-info-bulkretorna até 100 itens por chamada, reduzindo o total em até 100 vezes em comparação com chamadas individuais.POST /user-tweetsnão tem teto de 3.200. Percorranext_cursoraté ficar ausente. Veja dados históricos.
Busca
- A Sorsa usa a sintaxe da busca avançada da interface web do X. Termos básicos podem ser reaproveitados, mas revise operadores específicos da API v2. Veja operadores.
POST /mentionsacrescenta filtros no corpo:min_likes,min_replies,min_retweets,since_dateeuntil_date.
Listas
Comunidades
A API oficial não expõe os endpoints de comunidades abaixo.
Consulte os formatos e a nota de disponibilidade em listas e comunidades. Confirme com o suporte antes de migrar esse fluxo.
Verificação
As verificações respondem a perguntas sobre ações individuais. Sem um equivalente direto na API oficial, seria necessário consultar listas e procurar o usuário no cliente. Algumas verificações podem exigir paginação; veja o guia específico.
Veja verificação de campanhas.
Análises exclusivas da Sorsa
Esses endpoints cobrem o subconjunto cripto de contas acompanhadas: influenciadores, projetos e fundos. Veja Sorsa Score.
Utilitários
Veja conversão de IDs.
Mudanças na resposta
A v2 oficial usadata, includes e meta. A Sorsa retorna objetos planos, com autor incluído na publicação.
Perfil
API oficial v2, com seleção de campos:Publicação
API oficial v2, comexpansions=author_id:
Mapeamento de campos
Usuários
Publicações
Paginação
A API oficial enviapagination_token e retorna meta.next_token. A Sorsa usa next_cursor nos dois sentidos.
GET: parâmetro de consulta.
Diferenças de métodos HTTP
Conteúdo de publicações, busca e comunidades usam POST com JSON, incluindo
/user-tweets. Usuários, listas e utilitários usam GET com parâmetros de consulta ou caminho. A exceção entre as verificações é /check-comment, que usa GET mesmo recebendo um link de publicação. Consulte a referência em caso de dúvida.
Exemplos de migração de código
Consultar um perfil
Antes: API oficialBuscar publicações
AntesPercorrer seguidores
AntesSintaxe de busca
Revise os operadores da API v2 antes de reaproveitá-los na sintaxe web do X. Termos, frases,from: e to: podem ser mantidos quando apropriado. Use, por exemplo, -filter:nativeretweets para excluir repostagens nativas.
Veja a referência de operadores.
/mentions também aceita min_likes, min_replies, min_retweets, since_date e until_date; veja menções.
Tratamento de erros
A API oficial retorna um arrayerrors:
400, 401, 403, 404, 429 e 500. Veja códigos de erro.
Ao receber 429, aguarde e tente novamente. O limite de 20 req/s é compartilhado entre endpoints, sem janelas individuais. Veja limites.
Função de novas tentativas compatível com as duas APIs:
Checklist de migração
- Troque
Authorization: Bearer ...porApiKey: .... - Remova a lógica de assinatura OAuth 1.0a do caminho migrado.
- Troque
https://api.x.com/2porhttps://api.sorsa.io/v3. - Mapeie os caminhos pelas tabelas.
- Troque GET por POST nos endpoints de publicações, busca, comentários, citações e repostagens.
- Remova
tweet.fields,user.fields,media.fieldseexpansions. - Atualize os parsers, removendo a estrutura
data/includes/meta. - Renomeie campos, como
nameparadisplay_nameetextparafull_text. - Acesse métricas sem
public_metrics. - Troque
pagination_token/next_tokenpornext_cursor. - Trate o formato
{ "message": "..." }. - Ajuste o limitador para 20 req/s, sem janelas por endpoint.
- Teste operações críticas no API Playground.
- Monitore a cota com
GET /key-usage-info. - Mantenha a API oficial para escrita, se necessário.