Guía de integración

Conceptos clave y prácticas recomendadas para integrar la búsqueda de usuarios

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

---

​

Autenticación

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

Método	Ideal para	¿Puede 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 de cara al usuario	Sí (para los datos del usuario autorizado)
OAuth 1.0a User Context	Integraciones heredadas	Sí (para los datos del usuario autorizado)

​

Autenticación solo con App

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

cURL

shellscript

curl "https://api.x.com/2/users/by/username/XDevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​

Autenticación de contexto de usuario

Requerida para el endpoint de usuario autenticado (/2/users/me):

cURL

shellscript

curl "https://api.x.com/2/users/me" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

El endpoint /2/users/me solo funciona con autenticación de contexto de usuario. Los tokens App-Only devolverán un error.

---

​

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": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}

​

Campos disponibles

user.fields

Campo	Descripción
created_at	Marca temporal de creación de la cuenta
description	Biografía del usuario
entities	URLs analizadas en la biografía
location	Ubicación definida por el usuario
pinned_tweet_id	id de la Publicación fijada
profile_image_url	URL del avatar
protected	Indica si la cuenta está protegida
public_metrics	Recuentos de seguidores/seguidos
url	URL del sitio web
verified	Estado de verificación
withheld	Información sobre retenciones

tweet.fields (requiere la expansión pinned_tweet_id)

Campo	Descripción
created_at	Marca temporal de creación de la Publicación
text	Contenido de la Publicación
public_metrics	Recuentos de interacción
entities	Hashtags, menciones, URLs

​

Ejemplo con campos

cURL

shellscript

curl "https://api.x.com/2/users/by/username/XDevelopers?\
user.fields=created_at,description,public_metrics,verified&\
expansions=pinned_tweet_id&\
tweet.fields=created_at,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​

Respuesta con Expansions

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "verified": true,
    "pinned_tweet_id": "1234567890",
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052
    }
  },
  "includes": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "¡Bienvenido a la Plataforma de Desarrolladores de X!",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

Guía de campos y expansions

Más información sobre cómo personalizar las respuestas

---

​

Consultas por lotes

Consulta varios usuarios en una sola solicitud:

cURL (by IDs)

shellscript

curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Las solicitudes por lotes están limitadas a 100 usuarios. Usa varias solicitudes para conjuntos de datos más grandes.

---

​

Gestión de errores

​

Errores comunes

Estado	Error	Solución
400	Solicitud no válida	Verifica el formato de los parámetros
401	No autorizado	Verifica las credenciales de autenticación
403	Prohibido	Verifica los permisos de la App
404	No encontrado	El usuario no existe o fue suspendido
429	Demasiadas solicitudes	Espera y vuelve a intentarlo (consulta los límites de tasa)

​

Usuarios suspendidos o eliminados

Si un usuario está suspendido o eliminado:

• La consulta de un único usuario devuelve 404
• La consulta de varios usuarios omite a ese usuario de los resultados y devuelve un array errors

{
  "data": [
    { "id": "2244994945", "username": "XDevelopers" }
  ],
  "errors": [
    {
      "resource_id": "1234567890",
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with id: [1234567890]."
    }
  ]
}

​

Usuarios protegidos

Para cuentas protegidas que no sigues:

• La información básica (id, nombre, nombre de usuario) está disponible
• El contenido protegido (Publicación fijada) puede estar restringido
• protected: true indica el estado de la cuenta

---

​

Mejores prácticas

Solicitudes por lotes

Usa endpoints multiusuario para obtener hasta 100 usuarios a la vez y 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.

Almacena en caché los datos de usuario

Almacena en caché los perfiles de usuario localmente para reducir solicitudes repetidas.

Gestiona los errores correctamente

Comprueba si hay errores parciales en las respuestas por lotes.

---

​

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 funcionales

Gestión de errores

Gestiona los errores correctamente