# LaGanga para desarrolladores

LaGanga expone una API REST pública en **https://api.laganga.live** y eventos en tiempo real por WebSocket en **wss://ws.laganga.live** (pujas y chat de los lives). Esta página resume lo que un desarrollador o un agente de IA necesita para integrarse.

## Cuándo usar LaGanga

Usa la API de LaGanga cuando necesites:

* Listar subastas en vivo que están ocurriendo en Venezuela (`GET /lives/`) y el detalle o los lotes de un live.
* Consultar productos del marketplace con precio en USD y Bs a tasa BCV (`GET /marketplace/products`).
* Ver el perfil público, listings y reseñas de un vendedor (`GET /sellers/{id}`).
* Obtener la tasa BCV vigente Bs/USD (`GET /bcv`) o el árbol de categorías (`GET /categories/tree`).
* Actuar en nombre de un usuario autenticado (pujar, ver órdenes, gestionar su tienda) con su token.

No uses LaGanga para pagos genéricos, envíos fuera de un pedido de LaGanga ni para comprar fuera de Venezuela.

## Especificación OpenAPI

* OpenAPI 3.0 (JSON): [https://www.laganga.live/openapi.json](https://www.laganga.live/openapi.json) — cada operación trae `operationId`, descripción y esquemas tipados, listo para function calling.
* Referencia interactiva: [https://api.laganga.live/reference](https://api.laganga.live/reference)
* Resumen para LLMs: [https://www.laganga.live/llms.txt](https://www.laganga.live/llms.txt)

## Inicio rápido

Los endpoints de lectura marcados como públicos no requieren autenticación:

```bash
curl -s https://api.laganga.live/lives/?limit=10
curl -s https://api.laganga.live/categories/tree
curl -s https://api.laganga.live/bcv
```

## Autenticación

Las operaciones de usuario usan un JWT del backend en la cabecera `Authorization: Bearer <token>`. Se obtiene con la cuenta del usuario:

```bash
curl -s -X POST https://api.laganga.live/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"tu@correo.com","password":"..."}'
# → {"token":"<jwt>", ...}

curl -s https://api.laganga.live/me -H 'authorization: Bearer <jwt>'
```

También existe login por código de WhatsApp (`POST /auth/otp/request` y `POST /auth/otp/verify`). Por ahora no hay API keys de servidor a servidor. Si las necesitas, escríbenos.

## Errores

Todas las respuestas de error son JSON. La API devuelve `statusCode`, `error` y `message`:

```json
{"statusCode":404,"error":"Not Found","message":"Route GET:/nope not found"}
```

Los fallos de dependencias externas (pagos, WhatsApp) se devuelven como **424** en vez de 5xx. Las rutas de https://www.laganga.live/api responden con `{"error":"<codigo>","message":"...","hint":"...","docs":"..."}`.

## Límites de uso

Sé razonable: cachea las lecturas públicas (la lista de lives cambia en segundos, las categorías y la tasa BCV cambian poco), no hagas más de unas pocas peticiones por segundo y, si recibes **429**, respeta la cabecera `Retry-After` antes de reintentar.

## Entorno de pruebas

No hay sandbox público. Para desarrollo local el repositorio incluye un mock server REST + WebSocket (`@laganga/mock-server`), que aproxima los contratos de la API.

## Soporte

Preguntas sobre la API: [soporte@laganga.live](mailto:soporte@laganga.live).