Modulo de Pagos

import { Aside } from ‘@astrojs/starlight/components’;

Modulo de Pagos

Los endpoints REST descritos en este documento **aun no estan implementados** en `ms-credigestion`. Esta pagina sirve como contrato propuesto. La capa SOAP upstream (3 metodos en ServicioCartera) si esta documentada y disponible en ISISYSTEM.

Contexto Arquitectonico

El modulo de Pagos cierra el ciclo de la linea de credito: una vez que Consumo registra los cargos, Pagos los liquida segun la prelacion parametrizada por la empresa.

Cliente / Caja
    |
    v
+------------------+   REST/JSON    +------------------+
|   NoviSuite UI   | <------------> |   ms-credigestion|
+--------+---------+                +------------------+
         |                                   |
         | eventos / datos                   | SOAP/XML (ServicioCartera)
         v                                   v
+------------------+                +------------------+
|   MBA3 (ERP)     |                |   ISISYSTEM      |
+------------------+                +------------------+

ms-credigestion es el unico punto de entrada para registrar pagos contra ISISYSTEM. NoviSuite nunca habla SOAP directamente: recibe la respuesta normalizada de ms-credigestion y es NoviSuite quien coordina con MBA3 la emision de comprobantes (recibos y notas de credito).

Modelo de Responsabilidades

Componente	Responsabilidad
NoviSuite UI	Capturar la forma de pago, mostrar deuda y comprobante
ms-credigestion / Pagos	Validar request, llamar SOAP, normalizar respuesta, devolver JSON
isisystem-soap	Encapsular el envelope SOAP y manejo de errores upstream
ISISYSTEM Cartera	Calcular deuda, aplicar prelacion, recalcular mora, gestion y descuento
MBA3	Emitir recibo / nota de credito y reflejar en cuentas por cobrar

Flujos de Negocio

Flujo 1 — Consultar Deuda

1. Cajero ingresa cedula o numero de tarjeta en NoviSuite
2. NoviSuite llama POST /pagos/consulta-deuda
3. ms-credigestion invoca ConsultarDeudaTarjeta en ISISYSTEM
4. Respuesta normalizada incluye: pago de contado, pago minimo, mora, gestion, valor vencido y proxima fecha de pago

Flujo 2 — Aplicar Pago

1. Cajero captura formas de pago (efectivo y/o cheque) por un valor <= pago de contado
2. NoviSuite llama POST /pagos/aplicar con la lista iFormaPagoVm
3. ms-credigestion invoca GrabarPagoTarjeta
4. ISISYSTEM aplica la prelacion parametrizada y devuelve facturas afectadas, rubros aplicados y nuevos saldos por cupo
5. NoviSuite publica el numero de operacion para que MBA3 emita el recibo

Flujo 3 — Reversar Pago

1. Operador autorizado solicita reverso por numero de operacion
2. NoviSuite llama POST /pagos/reverso
3. ms-credigestion invoca GrabarReversoPagoTarjeta
4. ms-credigestion devuelve a NoviSuite las facturas y rubros revertidos; NoviSuite los publica a MBA3 para que emita la nota de credito correspondiente

Contrato REST Propuesto

Endpoints que ms-credigestion debera exponer para cubrir los flujos. Todas las rutas comparten el prefijo /credigestion.

POST /credigestion/pagos/consulta-deuda

POST /credigestion/pagos/consulta-deuda
Content-Type: application/json

{
  "numeroTarjeta": "0916884245"
}

Tambien acepta numeroIdentificacion en lugar de numeroTarjeta.

Respuesta 200 OK

{
  "cliente": {
    "codigo": 409912,
    "nombre": "PATERNO MATERNO NOMBRE SEGUNDO",
    "numeroTarjeta": "0916884245"
  },
  "deuda": {
    "pagoContado": 425.50,
    "pagoMinimo": 38.20,
    "valorMora": 1.10,
    "valorGestion": 0.00,
    "valorVencido": 0.00,
    "fechaProximoPago": "2025-04-15"
  }
}

POST /credigestion/pagos/aplicar

POST /credigestion/pagos/aplicar
Content-Type: application/json

