Changelog · Aguita API

2026-09-22 — Deducción de deuda en efectivo de saldo retirable, ganancias acumuladas en estadísticas, comisiones sobre base y anuncios recurrentes

mobile admin

Saldo retirable del conductor (`withdrawableUSD`) ahora resta la deuda en efectivo pendiente: max(0, balance - pendingPayout - cashDebt)
Estadísticas del conductor (`allTime.earningsUSD`) reflejan la suma real histórica de ganancias por viajes entregados
Comisión de Agüita clarificada en el recibo de órdenes calculada sobre el precio base del agua (`base_price_usd`)
Sistema de avisos y anuncios administrativos ampliado con recurrencia automática (diaria, semanal, mensual)
Documentación de la API actualizada en recursos backend para consumo en apps móviles y panel

admin

Cada cliente puede tener una cuenta de pago móvil guardada: cédula, teléfono y banco
El admin la registra y edita desde la ficha del cliente; se guarda solo desde la UI
El formulario de devolución llega pre-llenado con esa cuenta (`saved_account`)
Una cuenta por cliente: guardar de nuevo reemplaza la anterior
El cliente puede consultar la suya en `GET /me/bank-account`

admin

Nuevo formulario de devolución en cada orden: total o monto parcial
El dinero sale por SyPago a un pago móvil; el admin captura cédula, teléfono y banco
Una sola devolución por orden — un segundo intento es `422`, nunca una segunda transferencia
El monto se pide en USD y se envía en Bs a la tasa BCV, congelada en el registro
Una devolución TOTAL confirmada deja el pago en `REFUNDED`; una parcial no lo toca

Breaking cliente conductor admin

El desglose del fondo ya muestra los TRES aportes y suman el total
`total_liters_donated` cambia de valor: ahora son litros financiados a 5 USD/1000 L
Agüita iguala el aporte del CONDUCTOR (no el del cliente): `matchedByAguitaUSD`
El recibo del pedido incluye `aguita_solidary_usd`
`/admin/reports/orders` corrige `solidary_fund_usd`: antes omitía el aporte de Agüita
`aguita_solidary_pct` es derivado y de solo lectura

cliente conductor admin

El admin crea campañas: audiencia, hito de entregas, monto, vigencia, ciudad y tope
El crédito se aplica solo al crear el pedido; ya viene descontado en `POST /orders`
Aplicarlo consume TODO el saldo utilizable: lo que exceda el total del pedido se pierde
El saldo se divide en tres bolsas según dónde puede gastarse (todo / pedidos / remates)
`GET /credit/me` suma los acumulados `earnedUSD` y `redeemedUSD`
El conductor gana dinero real en su billetera, se paga en su próxima liquidación
Las órdenes traen `promo_credit_usd` y `client_charged_usd`

cliente admin

conductor

cliente conductor

POST /orders y reservar remate aceptan addressReference (hasta 255 caracteres)
Nuevo evento WebSocket surplus.reserved en drivers.{id} (conductor) + push
Reservar un remate emite al cliente los eventos de su orden (order.confirmed / order.awaiting_payment)

admin

Nuevo perfil del admin: GET/PUT /admin/auth/profile
Login admin con 2FA por SMS opcional (requires_2fa + verify_token, luego /admin/auth/2fa/verify)
Nueva bandeja de notificaciones del admin: GET /admin/notifications

Breaking cliente conductor admin

Breaking: se retiran los endpoints de payouts (/wallet/me/payouts, /driver/withdrawals)
Breaking: POST /orders y reservar remate exigen tasa BCV (422 ExchangeRateUnavailable)
Nuevo: recibos de liquidación del conductor en GET /wallet/me/settlements
Nuevo: bandeja admin de liquidaciones (config, retry, mark-external, annul)
Los movimientos del wallet ahora exponen direction (CREDIT/DEBIT)