Pedidos y ventas

Esta guía explica la página real de pedidos de Ballista, no el concepto genérico de vender. El módulo vive en la ruta /orders y su objetivo es convertir una solicitud comercial en una orden operativa que pueda seguir hacia inventario, tareas, facturación electrónica, historial y reportes.

En Ballista, Pedidos no es solo una tabla. Es el punto de entrada del flujo pedido-inventario-factura. Desde aquí una persona puede crear un pedido completo, buscar pedidos existentes, revisar estado, ver si ya hay factura electrónica asociada, corregir datos generales y abrir el detalle donde viven líneas, lotes, etiquetas, tareas y acciones de facturación.

Rutas del flujo

Estructura de /orders

La pantalla escritorio usa OrdersWorkbenchPanel. En móvil usa el mismo panel con variante compacta. La diferencia principal es visual: escritorio muestra indicadores, filtros y tabla; móvil muestra filtros compactos, indicadores y tarjetas por pedido.

Indicadores superiores

Al entrar a /orders, la primera lectura es el resumen:

Estos indicadores no reemplazan la tabla. Funcionan cómo alerta rápida: si hay muchos pendientes o el monto no cuadra, el siguiente paso es filtrar y abrir pedidos concretos.

Permisos visibles

La pantalla respeta permisos:

Si falta un permiso, Ballista muestra un aviso de permisos y algunos botones quedan deshabilitados. Eso no es error de la pantalla: significa que el usuario puede consultar, pero no ejecutar esa acción.

Botón Crear pedido

Crear pedido abre el asistente de creación completa. Esta es la entrada recomendada para crear pedidos nuevos porque guarda encabezado, líneas, lotes o producto compuesto, notas, tarea opcional y notificación opcional en un flujo coherente.

No debe confundirse con editar una fila. Crear pedido crea una orden nueva; Editar corrige datos generales de una orden existente.

Filtro rápido por estado

En escritorio aparece como una tarjeta lateral de Estado rápido; en móvil aparece como selector dentro de los filtros. Permite ver:

Este filtro no cambia datos. Solo reduce lo visible para revisar el grupo correcto.

Búsqueda simple

La pestaña Simple muestra un solo campo de búsqueda. Es útil cuando la persona recuerda algo general: número de pedido, nombre relacionado o texto que pueda aparecer en el registro.

Úsala cuando no necesitas precisión. Por ejemplo: "busca rápido todo lo que tenga ABC" o "encuentra el pedido 1042".

Filtros avanzados

La pestaña Avanzada separa la búsqueda en tres grupos.

Identificación

Fechas

Clasificacion

Después de llenar filtros, usa Search. Si quieres volver a empezar, usa Clear.

Botones Search y Clear

Importante: cambiar campos no siempre significa que la consulta ya se aplico. Usa Search para confirmar la búsqueda.

Tabla de resultados

La tabla aparece en el bloque orders-results. Cada fila representa un pedido. Las columnas principales son:

Columna E-invoice issued

Esta columna conecta pedidos con facturación electrónica.

Si una orden debería estar facturada y aparece como sin facturar, abre el detalle del pedido y revisa si se uso Facturar este pedido o busca en historial de facturación.

Cambio de estado en la fila

Si tienes permiso edit_orders, la columna Status muestra un selector. Cambiarlo llama al ruta interna de cambio de estado y refresca la lista.

Estados esperados:

No uses el estado como sustituto de trazabilidad. Si necesitas explicar por qué cambio, agrega contexto en el detalle o en tareas.

Acción Editar

Editar abre un formulario de edición rápida del encabezado. Permite corregir:

Editar no es para administrar líneas, lotes o etiquetas. Para eso abre el pedido con el link #id y trabaja desde el detalle.

Acción Delete

Delete elimina el pedido después de confirmación. Debe usarse solo si el pedido fue creado por error y no debería conservarse como evidencia operativa.