{
  "numeroTarjeta": "0916884245",
  "valorPago": 425.50,
  "fechaPago": "2025-03-25",
  "formasPago": [
    { "codigo": "001", "valor": 425.50 }
  ]
}

Para cheque la forma de pago debe incluir los campos bancarios (institucionFinanciera, numeroDocumento, numeroCuenta, identCuentaCorrentista, nombreCuentaCorrentista).

Respuesta 200 OK

{
  "numeroOperacion": 3433020,
  "facturasAfectadas": [
    { "numeroFactura": "001-001-000012345", "valor": 425.50 }
  ],
  "rubrosAplicados": [
    { "codigo": "001", "tipoDocumento": "F", "valor": 423.40 },
    { "codigo": "010", "tipoDocumento": "F", "valor": 2.10 }
  ],
  "cupos": [
    {
      "codigo": "003",
      "descripcion": "Tarjeta Credito General",
      "asignado": 850,
      "disponible": 850,
      "utilizado": 0
    }
  ]
}

POST /credigestion/pagos/reverso

POST /credigestion/pagos/reverso
Content-Type: application/json

{
  "numeroOperacion": 3433020,
  "motivo": "Reverso por error de captura"
}

Respuesta 200 OK

{
  "estado": "REVERSADO",
  "facturasAfectadas": [
    { "numeroFactura": "001-001-000012345", "valor": 425.50 }
  ],
  "rubrosRevertidos": [
    { "codigo": "001", "tipoDocumento": "F", "valor": 423.40 },
    { "codigo": "010", "tipoDocumento": "F", "valor": 2.10 }
  ]
}

Mapeo REST → SOAP

Endpoint REST	Operacion SOAP	Servicio
POST /pagos/consulta-deuda	ConsultarDeudaTarjeta	Cartera
POST /pagos/aplicar	GrabarPagoTarjeta	Cartera
POST /pagos/reverso	GrabarReversoPagoTarjeta	Cartera

El detalle del envelope SOAP, namespaces y manejo de errores estan en Modulo isisystem-soap.

Detalle SOAP Upstream

ConsultarDeudaTarjeta

Devuelve los rubros adeudados por el cliente. Es la base del calculo de “pago de contado” y “pago minimo”.

• URL: http://186.5.126.42:8092/Cartera/ServicioCartera.svc
• SOAPAction: http://tempuri.org/IServicioCar/ConsultarDeudaTarjeta

Parametros de Entrada

Campo	Tipo	Obligatorio	Descripcion
cNumeroTarjeta	Texto(20)	Condicional	Obligatorio si no viene cNumeroIdentificacion
cNumeroIdentificacion	Texto(20)	Condicional	Obligatorio si no viene cNumeroTarjeta
cUsuario	Texto(10)	Si	Usuario asignado
cCodigoEmpresa	Texto(6)	Si	Codigo de empresa

Parametros de Salida

Campo	Tipo	Descripcion
cTextoError	Texto(250)	Texto del error
lError	Booleano	true = error
nNumeroError	Numerico(3)	Nivel de error
nPagoContado	Numerico(18,2)	Pago de contado total
nPagoMinimo	Numerico(18,2)	Pago minimo a la fecha de corte
nValorMora	Numerico(18,2)	Mora acumulada
nValorGestion	Numerico(18,2)	Gestion de cobranza
nValorVencido	Numerico(18,2)	Capital vencido
dFechaProximoPago	Fecha	Fecha del proximo vencimiento

GrabarPagoTarjeta

Aplica un pago segun la prelacion configurada por la empresa. Recalcula mora, gestion y descuento por pago anticipado.

• URL: http://186.5.126.42:8092/Cartera/ServicioCartera.svc
• SOAPAction: http://tempuri.org/IServicioCar/GrabarPagoTarjeta

Parametros de Entrada

Campo	Tipo	Obligatorio	Descripcion
cNumeroTarjeta	Texto(20)	Si	Numero de tarjeta del cliente
cTerminal	Texto(15)	Si	Nombre del equipo
cUsuario	Texto(10)	Si	Usuario asignado
cCodigoEmpresa	Texto(6)	Si	Codigo de empresa
dFechaPago	Fecha	Si	Formato yyyy-mm-dd
nValorPago	Numerico(18,2)	Si	Valor total a aplicar
iFormaPagoVm	Subclase	Si	Lista de formas de pago (ver subclases)

