--- name: shopify-pedidos-alto-riesgo description: "Etiqueta los pedidos marcados como de alto riesgo para revisión manual y, si quieres, los retiene para que no se despachen. Úsala cuando quieras frenar posibles fraudes antes de enviar la mercancía." --- ## Propósito Consulta los pedidos recientes de alto riesgo y toma dos medidas de protección: etiqueta el pedido para que el equipo lo vea y, opcionalmente, pone una retención de preparación para que el pedido no se despache hasta revisarlo. Complementa a `shopify-reporte-riesgo-pedidos` (que solo lee) con acciones de escritura que crean una cola de revisión. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_orders,write_orders,write_fulfillments` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: `read_orders`, `write_orders`, `write_fulfillments` ## 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) | | min_order_value | float | no | 0 | Solo marca pedidos por encima de este valor | | tag | string | no | fraud-review | Etiqueta que se aplica a los pedidos marcados | | hold_fulfillment | bool | no | true | Pone además una retención de preparación en los pedidos marcados | | hold_reason | string | no | UNKNOWN_PAYMENT_RISK | Motivo de la retención de preparación | | dry_run | bool | no | true | Muestra el resultado sin ejecutar las mutaciones | | format | string | no | human | Formato de salida: `human` o `json` | ## Seguridad > ⚠️ `fulfillmentOrderHold` impide preparar los pedidos hasta que la retención se libere de forma explícita. Mientras dure la retención, los clientes tendrán una demora en el envío. Usa `hold_fulfillment: false` si solo quieres etiquetar sin bloquear la preparación. Ejecuta con `dry_run: true` para confirmar la lista de pedidos antes de aplicar cambios. Después de revisarlos, libera las retenciones con la skill `shopify-retener-pedidos`. ## Pasos 1. **OPERACIÓN:** `orders` — consulta **Entradas:** `query: "risk_level:high created_at:>=''"`, `first: 250`, selecciona `riskLevel`, `fulfillmentOrders`, `totalPriceSet` **Resultado esperado:** Pedidos de alto riesgo dentro de la ventana 2. **OPERACIÓN:** `tagsAdd` — mutación **Entradas:** `id` del pedido, `tags: []` **Resultado esperado:** Etiquetas del pedido actualizadas; `userErrors` 3. **OPERACIÓN:** `fulfillmentOrderHold` — mutación (si `hold_fulfillment: true`) **Entradas:** `fulfillmentOrderId`, `reason: `, `reasonNotes: "Pedido de alto riesgo — pendiente de revisión por fraude"` **Resultado esperado:** `heldFulfillmentOrder { id, status }`, `userErrors` ## Operaciones GraphQL ```graphql # orders:query — validada con api_version 2025-01 query HighRiskOrders($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { id name riskLevel totalPriceSet { shopMoney { amount currencyCode } } tags fulfillmentOrders(first: 5) { edges { node { id status } } } customer { id displayName numberOfOrders } } } pageInfo { hasNextPage endCursor } } } ``` ```graphql # tagsAdd:mutation — validada con api_version 2025-01 mutation TagsAdd($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { field message } } } ``` ```graphql # fulfillmentOrderHold:mutation — validada con api_version 2025-01 mutation FulfillmentOrderHold($id: ID!, $fulfillmentHold: FulfillmentOrderHoldInput!) { fulfillmentOrderHold(id: $id, fulfillmentHold: $fulfillmentHold) { fulfillmentOrder { id status } userErrors { field message } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: Frena los pedidos de alto riesgo ║ ║ Tienda: ║ ║ Inicio: ║ ╚══════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` Si `dry_run: true`, antepón `[SIMULACIÓN]` a cada paso de mutación y no lo ejecutes. **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ RESUMEN DEL RESULTADO Pedidos de alto riesgo encontrados: Pedidos etiquetados: Retenciones de preparación puestas: Errores: Archivo: risk_tagging_.csv ══════════════════════════════════════════════ ``` Para `format: json`, muestra: ```json { "skill": "shopify-pedidos-alto-riesgo", "store": "", "started_at": "", "dry_run": true, "outcome": { "orders_found": 0, "tagged": 0, "holds_placed": 0, "errors": 0, "output_file": "risk_tagging_.csv" } } ``` ## Formato de salida Archivo CSV `risk_tagging_.csv` con las columnas: `order_name`, `order_id`, `risk_level`, `total_price`, `currency`, `tag_applied`, `hold_placed`, `customer_name` ## 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 | | `userErrors` al retener | El pedido ya está preparado o ya tiene una retención | Regístralo como omitido y continúa | | No hay pedidos de alto riesgo | Periodo sin novedades | Termina con 0 pedidos marcados | ## Buenas prácticas - Ejecútala dentro de la primera o segunda hora después de recibir el pedido: la mayoría de los pedidos fraudulentos se hacen esperando que se despachen el mismo día. - Después de poner una retención, usa `shopify-reporte-riesgo-pedidos` para revisar en detalle los indicadores de riesgo antes de decidir si cancelas o liberas el pedido. - Libera los pedidos legítimos con la skill `shopify-retener-pedidos` para reducir al mínimo la demora en el envío. - Es poco probable que los pedidos de clientes recurrentes (`numberOfOrders > 3`) sean fraudulentos; considera excluirlos con `min_order_value` o con una consulta aparte.