Saltar al contenido principal

Estructura del Pedido y Líneas de Detalle

En la API de BaseGes ERP, las líneas de pedido se organizan siguiendo la estructura unificada de documentos comerciales.

Esto permite gestionar desde pedidos de mostrador extremadamente simples (un único artículo directo) hasta pedidos complejos organizados en partidas, unidades de obra con escandallos técnicos, artículos simples y líneas de texto explicativas.

1. Tipos de Línea Soportados​

El campo opcional type define la naturaleza funcional de cada línea dentro del árbol del pedido:

Tipo (type)Código NuméricoDescripción Funcional
Product0Artículo de catálogo o genérico con cantidad, precio, coste, descuento e IVA.
Workunit1Unidad de obra o conjunto compuesto por materiales, mano de obra o subcontratas.
Text3Línea puramente descriptiva. No requiere código, precios ni cantidades.
Category4Partida o capítulo agrupador que estructura las líneas en fases o secciones.

2. Deducción Automática de Tipos (El campo type es opcional)​

No es necesario indicar explícitamente la propiedad type en cada línea. Si se omite, el sistema aplica un algoritmo inteligente de deducción según el contenido de la línea:

Reglas de Deducción:​

  1. Normalización de líneas sueltas en la raíz:
    Si en la propiedad lines del pedido se envía directamente un listado de artículos o textos (sin partidas), la API crea automáticamente una partida contenedora por defecto ("Partida 1").
  2. Líneas con código (code):
    Si la línea no tiene hijos y contiene un código de referencia (ej. "TUB-PVC-50" o "#GENERAL"), se clasifica automáticamente como Product.
  3. Líneas descriptivas sin código:
    Si la línea solo contiene description sin código ni hijos, se clasifica automáticamente como Text.
  4. Líneas con hijos anidados:
    Si una línea contiene elementos en su array lines, se clasifica como Workunit (si se encuentra dentro de una partida) o como Category (si se encuentra en el nivel raíz).

3. Cómo Entrar Cada Tipo de Línea​

A. Artículos Simples de Catálogo (Product)​

Son artículos dados de alta en el catálogo maestro del ERP.

  • Campos suministrados: Se pueden especificar quantity, price, cost, discount, taxCode y unit.
  • Cálculo automático si se omiten precios o costes:
    Si no se envían price o cost, la API consulta el maestro de tarifas del cliente, aplicando automáticamente la tarifa preferente, los descuentos comerciales por familia y el coste de reposición (PMP o PUC).
  • 👉 Para más detalles, consulta la guía de Resolución de Precios, Tarifas y Costes en Documentos.

B. Artículos Genéricos o Fuera de Catálogo (#GENERAL)​

Para facturar o solicitar productos, portes, servicios extraordinarios o referencias libres que no existen en el catálogo:

  • Se utiliza el código especial "#GENERAL" (o una referencia libre combinada con descripción).
  • Es obligatorio suministrar la description y el price.
  • 👉 Consulta la guía completa de Artículos y Conceptos Genéricos.

C. Líneas de Texto y Comentarios (Text)​

Ideales para incluir especificaciones de entrega, condiciones comerciales especiales, plazos pactados o notas técnicas para almacén.

  • Solo requieren el campo description.
  • No afectan a los totales económicos ni al cálculo de impuestos.

D. Unidades de Obra y Escandallos (Workunit)​

Una unidad de obra representa un elemento compuesto (por ejemplo, una instalación o un conjunto prefabricado). Dispone de dos modalidades de entrada:

Modalidad 1: Desglose Manual​

El integrador define la cabecera de la unidad de obra y envía explícitamente sus componentes dentro del array lines:

{
  "code": "UO-INST-01",
  "description": "Instalación completa de bomba sumergible",
  "quantity": 1,
  "lines": [
    { "code": "BOMB-SUM-01", "description": "Bomba sumergible 1.5CV", "quantity": 1, "price": 320.00 },
    { "code": "MANO-OBRA-OF1", "description": "Horas oficial fontanería", "quantity": 4, "price": 35.00 }
  ]
}

Si la unidad de obra ya está creada y configurada en el catálogo maestro del ERP, solo necesitas enviar su código:

{
  "code": "UO-INST-01",
  "quantity": 2
}

Al detectar que lines está vacío, la API:

  1. Consulta el escandallo registrado para esa unidad de obra en el catálogo.
  2. Recupera todos sus componentes (materiales, mano de obra, etc.) con sus rendimientos y costes.
  3. Genera automáticamente todas las líneas hijas en el pedido de forma proporcional a la cantidad solicitada.

4. Ejemplos Completos de Payload​

Ejemplo: Pedido Estructurado con Partidas, Unidades de Obra y Textos​

{
  "date": "2026-11-06T09:30:00Z",
  "status": 0,
  "customerCode": "CLI-00120",
  "projectCode": "OBRA-2026",
  "orderReference": "REF-EXT-5582",
  "warehouseCode": "001",
  "lines": [
    {
      "type": 4,
      "description": "Capítulo 1: Materiales de Climatización",
      "lines": [
        {
          "code": "CLIM-SPLIT-01",
          "description": "Split inverter bomba de calor 3500W",
          "quantity": 2,
          "price": 450.00,
          "discount": 10.0
        },
        {
          "code": "UO-MONTAJE-CLIM",
          "description": "Unidad de obra: soporte, tubería frigorífica y conexión",
          "quantity": 2
        },
        {
          "description": "Nota técnica: incluye subida a cubierta con grúa pluma."
        }
      ]
    },
    {
      "type": 4,
      "description": "Capítulo 2: Varios",
      "lines": [
        {
          "code": "#GENERAL",
          "description": "Porte especial y descarga paletizada",
          "quantity": 1,
          "price": 60.00
        }
      ]
    }
  ]
}

5. Modificación de Pedidos: PUT vs PATCH​

La API ofrece dos endpoints complementarios para modificar pedidos existentes:

A. Actualización Completa (PUT /api/orders/{number})​

  • Sustitución Total: Sobrescribe toda la cabecera y reemplaza todas las líneas anteriores por las proporcionadas en el nuevo payload.
  • Recálculo íntegro: Recalcula de nuevo precios, costes, bases imponibles e impuestos de todo el árbol.
  • Historial comercial: Actualiza automáticamente la fecha de última venta en la ficha del cliente.

B. Modificación Parcial de Cabecera (PATCH /api/orders/{orderNumber})​

  • Operación Atómica y Rápida: No modifica ni recalcula las líneas de detalle.
  • Permite modificar únicamente campos específicos de la cabecera, como por ejemplo:
    • Fecha del pedido (date).
    • Estado (status: cambiar de Pending a Delivered o Canceled).
    • Estado logístico (logisticsStatus).
    • Prioridad (priority).
    • Referencia del pedido / Su pedido (orderReference).
    • Observaciones (notes).
    • Cambios en la dirección de entrega o datos de contacto sin alterar los importes económicos.
Ejemplo PATCH /api/orders/0000000108
{
  "status": 1,
  "logisticsStatus": 2,
  "notes": "Mercancía empaquetada y lista en muelle 3 para recogida por transporte."
}

6. Enlaces y Documentación Relacionada de Ventas​

El módulo de pedidos comparte modelos y reglas comerciales con el resto de circuitos del ERP: