---
name: shopify-emitir-tarjetas-regalo
description: "Emite tarjetas de regalo de Shopify (saldo a favor) a un cliente como compensación, incentivo después de una devolución o premio de fidelidad. Úsala cuando quieras compensar un envío retrasado o dar crédito en la tienda en lugar de devolver el dinero."
---

## Propósito
Emite tarjetas de regalo nativas de Shopify a tus clientes de forma automática: como compensación por un envío retrasado, como saldo a favor en la tienda en lugar de un reembolso en dinero o como premio de fidelidad. Usa el sistema de tarjetas de regalo propio de Shopify; no necesita apps externas. Las tarjetas emitidas aquí se redimen en el checkout igual que las que creas a mano. Nota: `giftCardCreate` está disponible en todos los planes de Shopify, pero puede requerir que la tienda tenga las tarjetas de regalo activadas en la configuración.

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_customers,write_gift_cards`
- Las consultas se ejecutan con `shopify store execute`.
- Permisos (scopes) de API: `read_customers`, `write_gift_cards`
- Las tarjetas de regalo deben estar activadas en el panel de Shopify → Configuración → Tarjetas de regalo

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| format | string | no | human | Formato de salida: `human` o `json` |
| dry_run | bool | no | false | Muestra las operaciones sin ejecutar mutaciones |
| customer_email | string | sí* | — | Correo del cliente que se busca y se asocia a la tarjeta de regalo |
| customer_id | string | sí* | — | GID del cliente (alternativa al correo) |
| amount | float | sí | — | Valor de la tarjeta de regalo en la moneda predeterminada de la tienda |
| reason | string | no | — | Nota interna que queda registrada en la tarjeta (p. ej., `"Cortesía: envío retrasado #1042"`) |
| expires_on | string | no | — | Fecha de vencimiento en ISO 8601 (p. ej., `2026-12-31`); si se omite, la tarjeta no vence |
| tag_customer | string | no | — | Etiqueta opcional que se agrega a la ficha del cliente (p. ej., `goodwill-issued`) |

*Se requiere `customer_email` o `customer_id`.

## Seguridad

> ⚠️ El paso 2 ejecuta `giftCardCreate`, que emite valor monetario real a cargo de tu tienda. Las tarjetas de regalo no se pueden eliminar una vez creadas; solo se pueden desactivar. Ejecútala con `dry_run: true` para confirmar el cliente, el monto y el vencimiento antes de aplicarla. Revisa el monto con cuidado: el valor emitido se puede redimir de inmediato en el checkout.

## Pasos

1. **OPERACIÓN:** `customer` — consulta
   **Entradas:** Busca por `customer_email` (con la búsqueda de clientes) o directamente por `customer_id`
   **Resultado esperado:** `id`, `firstName`, `lastName` y `email` del cliente; confirma que el cliente existe antes de emitir

2. **OPERACIÓN:** `giftCardCreate` — mutación
   **Entradas:** `input.initialValue`, `input.customerId`, `input.expiresOn` (opcional), `input.note` (el motivo)
   **Resultado esperado:** `giftCard.id`, `giftCard.code`, `giftCard.balance`, `giftCard.expiresOn`, `userErrors`

## Operaciones GraphQL

```graphql
# customer:query — validado con api_version 2025-01
query CustomerByEmail($query: String!) {
  customers(first: 1, query: $query) {
    edges {
      node {
        id
        firstName
        lastName
        defaultEmailAddress {
          emailAddress
        }
        tags
      }
    }
  }
}
```

```graphql
# giftCardCreate:mutation — validado con api_version 2025-01
mutation GiftCardCreate($input: GiftCardCreateInput!) {
  giftCardCreate(input: $input) {
    giftCard {
      id
      code
      balance {
        amount
        currencyCode
      }
      expiresOn
      note
      customer {
        id
      }
    }
    userErrors {
      field
      message
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.**

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

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

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
  Cliente:               <nombre> (<correo>)
  Código de la tarjeta:  <código>
  Monto:                 <monto> <moneda>
  Vence:                 <fecha o "No vence">
  Errores:               0
  Archivo:               ninguno
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-emitir-tarjetas-regalo",
  "store": "<dominio>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "CustomerByEmail", "type": "query", "params_summary": "correo <email>", "result_summary": "cliente <id>", "skipped": false },
    { "step": 2, "operation": "GiftCardCreate", "type": "mutation", "params_summary": "monto <amount>, cliente <id>", "result_summary": "tarjeta de regalo <code>", "skipped": false }
  ],
  "outcome": {
    "customer_id": "<id>",
    "customer_email": "<correo>",
    "gift_card_id": "<id>",
    "gift_card_code": "<código>",
    "amount": "<monto>",
    "currency": "<moneda>",
    "expires_on": "<fecha o null>",
    "errors": 0,
    "output_file": null
  }
}
```

## Formato de salida
No genera CSV. El resumen de la sesión muestra el código y el monto de la tarjeta de regalo. El agente de soporte copia el código para compartirlo con el cliente.

```
Tarjeta de regalo emitida:
  Cliente:  Ana Gómez (ana@ejemplo.com)
  Código:   ABCD-EFGH-IJKL-MNOP
  Valor:    25.00 USD
  Vence:    2026-12-31 (o "No vence")
  Nota:     Cortesía: envío retrasado #1042
```

## Manejo de errores
| Error | Causa | Solución |
|-------|-------|----------|
| Cliente no encontrado | El correo no coincide con ningún cliente | Verifica el correo; quienes compraron como invitados pueden no tener ficha de cliente |
| `userErrors` de giftCardCreate | Monto no válido (≤ 0) o falta un campo obligatorio | Verifica que `amount` sea un número positivo |
| Tarjetas de regalo desactivadas | La configuración de la tienda no permite tarjetas de regalo | Actívalas en el panel de Shopify → Configuración → Tarjetas de regalo |
| Falta el permiso `write_gift_cards` | La autenticación se hizo sin ese permiso | Vuelve a ejecutar `shopify store auth` con el permiso `write_gift_cards` |

## Buenas prácticas
1. Ejecútala siempre con `dry_run: true` para confirmar que el cliente existe y que el monto es correcto antes de emitir.
2. Incluye siempre una nota en `reason`: aparece en el registro de la tarjeta y ayuda a tu equipo a auditar las emisiones más adelante.
3. Usa `tag_customer: goodwill-issued` para saber qué clientes han recibido tarjetas de cortesía; combínalo con `shopify-segmento-fidelizacion` para seguir cómo compran después.
4. Usa `expires_on` en las tarjetas promocionales (p. ej., campañas de temporada) para crear urgencia; omítelo en las de cortesía para que el cliente sienta que el gesto es genuino.
5. Para emisiones en lote (p. ej., una falla del servicio que afectó a 100 clientes), recorre una lista de clientes con `format: json` para guardar el código de cada tarjeta en tus registros.