Módulo de Pagos a Proveedores — Requerimientos

Estado: Cerrado para entrega (2026-07-08). Las definiciones fueron validadas por las pruebas de los docs 02 (Service Layer) y 03 (en _borradores/, no publicado) (banco). Fecha de inicio: 2026-07-07 Actualizado 2026-08-06: Def. 11 — reintento ante fallo de la carga bancaria.

Requerimiento del negocio

Usuarios de compras solicitan una solución que permita solicitar pagos a proveedores.

• Las solicitudes deben ser aprobadas por encargados de pagos.
• Luego de la confirmación, el sistema deberá registrar un pago efectuado para que SAP efectúe el asiento contable correspondiente.

Modelo de referencia

Se seguirá el modelo ya implementado en el módulo de cobros (src/modules/payments/): solicitud como borrador en SAP (sin impacto contable) → aprobación → conversión en pago efectuado (documento contable en SAP).

Flujo funcional

1. El usuario de Compras crea una solicitud de pago a un proveedor (si es transferencia, se carga también la operación en el banco).
2. La transferencia se autoriza en la aplicación del banco (fuera del OMS — esa es la aprobación real del dinero).
3. El sistema detecta la transferencia ejecutada en el extracto y confirma automáticamente la solicitud: registra el pago efectuado en SAP, que genera el asiento contable. Si no puede determinar el egreso de forma inequívoca, la confirmación la hace Tesorería manualmente mirando los egresos del extracto.

Definiciones funcionales

1. Roles

Dos roles: Compras (solicitante) y Tesorería (confirma manualmente cuando la confirmación automática no aplica — ver Def. 6 — y registra pagos directos). No habrá más roles por ahora.

2. Datos de la solicitud

• Se infieren de la entidad VendorPayments de SAP; serán básicamente los mismos datos que la solicitud de cobros, más los datos del proveedor para la transferencia (BPBankAccounts + moneda de la cuenta — detallado en doc 03 §6b).
• Integración bancaria: la solicitud de pago (PaymentDraft) con tipo de pago transferencia produce la carga de la operación en la API del Banco Continental al momento de solicitar (detallado en doc 03).

3. Medios de pago

Los soportados por el pago de SAP: tarjetas, transferencias, etc.

4. Aplicación del pago (regla central)

El alta de facturas de compra queda fuera del OMS: se registran en SAP. Aquí solo se asignan facturas existentes al pago al solicitar, de la misma forma que hoy se hace en cobros con invoices:

• La solicitud debe tener siempre al menos un PaymentInvoice: o una factura, o un anticipo.
• Contra factura: el monto aplicado puede ser inferior o igual al saldo de la factura. Nunca superior.
• Sin factura: deberá existir/crearse un anticipo (DownPayment) por el valor del pago. Es lo que SAP soporta para la conciliación posterior del anticipo contra una factura.

Fundamento (validado en pruebas, ver doc 02 § B2b): SAP no impide el sobrepago — lo acepta, recorta lo aplicado al saldo y registra el excedente como pago a cuenta del proveedor. Ese pago a cuenta no se reconcilia automáticamente, porque no tiene un documento de anticipo que luego pueda aplicarse contra una factura: queda como saldo suelto a conciliar manualmente. Por eso la validación del monto es responsabilidad del OMS (contra DocTotal - PaidToDate) y todo pago sin factura debe canalizarse por la vía del anticipo explícito, nunca como pago a cuenta.

5. Ciclo de vida

• La solicitud puede ser borrada (se elimina el borrador).
• Un pago confirmado no puede borrarse ni anularse desde el OMS: eso lo hace el departamento de contabilidad directamente en SAP. No es competencia de este sistema.

6. Proceso de confirmación

La confirmación completa en el pago los datos de la transacción bancaria, obtenidos del extracto (egresos) del banco según la cuenta (PYG o USD) correspondiente a la moneda del pago. La regla (definida 2026-07-08, ver doc 03 §G4c):

• Automática (flujo principal): cuando el egreso del extracto puede determinarse de forma inequívoca — número de comprobante de la operación bancaria + monto iguales, reforzados por atributos extra (moneda, cuenta débito, RUC del beneficiario). La idea es quitar pasos siempre que se pueda.
• Manual (fallback): si no puede determinarse, Tesorería confirma seleccionando el egreso desde los extractos disponibles.

