Documentación del Sistema

Appearance

Vista de Reconciliacion de Pagos del Portal ​

Modulo: CtaCte (o Membresias — ver Consideraciones) Tipo: View Estado: Planificado Fecha: 2026-04-22

Descripcion ​

Vista en Bautista ERP donde el operador ve los pagos realizados por clientes a traves del Portal de Clientes y genera manualmente el recibo correspondiente en la cuenta corriente. Es el punto de entrada para la reconciliacion de pagos online con el sistema de ctacte.

Por que existe: Cuando un cliente paga online, el webhook del gateway solo actualiza portal_payments.status = 'approved'. La creacion del recibo en ordcta no es automatica — requiere intervencion manual del operador. Esta vista cierra ese gap. Ver Gap: Reconciliacion de Pagos Portal.

Frontend ​

Vistas ​

  • Listado de pagos pendientes de conciliacion: Pagos con status = 'approved' que no tienen recibo_id asociado.
  • Historial de pagos conciliados: Pagos ya conciliados (approved con recibo_id).

Ambas vistas pueden vivir como tabs dentro de la misma pantalla de "Pagos Portal".

Columnas del listado ​

ColumnaOrigenDescripcion
Fechaportal_payments.created_atFecha en que se realizo el pago
Clienteordcon.cnom + ordcon.ccuiNombre y DNI/CUIT del cliente
Montoportal_payments.amountMonto total pagado
Facturasportal_payments.facturas_pagadasComprobantes incluidos en el pago
Gatewayportal_payments.gatewayGateway usado: paypertic o mercadopago
Estadoportal_payments.statusEstado del pago en el gateway
Reciboportal_payments.recibo_idNro. de recibo si ya fue conciliado, o "Pendiente"

Filtros disponibles ​

  • Por sucursal (si el operador tiene acceso a multiples sucursales)
  • Por periodo (fecha desde / fecha hasta)
  • Por cliente (nombre o DNI/CUIT)

Interacciones del usuario ​

  1. El operador abre la vista de "Pagos Portal" desde CtaCte (o Membresias).
  2. Ve el listado de pagos approved sin recibo (tab "Pendientes de conciliacion").
  3. Selecciona una fila y hace click en "Generar Recibo".
  4. Se abre el flujo de creacion de recibo con los datos del pago precargados:
    • Cliente
    • Monto
    • Facturas / comprobantes incluidos
  5. El operador confirma la creacion del recibo.
  6. El sistema crea el recibo en ordcta (y movimiento en caja si corresponde) y actualiza portal_payments.recibo_id.
  7. El pago desaparece del tab "Pendientes" y aparece en el tab "Historial".

Permisos ​

PermisoDescripcionAcciones permitidas
CTACTE_PORTAL_PAGOS_VIEWVer pagos del portalListar, filtrar, consultar historial
CTACTE_PORTAL_PAGOS_RECONCILIARConciliar pagosGenerar recibo desde pago portal

Backend ​

Tabla involucrada: portal_payments ​

Tabla existente a nivel SUCURSAL (schema suc{sucursal_id}).

Campo claveTipoDescripcion
idUUIDIdentificador del pago
ordcon_idintegerFK a ordcon — cliente que pago
amountdecimalMonto total del pago
statusstringEstado: pending, approved, rejected, cancelled
gatewaystringGateway usado: paypertic, mercadopago
facturas_pagadasjsonbArray de facturas incluidas en el pago con sus montos
recibo_idinteger / nullFK a ordcta.id — null hasta que se concilia
external_idstringID del pago en el gateway externo
created_attimestampFecha de creacion del pago

Condicion de "pendiente de conciliacion": status = 'approved' AND recibo_id IS NULL

Servicio a implementar: PortalReciboCreatorService ​

Modulo: Modules/Portal/Application/Services/

Responsabilidad: Crear el recibo en ordcta a partir de un portal_payment aprobado. Servicio de dominio acotado, sin cheques, sin efectivo, sin retenciones. Solo recibos de cobro online (transferencia electronica).

Dependencias esperadas:

  • ReciboRelationsService — servicio existente para crear recibos en ordcta
  • ConnectionManager — resolucion de schemas SUCURSAL y CAJA
  • portal_payments — lectura del pago aprobado

Logica principal:

  1. Leer el portal_payment por ID, validar que status = 'approved' y recibo_id IS NULL
  2. Resolver el cliente via ordcon_id
  3. Construir el DTO de recibo con los datos del pago (monto, facturas, fecha, tipo de cobro online)
  4. Llamar a ReciboRelationsService para crear el recibo en ordcta (schema SUCURSAL)
  5. Si Tesoreria esta habilitado y portal.caja_id esta configurado, generar el movimi en la caja correspondiente (schema CAJA)
  6. UPDATE portal_payments SET recibo_id = {nuevo_recibo_id} donde id = {payment_id}
  7. Retornar el ID del recibo creado

Idempotencia: El servicio debe verificar que recibo_id IS NULL antes de crear el recibo. Si ya tiene recibo_id, retornar error PAYMENT_ALREADY_RECONCILED.

