---
name: shopify-clientes-duplicados
description: "Solo lectura: encuentra fichas de clientes que probablemente están duplicadas, cruzando correo, teléfono o nombre. Úsala para limpiar tu base de clientes antes de unir los duplicados a mano en Shopify."
---

## Propósito
Revisa la base de clientes en busca de registros probablemente duplicados, comparando correo, teléfono y nombre. Los clientes duplicados parten el historial de pedidos y dañan el cálculo del valor de vida del cliente (LTV) y la segmentación de marketing. Solo lectura: no ejecuta mutaciones.

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_customers`
- Las consultas se ejecutan con `shopify store execute`.
- Permisos de la API: `read_customers`

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | texto | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| match_on | texto | no | email | Criterio de coincidencia: `email`, `phone`, `name` o `all` |
| min_orders | entero | no | 0 | Solo marca duplicados en los que al menos un registro tenga esta cantidad de pedidos |
| format | texto | no | human | Formato de salida: `human` o `json` |

## Seguridad

> ℹ️ Skill de solo lectura: no ejecuta mutaciones. Puedes correrla en cualquier momento. La API de administración de Shopify no permite unir clientes duplicados: los duplicados marcados se tienen que unir a mano en el panel de Shopify.

## Pasos

1. **OPERACIÓN:** `customers` — consulta
   **Entradas:** `first: 250`; selecciona `email`, `phone`, `firstName`, `lastName`, `numberOfOrders`, `totalSpentV2` y el cursor de paginación
   **Resultado esperado:** Todos los clientes con sus datos de contacto y de pedidos; pagina hasta que `hasNextPage: false`

2. Arma mapas de búsqueda en memoria:
   - `email → [customer_ids]`
   - `phone → [customer_ids]` (si `match_on` incluye el teléfono)
   - `"firstName lastName" → [customer_ids]` (si `match_on` incluye el nombre)

3. Reporta como probables duplicados los grupos que tengan más de 1 cliente por clave

## Operaciones GraphQL

```graphql
# customers:query — validada con api_version 2025-01
query CustomersForDeduplication($after: String) {
  customers(first: 250, after: $after) {
    edges {
      node {
        id
        displayName
        firstName
        lastName
        defaultEmailAddress {
          emailAddress
        }
        phone
        numberOfOrders
        amountSpent {
          amount
          currencyCode
        }
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar la siguiente salida en cada etapa. Es obligatorio.**

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

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

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
REPORTE DE CLIENTES DUPLICADOS
  Clientes revisados:          <n>
  Grupos de duplicados:        <n>
  Clientes afectados:          <n>

  Grupos de duplicados (muestra):
    Correo: cliente@ejemplo.com
      Cliente A — <n> pedidos, $<n> gastados, creado el <fecha>
      Cliente B — <n> pedidos, $<n> gastados, creado el <fecha>
  Archivo: duplicate_customers_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-clientes-duplicados",
  "store": "<dominio>",
  "customers_scanned": 0,
  "duplicate_groups": 0,
  "customers_affected": 0,
  "output_file": "duplicate_customers_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `duplicate_customers_<YYYY-MM-DD>.csv` con las columnas:
`duplicate_group_id`, `match_key`, `match_type`, `customer_id`, `name`, `email`, `phone`, `number_of_orders`, `total_spent`, `created_at`

## 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 se encontraron duplicados | La base de clientes está limpia | Termina con ✅ no se encontraron duplicados |

## Buenas prácticas
- Shopify no ofrece una API nativa para unir clientes: los duplicados marcados se resuelven a mano en el panel de Shopify (Clientes → Combinar).
- `match_on: email` encuentra los duplicados más confiables; `match_on: name` da más falsos positivos (por los nombres comunes).
- Prioriza los duplicados en los que al menos un registro tiene pedidos: son los que más afectan el LTV y la segmentación de marketing.
- Causas comunes de duplicados: una compra como invitado seguida de la creación de una cuenta, importaciones manuales de clientes o clientes que usan varios correos.