{ "openapi": "3.1.0", "info": { "title": "Dintass Motori — API pública de la tienda", "version": "2026-09-25", "summary": "Endpoints JSON públicos de dintass.cl (catálogo, búsqueda, carro) y servidores MCP para agentes.", "description": "Dintass Motori (Santiago, Chile) vende maquinaria industrial, metrología INSIZE y herramientas de corte. La tienda corre en Shopify: esta especificación describe los endpoints públicos que ya existen en https://dintass.cl, tal como responden hoy.\n\n- Catálogo y búsqueda: lectura pública, sin autenticación.\n- Carro: sin autenticación; el carro se identifica con la cookie `cart` que la tienda entrega en la primera respuesta.\n- Compra: el pago siempre ocurre en el checkout de Shopify y requiere la aprobación del comprador. Enlace directo a un carro: `https://dintass.cl/cart/{variant_id}:{cantidad}`.\n- Productos \"Por importación\" (a pedido) no se compran en el carro: se cotizan en https://dintass.cl/pages/cotizar o por WhatsApp +56 9 7609 0060.\n- Todos los endpoints responden `Content-Type: application/json`. (Shopify también ofrece variantes `.js`, como `/cart.js` o `/products/{handle}.js`, con JSON pero `Content-Type: text/javascript`; usa las `.json`.)\n- Precios en pesos chilenos (CLP) con IVA. En catálogo y búsqueda vienen como texto en pesos (\"27760\"); en `/cart.json`, como enteros multiplicados por 100 (27760 CLP = 2776000).\n- Errores: los endpoints de carro y búsqueda responden JSON `{status, message, description}` o, si el cuerpo está mal formado, `{errors}` (ver el esquema `Error`), con una pista de resolución en cada respuesta documentada. Los endpoints de catálogo responden 404 sin cuerpo cuando el producto no existe.\n\nMás contexto para agentes: https://dintass.cl/agents.md, https://dintass.cl/pages/llms-txt y el catálogo completo en https://dintass.cl/pages/llms-full.", "contact": { "name": "Dintass Motori", "url": "https://dintass.cl/pages/contacto", "email": "maquinaria@dintassmotori.cl" }, "termsOfService": "https://dintass.cl/pages/terminos-y-condiciones" }, "externalDocs": { "description": "Instrucciones para agentes (UCP y MCP)", "url": "https://dintass.cl/agents.md" }, "servers": [ { "url": "https://dintass.cl", "description": "Tienda en producción" } ], "tags": [ { "name": "catalogo", "description": "Productos y colecciones (lectura pública)" }, { "name": "busqueda", "description": "Búsqueda predictiva de productos" }, { "name": "carro", "description": "Carro de compras de la sesión (cookie `cart`)" }, { "name": "agentes", "description": "Descubrimiento y servidores MCP para agentes de IA" } ], "security": [ {} ], "paths": { "/products.json": { "get": { "tags": [ "catalogo" ], "operationId": "listProducts", "summary": "Lista paginada de productos publicados", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Página de productos. Una página vacía (`products: []`) indica el final del catálogo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } } } } }, "/collections/{handle}/products.json": { "get": { "tags": [ "catalogo" ], "operationId": "listCollectionProducts", "summary": "Productos de una colección", "description": "Colecciones principales: `maquinas`, `metrologia-insize`, `herramientas-y-accesorios`, `entrega-inmediata`, `por-importacion`, `all`. Una colección inexistente responde 200 con `products: []`.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" }, "example": "metrologia-insize" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Página de productos de la colección", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } } } } }, "/products/{handle}.json": { "get": { "tags": [ "catalogo" ], "operationId": "getProduct", "summary": "Detalle de un producto con sus variantes", "description": "Usa el `id` de la variante para agregar al carro.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" }, "example": "pie-de-metro-digital-150mm-o-6-insize" } ], "responses": { "200": { "description": "Producto", "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/CatalogProduct" } } } } } }, "404": { "description": "No existe un producto publicado con ese handle (respuesta vacía). Resolución: busca el handle correcto con `/search/suggest.json`." } } } }, "/search/suggest.json": { "get": { "tags": [ "busqueda" ], "operationId": "searchProducts", "summary": "Búsqueda predictiva", "description": "Funciona con o sin tildes. Para buscar un código exacto (p. ej. `3227-504`), escríbelo tal cual.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 }, "example": "micrometro" }, { "name": "resources[type]", "in": "query", "schema": { "type": "string", "default": "product", "examples": [ "product", "product,collection,page" ] } }, { "name": "resources[limit]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 10 } } ], "responses": { "200": { "description": "Resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResults" } } } }, "422": { "description": "Falta el parámetro `q` o está vacío. Resolución: envía `q` con al menos un carácter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 422, "message": "Invalid parameter error", "description": "param is missing or the value is empty: q" } } } } } } }, "/cart.json": { "get": { "tags": [ "carro" ], "operationId": "getCart", "summary": "Carro actual", "security": [ {}, { "cartSession": [] } ], "responses": { "200": { "description": "Carro (vacío si no se envía la cookie `cart`). Precios en CLP × 100.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } } } } }, "/cart/add.json": { "post": { "tags": [ "carro" ], "operationId": "addToCart", "summary": "Agregar variantes al carro", "security": [ {}, { "cartSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "quantity" ], "properties": { "id": { "type": "integer", "description": "ID de la variante (de `/products/{handle}.json`)" }, "quantity": { "type": "integer", "minimum": 1 } } } } } }, "example": { "items": [ { "id": 52699011449112, "quantity": 1 } ] } } } }, "responses": { "200": { "description": "Líneas agregadas. En esta respuesta los precios vienen en CLP sin multiplicar; para totales lee `/cart.json`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartLine" } } } } } } }, "400": { "description": "Cuerpo inválido o sin `items`. Resolución: envía `{\"items\":[{\"id\":,\"quantity\":}]}` con `Content-Type: application/json`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": "Parameter Missing or Invalid" } } } }, "422": { "description": "La variante no existe, no está disponible o no hay stock suficiente. Resolución: obtén un `id` válido desde `/products/{handle}.json` y revisa `available`; los productos \"Por importación\" se cotizan en /pages/cotizar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 422, "message": "Cart Error", "description": "Cannot find variant" } } } } } } }, "/cart/change.json": { "post": { "tags": [ "carro" ], "operationId": "changeCartLine", "summary": "Cambiar la cantidad de una línea (0 la elimina)", "security": [ {}, { "cartSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quantity" ], "properties": { "id": { "type": "string", "description": "`key` de la línea del carro" }, "line": { "type": "integer", "minimum": 1, "description": "Posición de la línea (desde 1), alternativa a `id`" }, "quantity": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Carro actualizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "422": { "description": "La línea o variante no existe. Resolución: lee `/cart.json` y usa el `key` o la posición (`line`) de la línea.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 422, "message": "Cart Error", "description": "Cannot find variant" } } } } } } }, "/cart/update.json": { "post": { "tags": [ "carro" ], "operationId": "updateCart", "summary": "Actualizar cantidades, nota o atributos del carro", "description": "Atributos que usa la tienda: `tipo_documento` (`boleta` o `factura`), `rut` (obligatorio para boleta y factura, formato 12.345.678-9), `razon_social`, `giro` y `direccion_facturacion` (solo factura).", "security": [ {}, { "cartSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "updates": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Mapa `variant_id` → cantidad" }, "note": { "type": "string" }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } } } }, "example": { "attributes": { "tipo_documento": "boleta", "rut": "12.345.678-5" } } } } }, "responses": { "200": { "description": "Carro actualizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "422": { "description": "Alguna variante de `updates` no existe. Resolución: usa IDs de variante de `/products/{handle}.json`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 422, "message": "Cart Error", "description": "Cannot find variant" } } } } } } }, "/api/mcp": { "post": { "tags": [ "agentes" ], "operationId": "storefrontMcp", "summary": "Servidor MCP de la tienda (JSON-RPC 2.0)", "description": "Model Context Protocol sobre HTTP. Hoy expone `search_shop_policies_and_faqs` (políticas, despacho, devoluciones y preguntas frecuentes). Para catálogo, carro y checkout usa `/api/ucp/mcp`. Empieza con `tools/list`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } } } }, "responses": { "200": { "description": "Respuesta JSON-RPC 2.0. Los errores de protocolo vienen con HTTP 200 en el campo `error` (p. ej. -32600 JSON inválido, -32601 método inexistente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } } } }, "/api/ucp/mcp": { "post": { "tags": [ "agentes" ], "operationId": "ucpMcp", "summary": "Universal Commerce Protocol (UCP) sobre MCP", "description": "Herramientas `search_catalog`, `lookup_catalog`, `get_product`, carro (`create_cart`, `get_cart`, `update_cart`, `cancel_cart`), checkout (`create_checkout`, `update_checkout`, `complete_checkout`, …) y `get_order`, según https://ucp.dev. Descubrimiento en `/.well-known/ucp`. Las operaciones de invitado funcionan sin token; para actuar en nombre de un cliente con cuenta, pide un token OAuth 2.0 con el scope mínimo necesario (metadatos RFC 9728 en `/.well-known/oauth-protected-resource`). El pago siempre requiere la aprobación del comprador. Las llamadas a herramientas (`tools/call`) exigen que el agente se identifique con la URL de su perfil UCP, según https://ucp.dev; sin ella la respuesta es 422 `invalid_profile_url`.", "security": [ {}, { "shopifyCustomerAccount": [ "dev.ucp.shopping.catalog.search:read" ] }, { "shopifyCustomerAccount": [ "dev.ucp.shopping.checkout:manage" ] }, { "shopifyCustomerAccountOidc": [ "openid", "email" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } } } }, "responses": { "200": { "description": "Respuesta JSON-RPC 2.0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "400": { "description": "Cuerpo que no es JSON válido. Resolución: envía un objeto JSON-RPC 2.0 con `Content-Type: application/json`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" }, "example": { "jsonrpc": "2.0", "id": 0, "error": { "code": -32600, "message": "Invalid Request", "data": "Invalid JSON in request body." } } } } }, "422": { "description": "La herramienta no se pudo ejecutar; el detalle viene en `error.data.code`. Con `invalid_profile_url`, resolución: incluye la URL del perfil UCP del agente (ver https://ucp.dev) y reintenta; `error.data.continue_url` lleva a la tienda para terminar la compra en el navegador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" }, "example": { "jsonrpc": "2.0", "id": 1, "error": { "code": -32001, "message": "UCP discovery failed", "data": { "code": "invalid_profile_url", "content": "Unable to fetch agent profile: Missing profile uri", "continue_url": "https://dintass.cl/" } } } } } } } } }, "/.well-known/ucp": { "get": { "tags": [ "agentes" ], "operationId": "ucpDiscovery", "summary": "Perfil de descubrimiento UCP (versiones, servicios y capacidades)", "responses": { "200": { "description": "Perfil UCP", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "tags": [ "agentes" ], "operationId": "protectedResourceMetadata", "summary": "Metadatos del recurso protegido (RFC 9728)", "responses": { "200": { "description": "Metadatos con el servidor de autorización", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "cartSession": { "type": "apiKey", "in": "cookie", "name": "cart", "description": "Cookie de sesión del carro. La tienda la crea en la primera respuesta; reenvíala para seguir usando el mismo carro. No es una credencial ni da acceso a datos de clientes." }, "shopifyCustomerAccount": { "type": "oauth2", "description": "Servidor de autorización de cuentas de cliente de la tienda (Shopify). Scopes tomados de https://shopify.com/authentication/100426973464/.well-known/oauth-authorization-server. Pide solo los scopes que necesites.", "flows": { "authorizationCode": { "authorizationUrl": "https://shopify.com/authentication/100426973464/oauth/authorize", "tokenUrl": "https://shopify.com/authentication/100426973464/oauth/token", "scopes": { "openid": "Identificar al cliente (OpenID Connect)", "email": "Leer el correo del cliente", "dev.ucp.shopping.catalog.search:read": "Buscar en el catálogo vía UCP en nombre del cliente", "dev.ucp.shopping.checkout:manage": "Crear y actualizar checkouts vía UCP en nombre del cliente (el pago sigue requiriendo su aprobación)", "customer-account-mcp-api:full": "Acceso completo del cliente a su cuenta vía MCP (pedidos, direcciones)", "customer-account-api:full": "Acceso completo del cliente a su cuenta vía Customer Account API" } } } }, "shopifyCustomerAccountOidc": { "type": "openIdConnect", "openIdConnectUrl": "https://shopify.com/authentication/100426973464/.well-known/openid-configuration", "description": "Descubrimiento OpenID Connect del mismo servidor de autorización." } }, "parameters": { "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 30 } }, "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } }, "schemas": { "Error": { "description": "Error de los endpoints de carro y búsqueda. Errores de negocio (variante inexistente, sin stock, parámetro vacío): `{status, message, description}`. Cuerpo JSON mal formado: `{errors}`.", "oneOf": [ { "type": "object", "title": "ErrorDetallado", "required": [ "status", "message", "description" ], "properties": { "status": { "type": [ "integer", "string" ], "description": "Código HTTP (422) o código de error en texto", "examples": [ 422 ] }, "message": { "type": "string", "description": "Tipo de error", "examples": [ "Cart Error" ] }, "description": { "type": "string", "description": "Detalle legible del error", "examples": [ "Cannot find variant" ] } } }, { "type": "object", "title": "ErrorSimple", "required": [ "errors" ], "properties": { "errors": { "type": [ "string", "object" ], "description": "Mensaje, o mapa campo → mensajes", "examples": [ "Parameter Missing or Invalid" ] } } } ] }, "ProductList": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } } } }, "CatalogProduct": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "handle": { "type": "string" }, "body_html": { "type": "string" }, "vendor": { "type": "string", "examples": [ "INSIZE", "DTM" ] }, "product_type": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": [ "string", "null" ] }, "price": { "type": "string", "description": "CLP con IVA, como texto", "examples": [ "27760.00" ] }, "compare_at_price": { "type": [ "string", "null" ] }, "available": { "type": "boolean" } } } }, "images": { "type": "array", "items": { "type": "object", "properties": { "src": { "type": "string", "format": "uri" } } } } } }, "SearchResults": { "type": "object", "properties": { "resources": { "type": "object", "properties": { "results": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "handle": { "type": "string" }, "url": { "type": "string" }, "vendor": { "type": "string" }, "available": { "type": "boolean" }, "price": { "type": "string", "description": "CLP con IVA, como texto" } } } } } } } } } }, "CartLine": { "type": "object", "properties": { "key": { "type": "string" }, "id": { "type": "integer", "description": "ID de la variante" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "integer", "description": "CLP × 100 en /cart.json" }, "line_price": { "type": "integer", "description": "CLP × 100 en /cart.json" }, "variant_id": { "type": "integer" }, "product_title": { "type": "string" } } }, "Cart": { "type": "object", "properties": { "token": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "item_count": { "type": "integer" }, "total_price": { "type": "integer", "description": "CLP × 100" }, "currency": { "type": "string", "const": "CLP" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartLine" } } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "integer", "string" ] }, "method": { "type": "string", "examples": [ "tools/list", "tools/call" ] }, "params": { "type": "object" } } }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "integer", "string", "null" ] }, "result": {}, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} } } } } } } }