Developers — API de K Detalle

Recursos para desarrolladores y agentes de IA que quieran integrarse con K Detalle. La documentación técnica está en inglés.

Overview

K Detalle is an online store for artisanal candles, party favors (recuerdos) and religious keepsakes, based in Guadalajara, Mexico. Everything below is public and requires no API key, account, or sales call — you can make your first request in seconds. Prices are in MXN.

OpenAPI specification: https://www.kdetalle.com.mx/openapi.json
Agent instructions (agents.md): https://www.kdetalle.com.mx/agents.md (also at /llms.txt)
MCP endpoint (Streamable HTTP): POST https://www.kdetalle.com.mx/api/mcp
UCP shopping MCP endpoint: POST https://www.kdetalle.com.mx/api/ucp/mcp
UCP discovery: https://www.kdetalle.com.mx/.well-known/ucp
Sitemap: https://www.kdetalle.com.mx/sitemap.xml

Quickstart (zero auth)

List products:

curl "https://www.kdetalle.com.mx/products.json?limit=5"

Get one product by handle:

curl "https://www.kdetalle.com.mx/products/velas-virgen-de-guadalupe.json"

Search:

curl "https://www.kdetalle.com.mx/search/suggest.json?q=vela&resources%5Btype%5D=product"

Discover MCP tools:

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

REST endpoints

GET /products.json — list products (limit ≤ 250, page)
GET /products/{handle}.json — one product with variants and prices
GET /collections/{handle}/products.json — products in a collection (use all for the full catalog)
GET /search/suggest.json?q=… — predictive search
GET /cart.js, POST /cart/add.js, POST /cart/update.js, POST /cart/change.js, POST /cart/clear.js — session cart (AJAX API)

Full parameter and schema details, with operation IDs and typed responses, are in the OpenAPI spec.

MCP (Model Context Protocol)

The store runs an MCP server over Streamable HTTP at /api/mcp (no auth). Tools: search_shop_policies_and_faqs, get_cart, update_cart. UCP-conforming catalog and checkout tools (search_catalog, lookup_catalog, get_product, create_cart, create_checkout, update_checkout, complete_checkout) live at /api/ucp/mcp. Start with initialize, then tools/list.

Agent checkout (UCP)

This store supports the Universal Commerce Protocol natively. Fetch /.well-known/ucp to confirm capabilities and endpoints. Checkout requires explicit human buyer approval of payment — agents must never complete payment without contemporaneous consent. You can also use Shopify's official ucp CLI against this store, e.g.:

ucp catalog search --business https://www.kdetalle.com.mx --set /query='vela guadalupe' --format md

Authentication and scopes

Catalog, search, cart and MCP endpoints need no authentication. Customer account data (order history) uses OAuth 2.0 with PKCE; machine-readable metadata:

Protected resource (RFC 9728): /.well-known/oauth-protected-resource
Authorization server (RFC 8414, includes scopes_supported): https://shopify.com/authentication/65977155695/.well-known/oauth-authorization-server
Scopes: openid, email, customer-account-api:full, customer-account-mcp-api:full

Errors and rate limits

JSON endpoints return structured JSON errors, e.g. POST /cart/add.js with an invalid variant returns HTTP 422:

{"status":422,"message":"Cart Error","description":"Cannot find variant"}

MCP endpoints return JSON-RPC 2.0 error objects. Nonexistent pages return a real HTTP 404. Requests are rate-limited per IP — back off exponentially on HTTP 429.

Sandbox / testing

All read endpoints are safe to call against production. To test cart and checkout flows without a real store, use Shopify's free mock API at mock.shop (same shapes, no auth), then point your integration at this store.