Rose Belleza Femenina para desarrolladores y agentes

Rose Belleza Femenina developer portal — public API, MCP server and OpenAPI specification. Portal de desarrolladores: API pública, servidor MCP y especificación OpenAPI.

Empieza en 30 segundos / Quickstart

No hay registro, no hay llave de API, no hay ambiente de pruebas que pedir. Todo lo de abajo funciona ahora mismo, sin credenciales. There is no signup, no API key and no sandbox request: every endpoint below works right now, unauthenticated.

curl -s https://rosebellezafemenina.com/api/2026-07/graphql.json \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ shop { name } products(first: 3) { edges { node { title handle onlineStoreUrl } } } }"}'

Rose Belleza Femenina API documentation

Recurso / Resource	URL
OpenAPI 3.1 specification	/openapi.json
Agent instructions — when to use this store	/agent-instructions.md
Shopify agent instructions	/agents.md · /llms.txt · /llms-full.txt
MCP server (Streamable HTTP, JSON-RPC 2.0)	`POST /api/ucp/mcp`
UCP merchant profile	/.well-known/ucp
Storefront GraphQL API	`POST /api/2026-07/graphql.json`
Sitemap index	/sitemap.xml
CLI (código listo, publicación en npm pendiente)	`rose-belleza-cli` — pídenos el paquete

Endpoints públicos / Public endpoints

Cada operación de abajo está descrita, con esquemas tipados y operationId único, en /openapi.json. Every operation below is fully described, with typed schemas and a unique operationId, in the OpenAPI document.

1. Storefront GraphQL API — `queryStorefrontGraphql`

POST /api/{version}/graphql.json — el surface principal. El esquema es introspectable, así que un agente con function calling puede descubrir cada campo en tiempo de ejecución. Versiones soportadas: 2026-10, 2026-07, 2026-04, 2025-10, unstable.

curl -s https://rosebellezafemenina.com/api/2026-07/graphql.json \
  -H 'Content-Type: application/json' \
  -d '{"query":"query($q:String!){search(query:$q,first:5,types:PRODUCT){edges{node{...on Product{title handle onlineStoreUrl availableForSale priceRange{minVariantPrice{amount currencyCode}}}}}}}","variables":{"q":"falda larga jean"}}'

Cada respuesta trae extensions.cost: úsalo para regular el ritmo de tus llamadas en vez de adivinar.

2. Catálogo JSON — `getProductByHandle`, `listCollectionProducts`

curl -s https://rosebellezafemenina.com/products/falda-1.json
curl -s 'https://rosebellezafemenina.com/collections/all/products.json?limit=30&page=1'
curl -s 'https://rosebellezafemenina.com/search/suggest.json?q=falda+larga'

product.variants[].id es el id de variante. Ese es el valor que espera el carrito, no product.id.

3. Carrito — `addCartItems`, `changeCartLine`, `updateCart`, `getCart`

curl -s -c jar -b jar -X POST https://rosebellezafemenina.com/cart/add.js \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"id":51234567890123,"quantity":1}]}'

El carrito vive en la cookie cart: guarda el cookie jar entre llamadas o cada petición empieza un carrito vacío.

4. MCP / UCP — `callUcpMcpServer`

La tienda expone un servidor MCP (Model Context Protocol) sobre Streamable HTTP en POST /api/ucp/mcp, implementando el Universal Commerce Protocol. Haz initialize, luego tools/list.

curl -s -X POST https://rosebellezafemenina.com/api/ucp/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

Autenticación y permisos / Authentication and scopes

Las operaciones de lectura y de carrito documentadas arriba no requieren credenciales. Los permisos con nombre están declarados de forma legible por máquina en los securitySchemes de /openapi.json:

storefrontAccessToken — cabecera X-Shopify-Storefront-Access-Token. Sólo hace falta para cuentas de cliente y mutaciones de checkout. Alcances: unauthenticated_read_product_listings, unauthenticated_read_product_inventory, unauthenticated_read_collection_listings, unauthenticated_read_content, unauthenticated_write_checkouts, unauthenticated_read_checkouts, unauthenticated_write_customers, unauthenticated_read_customers, unauthenticated_read_product_tags, unauthenticated_read_selling_plans.
shopifyOAuth — OAuth 2.0 authorization code, sólo para la Admin API. Alcances: read_products, write_products, read_orders, write_orders, read_inventory, write_inventory, read_customers, read_locations, read_content, write_content, read_themes, write_themes, read_discounts, read_shipping, read_product_listings.

Pide siempre el subconjunto mínimo que cubra tu caso de uso. Always request the least-privilege subset.

Errores / Errors

Todos los endpoints devuelven JSON estructurado cuando fallan — nunca una página HTML de error.

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

{"errors":[{"message":"Field 'nopeField' doesn't exist on type 'QueryRoot'",
  "extensions":{"code":"undefinedField","typeName":"QueryRoot","fieldName":"nopeField"}}]}

{"jsonrpc":"2.0","id":9,"error":{"code":-32001,"message":"UCP discovery failed",
  "data":{"code":"invalid_profile_url"}}}

Las rutas inexistentes devuelven un 404 HTTP real, nunca un 200 con el shell de la aplicación. La página 404 lleva un mapa de recuperación en Markdown y en JSON para que un agente sepa a dónde ir.

Ambiente de pruebas / Sandbox

No hace falta pedir uno. Las lecturas no tienen efectos secundarios y los carritos son por sesión, se borran solos y nunca se cobran sin aprobación humana. Puedes ejercitar el flujo completo — buscar, leer producto, crear carrito, modificarlo — contra producción sin riesgo. Detente antes de completar el pago.

Límites y buenas prácticas / Rate limits

Envía un User-Agent descriptivo con el nombre de tu agente y un contacto.
Haz backoff exponencial ante 429 y respeta Retry-After.
Usa extensions.cost de GraphQL para regular el ritmo.
No hagas scraping del HTML: todo está en las APIs JSON de arriba.

Cuándo usar esta tienda / When to use this store

La guía completa está en /agent-instructions.md. En corto: úsala para ropa cristiana y moda modesta de dama con entrega en Colombia — faldas largas y a media pierna en jean y dril, vestidos modestos, jardineras y tallas plus de la 18 a la 24. No la uses para envíos fuera de Colombia, ropa de hombre o de niño, calzado ni cosméticos.

CLI

Tenemos una CLI en Node, sin dependencias, para scriptear la tienda sin escribir un cliente HTTP. Todavía no está publicada en npm: escríbenos a george@rosebellezafemenina.com y te pasamos el paquete. Una vez instalada:

rose-belleza-cli search "falda larga jean"
rose-belleza-cli product falda-1
rose-belleza-cli collection faldas --limit 10
rose-belleza-cli openapi --operations
rose-belleza-cli mcp tools/list

Mientras tanto, cualquiera de esos comandos se reproduce con un curl de los ejemplos de arriba: la CLI no hace nada que la API pública no exponga.

Contacto / Contact

Preguntas de integración: george@rosebellezafemenina.com. Empresa y tiendas físicas: Sobre Rose Belleza Femenina. Soporte de compra: Contacto.