Molinet cal Flari — API pública de la tienda

Lectura del catálogo, búsqueda y carrito de la almazara Molinet cal Flari.

Superficie pública y sin autenticación de la tienda Shopify de Molinet cal Flari (aceite de oliva virgen extra arbequina D.O.P. Les Garrigues, Cervià de les Garrigues, Lleida).

Todos los endpoints de lectura funcionan sin credenciales: un agente puede consultar catálogo, precios y disponibilidad sin registrarse.

Para comprar, esta tienda implementa el Universal Commerce Protocol (UCP) sobre MCP. El descubrimiento está en /.well-known/ucp y el servidor MCP en POST /api/ucp/mcp. Ahí es donde se crean y pagan los pedidos; esta especificación no duplica esas operaciones porque son JSON-RPC, no REST.

La API la sirve la plataforma Shopify, no un backend propio.

Especificacion OpenAPI 3.1.0 legible por maquina: /openapi.json · version fijada en /openapi-v1.json · instrucciones para agentes en /agents.md · manifiesto MCP en /mcp.json

Autenticacion

Las operaciones de lectura no necesitan credenciales. Se pueden llamar directamente desde cualquier cliente, sin registro, sin clave y sin entorno de pruebas aparte: la tienda real responde.

Solo las operaciones ligadas a una cuenta de cliente usan OAuth 2.0 con PKCE. Los metadatos estan publicados y son legibles por maquina en /.well-known/oauth-authorization-server (RFC 8414) y /.well-known/oauth-protected-resource (RFC 9728). Ambitos:

openid — Identificador del cliente autenticado.
email — Correo electrónico del cliente.
customer-account-api:full — Acceso completo a la API de cuenta de cliente: pedidos y datos propios.
customer-account-mcp-api:full — Acceso completo a la API MCP de cuenta de cliente.

Endpoints

catalogo

Productos y colecciones. Sin autenticación.

Metodo	Ruta	operationId	Que hace
`GET`	`/products.json`	`listarProductos`	Lista los productos publicados
`GET`	`/collections.json`	`listarColecciones`	Lista las colecciones publicadas
`GET`	`/collections/{handle}/products.json`	`listarProductosDeColeccion`	Lista los productos de una colección
`GET`	`/recommendations/products.json`	`recomendarProductos`	Productos recomendados a partir de uno dado
`GET`	`/products/{handle}.json`	`obtenerProducto`	Ficha de un producto por handle

busqueda

Sugerencias de búsqueda. Sin autenticación.

Metodo	Ruta	operationId	Que hace
`GET`	`/search/suggest.json`	`sugerirBusqueda`	Sugerencias de búsqueda

carrito

Carrito de la sesión. Sin autenticación; usa cookie de sesión.

Metodo	Ruta	operationId	Que hace
`GET`	`/cart.js`	`obtenerCarrito`	Devuelve el carrito de la sesión

comercio-agentico

Compra vía UCP sobre MCP.

Metodo	Ruta	operationId	Que hace
`POST`	`/api/ucp/mcp`	`llamarMcpUcp`	Servidor MCP de comercio (Universal Commerce Protocol)
`GET`	`/.well-known/ucp`	`descubrirUcp`	Perfil UCP de la tienda y versiones admitidas
`GET`	`/.well-known/ucp/{version}`	`descubrirUcpVersionado`	Perfil UCP de una version concreta

Ejemplo

curl -s "https://molinetcalflari.com/products.json?limit=2"

Devuelve los productos con sus variantes y precios. El precio va como cadena decimal en euros. Para el carrito, los importes van en centimos.

Errores

Toda respuesta 4xx y 5xx trae el mismo sobre en JSON, con el codigo HTTP repetido dentro del cuerpo:

{
  "status": 404,
  "message": "Product not found",
  "description": "No product with id 1 is published in the online store"
}

status — Código HTTP repetido en el cuerpo.
message — Resumen corto y estable del error.
description — Explicación con el detalle concreto: qué hacer o qué faltaba.

Versionado y obsolescencia

Este documento se versiona por ruta: la version estable vive en https://molinetcalflari.com/openapi-v1.json, y /openapi.json apunta siempre a la ultima. Un cambio incompatible se publica en /openapi-v2.json y la ruta anterior sigue sirviendose al menos 6 meses. (La forma /v1/... no es posible aqui: Shopify solo resuelve redirecciones de un unico tramo de ruta.) El campo info.version lleva la fecha ISO de la revision. Una operacion que vaya a retirarse se marca antes con deprecated: true en esta misma especificacion, que es el campo estandar de OpenAPI para eso, y se mantiene sirviendo durante el plazo indicado. Hoy ninguna lo esta.

La capa de comercio se versiona aparte, por el propio protocolo UCP: las versiones admitidas se enumeran en GET /.well-known/ucp bajo supported_versions, cada una con su endpoint. Un agente debe negociar la version ahi y no dar por hecha la mas reciente.

Los endpoints de catalogo (/products.json y companeros) son superficie de plataforma de Shopify: su contrato lo fija Shopify, no esta tienda.