7. Visibilidad

Al ser solo dos roles y un grupo reducido de usuarios, no se aplican reglas de visibilidad por ahora: todos ven todas las solicitudes y pagos.

8. Notificaciones

Se utilizarán de la misma forma que en cobros, por medio de un grupo de Google, igual que se hace actualmente en cobros.

9. Trazabilidad

• Origen del pago: confirmado — el UDF U_SalesPersonID existe en drafts y en VendorPayments (doc 02 §C1); además Reference2 guarda el ticket bancario.
• Aprobación: la autorización real queda trazada en el banco (la consulta por ticket expone carga y autoriza, doc 03 §G4); en la confirmación manual, el confirmador queda registrado en la notificación (patrón cobros). La colección Payments_ApprovalRequests de SAP queda fuera del MVP.

10. Registro directo de pagos ya efectuados

Se dará soporte para crear pagos ya efectuados (sin circuito de aprobación), siempre seleccionando el extracto del banco o el número de ticket correspondiente a la transacción (p. ej. si es por transferencia).

11. Fallo en la carga de la operación bancaria (definido 2026-08-06)

Cuando la solicitud se crea pero la carga en el banco falla, la solicitud no se descarta: queda registrada y el usuario puede reintentar la carga sin rehacer el formulario. El detalle técnico está en el doc 04 §5b; funcionalmente:

• La solicitud aparece en la bandeja como "Carga bancaria fallida", con acción de reintento disponible para Compras y Tesorería.
• El sistema nunca reintenta sin verificar antes contra el banco si la operación ya existe. Una doble carga es una transferencia real duplicada al proveedor, no anulable por API. Si esa verificación no puede hacerse, el reintento se bloquea y se informa el motivo — se prefiere trabar el circuito antes que arriesgar un pago doble.
• Caso aceptado sin solución (decisión): si la operación sí se cargó en el banco pero el sistema no llegó a guardar el número de ticket, no hay forma general de vincularlos desde el OMS por limitaciones de la API del banco. Se resuelve fuera del sistema. La verificación previa al reintento debe reconocer este caso para no duplicar, aunque no lo repare.

Temas profundizados / pendientes

Tema	Estado
Datos del proveedor (cuenta bancaria + moneda) en la solicitud	✅ Resuelto — doc 03 §6b; UDF U_Moneda creado en dev y producción (2026-08-06). Falta la carga de datos por cuenta
Integración con la API del Banco Continental	✅ Resuelto — doc 03 (endpoints validados en sandbox)
Consulta de extractos (egresos) por cuenta PYG/USD	✅ Resuelto — doc 03 §4.1 (sondeo condicional) y §6b (mapeo de cuentas)
Trazabilidad de la aprobación	✅ Resuelto — Def. 9 actualizada
Mecanismo del "grupo de Google" (Def. 8)	⏳ Abierto — no está en el backend de cobros; relevar
Reintento ante fallo de carga bancaria (Def. 11)	✅ Resuelto — doc 04 §5b (dependen de él: doc 02 B7 y doc 03 G6, ambos pendientes)

Historial

Fecha	Cambio
2026-07-07	Versión inicial: requerimiento funcional del usuario.
2026-07-07	Definiciones funcionales 1–10 (roles, datos, medios de pago, regla de aplicación, ciclo de vida, aprobación, visibilidad, notificaciones, trazabilidad, pago directo).
2026-07-08	Def. 4: regla de sobrepago con fundamento (doc 02 §B2b); alcance de facturas (alta en SAP). Def. 6: confirmación automática como flujo principal, manual como fallback. Flujo funcional actualizado al modelo bancario.
2026-07-08	Pasada final: Def. 9 (trazabilidad confirmada), Def. 2 (referencias al doc 03), tabla de temas con estados. Cierre para entrega.
2026-08-06	Def. 11: la solicitud sobrevive al fallo de carga bancaria y es reintentable; verificación previa obligatoria contra el banco (nunca reintentar a ciegas); caso "cargado sin ticket" aceptado sin solución. Diseño en doc 04 §5b.