2026-08-11 — addressReference y evento surplus.reserved

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

Summary

Los pedidos ganan un campo opcional de referencia de dirección, y reservar un remate ahora avisa al conductor en tiempo real (nuevo evento WebSocket + push) además de emitir al cliente los eventos de su orden. Todo es aditivo.

New

addressReference al crear un pedido (cliente)

POST /orders y POST /surplus/{surplusId}/reserve aceptan addressReference.

• Request: addressReference (string|null, opcional, max:255).
• Response: el objeto de orden devuelve address_reference (string|null) — el request es camelCase y la respuesta snake_case, consistente con el resto del objeto de orden. Presente en la vista de cliente y de conductor.
• Aparece en los endpoints que devuelven la orden completa (GET /orders/{orderId}, GET /orders/active, GET /orders/history, entre otros); no en los listados con campos acotados (GET /orders, GET /driver/orders).

WebSocket

Se emite cuando un cliente reserva un remate (POST /surplus/{surplusId}/reserve). payload (sin PIN): order_id, surplus_listing_id, status (CONFIRMED|WAITING_FOR_PAYMENT), liters_requested, water_type, address, latitude, longitude, driver_gross_usd, payment_method, client ({ name }).

• Push: además se envía la notificación push/inbox surplus_reserved al conductor (data: order_id, surplus_listing_id).
• Al reservar, el cliente también recibe en orders.{id}.client los eventos de su orden: order.confirmed (con PIN, si el pago es en efectivo y queda CONFIRMED) u order.awaiting_payment (si es método online y queda WAITING_FOR_PAYMENT); el conductor recibe order.ready_to_start en el caso en efectivo.

Changes

Contadores del perfil del cliente

Los contadores del cliente (totalOrders, totalLitersOrdered, totalSolidaryUSD) ahora se incrementan al entregar cada pedido y se rellenaron con el histórico de entregas. No cambia la forma de la respuesta; los valores dejan de ser siempre 0 en GET /me, GET /solidarity/me y las pantallas admin de clientes.