Hay un diseño tentador donde close_quote devuelve 409 Conflict si alguna línea no tiene inventario. Limpio. Seguro. Equivocado.
El atractivo es obvio: nunca prometas lo que no puedes entregar. Cada línea de una cotización cerrada está respaldada por inventario físico. El sistema es conservador, el almacén está feliz, y nada se vuelve negativo. Pero este diseño tiene una premisa escondida — que el inventario es estático y que el equipo comercial no sabe cosas que el sistema no sabe. Ambas premisas son falsas.
Por qué está equivocado Las ventas ocurren antes de que el almacén se ponga al día. Un comercial cierra una cotización el viernes en la noche; la recepción de mercancía es el martes. La cotización es legítima, el cliente está pagando, el equipo sabe que el producto viene en camino. Bloquear el cierre fuerza un baile de reprogramación que crea más problemas de los que resuelve.
La consecuencia real de imponer estrictamente el inventario al cierre es que los equipos comerciales construyen workarounds. Crean productos 'dummy' para absorber la reserva. Cierran la cotización en un entorno de prueba y envían el PDF por correo. Escriben el pedido en papel y lo ingresan cuando llega el inventario. Cada workaround es peor que el problema — crea inventario sombra, compromisos no rastreados, y un sistema paralelo que el sistema real no puede ver.
La respuesta de Quotery
POST /api/quotes/{id}/close/ nunca devuelve 409 por disponibilidad. Siempre cierra, reserva lo que hay, y devuelve un array shortages con cada producto faltante. El frontend renderiza un banner claro; el comercial actúa con información, no con errores.
El array shortages es la clave. No es solo un booleano de 'inventario insuficiente' — es una lista estructurada de exactamente qué productos faltan y por cuánto. El frontend renderiza un banner ámbar: '3 productos tienen inventario disponible insuficiente. Déficit total: 47 unidades en 2 proveedores.' El comercial puede hacer click para ver cada producto, su cantidad disponible actual, la cantidad reservada, y la brecha. Luego decide: proceder y emitir una orden de compra, dividir la cotización entre lo disponible ahora y lo pendiente, o llamar al cliente y ajustar.
Dónde SÍ imponemos
La entrega es diferente. Una nota de entrega que dejaría on_hand negativo SÍ se rechaza al postear. Puedes reservar lo que no existe; no puedes despachar lo que no existe. Ahí pertenece la restricción — un paso después, una transición más adelante.
Esta es la distinción crítica. La reserva es una promesa; la entrega es el cumplimiento. Las promesas pueden hacerse contra inventario futuro. El cumplimiento solo puede ocurrir contra inventario físico. Al colocar la restricción fuerte en la entrega en vez de en la cotización, le damos flexibilidad al equipo comercial sin permitir que el almacén despache producto que no tiene. Las dos operaciones tienen invariantes diferentes porque sirven a propósitos diferentes. El sistema impone cada una en el punto correcto.