Nota de Venta

Módulo: Ventas / Comercial Tipo: resource Estado: implementado Fecha: 2026-03-18

---

Descripción

Documento central del sistema. La Nota de Venta nace cuando Comercial confirma la venta y recorre todo el flujo hasta la facturación y cobro. Múltiples módulos pueden leer y escribir sus estados.

Es distinta de la Nota de Pedido (que describe qué fabricar) — la Nota de Venta es el documento comercial/fiscal del negocio cerrado.

Regla confirmada: La NV se genera automáticamente en el backend al confirmar la Nota de Pedido. No existe creación manual de NV desde el frontend. El estado inicial siempre es pedido_confirmado.

Relación NV–Ítems (configurable)

El sistema soporta ambos modos según configuración del negocio:

• Una NV por ítem/producto: típico en venta de maquinaria, donde cada máquina genera su propia NV con ciclo de vida independiente.
• Múltiples ítems por NV: típico en negocios con ventas de varios productos en una misma operación comercial.

El modo se determina por la naturaleza del negocio y no es excluyente — ambos pueden coexistir según el tipo de operación.

---

Ciclo de vida

stateDiagram-v2
    [*] --> pedido_confirmado: Comercial confirma venta

    pedido_confirmado --> en_fabricacion: Produccion inicia
    pedido_confirmado --> fact_anticipo: Facturar anticipo
    pedido_confirmado --> en_negro: Venta informal

    en_fabricacion --> con_cambios: Cambios detectados
    con_cambios --> en_fabricacion: Cambios resueltos
    en_fabricacion --> disponible: Fabricacion terminada
    en_fabricacion --> no_disponible: No se puede cumplir

    disponible --> con_cambios: Reasignacion stock
    disponible --> entregada: Entregar sin facturar
    disponible --> facturado: Entregar y facturar
    disponible --> fact_repuesto: Facturar como repuesto

    fact_anticipo --> pedido_confirmado: NC anula anticipo

    entregada --> pendiente_facturar: Pendiente facturacion
    pendiente_facturar --> facturado: Facturacion final

    facturado --> cobrada: Cobro completado
    fact_repuesto --> cobrada: Cobro completado
    en_negro --> cobrada: Cobro sin factura

    cobrada --> [*]

Reglas del ciclo

• Reversibilidad: Los estados pueden retroceder (ej: disponible → con_cambios) por decisiones comerciales o reasignacion de stock.
• Sin fabricacion: Cuando la NV no requiere fabricacion, pasa de pedido_confirmado directo a Administracion (estados de entrega/facturacion).
• Anticipo: fact_anticipo se revierte con NC → vuelve a pedido_confirmado → se refactura correctamente.
• En negro: en_negro nunca alcanza facturado, pero puede llegar a cobrada.

Regla confirmada: Aun cuando haya stock del articulo, la NV NO pasa directo a disponible. El ciclo completo de Produccion continua siempre. Produccion decide administrativamente si entrega stock o fabrica. Se recomienda notificacion al responsable cuando hay stock disponible.

---

Frontend

Acceso: Tab 2 "Acciones Especiales" del registro CRM → card "Nota de Venta" Condición de visibilidad: Solo se muestra si el tipo CRM del registro es comercial (INDUSTRIAL). No aparece en registros de tipo Básico ni Servicio Técnico. Habilitación: La card está deshabilitada hasta que exista al menos una NV vinculada al registro CRM. Se activa automáticamente al confirmar una NP (el backend crea la NV en ese momento). Al hacer clic en la card habilitada, el sistema abre directamente el formulario de esa NV (no un listado).

Origen del concesionario: Al confirmar la NP y generar la NV, el campo concesionario_id siempre recibe el cliente_id de la NP — tanto si ese cliente tiene es_concesionario = true como si es un cliente directo. La distinción es solo informativa (qué tipo de cliente es), pero el campo nunca queda null. No se requiere que el cliente sea concesionario para crear NP ni NV.

Permiso requerido: CRM_NOTA_VENTAComponente principal: NotaVentaOrchestrator (modal xl) Ruta de código: ts/crm/nota-venta/

Vistas

