---
name: shopify-notas-de-pedidos
description: "Reúne en una tabla las notas y los atributos personalizados de los pedidos recientes: mensajes de regalo, personalizaciones, grabados e instrucciones especiales. Úsala al empezar cada turno de despacho para que no se pase por alto ningún pedido especial. Solo lee."
---

## Propósito
Consulta los pedidos recientes y extrae las notas del pedido y los atributos personalizados de cada artículo (p. ej., mensajes de regalo, texto de personalización, instrucciones especiales, texto para grabar). Genera un reporte para que los equipos de operaciones y despacho atiendan las solicitudes especiales durante el alistamiento y el empaque. Solo lectura: no ejecuta mutaciones.

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

## 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 | 1 | Ventana de días hacia atrás (predeterminado: últimas 24 horas, para el uso operativo diario) |
| attribute_keys | array | no | [] | Claves específicas de atributos de artículo que se extraen (p. ej., `["gift_message", "engraving"]`); vacío = todas |
| only_with_notes | bool | no | false | Incluye solo los pedidos que tienen una nota o atributos |
| 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:** `orders` — consulta
   **Entradas:** `query: "created_at:>='<NOW - days_back days>'"`, `first: 250`, selecciona `note`, `customAttributes`, `lineItems { customAttributes }` y el cursor de paginación
   **Resultado esperado:** Los pedidos con sus notas y atributos personalizados; pagina hasta que `hasNextPage: false`

2. Si `only_with_notes: true`: deja solo los pedidos con `note` no vacía o con `customAttributes` no vacíos

3. Si se especificó `attribute_keys`: deja solo los atributos de artículo cuyas claves coinciden

## Operaciones GraphQL

```graphql
# orders:query — validado con api_version 2025-01
query OrderNotesAndAttributes($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        displayFulfillmentStatus
        note
        customAttributes {
          key
          value
        }
        lineItems(first: 20) {
          edges {
            node {
              id
              title
              quantity
              variant {
                sku
              }
              customAttributes {
                key
                value
              }
            }
          }
        }
        shippingAddress {
          firstName
          lastName
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

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

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════════╗
║  SKILL: Reporte de notas y atributos de pedidos  ║
║  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 NOTAS Y ATRIBUTOS DE PEDIDOS  (<days_back> día(s))
  Pedidos consultados:     <n>
  Pedidos con notas:       <n>
  Pedidos con atributos:   <n>

  #<name>  <cliente>  [<estado>]
    Nota: "<texto de la nota>"
    Artículo: "<producto>"  gift_message: "¡Feliz cumpleaños!"
  Archivo: order_notes_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-notas-de-pedidos",
  "store": "<dominio>",
  "period_days": 1,
  "orders_queried": 0,
  "orders_with_notes": 0,
  "orders_with_attributes": 0,
  "output_file": "order_notes_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `order_notes_<AAAA-MM-DD>.csv` con las columnas:
`order_name`, `order_id`, `created_at`, `fulfillment_status`, `customer_name`, `order_note`, `line_item_title`, `line_sku`, `attribute_key`, `attribute_value`

## 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 |
| No hay pedidos con notas | Periodo tranquilo o la tienda no recoge notas | Termina con 0 resultados si `only_with_notes: true` |

## Buenas prácticas
- Ejecútala al inicio de cada turno de despacho (p. ej., `days_back: 1`) para que quienes alistan y empacan tengan una lista impresa de instrucciones especiales antes de empezar.
- Usa `attribute_keys: ["gift_message"]` para enfocarte solo en los pedidos de regalo durante la temporada de fin de año.
- Los pedidos que tienen a la vez una nota y atributos de artículo necesitan una preparación más cuidadosa: márcalos para que los revise el personal con más experiencia.
- Imprime o exporta el CSV y adjúntalo a la lista de alistamiento para atender los casos especiales sin demoras durante el despacho.