Actualización y Reconciliación de Líneas (PUT /salesdocuments)

En BaseGes ERP, la actualización de un documento de venta (albarán o factura) mediante PUT /salesdocuments/{series}/{number} incorpora un motor de reconciliación de líneas.

A diferencia de los modelos destructivos que eliminan y vuelven a insertar todas las líneas, la reconciliación identifica qué líneas ya existían para actualizarlas en el mismo lugar, calcula los ajustes diferenciales de inventario y preserva los identificadores únicos.

Beneficio Principal

En documentos que mueven inventario (updatesStock: true), la reconciliación evita tener que realizar una devolución completa del stock del documento para luego volver a descontarlo. El sistema únicamente aplica la diferencia neta (delta) sobre el almacén.

---

1. Funcionamiento del Campo id

Cada elemento del árbol de líneas del documento dispone del campo opcional id (int):

Petición	Estado del campo id	Acción realizada por el motor
POST /salesdocuments	Omitido o null	Creación del documento; el sistema asigna un identificador único a cada línea.
PUT /salesdocuments/...	Informado con id existente	Actualización in-situ: Conserva el identificador y actualiza precio, cantidad, coste, descuento y textos.
PUT /salesdocuments/...	Omitido, null o 0	Alta de línea: Inserta la línea como nueva dentro del documento y le asigna un nuevo id.
PUT /salesdocuments/...	Ausente en la petición	Baja de línea: Cualquier línea previa no incluida en el payload se elimina del documento.

---

2. Ajuste Diferencial de Stock Físico

Cuando el documento tiene activado el movimiento de almacén (updatesStock: true), los cambios de cantidad se aplican mediante cálculo diferencial:

Diferencia = Cantidad Nueva - Cantidad Anterior

• Si Diferencia > 0 (Aumento de cantidad): Se descuentan únicamente las unidades adicionales del almacén.
• Si Diferencia < 0 (Disminución de cantidad): Se devuelven las unidades sobrantes al stock físico disponible.
• Si Diferencia = 0 (Misma cantidad): No se realiza ningún movimiento de inventario, actualizándose solo precios o descripciones.
• Línea eliminada: Se restituye al almacén la totalidad de la cantidad que había salido previamente.
• Línea nueva: Se descuenta del almacén la cantidad indicada para la nueva línea.

---

3. Validación de Seguridad

Si una petición de actualización incluye una línea con un valor de id que no pertenece al documento que se está modificando o que no existe:

• La petición se detiene de inmediato y devuelve un error 400 Bad Request:

  {
    "isSuccess": false,
    "error": "Las siguientes líneas no existen en este documento: 9942"
  }

• Esto previene colisiones accidentales de identificadores y modificaciones cruzadas entre documentos de distintos clientes.

---

4. Reordenación y Posicionamiento

El orden en el que se envían las líneas dentro del array de la petición PUT establece la ordenación definitiva del documento:

• Se recalculan correlativamente las posiciones de línea (position) respetando la secuencia enviada por la aplicación externa.
• Permite reorganizar capítulos, partidas o intercalar líneas explicativas sin necesidad de llamadas adicionales.

---

5. Ejemplo Práctico de Actualización

Supongamos un albarán de entrega (PUT /salesdocuments/01/0000000120) con dos líneas registradas:

• Línea id: 101: 10 unidades de cable ("CBL-001-AZ").
• Línea id: 102: 2 unidades de interruptor ("PIA-16A-1P").

El cliente decide añadir 5 cables más (total 15), retirar los interruptores e incluir una nueva línea de canaleta:

Payload PUT

{
  "series": "01",
  "number": "0000000120",
  "date": "2026-11-09",
  "customerCode": "CLI-00120",
  "updatesStock": true,
  "lines": [
    {
      "id": 101,
      "code": "CBL-001-AZ",
      "quantity": 15,
      "price": 1.55
    },
    {
      "code": "CAN-PVC-01",
      "description": "Canaleta PVC 40x20",
      "quantity": 4,
      "price": 3.20
    }
  ]
}

Acciones del Sistema

✓ Línea 101 (Cable):
  - Se actualiza in-situ conservando el id: 101.
  - La cantidad pasa de 10 a 15.
  - Delta de stock: +5 unidades (solo se descuentan 5 unidades adicionales del almacén).

✓ Línea 102 (Interruptor):
  - No viene en el payload -> Se ELIMINA del albarán.
  - Se reincorporan 2 unidades al stock físico del almacén.

✓ Nueva Línea (Canaleta):
  - Se inserta en el albarán con un nuevo identificador asignado.
  - Se descuentan 4 unidades del stock físico del almacén.

---

6. Modo de Compatibilidad (Legacy)

Para mantener la compatibilidad con integraciones previas que no envíen el campo id:

• Si ninguna de las líneas recibidas en el PUT incluye la propiedad id, el sistema ejecuta la sustitución completa habitual: revierte todo el stock anterior, vacía las líneas e inserta las nuevas.
• Recomendamos a todas las aplicaciones cliente enviar los id de las líneas devueltos en las respuestas de consulta para beneficiarse del ajuste diferencial y evitar bloqueos transitorios de existencias.

---

7. Enlaces Relacionados

• 🌲 Estructura del Documento y Tipos de Línea: Partidas, artículos y jerarquía.
• 🧩 Artículos y Conceptos Genéricos: Uso de referencias libres #GENERAL.
• 🛒 Reconciliación y Reservas en Pedidos de Venta: Gestión de reservas físicas y futuras en pedidos.