---
name: shopify-reporte-riesgo-pedidos
description: "Solo lectura: lista los pedidos según su nivel de riesgo de fraude, con los indicadores que detectó Shopify, para armar una cola de revisión manual. Úsala cuando quieras revisar pedidos sospechosos antes de despacharlos."
---

## Propósito
Consulta los pedidos recientes y muestra los que tienen riesgo de fraude alto o medio, junto con los indicadores específicos que marcó Shopify (dirección de facturación distinta a la de envío, dominio de correo riesgoso, IP de alto riesgo, etc.). Genera una cola de revisión priorizada para evaluar el fraude a mano. 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 la API: `read_orders`

## Parámetros

| Parámetro | Tipo | Obligatorio | Por defecto | Descripción |
|-----------|------|-------------|-------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| risk_level | string | no | high | Nivel de riesgo mínimo que se incluye: `high`, `medium` o `all` |
| days_back | integer | no | 7 | Cuántos días hacia atrás revisar pedidos |
| min_order_value | float | no | 0 | Incluye solo los pedidos por encima de este valor (en la moneda de la tienda) |
| format | string | no | human | Formato de salida: `human` o `json` |

## Seguridad

> ℹ️ Skill de solo lectura: no ejecuta mutaciones. Puedes correrla en cualquier momento. Los niveles de riesgo los genera el análisis de fraude de Shopify y son solo orientativos: no bloquean pedidos automáticamente a menos que configures los filtros de fraude de Shopify.

## Pasos

1. **OPERACIÓN:** `orders` — consulta
   **Entradas:** `query: "risk_level:<risk_level> created_at:>='<NOW - days_back days>'"`, `first: 250`, selecciona `riskLevel`, `riskFacts`, `totalPriceSet`, `customer`, cursor de paginación
   **Resultado esperado:** Pedidos con sus datos de riesgo; pagina hasta que `hasNextPage: false`

2. Ordena por nivel de riesgo (alto primero) y luego por valor del pedido, de mayor a menor

## Operaciones GraphQL

```graphql
# orders:query — validado con api_version 2025-01
query OrderRiskReport($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        displayFulfillmentStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        riskLevel
        riskFacts {
          message
          sentiment
        }
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
          numberOfOrders
        }
        shippingAddress {
          countryCode
          city
        }
        billingAddress {
          countryCode
          city
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar esta salida en cada etapa. Es obligatorio.**

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

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

**Al terminar**, muestra:

Para `format: human` (por defecto):
```
══════════════════════════════════════════════
REPORTE DE RIESGO DE PEDIDOS  (<days_back> días)
  Pedidos revisados:  <n>
  Riesgo alto:        <n>
  Riesgo medio:       <n>
  Riesgo bajo:        <n>

  Pedidos de riesgo alto:
    #<nombre>  $<monto>  <cliente>
      Riesgos: <indicador>, <indicador>
  Archivo: risk_report_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-reporte-riesgo-pedidos",
  "store": "<dominio>",
  "period_days": 7,
  "orders_reviewed": 0,
  "high_risk_count": 0,
  "medium_risk_count": 0,
  "output_file": "risk_report_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `risk_report_<YYYY-MM-DD>.csv` con las columnas:
`order_name`, `order_id`, `created_at`, `risk_level`, `total_price`, `currency`, `customer_name`, `customer_email`, `risk_indicators`, `financial_status`, `fulfillment_status`

## 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 de riesgo alto | Período sin alertas | Termina con el resumen: 0 pedidos marcados |
| `riskLevel` en null | El pedido es demasiado reciente para analizarlo | Exclúyelo del reporte y anota cuántos hubo |

## Buenas prácticas
- No canceles automáticamente los pedidos de riesgo alto: usa primero `shopify-pedidos-alto-riesgo` para marcarlos y retenerlos, y revísalos antes de cancelar.
- Un pedido de un cliente recurrente (`numberOfOrders > 3`) con riesgo alto suele ser un falso positivo: usa tu criterio antes de actuar.
- `min_order_value` te ayuda a enfocar la revisión en los pedidos de mayor valor; un piso equivalente a unos 50 dólares, expresado en la moneda de la tienda, es razonable para la mayoría de las tiendas.
- Córrela a diario como parte de la rutina de la mañana, sobre todo en temporadas de muchas ventas, cuando aumentan los intentos de fraude.