Vista	Descripción
Card NV (Tab 2)	La card "Nota de Venta" se habilita automáticamente al confirmar la NP. Al hacer clic abre directamente el detalle/edición de la única NV vinculada al registro CRM. No hay listado — la relación es 1:1 (NP → NV). Acciones disponibles según estado: Ver, Editar, Cancelar (si pedido_confirmado), Imprimir RE-COM004.
Formulario	Editar/ver NV: datos de cabecera (NP origen —solo lectura, asociada automáticamente—, vendedor —select de operadores del sistema (ordven/Vendedores es una entidad comercial independiente; la relación Vendedor↔Operador está planificada para una etapa futura)—, concesionario, modalidad A/B/C/D, campos financieros, forma de pago, lugar entrega, observaciones). El formulario hace focus automático al primer campo al abrirse.
Panel Adquirente	Si facturacion_terceros = true, se muestra el panel del adquirente con los datos de nota_venta_adquirente: nombre, CUIT, domicilio, condición IVA. El adquirente es siempre uno solo por operación. Se hereda automáticamente de nota_pedido_adquirente al confirmar la NP. Editable en NV.

Comportamiento MVP

En el MVP, la NV se crea desde el backend automáticamente al confirmar una NP. El estado inicial siempre es pedido_confirmado. Los estados posteriores del ciclo (en_fabricacion, disponible, facturado, cobrada, etc.) son seteados por otros módulos del sistema (Producción, Administración, Tesorería) — no desde esta vista CRM.

---

Campos

Identificacion

Campo	Tipo	Descripcion
id	UUID	Identificador unico
numero	string	Numero de la nota (auto-generado, formato N° 0001-XXXXXXXX)
nota_pedido_id	FK	Nota de Pedido de origen (Comercial)
estado	enum	Ver tabla de estados
created_at	datetime	Fecha de creacion (= confirmacion de venta)
updated_at	datetime	Ultima actualizacion

Actores

Campo	Tipo	Descripcion
concesionario_id	FK	Cliente asociado a la venta (heredado de nota_pedido.cliente_id). Puede ser concesionario o cliente directo. Siempre requerido.
adquirente	objeto	Adquirente/tercero de la operación. Almacenado en tabla nota_venta_adquirente. Es siempre uno solo. Se copia automáticamente desde nota_pedido_adquirente al confirmar la NP. Editable en NV.
facturacion_terceros	boolean	Si la factura va a un CUIT diferente del concesionario. Heredado de NP.
vendedor_id	FK	Operador del sistema que realizó la venta. Se selecciona del listado de operadores del sistema. ordven (Vendedores) es una entidad comercial independiente (código de vendedor, comisiones); la relación Vendedor↔Operador está planificada para una etapa futura. Puede ser diferente del usuario que registra la NV.
usuario_registrante_id	FK	Usuario que registra (puede ser diferente del vendedor)
contacto	string	Persona de contacto

Tercero/Adquirente: Es siempre uno solo por operación. Los datos se almacenan en la tabla relacionada nota_venta_adquirente. Campos: nota_venta_id (FK), nombre, cuit, domicilio, condicion_iva, importe. Se hereda automáticamente de nota_pedido_adquirente al generar la NV. Misma estructura que nota_pedido_adquirente en NP.

Clasificacion

Campo	Tipo	Descripcion
modalidad_venta	enum	A | B | C | D — clasificador declarativo (sin lógica asociada en MVP, extensible en v2)
formal	boolean	true = formal (con facturacion), false = informal (en_negro)
facturar_como	enum	equipo | repuesto — solo cuando formal = true
moneda	enum	ARS | USD — NV de exportacion o manipuladores telescopicos pueden ser en USD
tipo_cambio	decimal	Tipo de cambio al momento de facturar (solo cuando moneda = USD). Diferido post-MVP: campo existe pero lógica de tipo de cambio queda para post-MVP.
crm_llamada_id	FK	Relacion con el registro CRM de origen (via nota_pedido → crm_record)
evento	string	Nombre del evento si aplica (Mercolactea, Agroactiva, etc.) — evaluar si se hereda del CRM

Montos

Campo	Tipo	Descripcion
items	array	Items de la venta (articulos, cantidades, precios de lista)
opcionales	array	Items opcionales con sus montos
subtotal	decimal	Suma de los importes de ítems no opcionales — base para bonificaciones. Calculado automáticamente (read-only).
bonificaciones	relación	N bonificaciones dinámicas encadenadas. Ver tabla nota_venta_bonificacion.
costo_flete	decimal	Monto del flete con IVA incluido (copiado de NP tal cual)
flete_a_cargo_de	string	Quien paga el flete (ej: concesionario)
total_operacion	decimal	subtotal + total_flete + comision_concesionario_monto
precio_venta_publico_iva	decimal	Precio al publico antes de bonificaciones, con IVA
comision_concesionario	decimal	Monto calculado de comision
importe_a_facturar	decimal	Monto a facturar al tercero (IVA incluido). Solo aplica cuando facturacion_terceros = true. Se hereda de NP, editable en NV.

