Órdenes de pago y Caja
Pagar una orden de pago crea un egreso en Caja. Devolver un pago crea un ingreso. Anular un pago anula el egreso. Toda la lógica vive en App\Domain\Purchase\PaymentOrder; esta página describe solo lo que toca Caja.
| Pieza | Clase | Rol |
|---|---|---|
| Rutas | PaymentOrderPaymentController |
POST /api/payment-orders/payments, .../payments/{cashboxMovementId}/annul y .../payments/{cashboxMovementId}/refund. También existe payments/preview. |
| Casos de uso | RegisterPaymentUseCase, AnnulPaymentUseCase, RegisterPaymentRefundUseCase |
Orquestan todo dentro de DB::transaction. |
| Puente con Caja | PaymentCashboxMovementService |
Arma el payload, lo valida con StoreCashboxMovementRequest::fromArray y llama a CashboxMovementStoreService::store. |
| Vínculo | PaymentOrderMovement |
Une el movimiento de Caja con la línea de la orden de pago. Su kind es payment o refund. |
Permisos de Compras que exigen los casos de uso (PaymentOrderPolicy): payment-order.register-payment, payment-order.annul-payment y payment-order.register-refund. Además, al crear el movimiento rige el permiso create de CashboxMovementPolicy, porque CashboxMovementStoreService::store pasa por BaseControllerHelper::store.
Registrar un pago
Sección titulada «Registrar un pago»POST /api/payment-orders/payments | vRegisterPaymentUseCase::execute |-- Gate registerPayment |-- bloquea órdenes de compra, órdenes de pago, líneas y cuotas |-- valida: líneas pagables, mismo proveedor y moneda, total = monto del egreso, | cuenta en la moneda de la orden |-- PaymentCashboxMovementService::create | --> CashboxMovementStoreService::store (egreso) |-- PaymentRegistrationService::createMovements (PaymentOrderMovement, kind = payment) |-- aplica el pago a facturas, refresca facturas y órdenes de pago v201 con el CashboxMovementValidaciones antes de crear el movimiento
Sección titulada «Validaciones antes de crear el movimiento»| Validación | Método | Mensaje o efecto |
|---|---|---|
| Cada línea es una línea de orden de compra con cuota. | PaymentRegistrationService::assertLinesArePurchaseOrderLines |
Error sobre lines. |
| La orden de pago está aprobada o con pago parcial. | PaymentRegistrationService::assertPaymentOrdersArePayable |
Error sobre payment_order_status. |
| Todas las órdenes son del mismo proveedor y de la misma moneda. | PaymentRegistrationService::assertSameBeneficiaryAndCoin |
Error sobre lines. |
La suma de las líneas es igual a cashbox_movement.amount. |
PaymentRegistrationService::assertTotalMatchesCashboxMovement |
Error sobre cashbox_movement.amount. |
| La cuenta del egreso está en la moneda de la orden. | PaymentCashboxMovementService::assertAccountIsInOrderCoin |
Error sobre cashbox_movement.account_id. |
| Las líneas pasan la compuerta de pago y las aplicaciones a facturas son válidas. | PaymentGateService, PaymentApplicationService |
Errores de la compuerta. |
Campos del movimiento
Sección titulada «Campos del movimiento»PaymentCashboxMovementService::prepareForStore arma el payload:
| Campo | Valor |
|---|---|
type |
egreso (pago) o ingreso (devolución) |
account_id, payment_method_id, payment_date |
Los del formulario |
subtotal_amount |
Suma de las líneas (PaymentOrderCalculator::toAmount), no el monto enviado |
concept |
El enviado, o Pago de más los códigos de las órdenes (Devolución del pago de en una devolución) |
third_party_type |
provider |
provider_id |
beneficiary_provider_id de la primera orden de pago |
provider_account_id |
El enviado, o provider_account_id de la orden |
cost_center_id |
El enviado o, si falta, el de la primera orden de compra por orden de id (resolveCostCenterId) |
| Campos que pasan tal cual | opcode, observation, invoice_number, voucher_type, beneficiary_account, origin_bank_id, destination_bank_id, accounting_account_id, project_id, accounting_account_movements, cashbox_income_segment_id |
La comisión no está entre los campos que pasan: un pago de orden de pago no registra comisión.
Si ni el formulario ni las órdenes de compra traen centro de costos, responde Indica el centro de costo del egreso: la orden de compra no tiene uno.. Con el centro resuelto, el egreso genera su CostCenterMovement por el camino normal; ver Ciclo de vida.
Registrar una devolución
Sección titulada «Registrar una devolución»POST /api/payment-orders/payments/{cashboxMovementId}/refund ejecuta RegisterPaymentRefundUseCase sobre el movimiento del pago original.
| Paso | Detalle |
|---|---|
| Permiso | registerRefund |
| Datos | El request exige cashbox_movement.cashbox_income_segment_id, porque la devolución es un ingreso. PaymentRefundService::prepareCashboxMovement pone observation igual al motivo si no se envió. |
| Validaciones | El pago no debe estar anulado (assertAreNotAnnulled), cada línea debe ser del pago (assertLinesArePaymentLines) y no puede superar lo pagado que aún no se devolvió (assertRefundsFitPaid). La cuenta debe estar en la moneda de la orden. |
| Movimiento | PaymentCashboxMovementService::createRefund crea un ingreso con el mismo proveedor. |
| Vínculo | PaymentRefundService::createMany crea un PaymentOrderMovement por línea con kind igual a refund y refund_of_id apuntando al pago. |
| Efectos en la orden | Revierte aplicaciones a facturas (PaymentApplicationReversalService::reverseForRefund), refresca facturas, repropone aplicaciones y refresca los saldos de las órdenes. |
Anular un pago
Sección titulada «Anular un pago»Hay dos rutas que llegan al mismo caso de uso:
POST /api/payment-orders/payments/{cashboxMovementId}/annul, directo.PUT /api/cashbox-movement/{id}/anulate, que detecta que el movimiento está vinculado a un pago (PaymentCashboxMovementService::isLinkedToPayment, solokindigual apayment) y delega enAnnulPaymentUseCaseconstatus_update_commentcomo motivo.
AnnulPaymentUseCase::execute:
| Paso | Detalle |
|---|---|
| Permiso | annulPayment sobre las órdenes de pago y anulate sobre el movimiento |
| Bloqueos | Bloquea órdenes de compra, órdenes de pago, líneas, movimientos de la orden de pago y el movimiento de Caja |
| Validaciones | El movimiento no debe estar anulado ni conciliado (PaymentAnnulmentService::assertCashboxMovementIsAnnullable; si está conciliado dice que se registre una devolución), los movimientos del pago no deben estar anulados y el pago no debe tener devoluciones (assertHasNoRefunds) |
| Orden de pago | Revierte las aplicaciones a facturas y marca cada PaymentOrderMovement como anulado con el motivo |
| Caja | CashboxMovementAnnulService::annul: anula el movimiento, revierte el movimiento de centro de costos y, por el observador, el saldo de la cuenta |
| Cierre | Refresca facturas, repropone aplicaciones y refresca los saldos de las órdenes |
Bloqueos desde la pantalla de Caja
Sección titulada «Bloqueos desde la pantalla de Caja»CashboxMovementController protege los movimientos vinculados:
| Acción | Regla | Mensaje |
|---|---|---|
Editar (update) |
assertIsNotLinkedToPayment rechaza cualquier movimiento con un PaymentOrderMovement, de pago o de devolución. |
El movimiento está vinculado a una orden de pago: usa Anular pago o Registrar devolución. |
Eliminar (destroy) |
El mismo assertIsNotLinkedToPayment. |
El mismo mensaje. |
Anular una devolución (anulate) |
assertIsNotPaymentRefund |
El movimiento es la devolución de un pago de orden de pago: no se anula desde Caja. |
La devolución no tiene ruta de anulación en el código revisado: una vez registrada, queda.
Hallazgos del código
Sección titulada «Hallazgos del código»PaymentOrderPaymentController::annuly la rutaPUT cashbox-movement/{id}/anulatehacen lo mismo para un pago; la segunda comprueba el vínculo antes de la política de Caja, y el caso de uso aplicaanulatedespués de bloquear el movimiento.- El permiso
MovementCreatede Caja se exige además del permiso de Compras para registrar un pago o una devolución. Quien tenga el segundo y no el primero recibe un error de autorización al crear el movimiento.
