Saltar al contenido principal

Módulo de Pedidos de Venta (/api/orders)

El módulo de Pedidos de Venta permite consultar, crear y actualizar los pedidos de clientes en BaseGes ERP.

Forma parte central del circuito comercial del ERP, conectando la captación de ventas (presupuestos u ofertas comerciales) con la logística (reserva de stock en almacén) y la entrega final (albaranes y facturación).

Sandbox Scalar

Puedes probar todos los endpoints de pedidos en tiempo real con autenticación y ejemplos interactivos desde el Scalar Sandbox o inspeccionar los esquemas OpenAPI en Swagger UI.

1. Operaciones Disponibles​

Verbo HTTPEndpointAcción / Propósito
GET/api/ordersListado paginado de pedidos con filtros por cliente, obra, estado y búsqueda global.
GET/api/orders/{number}Detalle completo de un pedido: datos de cabecera, árbol de líneas, importes y totales.
POST/api/ordersCreación de un nuevo pedido de venta con autonumeración y reserva de stock.
PUT/api/orders/{number}Actualización completa de cabecera y sustitución íntegra de sus líneas.
PATCH/api/orders/{orderNumber}Modificación parcial rápida de la cabecera sin alterar las líneas existentes.

2. El Contador y Número de Pedido (number)​

A diferencia de las facturas o presupuestos que se organizan por series independientes, los pedidos utilizan un número identificativo único de hasta 10 caracteres.

La API ofrece dos modalidades al crear un pedido mediante POST /api/orders:

  • 🔄 Autonumeración Automática (Omisión de number): La API localiza el primer hueco disponible desde 1, formatea a 10 dígitos (ej. "0000000042") y asigna el número sin colisiones.
  • 🏷️ Asignación Manual o Externa (number informado): Si se envía un número (ej. "850"), se normaliza a 10 dígitos ("0000000850"), se comprueba que no exista previamente y se registra con ese identificador exacto.

A. Autonumeración Automática (Recomendada)​

Si se omite la propiedad number o se envía como null o vacía:

  1. La API analiza todos los identificadores numéricos existentes en la empresa.
  2. Localiza el primer hueco disponible (gap detection) comenzando por el entero 1. Por ejemplo, si existen los pedidos 1, 2 y 4, el sistema asignará automáticamente el número 3. Si no existen huecos intermedios, asignará el correlativo siguiente (máximo + 1).
  3. Aplica automáticamente un formato de 10 dígitos rellenando con ceros a la izquierda (por ejemplo, "0000000003").

B. Asignación Manual o Referencia Externa​

Si el integrador o sistema externo necesita forzar un número específico:

  1. La API formatea automáticamente el valor a 10 caracteres con ceros a la izquierda (por ejemplo, si se envía "850", se normalizará como "0000000850").
  2. Se comprueba si ya existe dicho número en el sistema.
  3. Si ya existe, se rechaza la solicitud con código 400 Bad Request: 
    {
      "error": "Bad Request",
      "message": "Ya existe un pedido con el código 0000000850."
    }
  4. Si no existe, el pedido se registra exactamente con el número indicado.

3. Campos de Cabecera y Validación de Cliente​

Campos Principales en POST /api/orders​

CampoTipoRestricciónDescripción
customerCodestringCondicional (Máx 8 car.)Obligatorio si es un "Pedido de un cliente con ficha". Identifica al titular comercial del pedido para aplicar sus condiciones, tarifas y direcciones. Opcional si es un pedido sin ficha.
dateDateTimeRequiredFecha del pedido en formato ISO 8601 (YYYY-MM-DD o YYYY-MM-DDTHH:mm:ss).
statusint o stringRequired, EnumEstado del pedido: Pending (0), Delivered (1) o Canceled (2).
Pedidos de un Cliente con Ficha vs. Sin Ficha

En BaseGes ERP, un pedido de venta admite dos modalidades de cliente:

  1. Pedido de un cliente con ficha (customerCode informado):
    • El cliente debe existir en el maestro de contactos de BaseGes ERP.
    • La API valida automáticamente que el código exista y que el cliente no tenga las ventas bloqueadas por riesgo o morosidad.
    • Se heredan de forma transparente su tarifa de precios preferente, descuentos comerciales por familia, condiciones de pago, NIF y direcciones habituales de entrega y facturación.
  2. Pedido de un cliente sin ficha (customerCode: null u omitido):
    • Corresponde a la opción de BaseGes ERP para ventas esporádicas, clientes de mostrador o compras puntuales sin ficha previa en el catálogo de clientes.
    • En este escenario, customerCode es opcional, debiendo suministrarse el nombre o razón social en customerName (ej. "Cliente Mostrador" o "Particular") y las direcciones deseadas en el payload.

