> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Inicio rápido

> Obtén tu clave de API y realiza tu primera solicitud a la API de X (Twitter) en minutos.

Esta guía te lleva desde la creación de una cuenta hasta tu primera respuesta: configura la autenticación y ejecuta tus primeras solicitudes `GET` y `POST`. Cada paso incluye ejemplos funcionales en cURL, Python y JavaScript.

## Paso 1: Obtén tu clave de API

1. Abre el [panel de Sorsa](https://api.sorsa.io/overview), pulsa **Sign in** y regístrate con cualquiera de las opciones disponibles. Sorsa no solicita información adicional a la que comparte tu proveedor de autenticación.
2. Tu cuenta incluye **100 solicitudes gratuitas**. No necesitas tarjeta, funcionan con todos los endpoints disponibles y no caducan, así que puedes empezar a probar de inmediato.
3. Cuando necesites más capacidad, elige un plan (10K, 100K o 500K solicitudes al mes) y un ciclo de facturación (mensual o anual), y paga con tarjeta o criptomonedas.

Al iniciar sesión, el panel muestra tu **clave de API** y tu **cuota de solicitudes restante**.

> **Mantén tu clave de API en privado.** Nunca la incluyas en código frontend, repositorios públicos ni JavaScript del lado del cliente. Trátala como una contraseña.

## Paso 2: Conoce los conceptos básicos

Antes de realizar tu primera llamada, ten en cuenta lo siguiente.

**URL base**

```text theme={null}
https://api.sorsa.io/v3
```

**Autenticación**

Cada solicitud debe incluir tu clave de API en el encabezado `ApiKey`:

```text theme={null}
ApiKey: YOUR_API_KEY
```

**Formato de respuesta**

Todos los endpoints devuelven JSON. Una solicitud correcta responde con HTTP `200`.

**Límite de solicitudes**

Todos los planes tienen un límite de 20 solicitudes por segundo. Consulta [Límites de solicitudes](https://docs.sorsa.io/es/rate-limits) para conocer las estrategias de regulación y reintento.

## Paso 3: Envía tu primera solicitud GET

**Antes de ejecutar los ejemplos:** instala el paquete `requests` de Python con `python -m pip install requests`. Ejecuta JavaScript en tu backend con Node.js 18 o posterior y `fetch`; guarda los ejemplos como archivos `.mjs` para usar `await` en el nivel superior. Sustituye `YOUR_API_KEY` por tu clave. Las respuestas de perfiles y publicaciones que aparecen a continuación son ilustrativas.

La forma más rápida de comprobar la configuración es consultar un perfil público mediante `/info`.

**cURL**

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Python**

```python theme={null}
import requests

response = requests.get(
    "https://api.sorsa.io/v3/info",
    params={"username": "elonmusk"},
    headers={"ApiKey": "YOUR_API_KEY"},
    timeout=30,
)

response.raise_for_status()
data = response.json()
print(data["display_name"])      # Elon Musk
print(data["followers_count"])   # 236021252
```

**JavaScript**

```javascript theme={null}
const response = await fetch(
  "https://api.sorsa.io/v3/info?username=elonmusk",
  { headers: { ApiKey: "YOUR_API_KEY" } }
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data.display_name);      // Elon Musk
console.log(data.followers_count);   // 236021252
```

**Ejemplo de respuesta**

```json theme={null}
{
  "id": "44196397",
  "username": "elonmusk",
  "display_name": "Elon Musk",
  "description": "",
  "location": "",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1234567890/avatar.jpg",
  "profile_background_image_url": "https://pbs.twimg.com/profile_banners/44196397/1700000000",
  "followers_count": 236021252,
  "followings_count": 1292,
  "tweets_count": 98479,
  "favourites_count": 214650,
  "media_count": 4374,
  "verified": true,
  "protected": false,
  "can_dm": false,
  "possibly_sensitive": false,
  "created_at": "2009-06-02T20:12:29Z",
  "bio_urls": [],
  "pinned_tweet_ids": ["2028500984977330453"]
}
```

Si recibes JSON con datos del usuario, tu clave funciona y puedes continuar.

## Paso 4: Envía tu primera solicitud POST

Muchos endpoints de publicaciones y búsquedas utilizan `POST` con un cuerpo JSON. Este ejemplo busca publicaciones con `/search-tweets`:

**cURL**

```bash theme={null}
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "query": "bitcoin" }'
```

**Python**

```python theme={null}
import requests

response = requests.post(
    "https://api.sorsa.io/v3/search-tweets",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={"query": "bitcoin"},
    timeout=30,
)

response.raise_for_status()
data = response.json()
for tweet in data.get("tweets", []):
    print(tweet["full_text"])
```

**JavaScript**

```javascript theme={null}
const response = await fetch("https://api.sorsa.io/v3/search-tweets", {
  method: "POST",
  headers: {
    ApiKey: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "bitcoin" }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
data.tweets?.forEach((tweet) => console.log(tweet.full_text));
```

**Ejemplo de respuesta (recortado)**

```json theme={null}
{
  "tweets": [
    {
      "id": "1782368585664626774",
      "full_text": "Bitcoin just crossed another milestone.",
      "created_at": "2024-01-15T10:30:00Z",
      "lang": "en",
      "likes_count": 200,
      "retweet_count": 50,
      "reply_count": 10,
      "view_count": 10000,
      "user": {
        "id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "followers_count": 236021252,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABF7d..."
}
```

Para obtener más resultados, envía el valor `next_cursor` devuelto en la siguiente solicitud. Consulta el procedimiento completo en [Paginación](https://docs.sorsa.io/es/pagination).

## Paso 5: Consulta tu consumo de API

Comprueba cuántas solicitudes te quedan en cualquier momento con `/key-usage-info`:

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/key-usage-info' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Ejemplo de respuesta**

```json theme={null}
{
  "key_requests": 100000,
  "remaining_requests": 94231,
  "total_requests": 5769,
  "valid_until": "2026-08-01T00:00:00Z"
}
```

Conviene consultar este endpoint antes de ejecutar trabajos grandes por lotes. También puedes revisar el historial completo en el [panel](https://api.sorsa.io/overview/usage).

## Códigos de error habituales

| Código | Significado            | Qué hacer                                                           |
| :----- | :--------------------- | :------------------------------------------------------------------ |
| 200    | OK                     | La solicitud se completó correctamente                              |
| 400    | Solicitud incorrecta   | Revisa los parámetros y el cuerpo de la solicitud                   |
| 401    | No autorizado          | Falta la clave de API o no es válida; revisa el encabezado `ApiKey` |
| 403    | Acceso prohibido       | No tienes acceso a este recurso                                     |
| 404    | No encontrado          | Revisa la URL del endpoint o el ID del recurso                      |
| 429    | Demasiadas solicitudes | Has alcanzado el límite de frecuencia; espera y vuelve a intentarlo |
| 500    | Error del servidor     | Reintenta tras una breve espera; contacta con soporte si persiste   |

Consulta los detalles y las estrategias de gestión en [Códigos de error](https://docs.sorsa.io/es/error-codes).

## Pruébala sin escribir código

¿Prefieres explorar primero desde el navegador? Revisa los endpoints en la [referencia de la API](https://docs.sorsa.io/es/api-reference-guide) o utiliza [API Playground](https://api.sorsa.io/playground). Ambas opciones permiten enviar solicitudes reales e inspeccionar las respuestas antes de escribir código.

## Próximos pasos

* [Autenticación](https://docs.sorsa.io/es/authentication): buenas prácticas de seguridad y configuración de encabezados.
* [Paginación](https://docs.sorsa.io/es/pagination): cursores y respuestas paginadas.
* [Límites de solicitudes](https://docs.sorsa.io/es/rate-limits): regulación de solicitudes y reintentos.
* [Referencia de la API](https://docs.sorsa.io/es/api-reference-guide): endpoints disponibles y esquemas.
* [Casos de uso](https://docs.sorsa.io/es/use-cases-overview): patrones de implementación prácticos.