Bonificaciones

Las bonificaciones permiten aplicar descuentos porcentuales al subtotal del equipo. Se almacenan en la tabla separada nota_venta_bonificacion (N filas por NV), lo que permite un número dinámico de bonificaciones sin estructura fija.

Tabla nota_venta_bonificacion:

Campo	Tipo	Descripción
nota_venta_id	FK	NV a la que pertenece
descripcion	string	Texto informativo opcional (ej: "Descuento de lista")
porcentaje	decimal	Porcentaje de descuento
orden	integer	Orden de aplicación (ASC)
deleted_at	datetime	Soft delete

Características:

• N bonificaciones dinámicas encadenadas (sin límite fijo).
• Son opcionales: si no hay filas, no se aplica ningún descuento.
• Se calculan sobre el subtotal (suma de ítems no opcionales).
• Cada bonificación se aplica sobre la base resultante de la anterior (cálculo encadenado).

Ejemplo:

Subtotal: $1.000.000 | Bono 1: 10% | Bono 2: 5%

Resultado: $1.000.000 × 0,90 = $900.000 → × 0,95 = $855.000

Nota sobre subtotal: Campo calculado automáticamente (read-only) como suma de los ítems no opcionales cargados en la NV. No se ingresa manualmente.

Entrega y pago

Campo	Tipo	Descripcion
forma_pago	text	Descripcion libre (ej: "7 cheques anticipados en cuotas iguales...")
lugar_entrega	string	Direccion de entrega
fecha_entrega	date	Fecha de entrega o plazo
facturacion_terceros	boolean	Si la factura va a un CUIT diferente del concesionario. Heredado de NP.
importe_a_facturar	decimal	Monto a facturar al tercero (IVA incluido). Solo aplica cuando facturacion_terceros = true. Se hereda de NP, editable en NV.
facturar_anticipo	boolean	Si se debe facturar como anticipo (para gestion de creditos)

Relaciones de vinculacion

Campo	Tipo	Descripcion
nv_padre_id	FK	NV original de la que se deriva esta NV (caso lotes de concesionarios). Puede ser NULL.

Documento de formato fisico: Ver documentos-generados para el layout completo del formulario de Nota de Venta.

Fuente de requerimientos: Ver analisis-requerimientos-nv para el detalle completo.

---

Versionado

La Nota de Venta implementa versionado formal con audit trail. Las NV van teniendo modificaciones continuas a lo largo de su vida (ej: cambios en forma de pago, adquirentes, montos).

Campos de versionado

Campo	Tipo	Descripcion
revision	integer	Numero de revision actual (inicia en 0 al crear, incrementa con cada modificacion)
revision_fecha	datetime	Fecha/hora de la ultima revision
revision_usuario_id	FK	Usuario que realizo la modificacion
revision_motivo	text	Descripcion del cambio realizado

Historial de revisiones (audit trail)

Cada revision genera un registro en el historial con:

Campo	Tipo	Descripcion
nota_venta_id	FK	NV versionada
revision	integer	Numero de revision
fecha	datetime	Fecha/hora del cambio
usuario_id	FK	Quien realizo el cambio
motivo	text	Descripcion del cambio
campos_modificados	json	Detalle de campos: campo, valor anterior, valor nuevo
snapshot	json	Estado completo del documento antes del cambio (para consulta de versiones anteriores)

Reglas de versionado

• La NV es modificable en cualquier estado. Cada modificación genera una nueva revisión. El acceso por estado depende del rol del usuario.
• Solo el vendedor original o Administracion pueden generar nuevas revisiones. Produccion NO puede modificar la NV.
• Cada revision incrementa el numero de revision en 1. Numeración: NV-XXXX Rev.0N (el número de documento no cambia entre versiones).
• La revisión de una NV comienza en 00. El formato físico lo confirma: N° 0001-00015013 Rev.00 (primera emisión).
• Se pueden consultar versiones anteriores completas (snapshot preserva el estado).
• Al generar una nueva revision, se reimprimen todos los documentos afectados:
  • Nota de Venta (RE-COM004) — con datos actualizados
  • Confirmacion de Nota de Pedido (RE-COM003) — si los cambios impactan el acuerdo comercial
  • Pedido a Produccion — si los cambios impactan especificaciones del equipo
• Se envia email a las areas afectadas detallando los cambios.

Requerimiento de informe asociado

• Informe de NV modificadas por usuario, con fecha, hora y motivo del cambio.

---

Estados

