2026-07-21 — Tasa BCV fija por orden y franjas de comisión

Para front-end, mobile e integradores de /api/v1.

Summary

La app gana un endpoint dedicado para leer la tasa BCV (VES) cacheada con su vigencia, y el monto en Bs que se muestra al pagar una orden queda fijado al snapshot de la orden en lugar de recalcularse con la tasa viva. En el panel, los métodos y formas de pago admiten franjas de comisión (commission_tiers) por rango de monto. Todo es aditivo: no cambia la forma de ninguna respuesta existente.

New

`GET /exchange-rates/bcv` (cliente, conductor)

Tasa BCV (VES) cacheada con metadatos de frescura, para que la app programe su propio refetch en vez de hacer polling. Requiere token (auth:sanctum).

Response: { code: "VES", rateBs, fetchedAt, expiresAt, stale }.
- rateBs (number): Bs por USD.
- fetchedAt (string|null, ISO-8601): cuándo se obtuvo la tasa.
- expiresAt (string|null, ISO-8601): cuándo conviene volver a pedirla.
- stale (boolean): true si la tasa cacheada está vencida.
Errores: 503 ServiceUnavailable si no se puede resolver la tasa.

Franjas de comisión por método y forma de pago (admin)

Los métodos y formas de pago aceptan un arreglo opcional commission_tiers que define la comisión de aguita por rango de monto. El aguita_prc plano sigue siendo la base: los montos no cubiertos por una franja usan ese valor.

Método	Endpoint	Rol	Para qué sirve
GET	`/admin/config/payment-methods`	admin	Ahora expone `commission_tiers` por método.
PATCH	`/admin/config/payment-methods/{method}`	admin	Persiste `commission_tiers` del método.
POST	`/admin/payment-forms`	admin	Acepta `commission_tiers` al crear la forma.
PATCH	`/admin/payment-forms/{paymentFormId}`	admin	Acepta `commission_tiers` al editar la forma.

Request: commission_tiers (array|null, opcional). Cada item:
- min_amount (number, requerido, >= 0).
- max_amount (number|null, requerido presente; null = sin tope, >= 0).
- aguita_prc (number, requerido, 0-50).
Validación adicional: las franjas no pueden solaparse (se permiten huecos) y cada aguita_prc va entre 0 y 50.
Errores: 422 ante franjas inválidas o solapadas (campo commission_tiers).

`GET /surplus/nearby` (cliente)

Acepta un parámetro opcional paymentMethod para previsualizar base_price y client_pays de cada remate con la comisión de ese método. Aplica también al alias GET /surplus.

Request: paymentMethod (string, opcional): código de una integración activa (por ejemplo CASH_USD); por defecto CASH_USD cuando se omite.
Errores: 422 si paymentMethod no es una integración activa.

Changes

`GET /orders/{orderId}/payment/form` (cliente)

Cuando la forma liquida en VES, el preview de pago (bs y bcv_rate) se calcula con la tasa BCV fijada en la orden al quedar lista para pagar, no con la tasa viva. La respuesta mantiene los mismos campos; el monto en Bs ahora coincide exactamente con lo que se cobrará.