--- name: shopify-reordenar-coleccion description: "Reordena los productos de una colección manual según su inventario: los que tienen stock arriba y los agotados abajo. Úsala cuando quieras que tus clientes vean primero lo que sí puedes vender, sin mover productos uno por uno en el panel de Shopify." --- ## Propósito Reordena los productos de una colección manual de Shopify según su nivel de inventario, sin tener que entrar al panel de Shopify. Esta skill consulta todos los productos de la colección, calcula el orden deseado según `totalInventory` y lo aplica en una sola mutación `collectionReorderProducts`. Nota: solo funciona en colecciones manuales (personalizadas); no admite las colecciones inteligentes que Shopify maneja por reglas. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_products,write_products` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: `read_products`, `write_products` ## Parámetros | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) | | format | string | no | human | Formato de salida: `human` o `json` | | dry_run | bool | no | false | Muestra las operaciones sin ejecutar mutaciones | | collection_id | string | sí | — | GID de la colección manual (p. ej., `gid://shopify/Collection/123`) | | sort_by | string | no | inventory_desc | `inventory_desc` (primero los que tienen más stock) o `inventory_asc` (primero los que tienen menos stock) | ## Seguridad > ⚠️ El paso 2 ejecuta `collectionReorderProducts`, que cambia de inmediato el orden en que se muestran los productos. El orden se puede revertir (vuelve a ejecutarla con el `sort_by` contrario para restaurar el orden anterior), pero el orden personalizado original no se puede recuperar una vez sobrescrito. La lista `moves` que se pasa a la mutación debe estar completa; los movimientos parciales producen un orden indefinido. Ejecútala siempre primero con `dry_run: true` para revisar el orden calculado antes de aplicarlo. `collectionReorderProducts` solo funciona en colecciones manuales (personalizadas). Si la colección tiene un `sortOrder` distinto de `MANUAL`, la skill debe detenerse con un mensaje claro: «No se puede reordenar: el orden de la colección no es MANUAL. Primero cambia la colección a orden manual en el panel de Shopify.» ## Pasos 1. **OPERACIÓN:** `collection` — consulta **Entradas:** `id: `, `first: 250` y el cursor de paginación **Resultado esperado:** Los datos de la colección (título, `sortOrder`) y todos sus productos con `totalInventory`; verifica que `sortOrder == "MANUAL"` y detente si no lo es; pagina hasta obtener todos los productos 2. **OPERACIÓN:** `collectionReorderProducts` — mutación **Entradas:** `id: ` y la lista `moves` ordenada por `totalInventory` según el parámetro `sort_by`; cada movimiento es `{id: , newPosition: ""}` (un texto, contando desde 0) **Resultado esperado:** `job.id` y `job.done`; `userErrors` ## Operaciones GraphQL ```graphql # collection:query — validado con api_version 2025-01 query CollectionProducts($id: ID!, $first: Int!, $after: String) { collection(id: $id) { id title sortOrder products(first: $first, after: $after) { edges { node { id title totalInventory variants(first: 100) { edges { node { inventoryQuantity } } } } } pageInfo { hasNextPage endCursor } } } } ``` ```graphql # collectionReorderProducts:mutation — validado con api_version 2025-01 mutation CollectionReorderProducts($id: ID!, $moves: [MoveInput!]!) { collectionReorderProducts(id: $id, moves: $moves) { job { id done } userErrors { field message } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: shopify-reordenar-coleccion ║ ║ Tienda: ║ ║ Inicio: ║ ╚══════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` Si `dry_run: true`, antepón `[SIMULACIÓN]` a cada paso de mutación y no lo ejecutes. **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ RESUMEN DEL RESULTADO Colección: Productos reordenados: Orden: Errores: 0 Archivo: ninguno ══════════════════════════════════════════════ ``` Para `format: json`, muestra: ```json { "skill": "shopify-reordenar-coleccion", "store": "", "started_at": "", "completed_at": "", "dry_run": false, "steps": [ { "step": 1, "operation": "CollectionProducts", "type": "query", "params_summary": "collection_id: , first: 250", "result_summary": " productos obtenidos", "skipped": false }, { "step": 2, "operation": "CollectionReorderProducts", "type": "mutation", "params_summary": "sort_by: inventory_desc, movimientos", "result_summary": "trabajo enviado", "skipped": false } ], "outcome": { "collection_title": "", "products_reordered": 0, "sort_by": "inventory_desc", "errors": 0, "output_file": null } } ``` ## Formato de salida No genera archivo CSV. La skill reporta el nuevo orden en el resumen final de la sesión. Usa `dry_run: true` para ver la lista de posiciones calculada sin aplicarla. ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | `sortOrder is not MANUAL` | La colección es inteligente (automática) | Cambia la colección a orden manual en el panel de Shopify | | `userErrors` en la mutación | ID de producto o posición no válidos | Verifica que todos los ID de producto pertenezcan a la colección | | Colección no encontrada | GID de colección no válido | Verifica el GID en el panel de Shopify | | Límite de solicitudes (429) | Demasiadas solicitudes paginadas | Baja `first` a 100 y reintenta | ## Buenas prácticas 1. Ejecútala siempre primero con `dry_run: true`: la skill muestra el orden de productos propuesto para que lo verifiques antes de aplicarlo. 2. `collectionReorderProducts` es asíncrona: `job.done` puede ser `false` justo después de enviarla. El orden queda aplicado en pocos segundos; recarga la tienda para verificarlo. 3. Usa `sort_by: inventory_desc` para mandar los productos agotados al final de la página de la colección y reducir la frustración de los clientes. 4. En colecciones grandes (más de 250 productos), la paginación es automática pero alarga la ejecución. Considera ejecutarla en horas de poco tráfico. 5. Esta skill solo lee `totalInventory` del producto: no suma por ubicación. Si necesitas ordenar según una bodega o tienda física específica, usa la skill `shopify-reabastecer-stock-bajo` para identificar qué productos priorizar.