--- name: shopify-dividir-envio description: "Divide una orden de preparación con varios artículos en envíos separados, para despachos parciales o desde distintas ubicaciones. Úsala cuando los productos de un pedido salgan de bodegas distintas, en fechas distintas o con otra transportadora." --- ## Propósito Divide una orden de preparación que tiene varios artículos en dos o más órdenes de preparación separadas, cada una de las cuales se puede despachar por su cuenta con su propio número de guía. Se usa cuando los artículos de un pedido salen de ubicaciones distintas, en fechas distintas o necesitan transportadoras distintas. Reemplaza el manejo manual de envíos divididos en el panel de Shopify. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_orders,write_fulfillments` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: `read_orders`, `write_fulfillments` - La orden de preparación que se va a dividir debe estar en estado `OPEN` ## Parámetros | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) | | fulfillment_order_id | string | sí | — | GID de la orden de preparación que se va a dividir | | split_groups | array | sí | — | Lista de `{line_item_ids: [], quantities: []}` que define cada grupo de envío | | dry_run | bool | no | true | Muestra la división sin ejecutar la mutación | | format | string | no | human | Formato de salida: `human` o `json` | ## Seguridad > ⚠️ `fulfillmentOrderSplit` es irreversible: una orden de preparación dividida no se puede volver a unir. La orden de preparación original se reemplaza por varias nuevas. Ejecuta con `dry_run: true` para confirmar los grupos antes de aplicar el cambio. Asegúrate de que todos los `line_item_ids` de `split_groups` pertenezcan a la orden de preparación indicada. ## Pasos 1. **OPERACIÓN:** `fulfillmentOrders` — consulta **Entradas:** Consulta la orden de preparación específica por el ID del pedido y filtra por `status: OPEN` **Resultado esperado:** Orden de preparación con todos sus `lineItems { id, remainingQuantity, variant { sku, title } }` 2. Valida `split_groups`: confirma que todos los IDs de artículos existan en la orden de preparación y que las cantidades sean ≤ a las cantidades pendientes 3. **OPERACIÓN:** `fulfillmentOrderSplit` — mutación **Entradas:** `fulfillmentOrderId` y el arreglo `fulfillmentOrderLineItems` de cada grupo **Resultado esperado:** Arreglo con las nuevas `fulfillmentOrders { id, lineItems }`, `userErrors` ## Operaciones GraphQL ```graphql # fulfillmentOrders:query — validada con api_version 2025-01 query FulfillmentOrderLines($orderId: ID!) { order(id: $orderId) { id name fulfillmentOrders(first: 10) { edges { node { id status lineItems(first: 50) { edges { node { id remainingQuantity totalQuantity variant { id sku title } } } } } } } } } ``` ```graphql # fulfillmentOrderSplit:mutation — validada con api_version 2025-01 mutation FulfillmentOrderSplit($fulfillmentOrderId: ID!, $fulfillmentOrderLineItems: [FulfillmentOrderLineItemInput!]!) { fulfillmentOrderSplit( fulfillmentOrderId: $fulfillmentOrderId fulfillmentOrderLineItems: $fulfillmentOrderLineItems ) { fulfillmentOrders { id status lineItems(first: 50) { edges { node { id remainingQuantity variant { sku title } } } } } userErrors { field message } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: shopify-dividir-envio ║ ║ 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 Orden de preparación original: Dividida en: envíos Errores: Envío 1: Envío 2: ══════════════════════════════════════════════ ``` Para `format: json`, muestra: ```json { "skill": "shopify-dividir-envio", "store": "", "started_at": "", "completed_at": "", "dry_run": true, "original_fulfillment_order_id": "", "resulting_fulfillment_orders": [], "errors": 0 } ``` ## Formato de salida Resumen legible de la división. No genera CSV: el resultado de la división se puede ver en el panel de Shopify, en la sección de preparación del pedido. ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | `THROTTLED` | Se superó el límite de solicitudes de la API | Espera 2 segundos y reintenta | | `userErrors`: artículo no válido | El ID del artículo no está en la orden de preparación | Detén el proceso e informa la diferencia | | `userErrors`: la cantidad supera lo pendiente | La cantidad a dividir es mayor que la cantidad pendiente | Detén el proceso e informa cada artículo afectado | | La orden de preparación no está en OPEN | Ya se despachó o se canceló | Detén el proceso e informa el estado | ## Buenas prácticas - Usa `dry_run: true` para revisar los grupos de envío resultantes antes de dividir: una división no se puede deshacer. - Asegúrate de que `split_groups` cubra todos los artículos de la orden de preparación; los que no asignes se quedan en la orden original (la que queda como residuo). - En pedidos con artículos que salen de bodegas distintas, usa la skill `shopify-cambiar-bodega-despacho` para mover cada grupo a la ubicación correcta después de dividir.