---
name: shopify-buscar-pedido
description: "Busca y resume el detalle completo de los pedidos de un cliente por correo, número de pedido o teléfono: estado, productos, envío, guía y reembolsos. Úsala para responder rápido a un cliente que pregunta por su pedido."
---

## Propósito
Trae el detalle completo de los pedidos de un cliente sin tener que navegar por el panel de Shopify. Sirve para que el equipo de atención responda las preguntas de los clientes sobre el estado del pedido, el seguimiento del envío y los reembolsos. Esta skill trabaja directamente sobre los datos propios de Shopify y devuelve todo el contexto del pedido en una sola operación.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | texto | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| format | texto | no | human | Formato de salida: `human` o `json` |
| dry_run | booleano | no | false | Muestra las operaciones sin ejecutar mutaciones |
| lookup_by | texto | sí | — | `order_number`, `email` o `phone` |
| lookup_value | texto | sí | — | El valor que se busca (p. ej., `#1001`, `ana@ejemplo.com`, `+573001234567`) |
| limit | entero | no | 5 | Cantidad máxima de pedidos que se devuelven |

## Pasos

1. **OPERACIÓN:** `orders` — consulta
   **Entradas:** `first: <limit>`, `query: "name:<order_number>"` o `"email:<email>"` o `"phone:<phone>"`, según `lookup_by`
   **Resultado esperado:** Pedidos completos con estado de pago, estado de preparación, productos, dirección de envío, seguimiento y reembolsos

## Operaciones GraphQL

```graphql
# orders:query — validada con api_version 2025-01
query OrderLookup($first: Int!, $query: String) {
  orders(first: $first, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        processedAt
        displayFinancialStatus
        displayFulfillmentStatus
        totalPriceSet {
          shopMoney { amount currencyCode }
        }
        subtotalPriceSet {
          shopMoney { amount currencyCode }
        }
        totalShippingPriceSet {
          shopMoney { amount currencyCode }
        }
        totalRefundedSet {
          shopMoney { amount currencyCode }
        }
        customer {
          id
          defaultEmailAddress {
            emailAddress
          }
          firstName
          lastName
          phone
        }
        shippingAddress {
          address1
          address2
          city
          province
          country
          zip
          phone
        }
        lineItems(first: 50) {
          edges {
            node {
              title
              quantity
              variant {
                sku
                price
              }
              fulfillmentStatus
            }
          }
        }
        fulfillments {
          trackingInfo {
            number
            url
            company
          }
          status
          createdAt
        }
        refunds {
          createdAt
          totalRefundedSet {
            shopMoney { amount currencyCode }
          }
        }
        note
        tags
      }
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar la siguiente salida en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: shopify-buscar-pedido                ║
║  Tienda: <dominio de la tienda>              ║
║  Inicio: <YYYY-MM-DD HH:MM UTC>              ║
╚══════════════════════════════════════════════╝
```

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

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
RESUMEN DEL RESULTADO
  Pedidos encontrados:   <n>
  Errores:               0
  Archivo:               ninguno
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-buscar-pedido",
  "store": "<dominio>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "OrderLookup", "type": "query", "params_summary": "lookup_by: <tipo>, lookup_value: <valor>, limit: <n>", "result_summary": "<n> pedidos", "skipped": false }
  ],
  "outcome": {
    "orders_found": 0,
    "errors": 0,
    "output_file": null
  }
}
```

## Formato de salida
Un resumen legible de cada pedido encontrado (no es un CSV). Para cada pedido, Claude presenta: número de pedido, fecha, estado de pago y de preparación, datos del cliente, productos, dirección de envío, números de guía y los reembolsos que haya. Para `format: json`, el arreglo con los objetos de pedido tal como llegan.

## Manejo de errores
| Error | Causa | Solución |
|-------|-------|----------|
| No se devuelven pedidos | Nada coincide con el valor buscado | Revisa el formato del valor (el número de pedido debe incluir `#`, p. ej., `#1001`) |
| `lookup_by` inválido | El valor no es `order_number`, `email` ni `phone` | Usa uno de los tres valores aceptados |
| Límite de solicitudes (429) | Demasiadas solicitudes | Reduce `limit` o espera y reintenta |

## Buenas prácticas
1. Las búsquedas por número de pedido requieren el prefijo `#` (p. ej., `#1001`), que corresponde al campo `name` en la consulta GraphQL.
2. Las búsquedas por teléfono deben usar el formato E.164 (p. ej., `+573001234567`); los números incompletos no coinciden.
3. La búsqueda por correo devuelve todos los pedidos de ese cliente: sube `limit` por encima de 5 (el valor predeterminado) si el cliente tiene muchos pedidos.
4. Con `format: json`, pasa la salida por `jq` para extraer campos específicos y usarlos en otros scripts.
5. Esta skill es de solo lectura: usa la skill `shopify-reembolso-y-reposicion` si necesitas hacer un reembolso después de buscar el pedido.