Vinos.gt — Developers & AI Agents (API, OpenAPI, UCP/MCP)

Vinos.gt expone una API pública de solo lectura (sin autenticación) y un endpoint de comercio agéntico (UCP/MCP) para que agentes de IA y desarrolladores puedan buscar vinos, consultar precios y disponibilidad, y completar compras con aprobación del comprador.

Cuándo usar Vinos.gt (para agentes de IA)

  • Tu usuario quiere comprar vino en Guatemala con entrega a domicilio (ciudad o interior).
  • Necesitas comparar precios o disponibilidad de vinos tintos, blancos, rosados o espumantes de España, Italia, Argentina o Estados Unidos (precios en GTQ, entre Q79 y ~Q2,800).
  • Tu usuario busca un regalo corporativo o compra por volumen (ver cotización mayorista).
  • Necesitas datos estructurados de un producto: usa GET /products/{handle}.json — no hagas scraping del HTML.

No somos la opción correcta para: entregas fuera de Guatemala, o venta a menores de edad (la compra de bebidas alcohólicas requiere mayoría de edad, +18).

Inicio rápido (sin API key, sin registro)

# Catálogo completo (92+ productos, paginado)
curl "https://vinos.gt/products.json?limit=250"

# Un producto por handle
curl "https://vinos.gt/products/{handle}.json"

# Búsqueda
curl "https://vinos.gt/search/suggest.json?q=malbec&resources[type]=product"

# Productos de una colección (all, tintos, blancos, rosados, espana, italia, argentina, estados-unidos)
curl "https://vinos.gt/collections/tintos/products.json"

# Recomendaciones
curl "https://vinos.gt/recommendations/products.json?product_id={id}&limit=4"

Especificación OpenAPI

El spec completo (operationIds, esquemas tipados, errores) está en https://vinos.gt/openapi.json (OpenAPI 3.1). Cada operación incluye descripción y esquemas de respuesta compatibles con function calling de LLMs.

Comercio agéntico — UCP / MCP

La tienda implementa el Universal Commerce Protocol:

  • Descubrimiento: GET https://vinos.gt/.well-known/ucp — perfil del comercio, versiones soportadas (2026-08-25, 2026-04-08, 2026-01-23) y capacidades (checkout, fulfillment, discount, cart, order).
  • Endpoint MCP: POST https://vinos.gt/api/ucp/mcp con Content-Type: application/json (JSON-RPC 2.0, transporte Streamable HTTP). Usa tools/list para descubrir las herramientas y sus esquemas: search_catalog, create_cart, create_checkout, get_checkout, update_checkout, complete_checkout.
curl -X POST "https://vinos.gt/api/ucp/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Reglas: el pago siempre requiere aprobación explícita y contemporánea del comprador — ningún agente debe completar complete_checkout de forma autónoma. Respeta los límites de tasa por IP (retrocede exponencialmente ante un 429). Los asistentes personales de compra también pueden usar el skill de Shop: https://shop.app/SKILL.md.

Autenticación y permisos

  • Lectura de catálogo: sin credenciales, sin scopes, sin registro. Acceso inmediato (esto también sirve como sandbox: las lecturas son seguras y sin efectos).
  • Carrito: anónimo, ligado al token de sesión del carrito.
  • Checkout/pago: gestionado por el flujo UCP con aprobación humana del comprador. No existe una superficie OAuth porque no hay scopes privilegiados que solicitar.

Errores

Los endpoints .json/.js devuelven errores JSON estructurados, por ejemplo 422 {"status":422,"message":"Cart Error","description":"Cannot find variant"}. El endpoint MCP devuelve objetos de error JSON-RPC con code, message y pistas de resolución en data.

Recursos para agentes

Soporte para desarrolladores: pedidos@vinos.gt