Estado	Descripción	Lo setea	Módulo
pedido_confirmado	Venta confirmada, NV creada	Comercial	CRM / Comercialización
en_fabricacion	Producción inició la fabricación	Producción	Módulo Producción
con_cambios	Producción detectó cambios en el pedido	Producción	Módulo Producción
disponible	Fabricación terminada, listo para Administración	Producción	Módulo Producción
no_disponible	Producción no puede cumplir el pedido	Producción	Módulo Producción
fact_repuesto	Facturada como repuesto	Administración	Módulo Administración
fact_anticipo	Facturada como anticipo (previo a venta real)	Administración	Módulo Administración
entregada	Entregada con remito sin factura	Administración	Módulo Administración
pendiente_facturar	Entregada, pendiente de facturar	Administración	Módulo Administración
facturado	Facturación final completada	Administración	Módulo Administración
en_negro	Venta informal sin facturación. La NV nunca alcanzará el estado facturado.	Comercial/Administración	CRM / Administración
cobrada	Cobro completado (con o sin factura)	Tesorería	Módulo Tesorería

Reversibilidad: Los estados pueden retroceder (ej: de disponible a con_cambios) por decisiones comerciales o reasignacion de stock ante urgencias de otros clientes.

---

Documentos relacionados

Documento	Relación
Nota de Pedido (Comercial)	Documento de origen — la NV se genera a partir de la Nota de Pedido confirmada
Doc: Pedido a Producción (A1)	La NV vinculada al pedido que va a Producción
Doc: Nota de Venta (A2)	La NV en su rol de documento que deriva a Administración
Orden de Trabajo	Generada en Producción, vinculada a la NV vía Nota de Pedido
Factura	Relación Factura:NV = 1:N — una factura puede cubrir múltiples notas de venta. Capacidad core del sistema.

Capacidad futura — División en facturas

Post-MVP: Al aprobar la NV en el ciclo comercial, el sistema debe permitir dividir el comprobante en múltiples facturas (ej: anticipo + saldo, o facturación en cuotas). La estructura de la NV debe contemplar esta capacidad sin implementarla en el MVP. El mecanismo exacto de división queda a definir en la próxima iteración.

---

Quién puede alterar estados

Módulo	Estados que puede setear	Condición
Comercial/CRM	pedido_confirmado	Al confirmar la Nota de Pedido
Producción	en_fabricacion, con_cambios, disponible, no_disponible	Según avance de fabricación
Administración	fact_repuesto, fact_anticipo, entregada, pendiente_facturar, facturado	Según tipo de operación y paso del flujo → flujo-administracion-process
Tesorería	cobrada	Al completar el proceso de cobro (con recibo oficial o provisorio) → flujo-tesoreria-ventas-process

Retenciones — mecanismo de dos pasos (fuente: "Modificaciones luego de Analizar el DFD.docx"):

• Mecanismo formal: el sistema debe permitir registrar "saldo pendiente por retenciones" y cambiar la NV de no-cobrada a cobrada cuando se confirma que el saldo restante corresponde a retenciones.
• Override manual: también debe permitir cambiar el estado manualmente como ajuste administrativo.

---

Preguntas abiertas

• [x] Stock vs Produccion: Si hay stock del articulo, la NV pasa directo de pedido_confirmado a disponible sin pasar por estados de Produccion? Resolved: NO. El sistema no debe automatizar el paso a "disponible" aunque haya stock. El ciclo completo continua siempre; Produccion decide administrativamente si entrega stock existente o fabrica. Se incluira notificacion al usuario responsable sobre este estado para agilizar la decision.
• [ ] Origen directo Produccion: Si el pedido es manual (sin flujo Comercial), la NV se crea en ese momento o no existe?
• [x] Reversibilidad de estados: Un estado puede retroceder? (ej: de disponible a con_cambios si se detecta un problema post-cierre) Resolved: Si, es posible retroceder estados (ej: de disponible a con_cambios) por decisiones comerciales o reasignacion de stock ante urgencias de otros clientes.

---

Proceso de origen

← flujo-comercial-process

Procesos que la consumen

→ flujo-produccion-process — estados de fabricación
→ flujo-administracion-process — facturación (tres caminos: repuesto, anticipo, venta normal)
→ flujo-tesoreria-ventas-process — cobro (C1, GEN_FA, GEN_FR → estado cobrada)

Flujo NV → Facturación: cuando la NV va a facturar, genera una prefa directamente (flujo propio). Este camino NV→prefa es independiente del flujo budget→prefa existente en CRM. Ambos caminos coexisten.