Guía de integración

Conceptos clave y prácticas recomendadas para integrar la consulta de Publicaciones

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

shellscript

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

shellscript

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"

---

​

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