Si el pedido ya tiene líneas, tareas, factura o historial, lo correcto normalmente es cancelar o corregir, no borrar.

Vista móvil

En móvil, la tabla se transforma en tarjetas. Cada tarjeta muestra:

La funcion es la misma que escritorio, pero optimizada para pantalla estrecha.

Wizard Crear pedido

El asistente crea una orden completa. Internamente se divide en cuatro estaciones.

Antes de abrirlo conviene entender que este flujo no es solo "guardar un formulario". El envío llama al ruta interna /api/orders/create-complete. Ese ruta interna crea la orden, crea sus líneas, valida impuestos, valida inventario, descuenta cantidades de lotes, crea asignaciones de lote, registra movimiento de inventario cuando la tabla existe, puede crear tarea, puede crear notificación, emite eventos en tiempo real y guarda auditoría del intento con traceId.

Requisitos antes de crear una orden

Para qué una orden pueda crearse bien, varias cosas ya deben existir en la base de datos. Algunas son obligatorias y otras dependen del tipo de pedido.

Checklist operativo antes de tocar Crear pedido

Antes de crear una orden, la persona usuaria debería poder responder estas preguntas. Si alguna respuesta falta, la orden probablemente va a quedar incompleta o va a fallar al guardar.

Datos que deben existir según el tipo de línea

La parte más importante del asistente no es solo llenar campos: es escoger de dónde sale lo que se vende. Ballista soporta dos caminos principales para las líneas del pedido.

Ejemplo simple: si vendes una materia prima ya empacada, normalmente usas Lot. Si vendes un producto preparado con fórmula, presentación o receta, normalmente usas Compound product.

Recorrido de creación de una orden de principio a fin

Este es el flujo completo que una persona debería seguir en la pantalla.

1. Entrar a /orders.
2. Revisar si el pedido ya existe usando búsqueda simple, filtros o cliente.
3. Si no existe, presionar Crear pedido.
4. Seleccionar Cliente.
5. Seleccionar Order type.
6. Elegir el estado inicial, normalmente pendiente si todavía no se ha ejecutado.
7. Definir Promised date.
8. Marcar E-invoice si el pedido debe terminar en factura electrónica.
9. Agregar dependiente si aplica.
10. Agregar referencia externa si aplica.
11. Crear una o varias líneas en Order lines.
12. Para cada línea, decidir si viene de Lot o de Compound product.
13. Revisar cantidad, precio unitario, impuesto y total de línea.
14. Activar Incluir tarea si alguien debe preparar, revisar, llamar, producir o entregar.
15. Activar Include notification si alguien debe recibir aviso inmediato.
16. Revisar mensajes de validación.
17. Presionar Crear pedido.
18. Si se guarda, abrir /orders/{id} desde el link del pedido.
19. Revisar líneas, lotes, totales, estado y trazabilidad.
20. Cuando corresponda, pasar a Facturar este pedido.

La idea no es que la persona memorice la tecnología. La idea es que entienda que una venta queda lista cuando tiene cliente, fecha, líneas, cantidades, precio, impuesto, inventario trazable y siguiente acción.

Qué se calcula al crear la orden

Cuando presionas Crear pedido, Ballista calcula y persiste varios valores:

Qué se guarda al crear la orden

El flujo completo puede guardar todo esto en una sola transaccion:

Todo esto ocurre de forma transaccional. Si falla inventario, impuesto, FK o validación, el servidor hace reversión: no debe quedar media orden creada ni inventario disponible rebajado a medias.

Qué significa que sea transaccional

Crear una orden toca muchas piezas al mismo tiempo. Por eso el servidor usa una transaccion: o se guarda todo bien, o no se guarda nada.

Esto es especialmente importante para inventario. La interfaz ayuda, pero la verdad final la decide el servidor con bloqueo de filas (FOR UPDATE) para evitar que dos pedidos reserven el mismo lote al mismo tiempo.

Cómo impacta inventario

Esta parte es clave: crear una orden completa con líneas que usan inventario rebaja la cantidad actual del lote.

