--- name: shopify-ajuste-inventario description: "Aplica ajustes de cantidad de inventario a variantes específicas en ubicaciones específicas. Úsala después de un conteo cíclico, de recibir devoluciones de tu operador logístico (3PL) o para corregir diferencias de sincronización." --- ## Propósito Aplica correcciones de cantidad de inventario a variantes específicas en ubicaciones específicas: es el equivalente automatizado de editar el inventario a mano en el admin de Shopify. Úsala cuando un conteo cíclico revele diferencias, cuando un lote de devoluciones de tu operador logístico (3PL) se registre tarde o cuando la skill `shopify-auditoria-inventario-bodegas` detecte desfases entre las cantidades Disponible y Comprometido. Reemplaza la edición manual del inventario fila por fila en el admin de Shopify. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_products,write_inventory`. Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: `read_products`, `write_inventory` ## Parámetros | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) | | format | string | no | human | Formato de salida: `human` o `json` | | dry_run | bool | no | false | Muestra una vista previa de las operaciones sin ejecutar cambios | | adjustments | array | sí | — | Lista de objetos `{sku, location_id, delta}`. `delta` es el cambio de cantidad con signo (p. ej., `+5` para sumar 5 unidades, `-3` para quitar 3) | | reason | string | no | `correction` | Motivo del ajuste que queda en el historial de auditoría: `correction`, `cycle_count`, `damaged`, `received`, `reservation_created`, `reservation_deleted`, `shrinkage` | | reference_document_uri | string | no | — | URI para vincular el ajuste a una orden de compra, una devolución o un documento de conteo cíclico | ## Seguridad > ⚠️ El paso 2 ejecuta `inventoryAdjustQuantities`, que cambia de inmediato las cantidades de inventario publicadas. Un ajuste incorrecto puede provocar sobreventa (si restas de más) o existencias infladas (si sumas por error). Ejecuta con `dry_run: true` para ver las cantidades antes y después de cada SKU antes de confirmar. El campo `reason` queda registrado de forma permanente en el historial de actividad de inventario de Shopify. ## Pasos 1. **OPERACIÓN:** `productVariants` — query **Entradas:** Para cada `{sku}` de `adjustments`: busca la variante por SKU para obtener su `inventoryItem.id`; trae también el `inventoryQuantity` actual para comparar antes y después **Resultado esperado:** Un mapa `{sku → inventoryItemId, currentQuantity}` de todos los SKU a ajustar; detente si algún SKU no aparece 2. **OPERACIÓN:** `inventoryAdjustQuantities` — mutation **Entradas:** Lista `changes` de `{inventoryItemId, locationId, delta, ledgerDocumentUri}` usando los parámetros reason y reference_document_uri **Resultado esperado:** `inventoryAdjustmentGroup.changes` con `quantityAfterChange` por artículo; `userErrors` ## Operaciones GraphQL ```graphql # productVariants:query — validado con api_version 2025-01 query VariantBySku($first: Int!, $query: String) { productVariants(first: $first, query: $query) { edges { node { id sku inventoryQuantity inventoryItem { id tracked } product { title } } } } } ``` ```graphql # inventoryAdjustQuantities:mutation — validado con api_version 2025-01 mutation InventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) { inventoryAdjustQuantities(input: $input) { inventoryAdjustmentGroup { id reason changes { name delta quantityAfterChange item { id sku } location { id name } } } userErrors { field message } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: Ajusta el inventario ║ ║ Tienda: ║ ║ Inicio: ║ ╚══════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` Si `dry_run: true`, antepón `[DRY RUN]` a cada paso de mutación y no lo ejecutes. **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ RESUMEN DEL RESULTADO SKU ajustados: Total de unidades sumadas: Total de unidades restadas: Errores: Archivo: ══════════════════════════════════════════════ ``` Para `format: json`, muestra un objeto JSON con este esquema: ```json { "skill": "shopify-ajuste-inventario", "store": "", "started_at": "", "completed_at": "", "dry_run": false, "steps": [ { "step": 1, "operation": "", "type": "query|mutation", "params_summary": "", "result_summary": "", "skipped": false } ], "outcome": { "skus_adjusted": 0, "total_units_added": 0, "total_units_removed": 0, "errors": 0, "output_file": "" } } ``` ## Formato de salida Archivo CSV `inventory-adjustments-.csv` con las columnas: `sku`, `product_title`, `location_name`, `quantity_before`, `delta`, `quantity_after`, `reason`. ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | SKU no encontrado | El SKU no existe en la tienda | Revisa cómo está escrito el SKU; usa `shopify-reabastecer-stock-bajo` para ver los SKU válidos | | `inventoryItem.tracked: false` | La variante tiene desactivado el seguimiento de inventario | Activa el seguimiento en el admin de Shopify antes de ajustar | | `userErrors` en la mutación | Delta inválido, ubicación inválida o problema de permisos | Revisa el permiso `write_inventory` y verifica el GID de la ubicación | | El delta dejaría la cantidad por debajo de 0 | El ajuste resta más de lo disponible | Confirma que el delta sea correcto; usa deltas negativos solo para salidas de stock que conozcas | ## Buenas prácticas 1. Ejecuta siempre primero con `dry_run: true`: la vista previa en CSV con el antes y el después te permite confirmar cada cambio antes de que toque el inventario publicado. 2. Usa `reason: cycle_count` con un `reference_document_uri` que apunte a tu hoja de conteo: así queda un rastro de auditoría permanente en el historial de actividad de inventario de Shopify. 3. Agrupa todas las correcciones de una misma jornada de conteo en un solo comando en lugar de aplicarlas una por una: el historial las agrupa bajo un solo `inventoryAdjustmentGroup`. 4. Después de ajustar, vuelve a correr `shopify-auditoria-inventario-bodegas` para confirmar que se resolvieron todas las diferencias. 5. Para lotes de devoluciones de tu 3PL, usa `reason: received` y vincula la URI del documento del lote: así es fácil conciliar con la factura de tu operador logístico.