Multi-schema ​

  • Recibo en ordcta: schema SUCURSAL — suc{sucursal_id} — resuelto via sucursal_id del portal_payment
  • Movimiento en movimi: schema CAJA — suc{sucursal_id}caja{caja_id} — requiere portal.caja_id configurado en data_config de la sucursal

Gap abierto: caja_id ​

La caja destino para el movimiento de Tesoreria aun no esta definida. Se configura via portal.caja_id en data_config de la sucursal. Si este valor no esta configurado, el servicio omite la creacion del movimi (solo crea el recibo en ordcta).

Esta decision de diseno queda pendiente hasta la implementacion de Fase 5.

Reglas de negocio ​

  1. Solo pagos approved: Solo se pueden conciliar pagos con status = 'approved'. Pagos pending, rejected o cancelled no son conciliables.
  2. Un recibo por pago: Cada portal_payment puede tener como maximo un recibo asociado. Si recibo_id != null, el pago ya fue conciliado y no puede reconciliarse nuevamente.
  3. Tipo de recibo: El recibo es de tipo "cobro online" (transferencia electronica). No incluye cheques, efectivo ni retenciones.
  4. Caja opcional: Si Tesoreria no esta habilitado o portal.caja_id no esta configurado, se crea solo el recibo en ordcta sin movimiento de caja.
  5. Idempotencia: El servicio verifica recibo_id IS NULL antes de proceder para evitar dobles acreditaciones.

Casos de uso ​

Caso 1: Conciliar un pago aprobado ​

Actor: Operador con permiso CTACTE_PORTAL_PAGOS_RECONCILIAR

Precondiciones:

  • Existe un portal_payment con status = 'approved' y recibo_id IS NULL
  • La sucursal tiene portal.gateway.nombre configurado (el pago ya ocurrio)

Flujo principal:

  1. El operador abre la vista "Pagos Portal" → tab "Pendientes de conciliacion"
  2. Localiza el pago del cliente (puede filtrar por fecha o cliente)
  3. Hace click en "Generar Recibo"
  4. El sistema precarga el formulario de recibo con: cliente, monto, facturas pagadas
  5. El operador revisa los datos y confirma
  6. PortalReciboCreatorService crea el recibo en ordcta y actualiza portal_payments.recibo_id
  7. El sistema muestra confirmacion con el numero de recibo generado
  8. El pago pasa al tab "Historial"

Postcondiciones:

  • Existe un nuevo recibo en ordcta de la sucursal correspondiente
  • portal_payments.recibo_id apunta al nuevo recibo
  • El saldo del cliente en ctacte refleja el pago

Flujos alternativos:

  • Pago ya conciliado: Si recibo_id != null, el sistema retorna PAYMENT_ALREADY_RECONCILED y no crea un segundo recibo
  • Caja no configurada: Si portal.caja_id no esta definido, se crea solo el recibo en ordcta sin movimiento de caja. Se muestra un aviso al operador

Caso 2: Consultar historial de pagos conciliados ​

Actor: Operador con permiso CTACTE_PORTAL_PAGOS_VIEW

Flujo principal:

  1. El operador abre la vista "Pagos Portal" → tab "Historial"
  2. Aplica filtros opcionales (periodo, cliente)
  3. Ve el listado de pagos conciliados con su numero de recibo y fecha de conciliacion

Consideraciones tecnicas ​

Modulo de ubicacion en el ERP ​

La vista puede ubicarse en:

  • CtaCte: Opcion natural — los recibos viven en ordcta y la vista es operativa para cualquier cliente con ctacte.
  • Membresias: Solo valido si el foco es exclusivamente socios/miembros con membresia activa.

Recomendacion: ubicar en CtaCte como subseccion "Pagos Portal" para mayor alcance. Si en el futuro los pagos del portal aplican exclusivamente a socios, se puede agregar un acceso rapido desde Membresias.

Performance ​

  • El listado de pagos pendientes debe paginarse (los pagos aprobados sin recibo pueden acumularse en periodos de alto volumen).
  • Indice recomendado en portal_payments: (status, recibo_id) para la query de pendientes.

Seguridad ​

  • El permiso CTACTE_PORTAL_PAGOS_RECONCILIAR debe ser restrictivo — solo roles operativos que tengan autoridad para acreditar pagos en ctacte.
  • El servicio verifica que el portal_payment pertenece a la sucursal del operador antes de proceder.

Testing ​

  • Test unitario: PortalReciboCreatorService — caso feliz, pago ya conciliado, caja no configurada
  • Test de integracion: flujo completo webhook → vista → conciliacion → recibo en ordcta
  • Test E2E: no aplica (vista solo accesible desde el ERP, no desde portal-usuarios)

Dependencias ​

Funcionalidades relacionadas ​

Servicios a implementar ​

  • PortalReciboCreatorService — nuevo servicio DDD en Modules/Portal/Application/Services/

Servicios existentes reutilizados ​

  • ReciboRelationsService — creacion de recibos en ordcta
  • ConnectionManager — resolucion de schemas SUCURSAL y CAJA