El total de nValorFormaPago debe coincidir exactamente con nValorPago.

Parametros de Salida

Campo	Tipo	Descripcion
cTextoError	Texto(250)	Texto del error
lError	Booleano	true = error
nNumeroError	Numerico(3)	Nivel de error
nNumeroOperacion	Numerico(9)	Numero de operacion del pago
oFacturaAfectadaVm	Subclase	Facturas a las que se aplico el pago
oRubroAplicadoVm	Subclase	Rubros aplicados (capital, interes, mora, gestion)
oTipoCupoVm	Subclase	Cupos restituidos por el pago

GrabarReversoPagoTarjeta

Reversa un pago previamente aplicado. ISISYSTEM devuelve el detalle para que MBA3 emita la nota de credito correspondiente.

• URL: http://186.5.126.42:8092/Cartera/ServicioCartera.svc
• SOAPAction: http://tempuri.org/IServicioCar/GrabarReversoPagoTarjeta

Parametros de Entrada

Campo	Tipo	Obligatorio	Descripcion
nNumeroOperacion	Numerico(9)	Si	Numero de operacion del pago original
cTerminal	Texto(15)	Si	Nombre del equipo
cUsuario	Texto(10)	Si	Usuario asignado
cCodigoEmpresa	Texto(6)	Si	Codigo de empresa
cMotivoReverso	Texto(250)	No	Justificacion del reverso

Parametros de Salida

Campo	Tipo	Descripcion
cTextoError	Texto(250)	Texto del error
lError	Booleano	true = error
nNumeroError	Numerico(3)	Nivel de error
oFacturaAfectadaVm	Subclase	Facturas restituidas
oRubroAplicadoVm	Subclase	Rubros revertidos

Subclases del Dominio Pago

Estas subclases viven en Modulo isisystem-soap:

• iFormaPagoVm — input de formas de pago
• oFacturaAfectadaVm — facturas aplicadas
• oRubroAplicadoVm — rubros aplicados/revertidos
• oTipoCupoVm — cupos restituidos

Reglas de Negocio

Prelacion de Aplicacion

ISISYSTEM aplica el pago en el orden parametrizado por la empresa. El orden tipico es:

1. Gestion de cobranza
2. Mora
3. Interes vencido
4. Capital vencido
5. Interes por vencer
6. Capital por vencer

ms-credigestion no decide la prelacion: delega 100% en ISISYSTEM.

Mora y Gestion

• La mora se recalcula a la fecha del pago
• La gestion solo aplica si la cartera esta marcada como en gestion (mas de N dias vencidos segun la parametrizacion)

Descuento por Pago Anticipado

Si el cliente paga el contado completo, ISISYSTEM aplica el descuento por interes no devengado. Este descuento aparece reflejado en oRubroAplicadoVm con un valor negativo.

Forma de Pago

• Efectivo (cCodigoFormaPago = 001): los campos bancarios deben venir vacios
• Cheque (cCodigoFormaPago = 002): todos los campos bancarios son obligatorios. ISISYSTEM rechaza la operacion si alguno falta

Manejo de Errores y Conciliacion

Escenario	HTTP	Accion
Tarjeta inexistente o anulada	404	Mostrar al cajero “cliente no encontrado”
nValorPago mayor a nPagoContado	422	Mostrar deuda vigente y pedir corregir
Suma de formas de pago != nValorPago	422	Validacion local antes de llamar SOAP
Cheque sin datos bancarios	422	Validacion local antes de llamar SOAP
lError = true desde ISISYSTEM	502	Devolver BadGatewayException con cTextoError
Timeout (mas de 30 s)	504	GatewayTimeoutException. Importante: consultar deuda al recuperarse para confirmar si el pago se aplico antes del timeout

En caso de timeout, no reintentar automaticamente GrabarPagoTarjeta. Consultar primero ConsultarDeudaTarjeta para verificar si la operacion quedo asentada y evitar duplicados.