Si la línea usa Lot

1. El usuario selecciona un lote.

2. La interfaz muestra disponibilidad (Available) y precio.

3. La interfaz valida que la cantidad pedida no supere disponibilidad en tiempo real.

4. El servidor vuelve a consultar el lote con FOR UPDATE.

5. Si current_quantity alcanza, ejecuta:

   current_quantity = current_quantity - cantidad_solicitada

6. Inserta una asignacion en sales_order_item_lot_allocations.

7. Inserta movimiento de inventario tipo reserve con cantidad negativa si la tabla existe.

Ejemplo: si el lote tiene current_quantity = 10 y la orden reserva 2, después de crear la orden queda current_quantity = 8.

Ejemplo completo con línea Lot

Supongamos que una persona vende 2 unidades de una materia prima empacada.

Si en el paso 9 el lote ya no tiene 2 unidades porque otra orden lo reservo, el servidor responde conflicto. En ese caso no se crea una orden parcial y no se descuenta inventario.

Si la línea usa Compound product

1. El usuario selecciona una variante de producto compuesto.

2. La interfaz manda id_producto_compuesto_variacion y cantidad.

3. El servidor busca la fórmula en compound_product_components.

4. Por cada componente calcula:

   cantidad_necesaria = cantidad_formula * cantidad_pedida

5. Busca lotes disponibles de esa materia prima.

6. Ordena lotes por fecha de vencimiento y luego por id.

7. Toma cantidades de uno o varios lotes hasta cubrir la necesidad.

8. Si no alcanza, responde conflicto de inventario y no crea la orden.

9. Si alcanza, descuenta los lotes y crea asignaciones igual que una línea de lote.

Ejemplo: una crema compuesta requiere 0.5 unidades de materia prima A por unidad. Si el pedido pide 4, el servidor necesita 2 unidades de A. Puede tomarlas de un lote o repartirlas entre varios lotes disponibles.

Ejemplo completo con Compound product

Supongamos que se vende una variante llamada Crema 100 ml, compuesta por materia prima A y materia prima B.

Ejemplo numerico: si Crema 100 ml usa 0.5 de A y 0.25 de B por unidad, vender 4 unidades requiere 2 de A y 1 de B. Si A está repartida entre dos lotes, Ballista puede reservar parte de un lote y parte de otro.

Si no hay suficiente A o B, la orden falla completa. Eso es correcto: vender un producto compuesto sin insumos suficientes sería prometer algo que producción no puede cumplir.

Qué significa reserve

El movimiento reserve significa que el inventario queda apartado por la orden. No es solo una nota visual. El lote baja su disponibilidad para que otro pedido no prometa el mismo inventario disponible.

Si después se elimina el pedido, el servidor restaura cantidades de las asignaciones y registra movimientos inversos/release según soporte disponible.

Relación con otros módulos

Crear una orden toca varias partes de Ballista:

Reglas de validación importantes

Estas son las reglas que más suelen bloquear una orden:

Idempotencia y traceId

El ruta interna de creación completa soporta X-Trace-Id. Si llega el mismo traceId con el mismo payload, el servidor puede devolver el resultado anterior sin duplicar pedido ni volver a descontar inventario.

Esto importa porque evita que doble click, reintentos o problemas de red creen dos órdenes iguales y descuenten inventario disponible dos veces.

Si llega el mismo traceId con payload diferente, el servidor responde conflicto. Eso protege la auditoría del flujo.

1. Order data

Define el encabezado comercial y operativo.

Lectura campo por campo:

Si falta Cliente, el asistente no debería crear la orden. Si marcas factura electrónica, asegurate de que el cliente y la configuración FE tengan datos suficientes antes de emitir.

Lo que este bloque NO hace: no emite factura, no descuenta inventario y no crea líneas. Solo define el encabezado que luego usaran inventario, detalle, reportes y facturación.

2. Order lines

