{"openapi":"3.1.0","info":{"title":"Arkanoid","description":"\n## Arkanoid\n\nTienda de videojuegos con 60 productos: consolas, videojuegos, accesorios, pantallas y coleccionables\npara Nintendo Switch 2, Nintendo Switch, PlayStation 5 y Xbox Series, entre otras plataformas.\nLos nombres, descripciones y mensajes comerciales están en español de México.\n\n## Guía de integración para clientes y agentes\n\n1. **Descubrir productos:** usa `listProducts` con los filtros que expresen la petición del cliente\n   (plataforma, categoría, etiqueta, rango de precio, texto libre y orden) en **una sola llamada**.\n   Por ejemplo, \"juegos familiares para Switch 2 de hasta $1,800\" es\n   `GET /products?platform=Nintendo Switch 2&category=Videojuegos&tag=familia&maxPrice=1800`.\n   `searchProducts` es un atajo de solo texto. Usa los `id` devueltos como `productId`;\n   no inventes identificadores de producto.\n2. **Elegir un producto:** compara `attributes.platform`, `attributes.brand`, `attributes.category`,\n   `price`, `listPrice` y `discountPercent`. Confirma que la plataforma del videojuego o accesorio\n   corresponde a la consola del cliente; no supongas compatibilidad entre plataformas distintas\n   si la descripción del producto no la indica.\n   Si hay varias opciones, conserva el producto y la plataforma solicitados por el cliente.\n3. **Identificar el carrito:** tú generas el `user_id`; ninguna sesión ni ruta lo proporciona.\n   Al inicio de la conversación crea un texto opaco, como `cliente-7f3a9c`, y reutilízalo en todas\n   las operaciones de carrito y pago de ese cliente. Cualquier texto no vacío es válido: no hay registro,\n   login ni ruta para crear sesiones, y el carrito se crea solo en la primera llamada.\n   No uses correos, teléfonos u otros datos personales como `user_id`.\n4. **Consultar antes de modificar:** `getCart` devuelve referencias `productId` y cantidades.\n   Consulta `getProduct` para obtener el nombre, la plataforma y el precio de cada referencia.\n5. **Agregar o establecer cantidades:** `addToCart` **suma** unidades; `updateCartItem`\n   **reemplaza** la cantidad. Para quitar un artículo usa `removeFromCart` o una cantidad\n   menor o igual a cero en `updateCartItem`. Las respuestas contienen el carrito completo actualizado.\n6. **Revisar la compra:** muestra productos, plataformas, cantidades y total en MXN.\n   Respeta las autorizaciones y confirmaciones de compra de la aplicación cliente.\n7. **Completar la compra:** consulta la documentación de `payCart` para los requisitos del pago.\n   Un HTTP 200 devuelve el recibo y vacía el carrito. Conserva el recibo en el cliente:\n   no hay una ruta para recuperarlo después.\n\n### Ejemplo de recorrido\n\n```http\nGET /products/search?q=star%20fox\nGET /cart/cliente123\nPOST /cart/cliente123\nContent-Type: application/json\n\n{\"productId\":\"45467911\",\"quantity\":2}\n```\n\nEl último paso agrega dos piezas de Star Fox para Nintendo Switch 2.\nCada pieza cuesta $1,199.20 MXN (precio de lista $1,499.00 MXN, con 20% de descuento ya aplicado):\nel subtotal es **$2,398.40 MXN**. No vuelvas a restar el descuento: `price` ya lo incluye.\nSi ya había una pieza, `POST` deja tres; usa `PUT /cart/cliente123/45467911`\ncon `{\"quantity\":2}` si deseas exactamente dos.\n\n## Contrato de datos y moneda\n\n- Solicitudes y respuestas: JSON; envía `Content-Type: application/json` cuando haya cuerpo.\n- Las rutas y claves JSON están en inglés y distinguen mayúsculas: `productId`, `creditCardNumber`,\n  `totalAmount`, `paymentSummary`, `purchasedItems`. Los valores comerciales están en español.\n- **Todos los importes son pesos mexicanos (MXN), nunca USD ni centavos.**\n  `price: 1199.2` equivale a $1,199.20 MXN. No multipliques ni dividas por 100 al enviar o leer precios.\n- `Product.currency` y `paymentSummary.currency` valen siempre `MXN`. La moneda del resumen\n  también aplica a `unitPrice` y `totalPrice` en todas las partidas del recibo.\n- `price` es el **precio vigente por pieza** y el único importe que se cobra. `listPrice` es el precio\n  de lista y `discountPercent` el descuento ya aplicado en `price`; ambos son informativos.\n  Si `discountPercent` es 0, `price` y `listPrice` son iguales.\n- Total de una partida = `price` × cantidad; total de compra = suma de las partidas.\n  `quantity` cuenta piezas. Los paquetes (bundles) se venden como una sola pieza con todo su contenido.\n  Usa aritmética decimal para calcular importes y muestra dos decimales al cliente.\n  El recibo devuelto por el servidor es la referencia final de la compra.\n- No hay cupones, descuentos adicionales, conversión de moneda, envío ni recargos calculados por estas rutas.\n  No se proporciona un desglose fiscal; no inventes impuestos o cargos adicionales.\n- El carrito contiene cantidades enteras. No se admiten cantidades fraccionarias.\n- Los listados devuelven arreglos sin paginación ni objetos contenedores; `[]` es un resultado válido.\n\n## Imágenes de productos\n\nCada producto incluye `imageUrl`, por ejemplo `/images/products/45467911.webp`.\nResuelve esa ruta con el **origen de esta API**, no con el origen de tu frontend ni con `/products`.\nSi la API está en `https://tienda.example`, la imagen completa es\n`https://tienda.example/images/products/45467911.webp`.\nPuedes usar esa URL en un elemento `<img>` o descargarla con GET: devuelve bytes\n`image/webp` de 512 × 512 píxeles, no JSON ni base64. No requiere autenticación ni una llamada de generación.\nUsa `name` como texto alternativo accesible. Las imágenes son ilustrativas;\nconsulta el nombre, la descripción y la plataforma para confirmar qué producto compras.\nLas rutas de archivos estáticos no aparecen como operaciones independientes en este esquema.\nSi una imagen no carga, muestra un recurso visual alternativo; no cambies el producto ni su precio.\nLas respuestas incluyen ETag y Last-Modified para permitir solicitudes condicionales y caché del cliente.\n\n## Búsqueda y filtros\n\n`listProducts` combina todos sus parámetros mediante **AND** y todos son opcionales:\n\n| Parámetro | Qué hace | Ejemplo |\n| --- | --- | --- |\n| `platform` | Plataforma compatible | `Nintendo Switch 2` |\n| `category` | Tipo de producto | `Videojuegos` |\n| `brand` | Marca del catálogo | `Nintendo` |\n| `tag` | Una o más etiquetas separadas por comas; el producto debe tener todas | `familia,multijugador` |\n| `q` | Texto libre en id, nombre, descripción y etiquetas | `mario` |\n| `minPrice` / `maxPrice` | Rango inclusivo sobre `price` (precio vigente con descuento), en MXN | `maxPrice=1800` |\n| `sort` | Orden del resultado | `priceAsc` |\n| `limit` | Máximo de productos devueltos, después de ordenar | `10` |\n\n**Valores tolerantes.** `platform`, `category`, `brand` y `tag` ignoran mayúsculas, acentos, guiones,\nespacios repetidos y plurales, y aceptan nombres cortos y sinónimos comunes:\n`Switch 2`, `switch2` o `NS2` equivalen a `Nintendo Switch 2`; `Switch` equivale a `Nintendo Switch`\n(nunca incluye Switch 2); `PS5` a `PlayStation 5`; `Xbox` o `Series X` a `Xbox Series`;\n`juegos` o `videojuego` a `Videojuegos`; `familiar` o `infantil` a la etiqueta `familia`;\n`mundo abierto` a `mundo-abierto`; `Sony` a la marca `PlayStation`.\nLos precios aceptan `1800`, `1800.50`, `$1,800` o `1800 MXN`; la coma es separador de miles.\n`min_price` y `max_price` también se aceptan como nombres de parámetro.\n\n**Parámetros vacíos.** Un parámetro ausente, vacío o con `null`, `undefined`, `todos` o `cualquiera`\nse ignora: no filtra. Envía únicamente los filtros que el cliente pidió.\n\n**Errores en vez de listas vacías engañosas.** Si un valor de `platform`, `category`, `brand`, `tag`\no `sort` no corresponde a nada del catálogo, la respuesta es **400** y `detail` enumera los valores\nválidos; corrige el valor y vuelve a consultar. Un **200 con `[]`** significa que los valores son\nválidos pero ningún producto cumple **todos** los filtros a la vez: relaja un filtro (por ejemplo\n`maxPrice` o `tag`) en lugar de concluir que el catálogo está vacío. El catálogo nunca está vacío:\n`GET /products` sin parámetros devuelve los 60 productos.\n\nValores del catálogo, de mayor a menor número de productos:\n\n- **platform:** `Nintendo Switch 2`, `Nintendo Switch`, `Xbox Series`, `PlayStation 5`, `TV`, `PC portátil`, `Nintendo`, `Multiplataforma`, `Coleccionable`.\n  `Nintendo Switch` y `Nintendo Switch 2` son plataformas distintas; no supongas compatibilidad\n  entre ellas si la descripción del producto no la indica. `Nintendo` corresponde a un solo\n  accesorio; para todo lo de Nintendo usa `brand=Nintendo`.\n- **category:** `Videojuegos`, `Accesorios`, `Consolas`, `Pantallas`, `Coleccionables`.\n- **brand:** `Nintendo`, `Xbox`, `PlayStation`, `Razer`, `Lenovo`, `Hisense`, `Hori`, `Licencias`, `Star Wars`, `LG`. En varios videojuegos y accesorios es la marca de la\n  consola (por ejemplo `Nintendo`), no la del estudio o editor del juego.\n- **tag:** `nostalgia`, `multijugador`, `control`, `familia`, `un-jugador`, `accion`, `clasico`, `consola`, `adulto`, `xbox`, `premium`, `plataformas`, `mundo-abierto`, `upsell`, `aventura`, `fiesta`, `carreras`, `cooperativo`, `estuche`, `bundle`, `n64`, `3d`, `viaje`, `pokemon`, `relajado`, `carga`, `ps5`, `portatil`, `economica`, `peleas`, `remake`, `rpg`, `coleccion`, `star-wars`, `shooter`, `set-completo`, `tv`, `4k`, `preventa`, `superheroes`, `simulacion`, `coleccionable`, `regalo`, `volante`, `audio`, `audifonos`, `digital`, `game-pass`, `pc`, `nave`, `arcade`, `snes`, `wii`, `ps1`, `amigos`, `minijuegos`, `sci-fi`, `sigilo`, `ps2`, `western`, `almacenamiento`, `construccion`, `creatividad`, `zelda`, `batallas`, `futbol`, `deportes`, `humor`, `economico`, `switch`, `tarjetas`, `competitivo`, `multiplataforma`.\n\n**Texto libre (`q`).** Busca sin distinguir mayúsculas ni acentos en `id`, `name`, `description` y\n`tags`; requiere al menos tres letras o dígitos. Primero busca la frase completa; si no aparece,\ndevuelve los productos que contienen todas las palabras significativas (ignora artículos y\npreposiciones como `de`, `para` o `la`). `pokemon` encuentra `Pokémon`; `4467` encuentra varios SKU.\nNo busca en marca, plataforma ni categoría como campos: usa sus filtros. Con `q` y sin `sort`,\nel resultado empieza por las coincidencias de la frase completa.\n\n**Orden (`sort`).** `relevance`: Orden del catálogo; con q, primero las coincidencias de la frase completa.; `priceAsc`: Precio vigente (price) de menor a mayor.; `priceDesc`: Precio vigente (price) de mayor a menor.; `discountDesc`: Mayor descuento (discountPercent) primero.; `nameAsc`: Nombre en orden alfabético.\nTambién acepta `price_asc`, `price-desc`, `precio`, `menor precio`, `descuento` o `-price` (descendente).\n\nCodifica espacios y acentos en la URL con la biblioteca HTTP del cliente.\nLos filtros `presentation`, `size` y `color` y los campos `packageType`, `unitsPerPackage` y `stock`\nde versiones anteriores ya no forman parte del contrato.\n\n## Estado, identidad y alcance\n\nEl catálogo tiene identificadores estables. Los carritos se guardan en memoria por proceso:\nun reinicio borra los carritos y varios procesos no comparten su contenido.\nPara conservar una sesión, utiliza la misma instancia del servicio.\n`user_id` es una clave de carrito, **no una credencial**; esta API no autentica usuarios\nni verifica la propiedad del carrito. No envíes tokens que el esquema no solicita.\nNo hay límite de existencias: todos los productos del catálogo están disponibles en cualquier cantidad.\nLa API no maneja inventario; no digas que un producto está agotado o tiene piezas limitadas.\nLos productos con la etiqueta `preventa` se venden igual que el resto; el catálogo no indica fechas de entrega.\nNo existen rutas de reservas, entrega, historial de pedidos, cancelación ni reembolsos.\nNo afirmes que una compra fue completada hasta recibir el recibo de `payCart`.\n\n## Errores, reintentos y concurrencia\n\n- **400:** la operación no se pudo completar; lee `detail` y corrige la causa antes de reintentar.\n- **404:** el producto, carrito o artículo solicitado no existe; vuelve a consultar catálogo o carrito.\n- **422:** la solicitud no cumple el esquema; revisa `detail[].loc`, `msg` y `type`.\n  Los mensajes de validación del framework pueden estar en inglés.\n- Los errores 400/404 usan `{\"detail\":\"mensaje\"}`; no se devuelve un recibo de éxito en un error.\n- **No hay claves de idempotencia.** No reintentes ciegamente `addToCart`: sumarías unidades otra vez.\n  Ante una respuesta perdida, consulta `getCart` y reconcilia la cantidad deseada.\n- `updateCartItem` establece una cantidad absoluta. Repetir una eliminación puede devolver 404;\n  consulta el carrito para verificar que el artículo ya no está.\n- No reintentes automáticamente un pago con resultado desconocido. Un carrito vacío no prueba\n  que se completó un pago; no reconstruyas un recibo ni inventes un folio.\n- Evita escrituras simultáneas sobre el mismo carrito: no hay control de versiones ni bloqueos\n  de concurrencia entre clientes.\n","version":"1.0.0"},"servers":[{"url":"/api","description":"Prefijo de la API en el mismo origen donde se sirve este esquema."}],"paths":{"/products":{"get":{"tags":["Productos"],"summary":"Consultar y filtrar productos","description":"Consulta el catálogo con filtros combinables. Todos los precios están en pesos mexicanos (MXN).\n\nExpresa la petición completa del cliente en una sola llamada. Todos los parámetros son opcionales\ny se combinan con AND. Los parámetros ausentes, vacíos o con `null` se ignoran. Ejemplos:\n\n- Juegos familiares para Switch 2 de hasta $1,800:\n  `/products?platform=Switch 2&category=Videojuegos&tag=familia&maxPrice=1800`\n- Los 5 accesorios más baratos para PS5: `/products?platform=PS5&category=Accesorios&sort=priceAsc&limit=5`\n- Juegos de Mario para Switch 2: `/products?platform=Switch 2&q=mario`\n- Catálogo completo: `/products`\n\nInterpreta el resultado así:\n\n- **200 con productos:** usa el `id` de cada uno como `productId` en addToCart; `price` es el precio\n  vigente por pieza, con el descuento ya aplicado.\n- **200 con `[]`:** los filtros son válidos pero ninguno de los productos cumple todos a la vez.\n  Relaja un filtro (sube maxPrice, quita tag o q) y vuelve a consultar. No digas que el catálogo está vacío.\n- **400:** un valor no existe en el catálogo; `detail` enumera los valores válidos. Corrígelo y reintenta.","operationId":"listProducts","parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string","description":"Plataforma con la que es compatible el producto. Ignora mayúsculas, acentos y guiones, y acepta nombres cortos y sinónimos: `Switch 2`, `switch2` o `NS2` → Nintendo Switch 2; `Switch` → Nintendo Switch (no incluye Switch 2); `PS5` → PlayStation 5; `Xbox` o `Series X` → Xbox Series. Valores del catálogo: Nintendo Switch 2, Nintendo Switch, Xbox Series, PlayStation 5, TV, PC portátil, Nintendo, Multiplataforma, Coleccionable. Un valor que no corresponde a ninguna plataforma devuelve 400 con la lista de valores válidos.","examples":["Nintendo Switch 2","Switch 2","PS5","Xbox"],"title":"Platform"},"description":"Plataforma con la que es compatible el producto. Ignora mayúsculas, acentos y guiones, y acepta nombres cortos y sinónimos: `Switch 2`, `switch2` o `NS2` → Nintendo Switch 2; `Switch` → Nintendo Switch (no incluye Switch 2); `PS5` → PlayStation 5; `Xbox` o `Series X` → Xbox Series. Valores del catálogo: Nintendo Switch 2, Nintendo Switch, Xbox Series, PlayStation 5, TV, PC portátil, Nintendo, Multiplataforma, Coleccionable. Un valor que no corresponde a ninguna plataforma devuelve 400 con la lista de valores válidos."},{"name":"category","in":"query","required":false,"schema":{"type":"string","description":"Tipo de producto. Acepta singular o plural y sinónimos (`juegos` → Videojuegos, `tv` → Pantallas). Valores del catálogo: Videojuegos, Accesorios, Consolas, Pantallas, Coleccionables. Un valor desconocido devuelve 400 con la lista de valores válidos.","examples":["Videojuegos","Consolas","Accesorios"],"title":"Category"},"description":"Tipo de producto. Acepta singular o plural y sinónimos (`juegos` → Videojuegos, `tv` → Pantallas). Valores del catálogo: Videojuegos, Accesorios, Consolas, Pantallas, Coleccionables. Un valor desconocido devuelve 400 con la lista de valores válidos."},{"name":"brand","in":"query","required":false,"schema":{"type":"string","description":"Marca del catálogo. En muchos videojuegos y accesorios es la marca de la consola, no la del estudio: Cyberpunk 2077 para Switch 2 tiene marca Nintendo. `Sony` → PlayStation, `Microsoft` → Xbox. Valores del catálogo: Nintendo, Xbox, PlayStation, Razer, Lenovo, Hisense, Hori, Licencias, Star Wars, LG. Un valor desconocido devuelve 400 con la lista de valores válidos.","examples":["Nintendo","PlayStation","Xbox"],"title":"Brand"},"description":"Marca del catálogo. En muchos videojuegos y accesorios es la marca de la consola, no la del estudio: Cyberpunk 2077 para Switch 2 tiene marca Nintendo. `Sony` → PlayStation, `Microsoft` → Xbox. Valores del catálogo: Nintendo, Xbox, PlayStation, Razer, Lenovo, Hisense, Hori, Licencias, Star Wars, LG. Un valor desconocido devuelve 400 con la lista de valores válidos."},{"name":"tag","in":"query","required":false,"schema":{"type":"string","description":"Una o más etiquetas de género, público o uso, separadas por comas. El producto debe tener **todas** (AND). Ignora mayúsculas, acentos, guiones y plurales y acepta sinónimos comunes: `familiar`, `infantil` o `niños` → familia; `multiplayer` → multijugador; `mundo abierto` → mundo-abierto; `retro` → clasico. Etiquetas del catálogo: nostalgia, multijugador, control, familia, un-jugador, accion, clasico, consola, adulto, xbox, premium, plataformas, mundo-abierto, upsell, aventura, fiesta, carreras, cooperativo, estuche, bundle, n64, 3d, viaje, pokemon, relajado, carga, ps5, portatil, economica, peleas, remake, rpg, coleccion, star-wars, shooter, set-completo, tv, 4k, preventa, superheroes, simulacion, coleccionable, regalo, volante, audio, audifonos, digital, game-pass, pc, nave, arcade, snes, wii, ps1, amigos, minijuegos, sci-fi, sigilo, ps2, western, almacenamiento, construccion, creatividad, zelda, batallas, futbol, deportes, humor, economico, switch, tarjetas, competitivo, multiplataforma. Una etiqueta desconocida devuelve 400 con la lista de etiquetas válidas.","examples":["familia","multijugador","familia,multijugador","mundo abierto"],"title":"Tag"},"description":"Una o más etiquetas de género, público o uso, separadas por comas. El producto debe tener **todas** (AND). Ignora mayúsculas, acentos, guiones y plurales y acepta sinónimos comunes: `familiar`, `infantil` o `niños` → familia; `multiplayer` → multijugador; `mundo abierto` → mundo-abierto; `retro` → clasico. Etiquetas del catálogo: nostalgia, multijugador, control, familia, un-jugador, accion, clasico, consola, adulto, xbox, premium, plataformas, mundo-abierto, upsell, aventura, fiesta, carreras, cooperativo, estuche, bundle, n64, 3d, viaje, pokemon, relajado, carga, ps5, portatil, economica, peleas, remake, rpg, coleccion, star-wars, shooter, set-completo, tv, 4k, preventa, superheroes, simulacion, coleccionable, regalo, volante, audio, audifonos, digital, game-pass, pc, nave, arcade, snes, wii, ps1, amigos, minijuegos, sci-fi, sigilo, ps2, western, almacenamiento, construccion, creatividad, zelda, batallas, futbol, deportes, humor, economico, switch, tarjetas, competitivo, multiplataforma. Una etiqueta desconocida devuelve 400 con la lista de etiquetas válidas."},{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"Texto libre en id, nombre, descripción y etiquetas, sin distinguir mayúsculas ni acentos; mínimo 3 letras o dígitos (si no, 400). Primero busca la frase completa y, si no aparece, los productos con todas las palabras significativas. Se combina con los demás filtros.","examples":["mario","pokemon","star fox"],"title":"Q"},"description":"Texto libre en id, nombre, descripción y etiquetas, sin distinguir mayúsculas ni acentos; mínimo 3 letras o dígitos (si no, 400). Primero busca la frase completa y, si no aparece, los productos con todas las palabras significativas. Se combina con los demás filtros."},{"name":"minPrice","in":"query","required":false,"schema":{"type":"number","minimum":0,"description":"Precio vigente mínimo (`price`, ya con descuento), inclusivo, en pesos mexicanos (MXN), no centavos. También acepta `min_price`, `$1,000` o `1000 MXN`.","examples":[500],"title":"Minprice"},"description":"Precio vigente mínimo (`price`, ya con descuento), inclusivo, en pesos mexicanos (MXN), no centavos. También acepta `min_price`, `$1,000` o `1000 MXN`."},{"name":"maxPrice","in":"query","required":false,"schema":{"type":"number","minimum":0,"description":"Precio vigente máximo (`price`, ya con descuento), inclusivo, en pesos mexicanos (MXN), no centavos. Úsalo para presupuestos: \"hasta $1,800 por juego\" es `maxPrice=1800`. También acepta `max_price`, `$1,800` o `1800 MXN`. Debe ser mayor o igual que minPrice.","examples":[1800],"title":"Maxprice"},"description":"Precio vigente máximo (`price`, ya con descuento), inclusivo, en pesos mexicanos (MXN), no centavos. Úsalo para presupuestos: \"hasta $1,800 por juego\" es `maxPrice=1800`. También acepta `max_price`, `$1,800` o `1800 MXN`. Debe ser mayor o igual que minPrice."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"Orden del resultado. `relevance`: Orden del catálogo; con q, primero las coincidencias de la frase completa. `priceAsc`: Precio vigente (price) de menor a mayor. `priceDesc`: Precio vigente (price) de mayor a menor. `discountDesc`: Mayor descuento (discountPercent) primero. `nameAsc`: Nombre en orden alfabético. También acepta snake_case, kebab-case y sinónimos: `price_asc`, `precio` o `-price` (descendente). Un valor desconocido devuelve 400.","examples":["priceAsc"],"enum":["relevance","priceAsc","priceDesc","discountDesc","nameAsc"],"title":"Sort"},"description":"Orden del resultado. `relevance`: Orden del catálogo; con q, primero las coincidencias de la frase completa. `priceAsc`: Precio vigente (price) de menor a mayor. `priceDesc`: Precio vigente (price) de mayor a menor. `discountDesc`: Mayor descuento (discountPercent) primero. `nameAsc`: Nombre en orden alfabético. También acepta snake_case, kebab-case y sinónimos: `price_asc`, `precio` o `-price` (descendente). Un valor desconocido devuelve 400."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Máximo de productos devueltos, aplicado después de filtrar y ordenar. Útil para respuestas cortas, por ejemplo los 5 más baratos con `sort=priceAsc&limit=5`. Sin limit devuelve todas las coincidencias; no hay paginación.","examples":[5],"title":"Limit"},"description":"Máximo de productos devueltos, aplicado después de filtrar y ordenar. Útil para respuestas cortas, por ejemplo los 5 más baratos con `sort=priceAsc&limit=5`. Sin limit devuelve todas las coincidencias; no hay paginación."}],"responses":{"200":{"description":"Productos que cumplen todos los filtros a la vez. [] significa que los valores son válidos pero ninguna combinación coincide; relaja un filtro. Sin parámetros devuelve el catálogo completo.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"title":"Response Listproducts"},"examples":{"juegosFamiliaresSwitch2HastaMil800":{"value":[{"id":"45276185","name":"Pokémon Pokopia Nintendo Switch 2","description":"Juego de Pokémon para crear y cuidar tu propio mundo, exclusivo de Switch 2.","price":1399.2,"listPrice":1749.0,"discountPercent":20,"currency":"MXN","imageUrl":"/images/products/45276185.webp","tags":["pokemon","simulacion","familia","relajado"],"attributes":{"brand":"Nintendo","platform":"Nintendo Switch 2","category":"Videojuegos"}},{"id":"45397520","name":"Yoshi and the Mysterious Book Nintendo Switch 2","description":"Nueva aventura de plataformas de Yoshi para Switch 2.","price":1399.2,"listPrice":1749.0,"discountPercent":20,"currency":"MXN","imageUrl":"/images/products/45397520.webp","tags":["plataformas","familia","relajado"],"attributes":{"brand":"Nintendo","platform":"Nintendo Switch 2","category":"Videojuegos"}},{"id":"44860443","name":"Super Mario Party Jamboree + Jamboree TV Nintendo Switch 2","description":"Más de 110 minijuegos para jugar en grupo, con la expansión Jamboree TV de Switch 2 que suma modos con micrófono y cámara (cámara se vende por separado). El juego de la noche con amigos.","price":1659.17,"listPrice":1999.0,"discountPercent":17,"currency":"MXN","imageUrl":"/images/products/44860443.webp","tags":["fiesta","multijugador","familia","amigos","minijuegos"],"attributes":{"brand":"Nintendo","platform":"Nintendo Switch 2","category":"Videojuegos"}},{"id":"44860442","name":"Kirby and the Forgotten Land + Star-Crossed World Nintendo Switch 2","description":"La aventura 3D de Kirby mejorada para Switch 2, con la expansión Star-Crossed World. Se puede jugar en cooperativo de 2.","price":1659.17,"listPrice":1999.0,"discountPercent":17,"currency":"MXN","imageUrl":"/images/products/44860442.webp","tags":["plataformas","3d","cooperativo","familia"],"attributes":{"brand":"Nintendo","platform":"Nintendo Switch 2","category":"Videojuegos"}}]},"coincidencia":{"value":[{"id":"45467911","name":"Star Fox Nintendo Switch 2","description":"El regreso de Fox McCloud y su escuadrón a los combates de naves en Switch 2. Para quien creció con Star Fox 64 y su 'Do a barrel roll!'.","price":1199.2,"listPrice":1499.0,"discountPercent":20,"currency":"MXN","imageUrl":"/images/products/45467911.webp","tags":["nave","accion","arcade","nostalgia","n64","un-jugador"],"attributes":{"brand":"Nintendo","platform":"Nintendo Switch 2","category":"Videojuegos"}}]},"sinCoincidencias":{"value":[]}}}}},"422":{"description":"Solicitud no válida. Corrige los campos señalados en detail[].loc antes de reintentar. Por ejemplo, quantity debe ser entero y mayor que cero al agregar un producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"400":{"description":"Un valor de filtro no existe en el catálogo o el rango de precios no es válido. detail explica la causa y, para platform, category, brand, tag y sort, enumera todos los valores válidos. Corrige ese parámetro y vuelve a consultar; no concluyas que el catálogo está vacío.","content":{"application/json":{"examples":{"plataformaDesconocida":{"value":{"detail":"Plataforma no reconocida: 'Switch 3'. Valores válidos: Nintendo Switch 2, Nintendo Switch, Xbox Series, PlayStation 5, TV, PC portátil, Nintendo, Multiplataforma, Coleccionable."}},"etiquetaDesconocida":{"value":{"detail":"Etiqueta no reconocida: 'terror'. Valores válidos: nostalgia, multijugador, control, familia, un-jugador, accion, clasico, consola, adulto, xbox, premium, plataformas, mundo-abierto, upsell, aventura, fiesta, carreras, cooperativo, estuche, bundle, n64, 3d, viaje, pokemon, relajado, carga, ps5, portatil, economica, peleas, remake, rpg, coleccion, star-wars, shooter, set-completo, tv, 4k, preventa, superheroes, simulacion, coleccionable, regalo, volante, audio, audifonos, digital, game-pass, pc, nave, arcade, snes, wii, ps1, amigos, minijuegos, sci-fi, sigilo, ps2, western, almacenamiento, construccion, creatividad, zelda, batallas, futbol, deportes, humor, economico, switch, tarjetas, competitivo, multiplataforma."}},"rangoInvalido":{"value":{"detail":"minPrice (2000.0) no puede ser mayor que maxPrice (1800.0)."}},"consultaCorta":{"value":{"detail":"q requiere al menos 3 letras o dígitos."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/search":{"get":{"tags":["Productos"],"summary":"Buscar productos por texto","description":"Busca productos solo por texto. Para combinar texto con plataforma, precio o etiquetas usa listProducts.\n\nEquivale a `listProducts?q=...` sin otros filtros. La búsqueda es parcial y no distingue mayúsculas\nni acentos: `pokemon` encuentra `Pokémon`. Si la frase completa no aparece, devuelve los productos que\ncontienen todas sus palabras significativas, en cualquier orden. Las etiquetas (`tags`) describen\ngénero, público y uso: `multijugador`, `nostalgia`, `mundo-abierto`.\nUna consulta como `4467` encuentra varios SKU; para un identificador exacto usa `getProduct`.\nSi no hay coincidencias devuelve []; para consultas menores de tres caracteres devuelve 422.\nNo busca por marca, plataforma o categoría como campos: usa los filtros de `listProducts`.","operationId":"searchProducts","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3,"description":"Busca por identificador, nombre, descripción o etiqueta (mínimo 3 caracteres). No distingue mayúsculas ni acentos. Primero la frase completa; si no aparece, los productos con todas las palabras significativas.","title":"Q"},"description":"Busca por identificador, nombre, descripción o etiqueta (mínimo 3 caracteres). No distingue mayúsculas ni acentos. Primero la frase completa; si no aparece, los productos con todas las palabras significativas.","examples":{"porNombre":{"summary":"Buscar Star Fox","value":"star fox"},"sinAcentos":{"summary":"Buscar Pokémon sin escribir el acento","value":"pokemon"},"porEtiqueta":{"summary":"Buscar juegos para varios jugadores","value":"multijugador"},"porIdentificador":{"summary":"Buscar por SKU","value":"45467911"}}}],"responses":{"200":{"description":"Coincidencias por identificador, nombre, descripción o etiqueta, con las de frase completa primero.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"title":"Response Searchproducts"},"examples":{"buscarJuego":{"value":[{"id":"45467911","name":"Star Fox Nintendo Switch 2","description":"El regreso de Fox McCloud y su escuadrón a los combates de naves en Switch 2. Para quien creció con Star Fox 64 y su 'Do a barrel roll!'.","price":1199.2,"listPrice":1499.0,"discountPercent":20,"currency":"MXN","imageUrl":"/images/products/45467911.webp","tags":["nave","accion","arcade","nostalgia","n64","un-jugador"],"attributes":{"brand":"Nintendo","platform":"Nintendo Switch 2","category":"Videojuegos"}}]},"sinCoincidencias":{"value":[]}}}}},"422":{"description":"Solicitud no válida. Corrige los campos señalados en detail[].loc antes de reintentar. Por ejemplo, quantity debe ser entero y mayor que cero al agregar un producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/products/{product_id}":{"get":{"tags":["Productos"],"summary":"Consultar un producto","description":"Consulta los detalles y el precio en MXN de un producto.\n\nUsa el id exacto devuelto por el catálogo. Esta operación permite resolver las referencias\nproductId del carrito para mostrar nombres, plataformas y precios al cliente.\nSi recibes 404, vuelve a consultar el catálogo; no sustituyas productos sin revisar la elección del cliente.","operationId":"getProduct","parameters":[{"name":"product_id","in":"path","required":true,"schema":{"type":"string","description":"SKU de 8 dígitos obtenido del campo id de listProducts o searchProducts, por ejemplo 45467911. Va directamente en la ruta: GET /products/45467911. No existe una ruta /products/detail ni se envía como parámetro de consulta (?id=); no sustituyas el id por palabras como detail, id o product_id. En operaciones de carrito debe corresponder al productId de la partida.","examples":["45467911"],"title":"Product Id"},"description":"SKU de 8 dígitos obtenido del campo id de listProducts o searchProducts, por ejemplo 45467911. Va directamente en la ruta: GET /products/45467911. No existe una ruta /products/detail ni se envía como parámetro de consulta (?id=); no sustituyas el id por palabras como detail, id o product_id. En operaciones de carrito debe corresponder al productId de la partida."}],"responses":{"200":{"description":"Detalles de un producto del catálogo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"},"examples":{"producto":{"value":{"id":"45467911","name":"Star Fox Nintendo Switch 2","description":"El regreso de Fox McCloud y su escuadrón a los combates de naves en Switch 2. Para quien creció con Star Fox 64 y su 'Do a barrel roll!'.","price":1199.2,"listPrice":1499.0,"discountPercent":20,"currency":"MXN","imageUrl":"/images/products/45467911.webp","tags":["nave","accion","arcade","nostalgia","n64","un-jugador"],"attributes":{"brand":"Nintendo","platform":"Nintendo Switch 2","category":"Videojuegos"}}}}}}},"422":{"description":"Solicitud no válida. Corrige los campos señalados en detail[].loc antes de reintentar. Por ejemplo, quantity debe ser entero y mayor que cero al agregar un producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"404":{"description":"El identificador no corresponde a un producto del catálogo. detail repite el id recibido; si no es un SKU de 8 dígitos, la ruta se construyó mal: usa GET /products/{id} con el id de listProducts.","content":{"application/json":{"examples":{"productoInexistente":{"value":{"detail":"Producto no encontrado: '99999999'. Usa el SKU de 8 dígitos del campo id de listProducts o searchProducts en la ruta, por ejemplo /products/45467911."}},"rutaMalConstruida":{"value":{"detail":"Producto no encontrado: 'detail'. Usa el SKU de 8 dígitos del campo id de listProducts o searchProducts en la ruta, por ejemplo /products/45467911."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cart/{user_id}":{"get":{"tags":["Carrito"],"summary":"Consultar carrito","description":"Consulta los productos y cantidades del carrito de un cliente.\n\nSi no existe, inicializa un carrito vacío y devuelve []. Cada partida contiene solamente\nproductId y quantity: consulta getProduct para conocer precios, nombres y plataformas.\nUsa esta operación antes de modificar cantidades y para reconciliar respuestas perdidas de addToCart.\nEl user_id lo generas tú: cualquier texto no vacío sin datos personales, como cliente-7f3a9c.\nNo requiere sesión, login ni registro; reutiliza el mismo valor durante toda la conversación.","operationId":"getCart","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales.","examples":["cliente-7f3a9c","cliente123"],"title":"User Id"},"description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales."}],"responses":{"200":{"description":"Carrito actual del cliente.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CartItem"},"title":"Response Getcart"},"examples":{"conProductos":{"value":[{"productId":"45467911","quantity":2}]},"vacio":{"value":[]}}}}},"422":{"description":"Solicitud no válida. Corrige los campos señalados en detail[].loc antes de reintentar. Por ejemplo, quantity debe ser entero y mayor que cero al agregar un producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}},"post":{"tags":["Carrito"],"summary":"Agregar al carrito","description":"Agrega un producto al carrito. Si ya existe, incrementa su cantidad.\n\nquantity cuenta piezas del producto y debe ser un entero mayor que cero.\nSi había una pieza y envías dos, quedan tres.\nPara dejar exactamente dos usa updateCartItem. El producto debe existir en el catálogo.\nNo es idempotente: repetir la misma solicitud vuelve a sumar unidades.\nSi pierdes la respuesta, consulta getCart antes de reintentar.\nEl user_id lo generas tú: cualquier texto no vacío sin datos personales, como cliente-7f3a9c.\nNo requiere sesión, login ni registro; reutiliza el mismo valor durante toda la conversación.","operationId":"addToCart","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales.","examples":["cliente-7f3a9c","cliente123"],"title":"User Id"},"description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartItem"},"examples":{"dosPiezas":{"summary":"Sumar dos piezas de Star Fox para Nintendo Switch 2","value":{"productId":"45467911","quantity":2}}}}}},"responses":{"200":{"description":"Carrito completo después de sumar las unidades solicitadas.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CartItem"},"title":"Response Addtocart"},"examples":{"actualizado":{"value":[{"productId":"45467911","quantity":2}]}}}}},"422":{"description":"Solicitud no válida. Corrige los campos señalados en detail[].loc antes de reintentar. Por ejemplo, quantity debe ser entero y mayor que cero al agregar un producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"404":{"description":"El identificador no corresponde a un producto del catálogo. detail repite el id recibido; si no es un SKU de 8 dígitos, la ruta se construyó mal: usa GET /products/{id} con el id de listProducts.","content":{"application/json":{"examples":{"productoInexistente":{"value":{"detail":"Producto no encontrado: '99999999'. Usa el SKU de 8 dígitos del campo id de listProducts o searchProducts en la ruta, por ejemplo /products/45467911."}},"rutaMalConstruida":{"value":{"detail":"Producto no encontrado: 'detail'. Usa el SKU de 8 dígitos del campo id de listProducts o searchProducts en la ruta, por ejemplo /products/45467911."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cart/{user_id}/{product_id}":{"put":{"tags":["Carrito"],"summary":"Actualizar cantidad","description":"Actualiza la cantidad de un producto. Un valor de 0 o menor lo elimina del carrito.\n\nLa cantidad reemplaza el valor actual: no es una diferencia ni un incremento.\nLa partida debe existir; para agregar un producto nuevo usa addToCart.\nRepetir un valor positivo mantiene esa cantidad si la partida aún existe.\nSi ya eliminaste la partida, una nueva modificación devuelve 404.","operationId":"updateCartItem","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales.","examples":["cliente-7f3a9c","cliente123"],"title":"User Id"},"description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales."},{"name":"product_id","in":"path","required":true,"schema":{"type":"string","description":"SKU de 8 dígitos obtenido del campo id de listProducts o searchProducts, por ejemplo 45467911. Va directamente en la ruta: GET /products/45467911. No existe una ruta /products/detail ni se envía como parámetro de consulta (?id=); no sustituyas el id por palabras como detail, id o product_id. En operaciones de carrito debe corresponder al productId de la partida.","examples":["45467911"],"title":"Product Id"},"description":"SKU de 8 dígitos obtenido del campo id de listProducts o searchProducts, por ejemplo 45467911. Va directamente en la ruta: GET /products/45467911. No existe una ruta /products/detail ni se envía como parámetro de consulta (?id=); no sustituyas el id por palabras como detail, id o product_id. En operaciones de carrito debe corresponder al productId de la partida."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartItemUpdate"},"examples":{"establecerDos":{"summary":"Dejar exactamente dos unidades","value":{"quantity":2}},"eliminar":{"summary":"Eliminar la partida","value":{"quantity":0}}}}}},"responses":{"200":{"description":"Carrito completo con la cantidad establecida o la partida eliminada.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CartItem"},"title":"Response Updatecartitem"},"examples":{"cantidadDos":{"value":[{"productId":"45467911","quantity":2}]},"eliminado":{"value":[]}}}}},"422":{"description":"Solicitud no válida. Corrige los campos señalados en detail[].loc antes de reintentar. Por ejemplo, quantity debe ser entero y mayor que cero al agregar un producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"404":{"description":"Consulta getCart para verificar el carrito y sus partidas antes de modificarlo.","content":{"application/json":{"examples":{"carritoInexistente":{"value":{"detail":"Carrito no encontrado para el cliente"}},"partidaInexistente":{"value":{"detail":"Producto no encontrado en el carrito"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Carrito"],"summary":"Eliminar del carrito","description":"Elimina un producto del carrito.\n\nElimina todas las unidades de la partida, sin cuerpo de solicitud. No vacía las demás partidas.\nDevuelve 200 con el carrito actualizado (no 204). Si la partida ya no existe, devuelve 404;\ngetCart permite verificar el resultado de una eliminación cuya respuesta se perdió.","operationId":"removeFromCart","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales.","examples":["cliente-7f3a9c","cliente123"],"title":"User Id"},"description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales."},{"name":"product_id","in":"path","required":true,"schema":{"type":"string","description":"SKU de 8 dígitos obtenido del campo id de listProducts o searchProducts, por ejemplo 45467911. Va directamente en la ruta: GET /products/45467911. No existe una ruta /products/detail ni se envía como parámetro de consulta (?id=); no sustituyas el id por palabras como detail, id o product_id. En operaciones de carrito debe corresponder al productId de la partida.","examples":["45467911"],"title":"Product Id"},"description":"SKU de 8 dígitos obtenido del campo id de listProducts o searchProducts, por ejemplo 45467911. Va directamente en la ruta: GET /products/45467911. No existe una ruta /products/detail ni se envía como parámetro de consulta (?id=); no sustituyas el id por palabras como detail, id o product_id. En operaciones de carrito debe corresponder al productId de la partida."}],"responses":{"200":{"description":"Carrito completo después de quitar la partida.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CartItem"},"title":"Response Removefromcart"},"examples":{"ultimoProductoEliminado":{"value":[]}}}}},"422":{"description":"Solicitud no válida. Corrige los campos señalados en detail[].loc antes de reintentar. Por ejemplo, quantity debe ser entero y mayor que cero al agregar un producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"404":{"description":"Consulta getCart para verificar el carrito y sus partidas antes de modificarlo.","content":{"application/json":{"examples":{"carritoInexistente":{"value":{"detail":"Carrito no encontrado para el cliente"}},"partidaInexistente":{"value":{"detail":"Producto no encontrado en el carrito"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/payments/{user_id}":{"post":{"tags":["Pagos"],"summary":"Pagar carrito","description":"Paga el carrito y recibe un ticket con todos los importes en pesos mexicanos (MXN).\nUsa el mismo user_id que generaste para el carrito; no requiere sesión, login ni registro.\n\n## Pasarela de pago y PIN de prueba\n\nEste endpoint utiliza una pasarela de pago de prueba (mock): **no realiza cargos reales**.\nNo envíes tarjetas ni NIP bancarios reales. El campo pin no es un NIP bancario, CVV, contraseña\nde usuario ni código enviado por SMS: es una regla de validación de esta pasarela.\n\n**Cómo calcular el PIN:** toma creditCardNumber como texto, elimina sus espacios y copia\nsus últimos cuatro dígitos, sin modificarlos. Envía esos cuatro dígitos como el string pin.\nEl número ficticio debe contener al menos cuatro dígitos; no se validan vencimiento ni CVV.\nLa API no solicita nombre de titular, fecha de expiración, cuenta bancaria ni otros secretos.\n\n| Tarjeta ficticia (string) | PIN (string) | Resultado con carrito no vacío |\n| --- | --- | --- |\n| `1111222233334444` | `4444` | HTTP 200, recibo en MXN y carrito vacío |\n| `1111 2222 3333 4444` | `4444` | HTTP 200; se permiten espacios en el número |\n| `1111222233330042` | `0042` | HTTP 200; conserva ceros iniciales |\n| `1111222233334444` | `0000` | HTTP 400, `PIN de prueba no válido`; el carrito no cambia |\n\nEjemplo de solicitud funcional (agrega productos al carrito del mismo user_id primero):\n\n```json\n{\"creditCardNumber\": \"1111222233334444\", \"pin\": \"4444\"}\n```\n\nEnvía ambos campos como strings JSON: `\"4444\"`, no el número `4444`.\nSi integras un agente, puede utilizar el par ficticio anterior para esta pasarela;\nno necesita solicitar un NIP bancario real al cliente.\n\n## Recorrido completo\n\n1. Agrega productos con addToCart y revisa el carrito con getCart usando el mismo user_id.\n2. Resuelve sus productId con getProduct y revisa cantidades y total en MXN con el cliente.\n3. Envía la tarjeta ficticia y su PIN coincidente en esta operación.\n4. Con HTTP 200, conserva ticketId, paymentSummary y purchasedItems. Todos los importes son MXN.\n   El número de tarjeta se devuelve enmascarado y el PIN no aparece en el recibo.\n5. El carrito queda vacío. Para una nueva compra, agrega nuevos productos.\n\n## Errores y reintentos\n\nSe valida primero que el carrito tenga productos, después el formato de tarjeta y por último el PIN.\nSi el carrito está vacío, recibirás `El carrito está vacío o no existe` aunque el PIN también esté mal.\nUn error 400 o 422 no elimina los productos del carrito.\nNo hay idempotencia ni consulta posterior de tickets: ante un timeout no repitas automáticamente\nel pago ni vuelvas a llenar el carrito para intentar cobrar otra vez. Un carrito vacío por sí solo\nno confirma la compra; conserva el recibo solamente cuando lo recibas del servidor.","operationId":"payCart","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales.","examples":["cliente-7f3a9c","cliente123"],"title":"User Id"},"description":"Clave del carrito que genera el cliente o agente: cualquier texto no vacío, por ejemplo cliente-7f3a9c. No hay registro, login ni ruta de sesión; el carrito se crea solo en la primera llamada. Genera una al inicio de la conversación y reutilízala en todas las operaciones de carrito y pago. No es una credencial; no uses correos, teléfonos ni datos personales."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"},"examples":{"pagoAprobado":{"summary":"Tarjeta ficticia y PIN coincidente: aprueba si el carrito tiene productos","value":{"creditCardNumber":"1111222233334444","pin":"4444"}},"cerosIniciales":{"summary":"El PIN es texto: conserva los ceros iniciales","value":{"creditCardNumber":"1111222233330042","pin":"0042"}},"pinIncorrecto":{"summary":"Ejemplo que devuelve HTTP 400 sin vaciar un carrito con productos","value":{"creditCardNumber":"1111222233334444","pin":"0000"}}}}}},"responses":{"200":{"description":"Pago aprobado: recibo completo en MXN y carrito vacío.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentReceipt"},"examples":{"compraDeDosPiezas":{"value":{"status":"success","message":"Pago procesado correctamente.","ticketId":"TICKET-8a646941-64c1-4b0a-9e3b-2d9df971bb05","paymentSummary":{"totalAmount":2398.4,"currency":"MXN","paymentMethod":{"card":"**** **** **** 4444"}},"purchasedItems":[{"productId":"45467911","name":"Star Fox Nintendo Switch 2","unitPrice":1199.2,"quantity":2,"totalPrice":2398.4}]}}}}}},"422":{"description":"Solicitud no válida. Corrige los campos señalados en detail[].loc antes de reintentar. Por ejemplo, quantity debe ser entero y mayor que cero al agregar un producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"400":{"description":"Pago no aprobado. No se vacía el carrito. Corrige detail antes de reintentar; no uses datos bancarios reales.","content":{"application/json":{"examples":{"carritoVacio":{"value":{"detail":"El carrito está vacío o no existe"}},"tarjetaNoValida":{"value":{"detail":"Formato de tarjeta no válido"}},"pinIncorrecto":{"value":{"detail":"PIN de prueba no válido"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"CartItem":{"properties":{"productId":{"type":"string","title":"Productid","description":"SKU del producto","examples":["45467911"]},"quantity":{"type":"integer","exclusiveMinimum":0.0,"title":"Quantity","description":"Cantidad de piezas del producto. En POST se suma a la cantidad existente.","examples":[2]}},"type":"object","required":["productId","quantity"],"title":"CartItem","description":"Partida del carrito. Consulta el producto para obtener nombre, plataforma y precio."},"CartItemUpdate":{"properties":{"quantity":{"type":"integer","title":"Quantity","description":"Nueva cantidad absoluta. Un valor de 0 o menor elimina el producto del carrito.","examples":[3,0]}},"type":"object","required":["quantity"],"title":"CartItemUpdate","description":"Cantidad absoluta: no es un incremento ni una diferencia respecto al carrito actual."},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Motivo del error en español; puede incluir el valor recibido y cómo corregir la solicitud","examples":["Carrito no encontrado para el cliente"]}},"type":"object","required":["detail"],"title":"ErrorResponse","description":"Error de negocio: la operación solicitada no pudo completarse."},"PaymentMethod":{"properties":{"card":{"type":"string","title":"Card","description":"Número de tarjeta enmascarado","examples":["**** **** **** 4444"]}},"type":"object","required":["card"],"title":"PaymentMethod"},"PaymentReceipt":{"properties":{"status":{"type":"string","title":"Status","description":"Estado del pago","examples":["success"]},"message":{"type":"string","title":"Message","description":"Mensaje con el resultado de la operación"},"ticketId":{"type":"string","title":"Ticketid","description":"Folio único del recibo. No es un productId ni permite consultar un pedido.","examples":["TICKET-8a646941-64c1-4b0a-9e3b-2d9df971bb05"]},"paymentSummary":{"$ref":"#/components/schemas/PaymentSummary"},"purchasedItems":{"items":{"$ref":"#/components/schemas/PurchasedItem"},"type":"array","title":"Purchaseditems"}},"type":"object","required":["status","message","ticketId","paymentSummary","purchasedItems"],"title":"PaymentReceipt","description":"Comprobante de la compra. Consérvalo: no existe una ruta para consultar recibos anteriores."},"PaymentRequest":{"properties":{"creditCardNumber":{"type":"string","title":"Creditcardnumber","description":"Número de tarjeta ficticio (mínimo 4 dígitos). La pasarela es de prueba; no envíes datos bancarios reales.","examples":["1111222233334444"]},"pin":{"type":"string","title":"Pin","description":"PIN de prueba de 4 dígitos: debe coincidir con los últimos 4 dígitos de la tarjeta ficticia. No uses un NIP bancario real.","examples":["4444"]}},"type":"object","required":["creditCardNumber","pin"],"title":"PaymentRequest","description":"Credenciales ficticias de la pasarela de prueba; nunca envíes datos bancarios reales."},"PaymentSummary":{"properties":{"totalAmount":{"type":"number","title":"Totalamount","description":"Suma de todas las partidas en pesos mexicanos (MXN)","examples":[2398.4]},"currency":{"type":"string","const":"MXN","title":"Currency","description":"Moneda de todos los importes del recibo","default":"MXN"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"}},"type":"object","required":["totalAmount","paymentMethod"],"title":"PaymentSummary","description":"Resumen de compra. currency aplica también a los importes de purchasedItems."},"Product":{"properties":{"id":{"type":"string","title":"Id","description":"SKU del catálogo e identificador único del producto","examples":["45467911"]},"name":{"type":"string","title":"Name","description":"Nombre del producto en español de México; suele incluir la plataforma","examples":["Star Fox Nintendo Switch 2"]},"description":{"type":"string","title":"Description","description":"Descripción del producto","examples":["El regreso de Fox McCloud y su escuadrón a los combates de naves en Switch 2."]},"price":{"type":"number","minimum":0.0,"title":"Price","description":"Precio vigente de una pieza en pesos mexicanos (MXN), no centavos. Ya incluye el descuento: es el importe que se cobra en el carrito","examples":[1199.2]},"listPrice":{"type":"number","minimum":0.0,"title":"Listprice","description":"Precio de lista antes del descuento, en MXN. Es informativo: no se cobra ni se suma a price","examples":[1499.0]},"discountPercent":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Discountpercent","description":"Descuento ya aplicado en price respecto a listPrice, en porcentaje entero. 0 significa sin descuento. No lo vuelvas a aplicar","examples":[20]},"currency":{"type":"string","const":"MXN","title":"Currency","description":"Moneda de los precios: pesos mexicanos","default":"MXN"},"imageUrl":{"type":"string","format":"uri-reference","title":"Imageurl","description":"Ruta de la imagen ilustrativa del producto, relativa al origen de la API. Descárgala con GET sin credenciales. Devuelve image/webp de 512 × 512 píxeles, no JSON.","examples":["/images/products/45467911.webp"]},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Etiquetas de género, público y uso, en minúsculas y sin acentos. searchProducts también busca en ellas","examples":[["nave","accion","arcade","nostalgia","n64","un-jugador"]]},"attributes":{"$ref":"#/components/schemas/ProductAttributes"}},"type":"object","required":["id","name","description","price","listPrice","discountPercent","imageUrl","tags","attributes"],"title":"Product","description":"Artículo vendible por pieza; price es el precio vigente en pesos mexicanos, no centavos."},"ProductAttributes":{"properties":{"brand":{"type":"string","title":"Brand","description":"Marca del producto según el catálogo","examples":["Nintendo"]},"platform":{"type":"string","title":"Platform","description":"Plataforma o familia de consolas con la que es compatible el producto","examples":["Nintendo Switch 2","PlayStation 5","Xbox Series"]},"category":{"type":"string","title":"Category","description":"Categoría del producto","examples":["Videojuegos"]}},"type":"object","required":["brand","platform","category"],"title":"ProductAttributes","description":"Atributos para distinguir productos y aplicar filtros exactos al catálogo."},"PurchasedItem":{"properties":{"productId":{"type":"string","title":"Productid","description":"Identificador del producto"},"name":{"type":"string","title":"Name","description":"Nombre del producto"},"unitPrice":{"type":"number","title":"Unitprice","description":"Precio vigente de una pieza en pesos mexicanos (MXN), con descuento"},"quantity":{"type":"integer","title":"Quantity","description":"Cantidad de piezas compradas"},"totalPrice":{"type":"number","title":"Totalprice","description":"Importe de la partida en pesos mexicanos (MXN)"}},"type":"object","required":["productId","name","unitPrice","quantity","totalPrice"],"title":"PurchasedItem","description":"Partida del recibo: totalPrice = unitPrice × quantity, con importes en MXN."},"ValidationErrorResponse":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationIssue"},"type":"array","title":"Detail","description":"Errores por corregir antes de reenviar la solicitud"}},"type":"object","required":["detail"],"title":"ValidationErrorResponse","description":"Uno o más errores de validación de la solicitud (HTTP 422)."},"ValidationIssue":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Loc","description":"Ubicación del campo: body, query o path, seguida de su nombre","examples":[["body","quantity"],["query","q"]]},"msg":{"type":"string","title":"Msg","description":"Explicación de la validación; puede estar en inglés"},"type":{"type":"string","title":"Type","description":"Código del error de validación","examples":["missing","greater_than"]},"input":{"title":"Input","description":"Valor rechazado, si el framework lo incluye"}},"additionalProperties":true,"type":"object","required":["loc","msg","type"],"title":"ValidationIssue","description":"Detalle de un campo que no cumple el contrato de entrada."}}},"tags":[{"name":"Productos","description":"Descubre productos y consulta precios en MXN. Operaciones de lectura sin modificar el carrito. Empieza aquí para obtener identificadores, marcas, plataformas y categorías válidos."},{"name":"Carrito","description":"Administra productos y cantidades de un cliente usando siempre el mismo user_id. POST suma cantidades; PUT establece cantidades absolutas; DELETE elimina una partida. Cada respuesta exitosa contiene el carrito completo, sin nombres ni precios."},{"name":"Pagos","description":"Completa la compra del carrito y obtiene un recibo en MXN. La pasarela de prueba (mock) no realiza cargos reales: usa solamente datos ficticios. Consulta payCart antes de enviar la solicitud; no uses tarjetas ni NIP bancarios reales."}]}