rckrdmrd 59f1e3badf Initial commit - erp-core

2026-01-04 06:12:07 -06:00

6.6 KiB

Raw Blame History

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

Tenant debe tener suscripción activa con feature clip_enabled
Tenant debe tener cuenta de Clip activa
API Keys de Clip generadas en dashboard de Clip

Flujo Principal - Configurar Integración

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

Flujo Principal - Procesar Pago

Vendedor crea venta en sistema
Vendedor selecciona "Cobrar con Clip"
Vendedor selecciona terminal a usar
Sistema crea transacción via Clip API
Terminal muestra monto a cobrar
Cliente presenta tarjeta (chip, NFC, o banda)
Cliente ingresa PIN si es requerido
Terminal procesa pago
Clip envía confirmación via webhook
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:

-- 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)

-- 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

// 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

// 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

// 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

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

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

Seguridad

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

Dashboard de Clip

Métricas Disponibles

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

Referencias

Dependencias

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

6.6 KiB Raw Blame History