Conciliación Automática de Pagos del Portal

Módulo: Portal de Clientes / CtaCte Tipo: Process Estado: Implementado Fecha: 2026-05-12

---

Descripción

Cuando un cliente paga desde el portal y el gateway aprueba el pago, el sistema genera el recibo en cuenta corriente de forma automática, sin intervención de ningún operador del ERP.

Este proceso reemplaza íntegramente la anterior Fase 5 (reconciliación manual), que fue eliminada. Ya no existe la vista "Pagos Portal" en CtaCte ni la acción "Generar Recibo".

Valor para el negocio:

• El saldo del cliente en ctacte se actualiza en el mismo instante en que el gateway aprueba el pago
• No se requiere disponibilidad de un operador para cerrar el ciclo contable
• Se elimina el riesgo de pagos aprobados que quedan sin registrar por olvido u operación tardía
• El movimiento en caja también se genera automáticamente, sin pasos adicionales

---

Flujo de la Conciliación Automática

Cliente paga → Gateway aprueba → Webhook recibido por backend
    ↓
TX1: backend registra status='approved' en portal_payments (commit)
    ↓
TX2 (independiente): AutoReconciliacionService
    1. getNumeradorRecibo() — mulcta SELECT FOR UPDATE
    2. insertMovCuenta() — crea recibo en ordcta (schema CtaCte)
    3. insertReciboComprobante() × N — vincula cada factura en recfac
    4. updateComprobante() × N — actualiza pago/saldo en ordcta
    5. insertMovimientoCaja() — movimi en schema Caja (portal.recibo.caja_schema)
    6. markReciboId() + markReciboAt() en portal_payments
    ↓
portal_payments.recibo_id = <nuevo recibo> | recibo_at = <timestamp>

TX1 y TX2 son transacciones separadas e independientes. Un fallo de TX2 no revierte TX1: el pago mantiene status='approved' y se registra el error en recibo_error para diagnóstico.

---

Prerequisitos de Configuración

Para que TX2 funcione, la sucursal debe tener configuradas dos claves en data_config:

Clave	Descripción	Configuración
portal.recibo.cuenta_bancaria	Número de cuenta bancaria contable para el movimiento en caja	ERP → Configuración del Sistema → Gateway de Pagos → Cuenta Bancaria
portal.recibo.caja_schema	Schema de la caja destino para el movimiento en movimi	ERP → Configuración del Sistema → Gateway de Pagos

Si cualquiera de las dos claves falta al momento de iniciar un pago, el backend rechaza el inicio con HTTP 422 (ReciboNotConfiguredException). No es posible que un cliente inicie un pago en una sucursal sin esta configuración.

---

Manejo de Errores de TX2

Si TX2 falla (error en el Port, timeout de BD, etc.):

1. TX2 hace rollback completo — no quedan recibos huérfanos en ordcta
2. portal_payments.recibo_error queda con el mensaje del error
3. portal_payments.recibo_id permanece NULL
4. portal_payments.status permanece 'approved' (TX1 no se revierte)
5. El pago puede ser re-conciliado en una operación de recuperación futura

El campo recibo_at solo se setea cuando TX2 completa exitosamente.

---

Reglas de Negocio

RN-001: Disparo post-webhook TX2 se dispara siempre que TX1 commitea con status='approved'. No hay intervención humana.

RN-002: TX2 independiente de TX1 Un fallo de TX2 no revierte el registro del pago aprobado. El sistema prioriza registrar la aprobación del gateway sobre el éxito de la acreditación contable.

RN-003: Schema de CtaCte desde sucursal_idSchemaResolver::resolveSchemaName(sucursalId) resuelve el schema: si sucursalId = null usa public; si sucursalId = N usa suc000N.

RN-004: Vendedor siempre null Los recibos generados por auto-reconciliación no tienen vendedor asociado (cven = NULL). Es el estándar para pagos externos.

RN-005: Prerequisito verificado al iniciar pagogetGatewayConfig() expone recibo_configured: true/false. El portal deshabilita los botones de pago si recibo_configured = false. El backend también lanza ReciboNotConfiguredException al intentar iniciar un pago sin configuración completa.

---

Estado de portal_payments después del flujo

Estado	recibo_id	recibo_at	recibo_error	Significado
approved	NULL	NULL	NULL	TX2 aún no ejecutada (o en ejecución)
approved	<id>	<timestamp>	NULL	Conciliación automática exitosa
approved	NULL	NULL	<mensaje>	TX2 falló — pendiente de recuperación

---

Diferencia con la Reconciliación Manual (eliminada)

Aspecto	Manual (Fase 5 — eliminado)	Automático (actual)
Trigger	Acción del operador ERP	Post-webhook
Intervención humana	Requerida	No requerida
Vista ERP	"Pagos Portal" en CtaCte	No existe
Demora hasta acreditación	Variable (horas/días)	Segundos
Movimiento en caja	Opcional, manual	Automático vía caja_schema

---

Ver también

• Conciliación Automática — Detalle Técnico
• Configuración de Gateway — prerequisito de configuración
• Feature Flag del Portal — control de habilitación del módulo