Ir al contenido

Ó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.

POST /api/payment-orders/payments
|
v
RegisterPaymentUseCase::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
v
201 con el CashboxMovement
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.

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.

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.

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, solo kind igual a payment) y delega en AnnulPaymentUseCase con status_update_comment como 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

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.

  • PaymentOrderPaymentController::annul y la ruta PUT cashbox-movement/{id}/anulate hacen lo mismo para un pago; la segunda comprueba el vínculo antes de la política de Caja, y el caso de uso aplica anulate después de bloquear el movimiento.
  • El permiso MovementCreate de 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.