Tienda headless

Andrea entra a tu frontend, elige un polo y lo paga. Esta guía arma ese flujo con Storefront API: catálogo, ficha de producto, carrito y checkout.

Requisitos

• El slug o un dominio de la tienda, en x-Store-Domain. No necesitas token.
• Productos publicados en la tienda.

Lista productos

GET /v1/products devuelve una página del catálogo publicado y sus filtros. Envía x-Store-Domain en cada llamada.

curl "https://storefront.ecomiq.pe/v1/products?page=1&pageSize=24" \
  -H "x-Store-Domain: mi-tienda"

Cada producto trae name, slug, price e imageUrl. Avanza page hasta totalPages. Si la vista no muestra filtros, agrega includeFilters=false. Más en Paginación.

Muestra un producto

GET /v1/products/{slug} devuelve la ficha completa: variantes, imágenes, especificaciones y stock. El slug es el de la URL de la tienda.

curl https://storefront.ecomiq.pe/v1/products/polo-de-algodon \
  -H "x-Store-Domain: mi-tienda"

Cada variante trae id, sku, price, isAvailable y options. Guarda el id de la variante elegida.

Crea un carrito

POST /v1/carts crea el carrito. La respuesta trae token, que identifica el carrito en las llamadas siguientes.

curl -X POST https://storefront.ecomiq.pe/v1/carts \
  -H "x-Store-Domain: mi-tienda" \
  -H "Content-Type: application/json" \
  -d '{ "email": "andrea@example.com" }'

Agrega artículos

Envía el id de la variante y la cantidad. La respuesta devuelve el carrito con items y totals.

curl -X POST https://storefront.ecomiq.pe/v1/carts/<cart-token>/items \
  -H "x-Store-Domain: mi-tienda" \
  -H "Content-Type: application/json" \
  -d '{ "variantId": "7204558912004325377", "quantity": 2 }'

Prepara el checkout

Agrega los datos de la compra con estas operaciones:

Luego, GET /v1/carts/{cartToken}/checkout devuelve el carrito y los métodos de pago habilitados en paymentMethods.methods.

curl https://storefront.ecomiq.pe/v1/carts/<cart-token>/checkout \
  -H "x-Store-Domain: mi-tienda"

Muestra paymentMethods.methods al comprador. Guarda el code que elija en paymentMethodCode.

Crea el pedido

Envía el code del método de pago. El checkout crea los pedidos del carrito.

curl -X POST https://storefront.ecomiq.pe/v1/carts/<cart-token>/checkout \
  -H "x-Store-Domain: mi-tienda" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethodCode": "<payment-method-code>" }'

La respuesta trae orderId, orderNumber y el estado del pago en payment. Un carrito con varios vendedores puede generar varios pedidos: están en orderIds.

Siguientes pasos

• Catálogo: búsqueda, filtros y variantes.
• Carrito: cupones, direcciones y envío.
• Checkout y pago: redirección, pago manual y estado del pedido.
• Organización, tienda y vendedor: cómo se elige la tienda en cada llamada.