Skip to main content

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.
Na Sorsa, envie a chave em ApiKey. Gere chaves no painel.
Veja autenticação.

Mapeamento de endpoints

Usuários

  • GET /info-batch aceita até 100 nomes ou IDs. Repita o parâmetro: ?usernames=a&usernames=b.
  • GET /followers e GET /follows retornam até 200 perfis completos por página, com bio, contadores e verificação.

Publicações

  • tweet_link aceita URL, como https://x.com/user/status/123, ou ID string, como "123".
  • POST /tweet-info-bulk retorna até 100 itens por chamada, reduzindo o total em até 100 vezes em comparação com chamadas individuais.
  • POST /user-tweets não tem teto de 3.200. Percorra next_cursor até 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 /mentions acrescenta filtros no corpo: min_likes, min_replies, min_retweets, since_date e until_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 usa data, includes e meta. A Sorsa retorna objetos planos, com autor incluído na publicação.

Perfil

API oficial v2, com seleção de campos:
Sorsa v3:

Publicação

API oficial v2, com expansions=author_id:
Sorsa v3:

Mapeamento de campos

Usuários

Publicações

Paginação

A API oficial envia pagination_token e retorna meta.next_token. A Sorsa usa next_cursor nos dois sentidos. GET: parâmetro de consulta.
POST: corpo JSON.
O cursor é retornado no nível superior:
Quando estiver ausente ou nulo, as páginas terminaram. Veja paginação.

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 oficial
Depois: Sorsa

Buscar publicações

Antes
Depois

Percorrer seguidores

Antes
Depois
Cada página da Sorsa retorna até 200 perfis completos. Na API oficial, dados mínimos podem exigir consultas adicionais para completar os perfis.

Sintaxe 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 array errors:
A Sorsa usa uma estrutura simples:
Os códigos são 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 ... por ApiKey: ....
  • Remova a lógica de assinatura OAuth 1.0a do caminho migrado.
  • Troque https://api.x.com/2 por https://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.fields e expansions.
  • Atualize os parsers, removendo a estrutura data/includes/meta.
  • Renomeie campos, como name para display_name e text para full_text.
  • Acesse métricas sem public_metrics.
  • Troque pagination_token/next_token por next_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.

Recursos sem equivalente direto na API oficial

Referências relacionadas