--- name: shopify-iniciar-devolucion description: "Crea un registro formal de devolución en Shopify para un pedido, con los artículos, las cantidades y el motivo: el primer paso del flujo nativo de devoluciones. Úsala cuando un cliente te contacte para devolver productos que ya recibió." --- ## Propósito Inicia una devolución formal en Shopify sobre un pedido entregado, indicando qué artículos se devuelven, en qué cantidades y por qué motivo. Esto crea el registro de la devolución en el sistema nativo de devoluciones de Shopify (que es distinto de solo hacer un reembolso). La usan los agentes de atención al cliente cuando un cliente los contacta para devolver artículos que ya le llegaron. El registro de devolución permite hacer seguimiento, inspeccionar en bodega y resolver después con un cambio o un reembolso. Nota: `returnCreate` exige que el pedido esté en estado `FULFILLED`. Para pedidos que todavía no se han despachado, usa `shopify-cancelar-y-reponer-stock`. Para artículos ya devueltos que necesitan reembolso, usa `shopify-reembolso-y-reposicion`. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_orders,write_returns` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: `read_orders`, `write_returns` ## Parámetros | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) | | format | string | no | human | Formato de salida: `human` o `json` | | dry_run | bool | no | false | Muestra las operaciones sin ejecutar las mutaciones | | order_id | string | sí | — | GID del pedido (p. ej., `gid://shopify/Order/12345`) | | return_line_items | array | no | todos los despachados | Arreglo de `{fulfillment_line_item_id, quantity, reason, reason_note}` que se devuelven | | return_reason | string | no | `OTHER` | Motivo de devolución predeterminado para todos los artículos que no tengan uno propio: `SIZE_TOO_SMALL`, `SIZE_TOO_LARGE`, `WRONG_ITEM`, `NOT_AS_DESCRIBED`, `DEFECTIVE`, `STYLE`, `COLOR`, `UNWANTED`, `OTHER` | | notify_customer | bool | no | true | Envía al cliente el correo de aviso de inicio de la devolución | ## Seguridad > ⚠️ El paso 2 ejecuta `returnCreate`, que crea un registro formal de devolución y, si `notify_customer: true`, le envía un correo al cliente. Hazlo solo después de confirmar con el cliente que va a devolver los productos. Ejecuta con `dry_run: true` para revisar los artículos y las cantidades de la devolución antes de crearla. ## Pasos 1. **OPERACIÓN:** `order` — consulta **Entradas:** `id: ` **Resultado esperado:** `name` del pedido, `displayFulfillmentStatus` (debe ser `FULFILLED`; detén el proceso si no lo es), `fulfillments` con sus `fulfillmentLineItems`, incluidos `id`, `quantity` y `discountedTotalSet` 2. **OPERACIÓN:** `returnCreate` — mutación **Entradas:** `returnInput.orderId`, arreglo `returnInput.returnLineItems` (cada uno con `fulfillmentLineItemId`, `quantity`, `reason`, `customerNote`) **Resultado esperado:** `return.id`, `return.status: OPEN`, `userErrors` ## Operaciones GraphQL ```graphql # order:query — validada con api_version 2025-01 query OrderForReturn($id: ID!) { order(id: $id) { id name displayFulfillmentStatus displayFinancialStatus customer { id defaultEmailAddress { emailAddress } firstName lastName } fulfillments { id status fulfillmentLineItems(first: 50) { edges { node { id quantity lineItem { title variant { id sku } } discountedTotalSet { shopMoney { amount currencyCode } } } } } } } } ``` ```graphql # returnCreate:mutation — validada con api_version 2025-01 mutation ReturnCreate($returnInput: ReturnInput!) { returnCreate(returnInput: $returnInput) { return { id status order { id name } } userErrors { field message } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: shopify-iniciar-devolucion ║ ║ 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 Pedido: ID de la devolución: Artículos incluidos: Estado de la devolución: Cliente notificado: Errores: 0 Archivo: ninguno ══════════════════════════════════════════════ ``` Para `format: json`, muestra: ```json { "skill": "shopify-iniciar-devolucion", "store": "", "started_at": "", "completed_at": "", "dry_run": false, "steps": [ { "step": 1, "operation": "OrderForReturn", "type": "query", "params_summary": "pedido ", "result_summary": "", "skipped": false }, { "step": 2, "operation": "ReturnCreate", "type": "mutation", "params_summary": " artículos, motivo: ", "result_summary": "devolución ", "skipped": false } ], "outcome": { "order_name": "", "return_id": "", "return_status": "", "line_items_count": "", "customer_notified": "", "errors": 0, "output_file": null } } ``` ## Formato de salida No genera CSV. El resumen de la sesión muestra el ID y el estado de la devolución. Los artículos incluidos en la devolución aparecen en la salida del paso 2. ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | `displayFulfillmentStatus` distinto de `FULFILLED` | El pedido todavía no se ha despachado | Usa `shopify-cancelar-y-reponer-stock` para pedidos sin despachar | | No se encuentra `fulfillmentLineItemId` | El ID del artículo no pertenece a los despachos de este pedido | Vuelve a consultar el pedido para obtener los IDs correctos de los artículos despachados | | `userErrors` de returnCreate | Cantidad o motivo no válidos | Verifica que `quantity` no supere `fulfillmentLineItem.quantity` | | La devolución ya existe | Ya se creó una devolución para esos artículos | Revisa las devoluciones del pedido en el panel de Shopify | ## Buenas prácticas 1. Ejecuta siempre primero con `dry_run: true`: confirma los IDs de los artículos despachados y las cantidades antes de crear el registro de devolución. 2. La skill `shopify-iniciar-devolucion` solo crea el registro de devolución: no hace el reembolso. Después de inspeccionar el artículo devuelto, usa `shopify-reembolso-y-reposicion` para procesar el reembolso del dinero. 3. Indica `reason` en cada artículo cuando tengan motivos de devolución distintos: así mejoran tus análisis de devoluciones en Shopify. 4. Para cambios (no reembolsos), crea aquí el registro de devolución y luego usa `shopify-reembolso-y-reposicion` con `create_replacement: true` para generar un borrador de pedido de reposición. 5. La devolución queda en `status: OPEN` al crearla; pasa a `IN_PROGRESS` cuando se genera la guía de devolución y a `CLOSED` cuando se procesa el reembolso.