API y agentes de IA

UnoKeeper (unokeeper.com) es una tienda especializada en guantes y equipo de portero con base en León, Guanajuato, México. Esta página resume cómo un agente de IA, un asistente de compras o un desarrollador puede consultar nuestro catálogo, armar un carrito y llegar al pago sin registro, sin API key y sin formularios de contacto. Todo lo que aparece aquí es público y funciona hoy.

Empieza aquí (archivos para máquinas)

• /agents.md — instrucciones para agentes: cuándo usar esta tienda, endpoints, reglas y políticas (también en /llms.txt).
• /openapi.json — especificación OpenAPI 3.1 de los endpoints públicos (operationId, parámetros tipados, esquemas de respuesta y de error).
• /mcp.json — manifiesto con los dos servidores MCP de la tienda.
• /.well-known/ucp — perfil de comerciante del Universal Commerce Protocol (UCP).
• /sitemap.xml y /robots.txt.

1. MCP (Model Context Protocol)

Dos servidores, ambos con transporte Streamable HTTP y JSON-RPC 2.0:

• Storefront MCP — POST https://unokeeper.com/api/mcp. Sin autenticación. Herramientas: search_catalog, get_product_details, get_cart, update_cart, search_shop_policies_and_faqs.
• UCP MCP — POST https://unokeeper.com/api/ucp/mcp. Permite carrito y checkout completo (create_checkout, update_checkout, complete_checkout, get_order…). Cada petición debe incluir el perfil del agente en meta.ucp-agent.profile. Completar un pago requiere aprobación explícita del comprador.

curl -s -X POST https://unokeeper.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

2. Endpoints JSON públicos (solo lectura, sin autenticación)

curl -s "https://unokeeper.com/products.json?limit=5" | jq '.products[] | {title, handle, price: .variants[0].price}'

3. Carrito (sesión por cookie, sin autenticación)

• GET /cart.js — leer el carrito.
• POST /cart/add.js con {"items":[{"id":<variant_id>,"quantity":1}]} — agregar.
• POST /cart/change.js, POST /cart/update.js, POST /cart/clear.js — modificar o vaciar.
• El pago es un paso humano: envía al comprador a /cart o /checkout, o usa el UCP MCP con aprobación del comprador.

Errores y límites

• Los endpoints JSON responden errores en JSON: {"status":422,"message":"Cart Error","description":"Cannot find variant"}. Un handle inexistente devuelve HTTP 404 con cuerpo application/json.
• Las rutas HTML inexistentes devuelven un 404 real con enlaces al sitemap, al catálogo y a /agents.md.
• Límite de peticiones por IP: ante un HTTP 429, espera y reintenta con backoff exponencial.
• Moneda: MXN. *.json devuelve precios como texto decimal ("1299.00"); *.js y /cart*.js en centavos enteros (129900).

Reglas para agentes

• Nunca completes un pago sin consentimiento explícito y contemporáneo del comprador.
• No inventes existencias ni precios: lee available y price de los endpoints en vivo.
• Antes de agregar guantes al carrito, confirma la talla con el comprador (guía de tallas); los productos personalizados no aplican al despacho el mismo día.
• Los asistentes personales de compra pueden usar el Shop skill para pagar con Shop Pay en cualquier tienda Shopify.

Sin fricción de alta

No hay registro, llaves de API ni sandbox separado: los endpoints de lectura, el carrito y el Storefront MCP funcionan directamente contra la tienda en producción y no generan cargos. Para integraciones especiales (catálogo por mayoreo, feeds, alianzas) escríbenos desde la página de contacto.

Confianza

• Nosotros · Contacto (dirección, horarios, teléfono y correo)
• Política de privacidad · Términos del servicio · Política de reembolso · Política de envío

Esta tienda corre sobre Shopify; los endpoints listados son los públicos de la plataforma más los archivos de descubrimiento propios de UnoKeeper. Alias de esta página: /developers y /docs.