Guía de integración

Esta guía abarca los conceptos clave que necesitas para integrar en tu aplicación los endpoints de consulta de Publicaciones.

Autenticación

Todos los endpoints de X API v2 requieren autenticación. Selecciona el método que mejor se adapte a tu caso de uso:

Método	Ideal para	¿Permite acceder a métricas privadas?
OAuth 2.0 App-Only	Servidor a servidor, datos públicos	No
OAuth 2.0 Authorization Code with PKCE	Apps orientadas al usuario	Sí (para las Publicaciones del usuario autorizado)
OAuth 1.0a User Context	Integraciones heredadas	Sí (para las Publicaciones del usuario autorizado)

Autenticación solo de la App

Para datos públicos de Publicaciones, usa un Bearer Token:

cURL

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

Autenticación con Contexto de Usuario

Para acceder a métricas privadas, autentícate en nombre del autor de la Publicación:

Los siguientes campos requieren autenticación con Contexto de Usuario:

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

Campos y expansions

La X API v2 devuelve una cantidad mínima de datos de forma predeterminada. Usa fields y expansions para solicitar exactamente lo que necesitas.

Respuesta predeterminada

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

Campos disponibles

tweet.fields

Campo	Descripción
`created_at`	Marca de tiempo de creación de la Publicación
`author_id`	ID de usuario del autor
`public_metrics`	Recuentos de Me gusta, retweets, respuestas y citas
`entities`	Hashtags, menciones, URLs, cashtags
`attachments`	Claves de medios, IDs de encuestas
`conversation_id`	Identificador del hilo
`context_annotations`	Clasificaciones de temas/entidades
`in_reply_to_user_id`	Usuario al que se responde
`lang`	Idioma detectado
`source`	Cliente desde el que se publicó
`possibly_sensitive`	Indicador de contenido sensible
`reply_settings`	Quién puede responder

user.fields (requiere la expansión de author_id)

Campo	Descripción
`username`	@handle
`name`	Nombre para mostrar
`profile_image_url`	URL del avatar
`verified`	Estado de verificación
`description`	Biografía
`public_metrics`	Recuentos de seguidores/seguidos
`created_at`	Fecha de creación de la cuenta

media.fields (requiere la expansión de attachments.media_keys)

Campo	Descripción
`url`	URL del medio
`preview_image_url`	URL de la miniatura
`type`	photo, video, animated_gif
`duration_ms`	Duración del video
`height`, `width`	Dimensiones
`alt_text`	Texto alternativo (accesibilidad)

Ejemplo con campos

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")

# Obtener una Publicación con campos adicionales y expansiones
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)  # Contiene objetos de usuario y multimedia 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); // Contiene objetos de usuario y multimedia expandidos

Edición de Publicaciones

Las Publicaciones se pueden editar hasta 5 veces durante los 30 minutos posteriores a su creación.

Cómo funciona

Cada edición genera un nuevo id de la Publicación
edit_history_tweet_ids contiene todas las versiones (de la más antigua a la más reciente)
El endpoint siempre devuelve la versión más reciente

Ejemplo de respuesta

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

Las Publicaciones obtenidas después de que haya transcurrido su ventana de edición de 30 minutos se consideran la versión final. En casos de uso en tiempo real, ten en cuenta que las Publicaciones creadas recientemente aún pueden editarse.

Gestión de errores

Errores comunes

Estado	Error	Solución
400	Solicitud no válida	Comprueba el formato de los parámetros
401	No autorizado	Comprueba las credenciales de autenticación
403	Prohibido	Comprueba los permisos de la App
404	No encontrado	La Publicación se ha eliminado o no existe
429	Demasiadas solicitudes	Espera e inténtalo de nuevo (consulta los límites de tasa)

Publicaciones eliminadas o protegidas

Si una Publicación se elimina o pertenece a una cuenta protegida que no sigues:

La consulta de una sola Publicación devuelve 404
La consulta de varias Publicaciones omite la Publicación de los resultados y devuelve un array errors

{
  "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]."
    }
  ]
}

Mejores prácticas

Solicitudes por lotes

Usa el endpoint para múltiples Publicaciones para obtener hasta 100 Publicaciones a la vez y así reducir las llamadas a la API.

Solicita solo los campos necesarios

Especifica solo los campos que necesitas para minimizar el tamaño de la respuesta y el tiempo de procesamiento.

Almacena respuestas en caché

Almacena en caché localmente los datos de las Publicaciones para reducir solicitudes repetidas para el mismo contenido.

Gestiona las ediciones

Para aplicaciones en tiempo real, considera volver a solicitar las Publicaciones después de la ventana de edición de 30 minutos.

Próximos pasos

Referencia de la API

Documentación completa del endpoint

Diccionario de datos

Todos los objetos y campos disponibles

Código de ejemplo

Ejemplos de código en funcionamiento

Gestión de errores

Gestiona los errores de forma adecuada