erp-core/docs/04-modelado/requerimientos-funcionales/mgn-016

MGN-016: Integraciones de Pagos y POS

Descripción del Módulo

El módulo de Integraciones de Pagos y POS permite a los tenants conectar terminales de pago y procesadores para cobrar a sus propios clientes. Esto incluye integraciones con MercadoPago, Clip, Stripe Terminal, y otros proveedores de pagos en punto de venta.

IMPORTANTE: Este módulo es diferente a MGN-015 (Billing):

• MGN-015: Cobra a los tenants por usar la plataforma SaaS
• MGN-016: Permite a los tenants cobrar a sus clientes finales

Requerimientos Funcionales

ID	Nombre	Prioridad	Story Points	Estado
RF-MGN-016-001	Integración MercadoPago	P1	13	Definido
RF-MGN-016-002	Integración Clip	P1	13	Definido
RF-MGN-016-003	Integración Stripe Terminal	P2	8	Definido
RF-MGN-016-004	Gestión de Terminales	P1	8	Definido
RF-MGN-016-005	Conciliación de Pagos	P1	13	Definido
RF-MGN-016-006	Reportes de Transacciones	P2	5	Definido

Total Story Points: 60

Arquitectura de Integraciones

┌──────────────────────────────────────────────────────────────────┐
│                         TENANT (Cliente SaaS)                     │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │ MercadoPago │    │    Clip     │    │   Stripe    │          │
│  │  Credentials│    │  Credentials│    │  Credentials│          │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘          │
│         │                  │                   │                  │
└─────────┼──────────────────┼───────────────────┼──────────────────┘
          │                  │                   │
          ▼                  ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   MercadoPago   │  │      Clip       │  │  Stripe API     │
│      API        │  │      API        │  │    Terminal     │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Dependencias

Dependencias Internas

• MGN-003 (Catalogs): Métodos de pago, monedas, contactos
• MGN-004 (Financial): Registro contable de pagos recibidos (auto-asientos)
• MGN-007 (Sales): Pagos de órdenes de venta (actualizar estado)
• MGN-014 (Mensajería): Notificaciones de transacciones y auditoría
• MGN-015 (Billing): Feature flags (mercadopago_enabled, clip_enabled)

Dependencias Externas

• MercadoPago API (OAuth2, Webhooks)
• Clip API (API Keys, Webhooks)
• Stripe API (Connect, Terminal)

Integraciones Requeridas

• MGN-007: Webhook payment.approved debe actualizar sales.orders.payment_status
• MGN-004: Transacciones confirmadas deben generar asientos contables automáticos

Actores del Módulo

Actor	Descripción	RFs Relacionados
Tenant Admin	Configura integraciones	RF-001, RF-002, RF-003, RF-004
Cajero/Vendedor	Procesa pagos	RF-001, RF-002, RF-003
Contador	Concilia transacciones	RF-005, RF-006
Sistema	Webhooks y sincronización	Todos

Entidades Principales

-- Schema: integrations
integrations.payment_providers       -- Proveedores configurados por tenant
integrations.payment_credentials     -- Credenciales encriptadas (OAuth tokens, API keys)
integrations.payment_terminals       -- Terminales físicas registradas
integrations.payment_transactions    -- Transacciones procesadas
integrations.webhook_logs            -- Logs de webhooks recibidos
integrations.reconciliation_batches  -- Lotes de conciliación

Proveedores Soportados

MercadoPago (México, LATAM)

• Métodos: Tarjeta, OXXO, SPEI, Mercado Crédito
• Terminales: Point Smart, Point Pro
• Comisiones: 3.49% + IVA (tarjeta presencial)

Clip (México)

• Métodos: Tarjeta (crédito/débito)
• Terminales: Clip Plus, Clip Pro
• Comisiones: 3.6% + IVA

Stripe Terminal (Global)

• Métodos: Tarjeta (crédito/débito)
• Terminales: BBPOS WisePOS E, Verifone P400
• Comisiones: 2.9% + $0.30 USD

Flujo General de Pago

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│ Vendedor│────▶│   ERP   │────▶│ Gateway │────▶│  Banco  │
│  (POS)  │     │ (crear  │     │(procesar│     │(aprobar)│
└─────────┘     │ intent) │     │  pago)  │     └────┬────┘
                └─────────┘     └─────────┘          │
                      ▲                              │
                      │         ┌─────────┐         │
                      └─────────│ Webhook │◀────────┘
                                │(confirmar│
                                └─────────┘

Seguridad

1. Credenciales: Encriptadas con AES-256, nunca en logs
2. OAuth: Refresh tokens con rotación automática
3. Webhooks: Validación de firma (HMAC)
4. PCI-DSS: Datos de tarjeta nunca tocan nuestros servidores
5. Auditoría: Todas las transacciones logueadas

Notas de Implementación

1. Multi-proveedor: Un tenant puede tener múltiples proveedores activos
2. Failover: Si un proveedor falla, ofrecer alternativa
3. Offline: Soportar modo offline para terminales físicas
4. Notificaciones: Alertar sobre transacciones fallidas
5. Reconciliación: Job diario para conciliar con extractos

Feature Flags

{
  "mercadopago_enabled": true,
  "clip_enabled": true,
  "stripe_terminal_enabled": false,
  "offline_mode": true,
  "auto_reconciliation": true
}