# RF-MGN-016-002: Integración Clip

**Módulo:** MGN-016 - Integraciones de Pagos y POS
**Prioridad:** P1
**Story Points:** 13
**Estado:** Definido
**Fecha:** 2025-12-05

## Descripción

El sistema debe permitir a los tenants conectar su cuenta de Clip para procesar pagos con tarjeta de crédito y débito usando terminales Clip. La integración soporta terminales Clip Plus, Clip Pro y Clip Total.

## Actores

- **Actor Principal:** Tenant Admin (configura integración)
- **Actores Secundarios:**
  - Vendedor/Cajero (procesa pagos)
  - Cliente final (realiza pago)
  - Clip API (procesa transacción)

## Precondiciones

1. Tenant debe tener suscripción activa con feature `clip_enabled`
2. Tenant debe tener cuenta de Clip activa
3. API Keys de Clip generadas en dashboard de Clip

## Flujo Principal - Configurar Integración

1. Tenant Admin accede a "Configuración > Integraciones > Pagos"
2. Admin selecciona "Conectar Clip"
3. Sistema solicita API Key y Merchant ID
4. Admin ingresa credenciales obtenidas de Clip Dashboard
5. Sistema valida credenciales con API de Clip
6. Sistema almacena credenciales encriptadas
7. Admin vincula terminales Clip existentes
8. Sistema confirma configuración exitosa

## Flujo Principal - Procesar Pago

1. Vendedor crea venta en sistema
2. Vendedor selecciona "Cobrar con Clip"
3. Vendedor selecciona terminal a usar
4. Sistema crea transacción via Clip API
5. Terminal muestra monto a cobrar
6. Cliente presenta tarjeta (chip, NFC, o banda)
7. Cliente ingresa PIN si es requerido
8. Terminal procesa pago
9. Clip envía confirmación via webhook
10. Sistema actualiza estado y genera recibo

## Terminales Clip Soportadas

| Modelo | Conectividad | Impresora | NFC | Precio Aprox |
|--------|--------------|-----------|-----|--------------|
| Clip Plus | Bluetooth | No | Sí | $599 MXN |
| Clip Pro | WiFi, Bluetooth | Sí | Sí | $1,699 MXN |
| Clip Total | 4G, WiFi | Sí | Sí | $2,499 MXN |

## Comisiones Clip

| Tipo de Pago | Comisión | Acreditación |
|--------------|----------|--------------|
| Débito | 2.99% + IVA | 2 días hábiles |
| Crédito (1 pago) | 3.6% + IVA | 2 días hábiles |
| Crédito (MSI 3) | 5.9% + IVA | 2 días hábiles |
| Crédito (MSI 6) | 7.9% + IVA | 2 días hábiles |
| Crédito (MSI 12) | 11.9% + IVA | 2 días hábiles |

## Reglas de Negocio

- **RN-1:** API Key se almacena encriptada
- **RN-2:** Cada terminal tiene un ID único en Clip
- **RN-3:** Transacciones se sincronizan via webhooks
- **RN-4:** Montos mínimos: $10 MXN, máximos según cuenta Clip
- **RN-5:** MSI disponible según tarjetas participantes
- **RN-6:** Reembolsos dentro de 90 días
- **RN-7:** Conciliación diaria con extracto de Clip

## Criterios de Aceptación

- [ ] Tenant Admin puede configurar API Key de Clip
- [ ] Sistema valida credenciales antes de guardar
- [ ] Admin puede vincular múltiples terminales
- [ ] Vendedor puede procesar pagos con Clip
- [ ] Sistema recibe webhooks de confirmación
- [ ] MSI disponible cuando la tarjeta lo permite
- [ ] Dashboard muestra transacciones Clip
- [ ] Reembolsos se pueden procesar desde el sistema
- [ ] Logs de auditoría completos

## Entidades Involucradas

### Usar tablas de integrations (ver RF-016-001)

Campos específicos para Clip:

