Guía de integración

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

Autenticación

Todos los endpoints de X API v2 requieren autenticación. Elige el método que se ajuste 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	Aplicaciones orientadas 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 App-Only

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

cURL

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obtener usuario por username
response = client.users.get_by_username("XDevelopers")
print(response.data)

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 con contexto de usuario

Requerida para el endpoint del 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 el user access token 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 el user access token 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.

Fields y expansions

X API v2 devuelve datos mínimos por defecto. Usa fields y expansions para solicitar exactamente lo que necesitas.

Respuesta predeterminada

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}

Fields disponibles

user.fields

Field	Descripción
`created_at`	Marca de tiempo de creación de la cuenta
`description`	Bio del usuario
`entities`	URLs analizadas en la bio
`location`	Ubicación definida por el usuario
`pinned_tweet_id`	ID del Post fijado
`profile_image_url`	URL del avatar
`protected`	Si la cuenta está protegida
`public_metrics`	Recuentos de seguidores/seguidos
`url`	URL del sitio web
`verified`	Estado de verificación
`withheld`	Información de retención

tweet.fields (requiere la expansion pinned_tweet_id)

Field	Descripción
`created_at`	Marca de tiempo de creación del Post
`text`	Contenido del Post
`public_metrics`	Recuentos de engagement
`entities`	Hashtags, menciones, URLs

Ejemplo con fields

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 usuario con fields y expansions adicionales
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 pinned tweet 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 pinned tweet expandido

Respuesta con expansions

Example response

{
  "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": "Welcome to the X Developer Platform!",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

Guía de fields y expansions

Aprende más sobre cómo personalizar respuestas

Búsquedas por lotes

Consulta varios usuarios en una sola solicitud:

cURL (por IDs)

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

curl "https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obtener múltiples usuarios por IDs
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 múltiples usuarios por usernames
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 múltiples usuarios por IDs
const byIds = await client.users.getUsers({
  ids: ["2244994945", "783214", "6253282"],
  userFields: ["username", "verified"],
});
byIds.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

// Obtener múltiples usuarios por usernames
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 múltiples solicitudes para conjuntos de datos más grandes.

Gestión de errores

Errores comunes

Estado	Error	Solución
400	Invalid request	Verifica el formato del parámetro
401	Unauthorized	Verifica las credenciales de autenticación
403	Forbidden	Verifica los permisos de la App
404	Not Found	El usuario no existe o fue suspendido
429	Too Many Requests	Espera y reintenta (consulta los rate limits)

Usuarios suspendidos o eliminados

Si un usuario está suspendido o eliminado:

La búsqueda de un solo usuario devuelve 404
La búsqueda de múltiples usuarios omite al usuario de los resultados con un array errors

Example response

{
  "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, name, username) está disponible
El contenido protegido (Post fijado) puede estar restringido
protected: true indica el estado de la cuenta

Mejores prácticas

Solicitudes por lotes

Usa endpoints multi-usuario para obtener hasta 100 usuarios a la vez, reduciendo las llamadas a la API.

Solicita solo los fields necesarios

Especifica solo los fields 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 errores con elegancia

Verifica errores parciales en respuestas por lotes.

Próximos pasos

Referencia de la API

Documentación completa del endpoint

Diccionario de datos

Todos los objetos y fields disponibles

Código de ejemplo

Ejemplos de código funcionales

Gestión de errores

Gestiona errores con elegancia

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Guía de integración

Autenticación

Autenticación App-Only

Autenticación con contexto de usuario

Fields y expansions

Respuesta predeterminada

Fields disponibles

Ejemplo con fields

Respuesta con expansions

Guía de fields y expansions

Búsquedas por lotes

Gestión de errores

Errores comunes

Usuarios suspendidos o eliminados

Usuarios protegidos

Mejores prácticas

Solicitudes por lotes

Solicita solo los fields necesarios

Almacena en caché los datos de usuario

Gestiona errores con elegancia

Próximos pasos

Referencia de la API

Diccionario de datos

Código de ejemplo

Gestión de errores

​Autenticación

​Autenticación App-Only

​Autenticación con contexto de usuario

​Fields y expansions

​Respuesta predeterminada

​Fields disponibles

​Ejemplo con fields

​Respuesta con expansions

Guía de fields y expansions

​Búsquedas por lotes

​Gestión de errores

​Errores comunes

​Usuarios suspendidos o eliminados

​Usuarios protegidos

​Mejores prácticas

Solicitudes por lotes

Solicita solo los fields necesarios

Almacena en caché los datos de usuario

Gestiona errores con elegancia

​Próximos pasos

Referencia de la API

Diccionario de datos

Código de ejemplo

Gestión de errores

Autenticación

Autenticación App-Only

Autenticación con contexto de usuario

Fields y expansions

Respuesta predeterminada

Fields disponibles

Ejemplo con fields

Respuesta con expansions

Búsquedas por lotes

Gestión de errores

Errores comunes

Usuarios suspendidos o eliminados

Usuarios protegidos

Mejores prácticas

Próximos pasos