Skip to main content

Migrar de la API oficial de X v2 a Sorsa API v3

Esta referencia cubre autenticación, equivalencias de endpoints, respuestas, paginación, métodos HTTP, sintaxis de búsqueda, errores y ejemplos de cURL, Python y JavaScript. Sorsa es de solo lectura. Si tu integración publica, envía mensajes, da Me gusta o sigue cuentas, conserva la API oficial para esas operaciones y migra solo las lecturas. Las 100 solicitudes gratuitas de cada cuenta, sin tarjeta, permiten validar los endpoints antes de migrar tráfico de producción.
Nota: consulta costes y ejemplos paso a paso en la guía completa de migración.

Resumen de cambios

Autenticación

La API oficial utiliza OAuth 2.0 Bearer para solicitudes de aplicación y OAuth 1.0a User Context para solicitudes de usuario.
Sorsa utiliza una clave en el encabezado ApiKey. Genera las claves en el panel.
Consulta Autenticación.

Equivalencias de endpoints

Usuarios

  • GET /info-batch acepta hasta 100 nombres o IDs. Repite el parámetro: ?usernames=a&usernames=b.
  • GET /followers y GET /follows devuelven hasta 200 perfiles completos por página, con biografía, contadores y verificación.

Publicaciones

  • tweet_link acepta una URL completa como https://x.com/user/status/123 o el ID "123".
  • POST /tweet-info-bulk devuelve hasta 100 publicaciones por solicitud. Utilízalo en lugar de repetir POST /tweet-info para reducir hasta 100 veces las llamadas.
  • POST /user-tweets no tiene un máximo de 3.200 publicaciones. Recorre next_cursor hasta que no aparezca para consultar toda la cronología. Consulta Datos históricos.

Búsquedas

  • /search-tweets utiliza la sintaxis de búsqueda avanzada de la web de X. Muchos términos básicos se conservan, pero revisa los operadores específicos de API v2 antes de reutilizar consultas. Consulta Operadores de búsqueda.
  • POST /mentions añade filtros como min_likes, min_replies, min_retweets, since_date y until_date.

Listas

Comunidades

La API oficial de X no expone estos endpoints de comunidades; son funciones de Sorsa. Consulta los parámetros y la nota de disponibilidad en Listas y comunidades. Confirma la compatibilidad actual antes de migrar este tipo de flujo.

Verificación

Estos endpoints responden a preguntas sobre acciones concretas. La API oficial no tiene un equivalente directo; replicarlos requiere recuperar listas y examinarlas en el cliente. Consulta Verificación de campañas.

Análisis exclusivo de Sorsa

Estos endpoints indexan un subconjunto de cuentas del sector de criptomonedas: influencers, proyectos y fondos. Consulta Sorsa Score y análisis de criptomonedas.

Utilidades

Consulta Conversión de IDs.

Cambios en las respuestas

Es uno de los cambios principales. La API oficial envuelve los resultados en data, includes y meta. Sorsa devuelve objetos planos con el autor incluido en cada publicación.

Perfil de usuario

API oficial de X v2, con selección de campos:
Sorsa API v3:

Publicación

API oficial de X v2, con expansions=author_id:
Sorsa API v3:

Equivalencias de campos

Campos de usuario

Campos de publicación

Paginación

La API oficial envía pagination_token y devuelve meta.next_token. Sorsa utiliza next_cursor en ambas direcciones. En GET, envíalo como parámetro de consulta:
En POST, inclúyelo en el cuerpo JSON:
La respuesta lo devuelve en el nivel superior:
Si falta o es null, no quedan páginas. Consulta Paginación.

Diferencias de método HTTP

Algunos endpoints GET de la API oficial son POST en Sorsa. Como regla general, los endpoints de publicaciones, búsquedas y comunidades utilizan POST con JSON; esto incluye /user-tweets aunque reciba un usuario. Los de usuarios, listas y utilidades utilizan GET con parámetros de consulta o ruta. La excepción es /check-comment: usa GET aunque reciba un enlace de publicación. Comprueba siempre la referencia si tienes dudas.

Ejemplos de migración de código

Consultar un perfil

Antes: API oficial
Después: Sorsa API

Buscar publicaciones

Antes:
Después:

Recorrer todos los seguidores

Antes:
Después:
Cada página de Sorsa devuelve hasta 200 perfiles completos. La API oficial suele devolver IDs y datos mínimos, que requieren consultas adicionales para completar perfiles.

Sintaxis de búsqueda

Sorsa utiliza los operadores de la búsqueda avanzada web de X, que difieren de los de API v2. Conserva palabras, frases, from: y to: cuando corresponda, adapta los filtros específicos y prueba la consulta. Por ejemplo, usa -filter:nativeretweets para excluir retuits nativos. Referencia completa: Operadores de búsqueda. /mentions admite además min_likes, min_replies, min_retweets, since_date y until_date. Consulta Seguimiento de menciones.

Gestión de errores

La API oficial devuelve un array errors:
Sorsa utiliza una estructura sencilla:
Los códigos comunes son 400, 401, 403, 404, 429 y 500. Consulta Códigos de error. Ante un 429, espera y reintenta. El límite común es 20 solicitudes por segundo, sin ventanas independientes por endpoint. Consulta Límites de solicitudes. Función de reintento compatible con ambas APIs:

Lista de comprobación de la migración

  • Sustituye Authorization: Bearer ... por ApiKey: ....
  • Elimina la firma OAuth 1.0a de las lecturas migradas: claves de consumidor, tokens y generación de firmas.
  • Cambia https://api.x.com/2 por https://api.sorsa.io/v3.
  • Adapta cada ruta según las tablas.
  • Cambia GET por POST en publicaciones, búsquedas, comentarios, citas y usuarios que retuitearon.
  • Elimina tweet.fields, user.fields, media.fields y expansions.
  • Actualiza los lectores de respuestas: elimina la extracción de data, includes y meta.
  • Cambia los nombres de campos, como name por display_name y text por full_text.
  • Accede a las métricas sin public_metrics.
  • Sustituye pagination_token y next_token por next_cursor.
  • Adapta los errores a { "message": "..." }.
  • Aplica el límite común de 20 solicitudes por segundo.
  • Prueba los endpoints críticos en API Playground.
  • Supervisa la cuota con GET /key-usage-info.
  • Conserva la API oficial para operaciones de escritura si las necesitas.

Funciones sin equivalente en la API oficial

Referencias relacionadas