```sql
-- En payment_providers.config
{
  "merchant_id": "CLIP_MERCHANT_123",
  "environment": "production",
  "msi_enabled": true,
  "accepted_installments": [3, 6, 12]
}

-- En payment_credentials
{
  "api_key_encrypted": "...",
  "webhook_secret_encrypted": "..."
}
```

### integrations.payment_terminals (Clip específico)

```sql
-- Campos adicionales para Clip
{
  "terminal_serial": "CLP-123456",
  "terminal_model": "clip_pro",
  "firmware_version": "1.2.3",
  "last_seen_at": "2025-01-01T10:00:00Z"
}
```

## API de Clip

### Crear Transacción

```typescript
// POST https://api.clip.mx/v1/transactions
const transaction = {
  amount: 1500.00,
  currency: "MXN",
  reference: "ORD-2025-001",
  terminal_id: "term_abc123",
  installments: 1, // 1, 3, 6, o 12
  metadata: {
    order_id: "uuid-order",
    customer_email: "cliente@email.com"
  }
};

// Headers
{
  "Authorization": "Bearer {api_key}",
  "Content-Type": "application/json"
}
```

### Webhook de Clip

```typescript
// POST /webhooks/clip
interface ClipWebhook {
  event: 'transaction.approved' | 'transaction.declined' | 'transaction.refunded';
  data: {
    id: string;
    amount: number;
    status: 'approved' | 'declined' | 'refunded';
    reference: string;
    card: {
      last_four: string;
      brand: 'visa' | 'mastercard' | 'amex';
      type: 'credit' | 'debit';
    };
    installments: number;
    terminal_id: string;
    created_at: string;
  };
}
```

### Listar Terminales

```typescript
// GET https://api.clip.mx/v1/terminals
// Response:
{
  "terminals": [
    {
      "id": "term_abc123",
      "serial": "CLP-123456",
      "model": "clip_pro",
      "status": "active",
      "last_transaction_at": "2025-01-01T10:00:00Z"
    }
  ]
}
```

## Manejo de Errores Clip

| Código | Descripción | Acción |
|--------|-------------|--------|
| `insufficient_funds` | Fondos insuficientes | Sugerir otro método |
| `card_declined` | Tarjeta rechazada | Contactar banco |
| `invalid_amount` | Monto inválido | Verificar monto |
| `terminal_offline` | Terminal sin conexión | Verificar conexión |
| `msi_not_available` | MSI no disponible | Ofrecer pago normal |

## Flujo de Reembolso

1. Admin/Gerente solicita reembolso
2. Sistema valida que transacción existe y está en período válido
3. Sistema envía solicitud a Clip API
4. Clip procesa reembolso
5. Webhook confirma reembolso
6. Sistema actualiza estado y genera nota de crédito

```typescript
// POST https://api.clip.mx/v1/transactions/{id}/refund
{
  "amount": 500.00, // Reembolso parcial o total
  "reason": "Devolución de producto"
}
```

## Seguridad

1. **API Key:** Nunca en logs ni frontend
2. **Webhook:** Validar signature header
3. **Terminales:** Solo admin puede vincular/desvincular
4. **Montos:** Validar server-side antes de enviar a Clip
5. **PCI:** Datos de tarjeta nunca en nuestros sistemas

## Dashboard de Clip

### Métricas Disponibles

```typescript
interface ClipDashboard {
  today: {
    transactions: number;
    volume: number;
    average_ticket: number;
  };
  terminals: {
    active: number;
    total: number;
    last_transaction: Date;
  };
  pending_settlement: number;
}
```

## Referencias

- [Clip Developers](https://developer.clip.mx/)
- [Clip API Reference](https://developer.clip.mx/reference)
- [Clip Webhooks](https://developer.clip.mx/docs/webhooks)

## Dependencias

- **RF Requeridos:** Ninguno (módulo base)
- **Bloqueante para:** RF-MGN-016-004 (Gestión de Terminales), RF-MGN-016-005 (Conciliación)