2026-08-04 — Sistema de liquidaciones

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

Summary

Se reemplaza el sistema de "payouts" por un sistema de liquidaciones (settlements): el saldo del conductor se corta por período, genera un recibo y se dispersa. El conductor consulta sus recibos; el panel gana configuración y una bandeja para resolver recibos fallidos. Como parte del cambio se retiran los endpoints de payouts anteriores y se endurece la creación de pedidos cuando no hay tasa BCV.

Breaking changes

Se eliminan los endpoints de payouts

Los endpoints del sistema de payouts anterior ya no existen; su función la cubren los recibos de liquidación y la bandeja admin.

Removidos: POST /wallet/me/payouts, GET /wallet/me/payouts, POST /driver/withdrawals, GET /driver/withdrawals y POST /admin/drivers/{driverId}/wallet/settle.
Migración: dejar de llamar a esos endpoints; el conductor ve sus pagos en GET /wallet/me/settlements y el admin resuelve en la bandeja. Se mantienen GET /wallet/me/payout-config, POST /wallet/me/payout-config y PUT /driver/payout-method.

`POST /orders` requiere una tasa BCV disponible

Crear un pedido (y reservar un remate) exige que exista una tasa BCV (VES) almacenada; si no, la operación se rechaza en lugar de crear un pedido sin snapshot.

Afecta: POST /orders (cliente) y POST /surplus/{surplusId}/reserve (cliente).
Errores: 422 ExchangeRateUnavailable.
Migración: manejar 422 ExchangeRateUnavailable y reintentar cuando la tasa vuelva a estar disponible (ver GET /exchange-rates/bcv).

Cambian los tipos de movimiento del wallet

Se retiran dos valores del campo type de los movimientos del wallet.

Removidos: PAYOUT_FAILED_REFUND y WALLET_TOPUP.
Migración: no depender de esos valores. Valores vigentes de type: ORDER_EARNING, SURPLUS_EARNING, CASH_COMMISSION_DEBT, CASH_SOLIDARY_DRIVER, CASH_SOLIDARY_CLIENT, PAYOUT_SENT, MANUAL_ADJUSTMENT.

New

Recibos de liquidación del conductor (conductor)

Método	Endpoint	Rol	Para qué sirve
GET	`/wallet/me/settlements`	conductor	Lista paginada (cursor) de los recibos propios.
GET	`/wallet/me/settlements/{id}`	conductor	Un recibo con sus líneas.

GET /wallet/me/settlements — filtros: status, date_from, date_to, limit (1-100, por defecto 25), cursor. Response: { items, next_cursor, has_more }. Cada item: id, receipt_number, fiscal_period, status, cutoff_from, cutoff_to, issued_at, net_usd, payable_usd, total_paid_bs_cents, paid_at, created_at.
GET /wallet/me/settlements/{id} — agrega payout_method, subtotal_usd, commission_usd, iva_prc, net_bs_cents y lines[] (line_number, type ORDER|ADJUSTMENT, order_id, order_date, description, net_usd, exchange_rate_amount, total_bs_cents). Errores: 404 ReceiptNotFound.
Valores de status: GENERATED, IN_PAYMENT, PAID, FAILED, PAID_EXTERNALLY, VOIDED.

`GET /driver/vehicle` (conductor)

Devuelve el vehículo del conductor autenticado.

Response: { vehicle } con plate, capacity_liters, brand, model, year, hose_length_meters, has_motopump, operation_radius_km, photo_urls, sanitary_cert_url, cert_expires_at, status.
Errores: 404 DriverNotFound · 404 VehicleNotFound.

Configuración de liquidaciones (admin)

Método	Endpoint	Rol	Para qué sirve
GET	`/admin/settlements/config`	super-admin	Leer la configuración de liquidaciones.
PATCH	`/admin/settlements/config`	super-admin	Actualizar la configuración (parcial).

PATCH acepta (todos opcionales): cutoff_enabled (bool), cutoff_time (H:i), payout_enabled (bool), payout_time (H:i, posterior a cutoff_time), min_balance (number, >= 0.5 USD), active_days (array de 7 booleanos, 0=Dom), iva_prc (number 0-100), timezone (offset ±HH:MM o identificador IANA).
Response: { config, audit_entry } (audit_entry es null si no hubo cambios).
Errores: 422 si payout_time no es posterior a cutoff_time o algún campo es inválido.

Bandeja de resolución de liquidaciones (admin)

Recibos en estado FAILED que requieren intervención manual.

Método	Endpoint	Rol	Para qué sirve
GET	`/admin/settlements/tray`	super-admin	Listar recibos fallidos.
POST	`/admin/settlements/receipts/{id}/retry`	super-admin	Reintentar la dispersión.
POST	`/admin/settlements/receipts/{id}/mark-external`	super-admin	Marcar pagado por fuera de agüita.
POST	`/admin/settlements/receipts/{id}/annul`	super-admin	Anular el recibo y liberar su reserva.

GET /admin/settlements/tray — filtros: failure_kind (business|deadline), limit (1-100, por defecto 25), page. Response: { items, meta }. Cada item: id, receipt_number, driver_id, driver_name, payout_method, net_usd, payable_usd, total_paid_bs_cents, failure_reason, failure_kind, provider_code, attempts, failed_at, created_at.
retry — sin body. Errores: 404 ReceiptNotFound · 409 ReceiptNotFailed · 409 RetryUnsafeDeadline (cuando el recibo falló por vencimiento de conciliación).
mark-external — Request: reason (string, requerido, max:500), reference (string, requerido, max:191). Errores: 404 ReceiptNotFound · 409 ReceiptNotFailed · 422.
annul — Request: reason (string, requerido, max:500). Errores: 404 ReceiptNotFound · 409 ReceiptNotFailed · 422.

Notificaciones al conductor (inbox + push)

Nuevas notificaciones en la bandeja GET /notifications y push FCM; no son eventos WebSocket.

settlement_paid — cuando el recibo queda PAID o PAID_EXTERNALLY. data: receipt_id, receipt_number, total_paid_bs_cents, reference.
settlement_payout_failed — cuando el pago falla por método/cuenta inválida. data: receipt_id, receipt_number.

Changes

Movimientos del wallet: nuevo `direction`

GET /wallet/me/transactions (y su alias GET /driver/wallet/transactions) exponen direction (CREDIT|DEBIT) por movimiento, para conocer el signo del impacto en el saldo de forma explícita (necesario porque MANUAL_ADJUSTMENT puede ser cualquiera de los dos). La respuesta mantiene los demás campos.