---
name: ecomiq-storefront-api
description: Construye una tienda headless con Ecomiq Storefront API (https://storefront.ecomiq.pe y GraphQL) — catálogo, ficha de producto, carrito, checkout, cuentas de cliente y URLs. Úsalo cuando haya que mostrar productos de una tienda Ecomiq en un frontend propio o en una app, o aparezcan x-Store-Domain, /v1/carts o /graphql.
---

# Ecomiq Storefront API

Storefront API es la API pública de una tienda: catálogo, carrito, checkout y
cuentas de cliente.

- URL base: `https://storefront.ecomiq.pe`. Las rutas empiezan en `/v1/`.
- GraphQL (solo lecturas): `POST https://storefront.ecomiq.pe/graphql`
- Referencia: https://docs.ecomiq.pe/es/docs/storefront
- OpenAPI: https://docs.ecomiq.pe/openapi/storefront.openapi.json
- Índice para IA: https://docs.ecomiq.pe/llms.txt

Antes de usar una operación que no está aquí, búscala en el OpenAPI. Nunca
inventes rutas ni campos.

## Elegir la tienda

Envía el slug o un dominio de la tienda en `x-Store-Domain` en cada llamada.
Catálogo, carrito y checkout son públicos: no usan token.

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

## Catálogo

- `GET /v1/products?page=&pageSize=` devuelve `products`, `totalCount`,
  `totalPages` y `filters`. Filtra con `categoryId` y los demás parámetros del
  OpenAPI.
- `GET /v1/products/{slug}` devuelve la ficha con variantes e imágenes.
- `GET /v1/categories/{slug}` y `GET /v1/sitemap` para navegación y SEO.
- `GET /v1/urls/resolve?path=` resuelve una URL de la tienda: devuelve el
  producto o la categoría, o la URL vigente para una redirección 301.
- Productos, sugerencias y categorías incluyen `url`; úsala para enlazar.

## Carrito y checkout

1. `POST /v1/carts` crea el carrito; la respuesta trae `token`. Guárdalo.
2. `POST /v1/carts/{cartToken}/items` agrega artículos.
3. Prepara el checkout:
   - comprador: `PATCH /v1/carts/{cartToken}/buyer`
   - direcciones: `PATCH /v1/carts/{cartToken}/addresses` (devuelve el carrito)
   - opciones de envío: `GET /v1/carts/{cartToken}/shipping-options` después de
     guardar la dirección
   - método de envío: `PUT /v1/carts/{cartToken}/shipping-method`
4. `GET /v1/carts/{cartToken}/checkout` devuelve el carrito y los métodos de
   pago.
5. `POST /v1/carts/{cartToken}/checkout` crea el pedido.

## GraphQL

- Solo `Query`, sin `Mutation`: las escrituras van por REST.
- Requiere `x-Store-Domain`.
- Separa los valores dinámicos en `variables`.
- Una ficha de producto necesita dos consultas: primero el producto por slug,
  luego relacionados y reseñas con su ID.
- Una respuesta puede traer `data` y `errors` a la vez; revisa `errors`.

## Cuentas de cliente

- `POST /v1/customer/auth/config` crea o actualiza el cliente OAuth del origen y
  devuelve el modo de inicio de sesión (`hosted` o `storefront`), el CAPTCHA y los datos OAuth.
- Tras verificar el correo, `GET /v1/customer/registration` indica si falta
  completar datos (`requiresCompletion`); se completan con
  `POST /v1/customer/registration`.
- Mientras el registro esté pendiente, las APIs de cuenta y crear pedidos
  responden `Customer.RegistrationRequired`.
- El servidor valida siempre: ocultar un campo en el frontend no lo evita.

## Convenciones

- Los IDs son strings opacos: no los conviertas a número.
- Errores en Problem Details con `code` estable.
- Respeta `Retry-After` ante `429`.