Saltar al contenido principal

Resolución de Precios, Descuentos y Costes en Documentos

Este documento describe el proceso de negocio estándar mediante el cual la API de BaseGes ERP resuelve los precios de venta, los porcentajes de descuento y los costes unitarios al crear o actualizar líneas de documentos comerciales y operativos.

Proceso Transversal Unificado

Este comportamiento de negocio es común y aplica de forma idéntica a todos los documentos con líneas de venta o consumo de materiales en la API:

  • Presupuestos Técnicos (/budgets)
  • Pedidos de Venta (/orders)
  • Documentos de Venta (/salesdocuments - Albaranes y Facturas)
  • Órdenes de Trabajo y Mantenimiento GMAO (/workorders)

1. Principio de Diseño: Valores Explícitos vs. Omisión (null)​

La API sigue una política estricta de no intrusión:

  1. Si la aplicación cliente (un CRM externo, una app móvil de técnicos, un e-commerce o un integrador) conoce y envía un precio, descuento o coste explícito, la API lo respeta fielmente.
  2. Si el cliente de la API envía null (o no incluye la propiedad en el payload JSON), la API activa automáticamente el motor de precios (Pricing Engine) de BaseGes ERP para resolver el valor exacto según las reglas maestras de tarifas, ofertas y valoración de stock.

No es necesario configurar ningún flag o parámetro adicional en la cabecera ni en el comando; la presencia o ausencia de valor en cada campo determina el comportamiento.

Campo en LineDtoSi se proporciona un valor numérico (ej. 120.00)Si se envía null o se omiteFallback (si no hay regla en ERP)
price (Precio)Se respeta el precio unitario recibido.Se consulta el Motor de Precios para el cliente/proyecto.Precio de venta catálogo (SalePrice / PVP).
discount (Descuento %)Se aplica el % recibido (ej. 10.0 para un 10%).Se aplica el % de descuento obtenido del motor de tarifas/ofertas.0.0% (sin descuento).
cost (Coste unitario)Se respeta el coste recibido.Se obtiene el coste unitario del ERP según el criterio de valoración de empresa (PUC o PMP).Precio de compra del catálogo (PurchasePrice).

2. Flujo de Decisión de una Línea​

Cuando la API procesa una línea de producto en un documento, evalúa secuencialmente tres decisiones clave:

1. Resolución de Precio (price)
  • ¿Se envía un precio numérico en el payload?
    • SÍ: Se respeta fielmente el precio unitario manual recibido.
    • NO (null o no incluido): Se consulta el Motor de Precios para el cliente/obra. Si existe tarifa u oferta activa, se aplica su precio base; si no existe regla, se aplica el PVP del catálogo.
2. Resolución de Descuento (discount)
  • ¿Se envía un porcentaje de descuento en el payload?
    • SÍ: Se respeta el descuento manual recibido (ej. 10.0 para un 10%).
    • NO (null o no incluido): Se aplica el porcentaje de descuento comercial obtenido del motor de tarifas/ofertas del cliente por familia o grupo; si no hay descuento aplicable, se asigna 0%.
3. Resolución de Coste Unitario (cost)
  • ¿Se envía un coste numérico en el payload?
    • SÍ: Se respeta el coste manual suministrado.
    • NO (null o no incluido): Se obtiene el coste unitario del ERP según el criterio de valoración de la empresa (PUC - Precio Última Compra o PMP - Precio Medio Ponderado); si no hay histórico de compras, se toma el precio de coste base del catálogo.
Cálculo Automático de la Línea

Con los tres valores resueltos (price, discount, cost), la API calcula automáticamente:

  • Importe Neto: Cantidad * Precio * (1 - Descuento / 100)
  • Coste Total: Cantidad * Coste
  • Margen Bruto: Importe Neto - Coste Total

3. Jerarquía del Motor de Tarifas y Descuentos (Pricing Engine)​

Cuando price o discount no se especifican, el motor de precios de BaseGes ERP evalúa las condiciones comerciales en el siguiente orden de precedencia:

  1. Excepciones de Cliente: Condiciones de precio neto o descuento pactadas específicamente para ese cliente y artículo concreto.
  2. Descuentos Comerciales: Descuentos asignados al cliente por Familia, Subfamilia o Grupo de artículos.
  3. Ofertas Comerciales: Precios especiales y promociones por volumen con vigencia de fechas activas.
  4. Tarifas de Venta: Tarifa asignada a la ficha del cliente o indicada a nivel de documento/obra.
  5. Catálogo Base (PVP): Si el artículo no encaja en ninguna tarifa u oferta, se utiliza su PVP estándar con descuento 0%.

4. Determinación del Coste Unitario (PUC vs. PMP)​

Para calcular la rentabilidad real de las líneas del documento, el coste unitario se determina respetando el criterio de valoración configurado en la empresa:

  • Si la empresa valora por Última Compra: La API prioriza el PUC (Precio Última Compra) registrado en el histórico de compras del artículo.
  • Si la empresa valora por Precio Medio: La API prioriza el PMP (Precio Medio Ponderado) de existencias en almacén.
  • Fallback a Ficha: Si el artículo carece de movimientos o el valor resultante es 0, se utiliza el precio de coste base de la ficha del catálogo.
Consistencia en Márgenes

Al delegar el coste a la API enviando cost: null, se asegura que el margen comercial refleje con total fidelidad la rentabilidad real configurada en BaseGes ERP, sin discrepancias entre departamentos técnicos y contables.

5. Optimización por Lotes (Batch Pre-Calculation)​

Para garantizar un rendimiento óptimo y evitar tiempos de respuesta lentos en documentos extensos:

  1. Al recibir la petición (POST o PUT), se recopilan todas las referencias de artículos presentes en las líneas del documento.
  2. Se resuelve en una única operación interna de cálculo masivo todo el conjunto de precios, condiciones y costes.
  3. Cada línea del documento se procesa instantáneamente en memoria con sus valores exactos.

6. Ejemplos Prácticos de Petición​

Ejemplo 1: Delegación Total al ERP (Recomendado)​

El cliente omite precios, descuentos y costes. El ERP calcula todos los importes automáticamente:

{
  "series": "01",
  "customerCode": "CLI00120",
  "projectCode": "OBRA-2026",
  "lines": [
    {
      "type": "Product",
      "code": "CAB-FLEX-3G25",
      "quantity": 100,
      "price": null,
      "discount": null,
      "cost": null,
      "taxCode": "IVA21"
    }
  ]
}
  • Resultado: La línea se generará con el precio de tarifa del cliente CLI00120, su descuento pactado de familia, y el coste según PUC/PMP de la empresa.

Ejemplo 2: Precio Manual Cerrado con Coste Automático​

Se acuerda un precio especial cerrado para una línea, pero se desea que el coste lo determine el ERP:

{
  "series": "01",
  "customerCode": "CLI00120",
  "lines": [
    {
      "type": "Product",
      "code": "CAB-FLEX-3G25",
      "quantity": 50,
      "price": 1.25,
      "discount": 0.0,
      "cost": null,
      "taxCode": "IVA21"
    }
  ]
}
  • Resultado: Se respeta el precio de venta unitario de 1.25 € y descuento 0%. El coste de la línea y el margen se calculan automáticamente con el PUC/PMP del ERP.