# APIs del Sistema — Guía completa

Este documento integra toda la información sobre APIs del sistema: obtención de claves, prioridades, estrategias, comparación y configuración.

---

## Tabla de Contenidos

1. [APIs priorizadas (MVP)](#apis-priorizadas-mvp)
2. [Obtención de claves](#obtención-de-claves)
3. [Guía de integración](#guía-de-integración)
4. [Comparación detallada](#comparación-detallada)
5. [Estrategias técnicas](#estrategias-técnicas)
6. [Configuración y despliegue](#configuración-y-despliegue)

---

## APIs priorizadas (MVP)

### Prioridad Alta

1. **IGDB (Internet Game Database)** - Calidad superior, amplia cobertura
2. **RAWG (Rawg.io)** - Buena cobertura, datos de tiendas

### Prioridad Media

3. **TheGamesDB** - Artwork comunitario
4. **ScreenScraper** - Media específica para ROMs

### Prioridad Baja (para futuras versiones)

5. **PriceCharting** - Precios físicos
6. **IsThereAnyDeal** - Ofertas digitales
7. **MobyGames** - Datos históricos detallados
8. **eBay** - Datos de mercado

---

## Obtención de claves

### IGDB (Internet Game Database)

IGDB usa **OAuth 2.0 via Twitch**. Steps:

1. Go to [Twitch Developer Console](https://dev.twitch.tv/console/apps)
2. Sign in with your Twitch account (create one if needed)
3. Click "Create Application"
   - Name: "Quasar" (or your app name)
   - Category: Select relevant category
   - Accept terms, click Create
4. You'll see:
   - **Client ID** — Copy this
   - Click "New Secret" to generate **Client Secret** — Copy this
5. Go to Settings → OAuth Redirect URLs
   - Add: `http://localhost:3000/oauth/callback` (development)
   - For production: `https://yourdomain.com/oauth/callback`
6. In your `.env` file:
   ```
   IGDB_CLIENT_ID=your_client_id
   IGDB_CLIENT_SECRET=your_client_secret
   ```
7. Start Quasar, it will use IGDB automatically

**Rate Limit:** 4 requests/second

### RAWG (Rawg.io)

RAWG has a simpler **API Key** approach:

1. Go to [RAWG Settings](https://rawg.io/settings/account)
2. Sign up if needed, then login
3. Find "API Key" section
4. Click "Create new key" (if needed) or copy existing key
5. In your `.env` file:
   ```
   RAWG_API_KEY=your_api_key_here
   ```
6. Start Quasar

**Rate Limit:** 20 requests/second (free tier)

**Note:** RAWG requires attribution in UI (include "Powered by RAWG" somewhere visible)

### TheGamesDB (thegamesdb.net)

TheGamesDB uses a simple **API Key**:

1. Go to [TheGamesDB API](https://thegamesdb.net/api)
2. Find "API Key" section (free registration required)
3. Register or login
4. Copy your API key
5. In your `.env` file:
   ```
   THEGAMESDB_API_KEY=your_api_key_here
   ```
6. Start Quasar

**Rate Limit:** 1 request/second (free tier)

### ScreenScraper

ScreenScraper requiere cuenta y modelo de donación:

1. Go to [ScreenScraper](https://www.screenscraper.fr/)
2. Create account
3. Niveles de donación ofrecen límites distintos (ej.: 50.000 scrapes/día en nivel Bronze)
4. En tu `.env` file:
   ```
   SCREENSCRAPER_USERNAME=your_username
   SCREENSCRAPER_PASSWORD=your_password
   ```

---

## Guía de integración

### IGDB

- **Obtener credenciales**: registrar una app en Twitch Developer Console para obtener `CLIENT_ID` y `CLIENT_SECRET`. Obtener token con grant type `client_credentials` (POST a `https://id.twitch.tv/oauth2/token`).

- **Endpoints principales**: `POST https://api.igdb.com/v4/games` (consulta flexible via body con sintaxis IGDB), `POST https://api.igdb.com/v4/covers`, `POST https://api.igdb.com/v4/platforms`.

- **Ejemplo (buscar)**:

```bash
# Obtener token
curl -X POST 'https://id.twitch.tv/oauth2/token?client_id=$IGDB_CLIENT_ID&client_secret=$IGDB_CLIENT_SECRET&grant_type=client_credentials'

# Buscar juegos
curl -X POST 'https://api.igdb.com/v4/games' \
  -H "Client-ID: $IGDB_CLIENT_ID" \
  -H "Authorization: Bearer $IGDB_TOKEN" \
  -H 'Accept: application/json' \
  --data 'fields id,name,first_release_date,platforms.name,genres.name,cover.url; search "zelda"; limit 5;'
```

- **Respuesta (esquemática)**:

```json
[
  {
    "id": 12345,
    "name": "Ejemplo",
    "first_release_date": 1459468800,
    "platforms": [{ "name": "Nintendo Switch" }],
    "cover": { "url": "//images.igdb.com/...jpg" }
  }
]
```

- **Límites y manejo**: la API puede devolver `429` o cabeceras de límite; implementar retries exponenciales (ej. 3 intentos) y respetar `Retry-After`. Implementar circuit breaker si la API falla repetidamente.
- **Atribución**: mostrar origen de datos (ej. "Datos: IGDB") según términos del servicio.

### RAWG

- **Obtener credenciales**: registrarse en RAWG para obtener `RAWG_API_KEY` (https://rawg.io/apidocs).
- **Endpoints principales**: `GET https://api.rawg.io/api/games?key=API_KEY&search=...`, `GET https://api.rawg.io/api/games/{id}`.
- **Ejemplo**:

```bash
curl 'https://api.rawg.io/api/games?key=$RAWG_API_KEY&search=zelda&page_size=5'
```

- **Respuesta (esquemática)**:

```json
{
  "count": 100,
  "results": [
    { "id": 3498, "name": "GTA V", "released": "2013-09-17", "background_image": "https://..." }
  ]
}
```

- **Límites y manejo**: RAWG suele tener límites por clave/plan; cachear y fallback a otros proveedores si falla.
- **Atribución**: revisar condiciones y mostrar HTTP o texto de fuente si es requerido por el proveedor.

### TheGamesDB

- **Obtener credenciales**: crear cuenta y generar API Key en https://thegamesdb.net.
- **Endpoints**: búsqueda por nombre y detalles (`/v1/Games/ByGameName?name=...`, `/v1/Games/ByGameID?id=...`).
- **Ejemplo**:

```bash
curl -H 'Authorization: Bearer $THEGAMESDB_KEY' 'https://api.thegamesdb.net/v1/Games/ByGameName?name=zelda'
```

### Estrategia de fallback y normalización

- **Orden de prioridad**: IGDB → RAWG → TheGamesDB (configurable).
- **Normalización (mapping)**:
  - `title` ← `name`
  - `platform` ← `platforms[].name`
  - `release_date` ← `first_release_date` / `released` → convertir a ISO 8601
  - `genres` ← `genres[].name`
  - `cover_url` ← `cover.url` / `background_image`
  - `external_ids` ← `{ igdb: id, rawg: id, thegamesdb: id }`

- **Fallback**: si IGDB no tiene portada, intentar RAWG; si falla, usar TheGamesDB. Registrar la fuente usada.

### Caché y almacenamiento de artwork

- **Caché metadata**: LRU en memoria o Redis con TTL (por ejemplo 24h) para evitar sobrecargar APIs.
- **Almacenamiento de imágenes**: descargar y optimizar con `sharp` (crear versiones: thumb, medium), almacenar en `storage/artwork/{gameId}/cover.jpg` o S3.
- **Servicio proxy**: servir imágenes desde backend para no exponer keys ni URLs externas.

### Manejo de errores y resiliencia

- Implementar **retries** exponenciales con jitter (3 intentos).
- Implementar **circuit breaker** para desconectar llamadas a un proveedor fuera de servicio por N minutos.
- Limitar concurrencia por proveedor (p. ej. 5 llamadas simultáneas) y usar colas para trabajos masivos (enriquecimiento masivo).

---

## Comparación detallada

### Resumen por API

#### IGDB (Internet Games Database)

- **Resumen:** Base de datos muy completa (propiedad de Twitch/Amazon) con endpoints para juegos, covers, screenshots, plataformas, ratings, compañías y más.
- **Autenticación / Requisitos:** OAuth vía Twitch (Client ID + Client Secret → token) — requiere cuenta Twitch y 2FA para registrar apps.
- **Datos principales:** covers, screenshots, genres, developers, ESRB/PEGI, platforms, videos, websites, age ratings, tags.
- **Rate limits / cuotas:** 4 peticiones/segundo; hasta 8 peticiones abiertas (si se excede → 429 Too Many Requests).
- **Fecha verificación:** 2026-02-07
- **TOS / Developer Agreement:** Twitch Developer Service Agreement — https://www.twitch.tv/p/legal/developer-agreement/
- **Cláusula clave:** "There is a rate limit of 4 requests per second. If you go over this limit you will receive a response with status code `429 Too Many Requests`." — https://api-docs.igdb.com/
- **Costes / modelo:** Gratuito para uso no comercial; acuerdos comerciales para partners (atribución en caso de partnership).
- **Enlace:** https://api-docs.igdb.com/

#### RAWG

- **Resumen:** Gran base de datos (medio millón de juegos), buena para metadata general y enlaces a tiendas.
- **Autenticación / Requisitos:** API key en query string (`key=YOUR_API_KEY`).
- **Datos principales:** descripciones, screenshots, plataformas, géneros, ratings, enlaces a tiendas, playtime estimado.
- **Rate limits / cuotas:** Planes gratuitos con límites (ej. free tier limitada) y planes comerciales con mayor cuota (p.ej. hasta 50k requests/mes en planes de negocio).
- **Fecha verificación:** 2026-02-07
- **TOS / Developer Agreement:** https://rawg.io/tos_api
- **Cláusula clave:** "Free for personal use as long as you attribute RAWG as the source of the data and/or images and add an active hyperlink from every page where the data of RAWG is used. No data redistribution." — https://rawg.io/tos_api
- **Costes / modelo:** Free tier para proyectos personales; planes comerciales (pago mensual) para uso en productos con gran tráfico.
- **Enlace:** https://rawg.io/apidocs

#### TheGamesDB

- **Resumen:** Base de datos comunitaria para juegos y artwork, con API pública v2.
- **Autenticación / Requisitos:** Registro y uso de API key (ver docs); repositorio público del proyecto (GPLv3 para el código del servidor).
- **Datos principales:** imágenes, covers, plataformas, metadatos básicos.
- **Rate limits / cuotas:** No siempre documentados públicamente (consultar docs/registro).
- **Fecha verificación:** 2026-02-07
- **TOS / Developer Agreement:** No documentado públicamente — consultado https://api.thegamesdb.net/ y https://github.com/TheGamesDB/TheGamesDBv2 (código bajo GPL‑3.0)
- **Cláusula clave:** No documentado públicamente — verificar con el equipo de TheGamesDB antes de uso comercial/redistribución.
- **Enlace:** https://api.thegamesdb.net/

#### ScreenScraper

- **Resumen:** Servicio francés orientado a frontends, con enorme cantidad de media y opciones de scraping.
- **Autenticación / Requisitos:** Cuenta en ScreenScraper; modelo de soporte/donación que habilita límites mayores.
- **Datos principales:** screenshots, boxart, videos, manuals, metadata comunitaria.
- **Rate limits / cuotas:** Planes por donación (ej.: 50.000 scrapes/día en niveles básicos; aumentos en niveles superiores).
- **Fecha verificación:** 2026-02-07
- **TOS / Developer Agreement:** https://www.screenscraper.fr/
- **Cláusula clave:** "Niveles de donación ofrecen límites distintos (p.ej. 50.000 scrapes/día en nivel Bronze); consultar la cuenta para límites exactos." — https://www.screenscraper.fr/
- **Costes / modelo:** Donación / suscripción para aumentar cuotas y velocidad.
- **Enlace:** https://www.screenscraper.fr/

#### MobyGames

- **Resumen:** Base histórica con screenshots, covers, reviews y credits; muy usada por investigación y metadata profunda.
- **Autenticación / Requisitos:** API y/o MobyPlus; la API requiere registro y suscripción.
- **Datos principales:** screenshots, covers, credits, precios históricos limitados.
- **Rate limits / cuotas:** Non-commercial API requests are limited to 720 per hour (one every five seconds) with a max request rate of 1 per/second.
- **Fecha verificación:** 2026-02-07
- **TOS / Developer Agreement:** https://www.mobygames.com/api/subscribe/
- **Cláusula clave:** "Non-commercial API requests are limited to 720 per hour (one every five seconds) with a max request rate of 1 per/second." — https://www.mobygames.com/api/subscribe/
- **Costes / modelo:** Acceso vía suscripción / MobyPro; contactar para condiciones comerciales.
- **Enlace:** https://www.mobygames.com/api/subscribe/

#### PriceCharting

- **Resumen:** Fuente especializada en historial de precios para juegos físicos y coleccionables.
- **Autenticación / Requisitos:** API documentada en el sitio; el acceso completo requiere suscripción / token pagado.
- **Datos principales:** precios históricos, condiciones (complete, loose), plataforma y comparables de mercado.
- **Rate limits / cuotas:** No siempre publicadas públicamente; contactar a PriceCharting para detalles.
- **Fecha verificación:** 2026-02-07
- **TOS / Developer Agreement:** https://www.pricecharting.com/api-documentation (ver también https://www.pricecharting.com/page/terms-of-service)
- **Cláusula clave:** "API's are a premium tool. You must have a paid subscription to access the API." — https://www.pricecharting.com/api-documentation
- **Costes / modelo:** Servicio comercial (licencias / API keys pagadas).
- **Enlace:** https://www.pricecharting.com/api-documentation

#### IsThereAnyDeal (Itad)

- **Resumen:** Agregador de ofertas con histórico y mapeo de keys/tiendas; útil para tracking de ofertas digitales.
- **Autenticación / Requisitos:** API Key (docs en https://docs.isthereanydeal.com/).
- **Datos principales:** price history, deals, store IDs, game mappings.
- **Rate limits / cuotas:** Access to API is rate limited and subject to change (limits provided in headers); contactar si necesita mayor cuota.
- **Fecha verificación:** 2026-02-07
- **TOS / Developer Agreement:** https://docs.isthereanydeal.com/
- **Cláusula clave:** "You MUST NOT change provided data in any way. You SHOULD provide a link to IsThereAnyDeal.com or mention IsThereAnyDeal API." — https://docs.isthereanydeal.com/
- **Costes / modelo:** Free tier; acuerdos comerciales para uso intensivo.
- **Enlace:** https://docs.isthereanydeal.com/

#### eBay

- **Resumen:** Fuente de datos de mercado (listings, precios vendidos) para estimar valor real de mercado.
- **Autenticación / Requisitos:** Registro en eBay Developers Program; claves y OAuth para endpoints de venta/completed items.
- **Datos principales:** listados, historiales vendidos (completed), especificaciones de artículos.
- **Rate limits / cuotas:** Límite de llamadas por aplicación; eBay puede limitar y suspender acceso si se exceden los límites.
- **Fecha verificación:** 2026-02-07
- **TOS / Developer Agreement:** https://developer.ebay.com/join/api-license-agreement
- **Cláusula clave:** "You may not sell, rent, trade, distribute, lease (or otherwise commercialize), copy, store or modify eBay Content, other than for the purposes allowed by this API License Agreement." y "eBay reserves the right to limit the number of periodic API calls you are allowed to make." — https://developer.ebay.com/join/api-license-agreement
- **Costes / modelo:** Free para desarrolladores con límites; uso intensivo o comerciales pueden requerir acuerdos o certificaciones.
- **Enlace:** https://developer.ebay.com/

### Tabla resumida

| API            | Data types                                              | Auth                             | Free / Paid                                | Fecha verificación | Licencia / Nota legal                                                                                   | Notes                                                          |
| -------------- | ------------------------------------------------------- | -------------------------------- | ------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| IGDB           | covers, screenshots, genres, ESRB, companies, platforms | OAuth via Twitch                 | Free (non-commercial); commercial partners | 2026-02-07         | TOS: https://www.twitch.tv/p/legal/developer-agreement/                                                 | 4 rps rate limit; muy completa                                 |
| RAWG           | games, screenshots, stores, ratings, playtime           | API key (query param)            | Free tier; paid commercial plans           | 2026-02-07         | TOS: https://rawg.io/tos_api (atribución requerida)                                                     | Free for personal use; atribución requerida; no redistribución |
| TheGamesDB     | images, basic metadata                                  | API key (registro)               | Free / community                           | 2026-02-07         | Repo/TOS: https://github.com/TheGamesDB/TheGamesDBv2 (codigo GPL-3.0) / TOS no documentada públicamente | No TOS público claro; código backend GPL‑3.0                   |
| ScreenScraper  | images, videos, manuals                                 | Account + token (donation tiers) | Donation / paid tiers                      | 2026-02-07         | TOS: https://www.screenscraper.fr/ (donation/tiers)                                                     | Donación/premium para mayores cuotas (p.ej. 50k/día)           |
| PriceCharting  | price history                                           | API key / commercial             | Paid                                       | 2026-02-07         | Paid: https://www.pricecharting.com/api-documentation                                                   | API premium; requiere suscripción                              |
| IsThereAnyDeal | deals, price history                                    | API key                          | Free tier / paid                           | 2026-02-07         | TOS: https://docs.isthereanydeal.com/                                                                   | Requiere atribución; prohíbe modificar datos                   |
| MobyGames      | screenshots, credits, covers                            | Subscribe / API key              | Paid / subscription                        | 2026-02-07         | Paid/Subscribe: https://www.mobygames.com/api/subscribe/                                                | Access via subscription; non-commercial rate limits documented |
| eBay           | listings, sold data                                     | eBay Dev keys / OAuth            | Free (with limits)                         | 2026-02-07         | TOS: https://developer.ebay.com/                                                                        | Terms restrict distribution; API License Agreement             |

### Conclusión y recomendación para MVP

Recomiendo un **set inicial de APIs (priorizado)**: **IGDB, RAWG, TheGamesDB, ScreenScraper, PriceCharting, IsThereAnyDeal.**

- **Por qué:** IGDB + RAWG cubren **amplia metadata** y campos útiles (genres, plataformas, covers); TheGamesDB aporta **artwork comunitario**; ScreenScraper cubre assets específicos para ROM/frontends (videos/logos); PriceCharting e IsThereAnyDeal cubren **precios físicos y ofertas digitales** respectivamente.
- **Prioridad:** 1) IGDB (calidad + licencia accesible) 2) RAWG (cobertura y datos de tiendas) 3) TheGamesDB (artwork) 4) ScreenScraper (media específica) 5) PriceCharting (precios físicos) 6) IsThereAnyDeal (ofertas digitales).

---

## Estrategias técnicas

### Variables de entorno (ejemplos)

```
IGDB_CLIENT_ID=...
IGDB_CLIENT_SECRET=...
RAWG_API_KEY=...
THEGAMESDB_API_KEY=...
SCREENSCRAPER_USERNAME=...
SCREENSCRAPER_PASSWORD=...
EXTERNAL_API_CONCURRENCY=5
```

> Nota: **Nunca** exponer estas claves en el cliente; siempre pasar por el backend.

### Normalización de datos

```typescript
interface NormalizedGame {
  title: string;
  platform: string;
  release_date: string; // ISO 8601
  genres: string[];
  cover_url: string;
  external_ids: {
    igdb?: string;
    rawg?: string;
    thegamesdb?: string;
  };
  source: 'igdb' | 'rawg' | 'thegamesdb' | 'screenscraper';
}
```

### Ejemplo de implementación

```typescript
class MetadataService {
  private apis = [
    new IGDBService(),
    new RAWGService(),
    new TheGamesDBService(),
    new ScreenScraperService(),
  ];

  async searchGame(title: string): Promise<NormalizedGame> {
    for (const api of this.apis) {
      try {
        const result = await api.search(title);
        if (result) {
          return this.normalize(result, api.getSource());
        }
      } catch (error) {
        console.warn(`${api.getSource()} failed:`, error);
        continue;
      }
    }
    throw new Error('All APIs failed');
  }

  private normalize(data: any, source: string): NormalizedGame {
    return {
      title: data.name || data.title,
      platform: data.platforms?.[0]?.name || '',
      release_date: this.normalizeDate(data.first_release_date || data.released),
      genres: data.genres?.map((g: any) => g.name) || [],
      cover_url: data.cover?.url || data.background_image || '',
      external_ids: {
        igdb: data.id,
        rawg: data.id,
        thegamesdb: data.id,
      },
      source: source as any,
    };
  }
}
```

---

## Configuración y despliegue

### Testing Without Real Keys

Para desarrollo/testing:

- Dejar API keys como `your_*_here` en `.env.local`
- Quasar will gracefully degrade and show limited metadata
- Frontend will still work with manual game entry

### Production Deployment

Para producción:

1. Generar nuevas claves en cada servicio (no reutilizar claves de desarrollo)
2. Almacenar claves en **Gitea Secrets** (para pipelines CI/CD automatizados)
3. O usar variables de entorno en tu proveedor de hosting
4. Rotar claves cada 3 meses
5. Monitorear límites de rate en los dashboards de los servicios

### Gitea Actions CI/CD Setup

Para habilitar pruebas automatizadas con API keys en Gitea Actions:

#### 1. Store Secrets in Gitea

Navigate to your repository settings:

```
https://your-gitea-instance/your-org/quasar/settings/secrets/actions
```

Add these secrets:

- `IGDB_CLIENT_ID` (from Twitch Developer Console)
- `IGDB_CLIENT_SECRET` (from Twitch Developer Console)
- `RAWG_API_KEY` (from RAWG settings)
- `THEGAMESDB_API_KEY` (from TheGamesDB API)
- `SCREENSCRAPER_USERNAME` (from ScreenScraper)
- `SCREENSCRAPER_PASSWORD` (from ScreenScraper)

#### 2. Workflow Configuration

The `.gitea/workflows/ci.yml` workflow automatically:

- ✅ Installs dependencies
- ✅ Runs linting checks
- ✅ Executes backend tests (Vitest)
- ✅ Executes frontend tests (Vitest)
- ✅ Starts backend + frontend servers
- ✅ Runs E2E tests (Playwright) with real metadata APIs
- ✅ Uploads test reports on failure

#### 3. Testing Flow

1. **Push** code to `main` or `develop`
2. **Gitea Actions** picks up the `.gitea/workflows/ci.yml`
3. **Secrets are injected** as environment variables
4. **E2E tests** fetch real metadata from APIs (using injected secrets)
5. **Build fails** if any test fails (prevents broken code)

#### 4. Local Development

For local testing, use `.env.local`:

```bash
IGDB_CLIENT_ID=your_local_id
IGDB_CLIENT_SECRET=your_local_secret
RAWG_API_KEY=your_local_key
THEGAMESDB_API_KEY=your_local_key
SCREENSCRAPER_USERNAME=your_username
SCREENSCRAPER_PASSWORD=your_password
```

**Note:** CI/CD uses Gitea Secrets (not `.env` files), so never commit real credentials.

### Troubleshooting

**"IGDB_CLIENT_ID not found"** → Check `.env` file exists and has correct format

**"429 Too Many Requests"** → Rate limit exceeded, wait and retry

**"Invalid API Key"** → Copy key exactly (no spaces), verify it's active on service website

**"ScreenScraper authentication failed"** → Check donation level and account status

---

## Fuentes

- IGDB API docs: https://api-docs.igdb.com/ — TOS: https://www.twitch.tv/p/legal/developer-agreement/
- RAWG API & TOS: https://rawg.io/apidocs / https://rawg.io/tos_api
- TheGamesDB API / repo: https://api.thegamesdb.net/ / https://github.com/TheGamesDB/TheGamesDBv2/blob/master/LICENSE
- ScreenScraper: https://www.screenscraper.fr/
- MobyGames API: https://www.mobygames.com/api/subscribe/
- PriceCharting API & Terms: https://www.pricecharting.com/api-documentation / https://www.pricecharting.com/page/terms-of-service
- IsThereAnyDeal docs/TOS: https://docs.isthereanydeal.com/
- eBay API License Agreement: https://developer.ebay.com/join/api-license-agreement

## Metadatos

- **Autor:** Quasar (investigación automatizada)
- **Fecha verificación:** 2026-02-07
- **Última actualización:** 2026-02-07

---

**Nota:** Si quieres, puedo preparar una matriz técnica (endpoints concretos, ejemplos de requests y una PoC de integración para 2 APIs prioritarias).