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

En la API de BaseGes ERP, la actualización de un pedido mediante PUT /api/orders/{number} utiliza un mecanismo de reconciliación inteligente de líneas.

Este sistema evita la eliminación y reinserción masiva de líneas, preservando la identidad de cada registro, protegiendo las reservas de inventario y manteniendo la coherencia de las cantidades pendientes de servir.

¿Por qué es fundamental la reconciliación?

En integraciones con tiendas online (B2B/B2C), plataformas logísticas y sistemas externos, borrar y recrear líneas en cada actualización causa tres problemas críticos:

1. Pérdida de identidad: Los identificadores únicos de las líneas cambian en cada guardado, rompiendo la trazabilidad externa.
2. Alteración destructiva de reservas: Liberar todo el stock reservado para volver a solicitarlo puede hacer que otro proceso consuma el stock disponible, provocando que el pedido pierda su reserva confirmada.
3. Pérdida de estados parciales: Si un pedido ya tiene entregas parciales asociadas, destruir las líneas provocaría inconsistencias graves en las cantidades pendientes.

---

1. El Identificador de Línea (id)

Cada elemento del array lines dispone de una propiedad opcional id (int):

Escenario	Uso del campo id	Comportamiento del Sistema
Alta (POST /api/orders)	Omitido o null	El sistema crea las líneas y devuelve el pedido con un id único asignado a cada línea.
Modificación (PUT /api/orders/{number})	Informado con el id original	El sistema actualiza los datos de esa línea concreta conservando su mismo identificador.
Nueva línea en PUT	Omitido, null o 0	El sistema detecta que es una línea añadida y le asigna un nuevo id.
Línea no incluida en PUT	No enviada en el array	El sistema detecta que la línea ha sido descartada y la elimina del pedido.

---

2. Diagrama de Flujo de Reconciliación

                        ┌─────────────────────────────────┐
                        │  Línea recibida en el PUT       │
                        └────────────────┬────────────────┘
                                         │
                          ¿Dispone de 'id' válido?
                                        / \
                                       /   \
                                  SÍ  /     \  NO (o null / 0)
                                     /       \
                                    ▼         ▼
                     ¿El 'id' existe en el pedido?  [ ALTA ]
                                    / \             Nueva línea añadida;
                               SÍ  /   \  NO        se le asigna un nuevo 'id'
                                  /     \
                                 ▼       ▼
                          [ ACTUALIZACIÓN ]     [ ERROR 400 ]
                          Modificación in-situ  Id ajeno o desconocido;
                          de la línea existente se rechaza la petición

Reglas de Validación de Seguridad:

• Si se envía un id que no pertenece al pedido que se está editando (o que no existe en el sistema), la petición se rechaza inmediatamente con código 400 Bad Request.
• Esto garantiza que ninguna integración pueda modificar o transferir líneas entre diferentes pedidos por error.

---

3. Comportamiento de las Reservas de Stock

Cuando el ERP tiene activado el control de reservas, la reconciliación actúa de forma selectiva y no destructiva:

Estado de la Línea en el PUT	Impacto en la Reserva de Stock
Línea sin cambios de cantidad	Sin impacto. Conserva exactamente su stockReserved (reserva física) y stockReservedFuture (reserva futura) sin reevaluación.
Línea con cambio de cantidad	1. Se libera la reserva previa de esa línea concreta. 2. Se calcula la nueva reserva para la nueva cantidad según la disponibilidad actual del almacén. 3. Se actualizan los campos stockReserved y stockReservedFuture de la línea.
Nueva línea añadida	Solicita la reserva de las unidades requeridas (reserva física hasta el stock disponible, resto a futura).
Línea eliminada	Libera inmediatamente las unidades de reserva actual y futura que retenía, devolviéndolas al stock libre del almacén.

Ventaja Competitiva

Un cliente que modifica una observación o añade un nuevo artículo a su pedido existente no pierde la prioridad ni la reserva física de los artículos que ya tenía confirmados previamente.

---

4. Reordenación de Líneas

El orden en el que se envían las líneas dentro de la propiedad lines en el PUT define la secuencia y posición visual de las líneas en el documento final:

• El sistema reenumera automáticamente el número de orden de cada línea según su posición en la matriz enviada.
• Permite reordenar artículos existentes o intercalar textos explicativos entre líneas simplemente cambiando el orden en el payload JSON.

---

5. Ejemplo Práctico de Reconciliación

Situación Inicial:

Consultamos un pedido existente (GET /api/orders/0000000042):

• Línea id: 501: Artículo "BOMB-SUM-01", cantidad: 2, stockReserved: 2.
• Línea id: 502: Artículo "TUB-PVC-50", cantidad: 10, stockReserved: 10.

Objetivo de la Modificación:

1. Mantener la línea 501 aumentando su cantidad de 2 a 3.
2. Eliminar la línea 502 (el cliente cancela el tubo).
3. Añadir una nueva línea de producto ("VALV-RET-01" con 1 unidad).

Petición PUT

{
  "customerCode": "43000001",
  "date": "2026-11-09",
  "status": 2,
  "paymentMethod": "00000001",
  "lines": [
    {
      "id": 501,
      "code": "BOMB-SUM-01",
      "quantity": 3,
      "price": 320.00
    },
    {
      "code": "VALV-RET-01",
      "quantity": 1,
      "price": 45.00
    }
  ]
}

Efecto Aplicado

✓ Línea 501:
  - Mantiene el id: 501.
  - Actualiza la cantidad a 3.
  - Ajusta la reserva: si hay stock, pasa a stockReserved: 3.

✓ Línea 502:
  - Al no incluirse en el array, se ELIMINA del pedido.
  - Su reserva de 10 unidades se LIBERA inmediatamente al stock disponible del almacén.

✓ Nueva Línea:
  - Se da de alta en el pedido y el sistema le asigna un nuevo identificador (ej. id: 503).
  - Reserva 1 unidad de stock físico o futuro.

---

6. Modo de Compatibilidad Retroactiva (Legacy)

Si una integración existente envía la petición PUT sin incluir el campo id en ninguna de las líneas:

• El sistema activa automáticamente el modo legacy de sustitución íntegra.
• Libera todas las reservas previas del pedido, borra las líneas existentes e inserta las nuevas generando nuevos identificadores.
• Esto garantiza que las integraciones ya existentes sigan funcionando sin requerir adaptaciones inmediatas, aunque se recomienda migrar al modelo con id para optimizar el rendimiento y la trazabilidad.

---

7. Enlaces Relacionados

• 🌲 Estructura del Pedido y Líneas de Detalle: Jerarquía de partidas, unidades de obra y deducción de tipos.
• 📦 Reserva de Stock y Gestión de Inventario: Reglas de asignación de existencias físicas y reservas futuras.
• 📝 Reconciliación en Documentos de Venta (Albaranes): Conciliación con ajuste diferencial de stock.