Guía de integración

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

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

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.users.getByUsername("XDevelopers");
console.log(response.data);

Autenticación de contexto de usuario

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

cURL

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

from xdk import Client

# Usando un token de acceso de usuario OAuth 2.0
client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Obtener el perfil del usuario autenticado
response = client.users.get_me()
print(response.data)

import { Client } from "@xdevplatform/xdk";

// Usando un token de acceso de usuario OAuth 2.0
const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const response = await client.users.getMe();
console.log(response.data);

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

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obtener el usuario con campos adicionales y expansiones
response = client.users.get_by_username(
    "XDevelopers",
    user_fields=["created_at", "description", "public_metrics", "verified"],
    expansions=["pinned_tweet_id"],
    tweet_fields=["created_at", "public_metrics"]
)

print(response.data)
print(response.includes)  # Contiene el Tweet fijado expandido

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.users.getByUsername("XDevelopers", {
  userFields: ["created_at", "description", "public_metrics", "verified"],
  expansions: ["pinned_tweet_id"],
  tweetFields: ["created_at", "public_metrics"],
});

console.log(response.data);
console.log(response.includes); // Contiene el Tweet fijado expandido

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)

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obtener varios usuarios por id
response = client.users.get_users(
    ids=["2244994945", "783214", "6253282"],
    user_fields=["username", "verified"]
)
for user in response.data:
    print(f"{user.username}: {user.verified}")

# Obtener varios usuarios por nombres de usuario
response = client.users.get_users_by_usernames(
    usernames=["XDevelopers", "X", "XAPI"],
    user_fields=["username", "verified"]
)
for user in response.data:
    print(f"{user.username}: {user.verified}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Obtener varios usuarios por id
const byIds = await client.users.getUsers({
  ids: ["2244994945", "783214", "6253282"],
  userFields: ["username", "verified"],
});
byIds.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

// Obtener varios usuarios por nombres de usuario
const byUsernames = await client.users.getUsersByUsernames({
  usernames: ["XDevelopers", "X", "XAPI"],
  userFields: ["username", "verified"],
});
byUsernames.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

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