Campos Opcionales de Negocio​

PropiedadTipoLongitud Máx.Resolución Automática si se Omite
customerNamestring50 car.Opcional. Se completa con la razón social registrada en la ficha del cliente.
projectCodestring8 car.Código de obra o proyecto. Asocia los costes y facturación a la obra indicada.
paymentMethodstring20 car.Se hereda de la forma de pago configurada en la ficha del cliente.
warehouseCodestring8 car.Código de almacén asignado al pedido para la reserva de existencias.
orderReferencestring50 car.Referencia externa del cliente o número de su orden de compra ("Su Pedido").
notesstring256 car.Observaciones generales del pedido.
discountdecimal—Porcentaje de descuento comercial global a pie de pedido.
priorityintEnumPrioridad de preparación: Normal (0), Low (1), High (2), Urgent (3).
logisticsStatusintEnumEstado logístico: Pending (0), InPreparation (1), Ready (2), etc.

Resolución Automática de Direcciones y Contacto​

Si no se envían datos de entrega o facturación en el payload:

  • Dirección de entrega: Si se omiten deliveryAddress, deliveryZip, deliveryCity, deliveryState o deliveryCountry, se copian automáticamente de la dirección de entrega habitual de la ficha del cliente.
  • Dirección de facturación: Si no se indican billingAddress, billingZip, etc., se completan con la dirección fiscal registrada del cliente.
  • Datos enviados explícitamente: Si se proporcionan en la petición, se respetan para ese pedido específico sin sobreescribir la ficha maestra del cliente.

4. Consulta y Filtros (GET /api/orders)​

El listado paginado soporta los siguientes parámetros de consulta por querystring:

GET /api/orders?page=1&pageSize=20&customerCode=CLI00120&status=Pending&search=bomba
  • Paginación:
    • page: Número de página (mínimo: 1, por defecto: 1).
    • pageSize: Registros por página (entre 1 y 100, por defecto: 50).
  • Filtros Directos:
    • customerCode: Filtrar por el código exacto de cliente.
    • projectCode: Filtrar por el código exacto de obra o proyecto.
    • status: Filtrar por estado (Pending, Delivered, Canceled).
  • Búsqueda Global Multi-campo (search): Realiza una búsqueda textual parcial combinada en:
    1. Número del pedido.
    2. Referencia externa del cliente (Su Pedido).
    3. Código de cliente.
    4. Nombre o razón social del cliente.
    5. Nombre o descripción de la obra / proyecto.
    6. Observaciones y notas del pedido.

5. Ejemplos de Creación (POST /api/orders)​

{
  "date": "2026-11-06T10:00:00Z",
  "status": 0,
  "customerCode": "CLI-00120",
  "projectCode": "OBRA-2026",
  "orderReference": "PO-CLIENT-981",
  "warehouseCode": "001",
  "notes": "Entregar en horario de mañanas por puerta lateral",
  "lines": [
    {
      "code": "TUB-PVC-50",
      "description": "Tubo PVC presión 50mm x 5m",
      "quantity": 10,
      "price": 14.50,
      "discount": 5.0
    },
    {
      "description": "Línea de observación: incluye accesorios de unión sin cargo."
    }
  ]
}

6. Siguientes Pasos​

  1. 🌲 Estructura del Pedido y Líneas de Detalle: Inserción de artículos de catálogo, artículos genéricos #GENERAL, líneas de texto, unidades de obra autoexpandidas y deducción automática de tipos.
  2. 📦 Reserva de Stock y Gestión de Inventario: Funcionamiento de la reserva física actual, reserva futura, cálculo de cantidades pendientes y configuración multialmacén.
  3. 📝 Documentos de Venta (Albaranes): Circuito de expedición y entrega de pedidos.
  4. 🏷️ Tarifas y Resolución de Precios: Reglas de asignación automática de precios y costes cuando se omiten en el pedido.