---
name: shopify-velocidad-de-venta
description: "Calcula para cada SKU cuántos días de inventario te quedan al ritmo actual de ventas y qué porcentaje de tu stock ya vendiste. Úsala para planear compras y reabastecer antes de quedarte sin stock. Solo lee, no cambia nada."
---

## Propósito
Calcula dos métricas clave de reabastecimiento para cada SKU con stock:
- **Días de inventario (DoS)**: cuántos días de stock quedan al ritmo actual de ventas
- **Tasa de venta (sell-through)**: porcentaje del stock vendido frente al total recibido en el periodo

Solo lectura: no ejecuta mutaciones.

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_products,read_orders,read_inventory`
- Las consultas se ejecutan con `shopify store execute`.
- Permisos (scopes) de API: `read_products`, `read_orders`, `read_inventory`

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| days_back | integer | no | 30 | Ventana de días de ventas para calcular la velocidad |
| dos_alert_threshold | integer | no | 14 | Marca los SKU que tengan menos de estos días de inventario |
| vendor_filter | string | no | — | Proveedor opcional para limitar el reporte |
| format | string | no | human | Formato de salida: `human` o `json` |

## Seguridad

> ℹ️ Skill de solo lectura: no ejecuta mutaciones. Puedes ejecutarla en cualquier momento sin riesgo.

## Pasos

1. **OPERACIÓN:** `productVariants` — consulta
   **Entradas:** `first: 250`, selecciona `sku`, `inventoryQuantity`, `inventoryItem { id }` y el cursor de paginación
   **Resultado esperado:** Todas las variantes con sus cantidades disponibles; pagina hasta que `hasNextPage: false`

2. **OPERACIÓN:** `orders` — consulta
   **Entradas:** `query: "created_at:>='<NOW - days_back days>'"`, `first: 250`, selecciona `lineItems { variant { id }, quantity }` y el cursor de paginación
   **Resultado esperado:** Las unidades vendidas por variante en la ventana

3. **OPERACIÓN:** `inventoryItems` — consulta
   **Entradas:** Por lotes, con los ID de artículo de inventario de las variantes con stock
   **Resultado esperado:** El costo y si se lleva control de inventario de cada artículo

4. Calcula por SKU:
   - `daily_velocity = units_sold / days_back`
   - `days_of_supply = on_hand / daily_velocity` (∞ si la velocidad = 0)
   - `sell_through_rate = units_sold / (units_sold + on_hand)` × 100

## Operaciones GraphQL

```graphql
# productVariants:query — validado con api_version 2025-01
query VariantsForVelocity($query: String, $after: String) {
  productVariants(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        sku
        inventoryQuantity
        product {
          id
          title
          vendor
        }
        inventoryItem {
          id
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

```graphql
# orders:query — validado con api_version 2025-01
query SalesVelocityData($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        lineItems(first: 50) {
          edges {
            node {
              quantity
              variant {
                id
                sku
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

```graphql
# inventoryItems:query — validado con api_version 2025-01
query InventoryItemDetails($ids: [ID!]!) {
  nodes(ids: $ids) {
    ... on InventoryItem {
      id
      sku
      unitCost {
        amount
        currencyCode
      }
      tracked
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════════╗
║  SKILL: Días de inventario y velocidad de venta  ║
║  Tienda: <dominio de la tienda>                  ║
║  Inicio: <AAAA-MM-DD HH:MM UTC>                  ║
╚══════════════════════════════════════════════════╝
```

**Después de cada paso**, muestra:
```
[N/TOTAL] <CONSULTA|MUTACIÓN>  <OperationName>
          → Parámetros: <resumen breve de las entradas clave>
          → Resultado: <cantidad o desenlace>
```

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
REPORTE DE VELOCIDAD DE VENTA  (ventana de <days_back> días)
  SKU analizados:                          <n>
  Críticos (< <threshold> días de inventario): <n>
  Sanos (≥ <threshold> días de inventario):    <n>
  Sin ventas (velocidad cero):             <n>

  SKU críticos:
    "<producto>"  SKU: <sku>  Días de inventario: <n>  Velocidad: <n>/día
  Archivo: velocity_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-velocidad-de-venta",
  "store": "<dominio>",
  "period_days": 30,
  "dos_alert_threshold": 14,
  "skus_analyzed": 0,
  "critical_count": 0,
  "healthy_count": 0,
  "zero_velocity_count": 0,
  "output_file": "velocity_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `velocity_<AAAA-MM-DD>.csv` con las columnas:
`variant_id`, `sku`, `product_title`, `vendor`, `on_hand`, `units_sold`, `daily_velocity`, `days_of_supply`, `sell_through_pct`, `alert`

## Manejo de errores
| Error | Causa | Solución |
|-------|-------|----------|
| `THROTTLED` | Se superó el límite de solicitudes de la API | Espera 2 segundos y reintenta hasta 3 veces |
| Velocidad cero en todos los SKU | No hay pedidos en la ventana | Marca todos los SKU con stock como "sin ventas" y revisa la ventana de fechas |
| Variante sin artículo de inventario | Kit o producto virtual | Omite los datos de inventario y calcula la velocidad solo con los pedidos |

## Buenas prácticas
- `days_back: 30` funciona bien para los productos de alta rotación; usa `days_back: 90` para los de rotación lenta o de temporada.
- Los SKU con menos de 14 días de inventario y campañas de marketing activas son la máxima prioridad para volver a pedir: compáralos con los tiempos de entrega de tus proveedores.
- Los SKU con velocidad cero son candidatos para la skill `shopify-inventario-muerto`: si llevan 90 días o más sin ventas y con stock disponible, considera rebajarlos o descontinuarlos.
- Ejecútala cada semana en temporada alta para detectar a tiempo los SKU que se agotan rápido.