---
name: shopify-conciliar-pagos
description: "Solo lectura: concilia los pagos (payouts) de Shopify Payments con las transacciones de los pedidos que los originaron y marca las diferencias de montos. Úsala cuando quieras confirmar que lo que te deposita Shopify cuadra con tus ventas, reembolsos y comisiones."
---

## Propósito
Concilia los pagos de Shopify Payments con las transacciones de los pedidos que los componen. Para cada pago, suma las ventas brutas, los reembolsos, los ajustes y las comisiones, y compara el neto calculado con el monto `net` que reporta el pago. Las diferencias se marcan con su delta y la causa probable. Solo lectura: no ejecuta mutaciones.

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_shopify_payments_payouts,read_orders`
- Las consultas se ejecutan con `shopify store execute`.
- Permisos (scopes) de API: `read_shopify_payments_payouts`, `read_orders`
- La tienda debe usar Shopify Payments. Si la tienda solo usa pasarelas de terceros, esta skill termina limpiamente con un mensaje.

## 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 | 30 | Ventana de días hacia atrás que cubre los pagos emitidos en ese periodo |
| tolerance | number | no | 0.01 | Diferencia aceptable, en la moneda de la tienda, antes de marcar una discrepancia |
| format | string | no | human | Formato de salida: `human` o `json` |

## Seguridad

> ℹ️ Skill de solo lectura: no ejecuta mutaciones. El resultado de la conciliación es informativo; no tomes las discrepancias marcadas como errores confirmados antes de revisar las transacciones correspondientes en el admin de Shopify.

## Pasos

1. **OPERACIÓN:** `shopifyPaymentsAccount` — consulta
   **Entradas:** selecciona `payouts(first: 100, query: "issued_at:>='<NOW - days_back days>'")` con `id`, `issuedAt`, `status`, `net`, `gross`, `summary { chargesGross, chargesFee, refundsGross, refundsFee, adjustmentsGross, adjustmentsFee, retriedPayoutsGross, retriedPayoutsFee }`
   **Resultado esperado:** Todos los pagos de la ventana. Si la cuenta es null, termina: la tienda no usa Shopify Payments.

2. Para cada pago, calcula el valor esperado de la conciliación:
   ```
   expected_net = chargesGross - chargesFee
                - refundsGross + refundsFee   (refundsFee normalmente es negativo / revertido)
                + adjustmentsGross - adjustmentsFee
                + retriedPayoutsGross - retriedPayoutsFee
   ```
   `delta = reported_net - expected_net`

3. **OPERACIÓN:** `orders` — consulta (solo para los pagos marcados, para ver el detalle)
   **Entradas:** `query: "transactions:'gateway:shopify_payments processed_at:>=<payout.issuedAt - 7d> processed_at:<=<payout.issuedAt + 1d>'"`, `first: 250`
   **Resultado esperado:** Pedidos candidatos que pudieron aportar al pago, usados para un cruce a nivel de pedido en las discrepancias principales

4. Clasifica cada pago:
   - `ok` si `|delta| <= tolerance`
   - `discrepancy` en caso contrario; registra el signo (positivo: el pago trajo más de lo esperado; negativo: trajo menos)

5. Suma los totales de la ventana: total de pagos, total conciliado, total de discrepancias y suma de los deltas absolutos

## Operaciones GraphQL

```graphql
# shopifyPaymentsAccount:query — validada con api_version 2025-01
query PayoutReconciliation($payoutQuery: String!, $payoutAfter: String) {
  shopifyPaymentsAccount {
    id
    payoutSchedule { interval }
    payouts(first: 100, after: $payoutAfter, query: $payoutQuery) {
      edges {
        node {
          id
          issuedAt
          status
          net { amount currencyCode }
          gross { amount currencyCode }
          summary {
            chargesGross { amount currencyCode }
            chargesFee { amount currencyCode }
            refundsFeeGross { amount currencyCode }
            refundsFee { amount currencyCode }
            adjustmentsGross { amount currencyCode }
            adjustmentsFee { amount currencyCode }
            retriedPayoutsGross { amount currencyCode }
            retriedPayoutsFee { amount currencyCode }
          }
        }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}
```

```graphql
# orders:query — validada con api_version 2025-01
query OrdersFundingPayout($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        processedAt
        totalPriceSet { shopMoney { amount currencyCode } }
        totalReceivedSet { shopMoney { amount currencyCode } }
        transactions {
          id
          gateway
          kind
          status
          processedAt
          amountSet { shopMoney { amount currencyCode } }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}
```

## Seguimiento de la sesión

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

**Al iniciar**, muestra:
```
╔════════════════════════════════════════════════╗
║  SKILL: Concilia los pagos de Shopify Payments ║
║  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>
```

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
CONCILIACIÓN DE PAGOS  (<days_back> días)
  Pagos en la ventana:         <n>
  Conciliados (ok):            <n>
  Discrepancias:               <n>   ⚠️
  Suma de deltas absolutos:    <monto>

  Discrepancias principales:
    Pago <fecha>  Reportado: <n>  Esperado: <n>  Δ: <n>

  Archivo: payout_reconciliation_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-conciliar-pagos",
  "store": "<dominio>",
  "period_days": 30,
  "payouts_count": 0,
  "reconciled_count": 0,
  "discrepancy_count": 0,
  "sum_abs_delta": 0,
  "currency": "<moneda de la tienda>",
  "output_file": "payout_reconciliation_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `payout_reconciliation_<AAAA-MM-DD>.csv` con las columnas:
`payout_id`, `issued_at`, `status`, `reported_net`, `expected_net`, `delta`, `currency`, `charges_gross`, `charges_fee`, `refunds_gross`, `refunds_fee`, `adjustments_gross`, `verdict`

## 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 |
| `shopifyPaymentsAccount` es null | La tienda no usa Shopify Payments | Termina limpiamente; sugiere conciliar desde el panel de la pasarela de terceros |
| Monedas distintas dentro de un pago | Tienda con varias monedas | Concilia solo los pagos cuya moneda de presentación coincide con la moneda de la cuenta; marca los demás como `currency_mismatch` |
| Pago todavía en `IN_TRANSIT` | Aún no es definitivo | Omítelo y concílialo cuando su estado pase a `PAID` |

## Buenas prácticas
- Ejecútala cada semana, la mañana siguiente a un pago programado: conciliar el mismo día detecta las discrepancias mientras las transacciones todavía son fáciles de investigar.
- Revisa a fondo cada discrepancia marcada: los reembolsos procesados dentro de la ventana de un pago suelen aparecer en el `refundsGross` del pago siguiente, lo que puede parecer un pago de menos si olvidas conciliar entre ventanas.
- Usa esta skill junto con tu exportación contable: estas cifras deben coincidir al centavo con los registros de depósitos de tu software contable.
- Usa con cuidado una tolerancia mayor a 0.01 en la moneda de la tienda: cualquier diferencia de más de unos pocos centavos suele reflejar una comisión o un ajuste real que merece explicación.
- Esta skill no detecta fraude; detecta diferencias contables. Si sospechas de un fraude, escálalo desde la vista de detalle del pago en el admin de Shopify.