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://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
Resumen para LLMs: https://laganga.live/llms.txt

Inicio rápido

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

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:

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:

{"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://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.