Define que se vende o prepara. Cada línea puede venir de dos fuentes:

Campos y lecturas importantes:

Si una línea usa lote y la cantidad supera disponibilidad, el asistente puede mostrar conflicto de inventario. Eso debe resolverse antes de prometer o crear el pedido.

Lectura práctica de una línea:

Criterio útil: no trates el precio y el inventario cómo campos separados. En Ballista, una línea completa debe decir que se vende, en que cantidad, de dónde sale, cuanto cuesta, que impuesto tiene y que inventario disponible queda reservado.

3. Optional actions

Esta seccion evita que el pedido quede sin seguimiento.

Usa tareas cuando alguien debe preparar, revisar, llamar, comprar o dar seguimiento. Usa notificación cuando necesitas avisar a una persona concreta.

Ejemplos concretos:

4. Feedback y envío

Antes de crear, el asistente puede mostrar:

El botón final Crear pedido envía encabezado, líneas, tarea opcional y notificación opcional como un solo flujo. Si se crea correctamente, la lista se refresca.

Después de presionar el botón, piensa el resultado asi:

Abrir /orders/{id}

El número de pedido en la tabla abre el detalle. Ese detalle es el lugar correcto para trabajar con profundidad.

En el detalle se revisa:

Criterio útil: usa /orders para encontrar y administrar pedidos; usa /orders/{id} para explicar y modificar un pedido con detalle.

Flujo hacia factura electrónica

Cuando el pedido está listo para facturar:

1. Abre /orders/{id}.
2. Revisa cliente, receptor, líneas, cantidades, impuestos y totales.
3. Usa Facturar este pedido.
4. Facturación carga el contexto del pedido.
5. Revisa emisor, receptor, condición de venta, moneda, líneas, impuestos y total.
6. Emite o simula según el ambiente configurado.
7. Revisa el resultado en historial de facturación.

Si la factura falla, normalmente no se arregla desde la lista de pedidos. Revisa cliente, datos fiscales, impuestos, CABYS, configuración FE o certificado en configuración de facturación.

Flujo recomendado para operar

1. Entra a /orders.
2. Revisa indicadores para saber volumen y pendientes.
3. Usa filtro rápido o búsqueda avanzada para ubicar el pedido.
4. Si el pedido no existe, usa Crear pedido.
5. Completa Order data.
6. Agrega líneas desde lotes o productos compuestos.
7. Agrega tarea/notificación si alguien debe actuar.
8. Crea el pedido.
9. Abre /orders/{id}.
10. Revisa líneas, lotes, totales y trazabilidad.
11. Cambia estado solo cuando la operación realmente avanzo.
12. Si corresponde, usa Facturar este pedido.
13. Verifica factura en historial de facturación.
14. Usa Reportes para revisar resultados del periodo.

Problemas comunes

Para soporte

Cuando reportes un problema de pedidos, incluye:

• ruta exacta: /orders, /orders/{id}, /billing o /tasks;
• id del pedido;
• cliente y dependiente si aplica;
• filtros usados;
• estado esperado y estado visible;
• si el problema está en lista, asistente, detalle, factura o tarea;
• mensaje de validación o traceId si aparece;
• si el pedido usa lote o producto compuesto.

Cómo se conecta

Pedidos conecta con Inventario y producción, porque las líneas pueden consumir lotes o productos compuestos. También conecta con Facturación y control, porque Facturar este pedido convierte el pedido en documento fiscal. Finalmente conecta con Reportes y decisiones, porque estados, fechas, montos y facturación alimentan indicadores.

Resumen

En Ballista, /orders sirve para encontrar, filtrar, crear y administrar pedidos. /orders/{id} sirve para trabajar el pedido en profundidad. Crear pedido captura encabezado, líneas, inventario disponible, tarea y notificación. Facturar este pedido conecta el pedido con facturación electrónica. Si algo no cuadra, revisa primero el módulo origen: clientes, lotes, productos compuestos, impuestos, configuración FE o permisos.