Saltar al contenido principal

Gestión de Artículos

El recurso /products permite consultar, crear y actualizar los artículos y materiales simples en el catálogo de BaseGes ERP, así como consultar su stock por almacén.

Seguridad

Requiere autorización mediante cabecera HTTP:

  • X-Api-Key: {tu_clave_api} o Authorization: Bearer {tu_token_jwt}

Resumen de Operaciones​

MétodoEndpointAcciónCuerpo de PeticiónCódigo Éxito
GET/productsListado paginado de artículos con filtrosNinguno200 OK
GET/products/stockListado de artículos con stock por almacénNinguno200 OK
GET/products/{code}/stockDetalle de stock de un artículo concretoNinguno200 OK
GET/products/{code}Consulta detallada de un artículoNinguno200 OK
POST/productsAlta de un nuevo artículoJSON (CreateProductCommand)201 Created
PATCH/products/{reference}Modificación de datos y preciosJSON (UpdateProductCommand)200 OK

1. Alta de un Nuevo Artículo (POST)​

POST /products

Crea una nueva referencia en el maestro de artículos de BaseGes.

Parámetros del Payload JSON​

CampoTipoObligatorioDescripción
referencestringSíCódigo o referencia única del artículo (ej. "CBL-001-AZ").
shortDescriptionstringSíDescripción corta o título principal del artículo.
descriptionstringNoDescripción técnica ampliada o especificaciones.
barcodestringNoCódigo de barras (EAN-13, EAN-128, etc.).
associatedReferencestringNoReferencia del fabricante o proveedor habitual.
familyCodestringNoCódigo de familia (ej. "01").
subfamilyCodestringNoCódigo de subfamilia (ej. "0102").
groupCodestringNoCódigo de grupo de artículos.
taxCodestringNoCódigo de tipo de IVA devengado (ej. "IVA21").
grossPurchasePricenumberNoPrecio bruto de compra de tarifa del proveedor.
purchasePriceDiscountnumberNoDescuento habitual aplicado por el proveedor (%).
marginPercentnumberNoMargen comercial aplicado sobre el coste (%).
salePricenumberNoPrecio de venta base sin impuestos (PVP).
salePriceWithTaxnumberNoPrecio de venta final con IVA incluido.

Ejemplo de Petición POST​

{
  "reference": "CAB-FLEX-3G25",
  "shortDescription": "Cable Manguera Flexible 3G 2.5 mm² Libre de Halógenos",
  "description": "Cable de cobre pulido clase 5 según UNE-EN 60228. Aislamiento poliolefina ignifugada.",
  "barcode": "8435123456789",
  "familyCode": "02",
  "subfamilyCode": "0201",
  "taxCode": "IVA21",
  "grossPurchasePrice": 1.20,
  "purchasePriceDiscount": 15.0,
  "marginPercent": 35.0,
  "salePrice": 1.55,
  "salePriceWithTax": 1.88
}

Respuesta Exitosa (201 Created)​

{
  "reference": "CAB-FLEX-3G25",
  "shortDescription": "Cable Manguera Flexible 3G 2.5 mm² Libre de Halógenos",
  "salePrice": 1.55
}

2. Actualización de Artículo (PATCH)​

PATCH /products/{reference}

Permite modificar campos puntuales del artículo (cambiar precio de venta, actualizar código de barras o reclasificar de familia):

PATCH /products/CAB-FLEX-3G25 HTTP/1.1
Host: localhost:5000
Content-Type: application/json
X-Api-Key: tu-api-key-secreta

{
  "salePrice": 1.65,
  "salePriceWithTax": 2.00,
  "marginPercent": 38.0
}

3. Consulta y Búsqueda de Artículos (GET)​

GET /products

Parámetros de Consulta (Query String)​

ParámetroTipoDescripción
pageintegerNúmero de página (predeterminado 1).
pageSizeintegerArtículos por página (predeterminado 50, máx 100).
ReferencestringFiltro por coincidencia en la referencia.
ShortDescriptionstringFiltro por texto en la descripción corta.
BaracodestringBúsqueda por código de barras o lector láser.
FamilyCodestringFiltrar solo artículos de una familia concreta.
SubfamilyCodestringFiltrar por subfamilia.
GroupCodestringFiltrar por grupo de artículos.
searchstringBúsqueda parcial en referencia/código (Id / tArticulos1), descripción corta (ShortDescription / tArticulos2) y código de barras (Barcode / tArticulos7).
GET /products?FamilyCode=02&search=Flexible&page=1&pageSize=20 HTTP/1.1
Host: localhost:5000
X-Api-Key: tu-api-key-secreta

4. Listado de Stock por Almacén (GET)​

GET /products/stock

Devuelve una lista paginada de artículos con su stock actual (físico), reservado, futuro y disponible.

Parámetros de Consulta (Query String)​

ParámetroTipoDescripción
pageintegerNúmero de página (predeterminado 1).
pageSizeintegerArtículos por página (predeterminado 50, máx 100).
codestringBúsqueda parcial por código o referencia del artículo.
descriptionstringBúsqueda parcial por descripción corta o descripción completa.
warehouseCodestringCódigo de almacén para filtrar el stock (opcional).

Comportamiento según Configuración de Empresa​

  • Con control de stock por almacén (StockByWarehouse = true): Desglosa las existencias por cada almacén en la propiedad stockByWarehouse. Si se pasa warehouseCode, filtra únicamente para dicho almacén.
  • Sin control de stock por almacén (StockByWarehouse = false): Devuelve el stock global del artículo registrado en el maestro de artículos, asignándolo al almacén predeterminado o global.
GET /products/stock?code=CAB&warehouseCode=01&page=1&pageSize=20 HTTP/1.1
Host: localhost:5000
X-Api-Key: tu-api-key-secreta

Ejemplo de Respuesta (200 OK)​

{
  "items": [
    {
      "reference": "CAB-FLEX-3G25",
      "shortDescription": "Cable Manguera Flexible 3G 2.5 mm² Libre de Halógenos",
      "barcode": "8435123456789",
      "totalStock": 150.0,
      "totalReserved": 20.0,
      "totalFuture": 50.0,
      "totalAvailable": 130.0,
      "stockByWarehouse": [
        {
          "warehouseCode": "01",
          "location": "A-01",
          "stock": 100.0,
          "reserved": 10.0,
          "future": 50.0,
          "available": 90.0
        },
        {
          "warehouseCode": "02",
          "location": "B-03",
          "stock": 50.0,
          "reserved": 10.0,
          "future": 0.0,
          "available": 40.0
        }
      ]
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20,
  "isStockByWarehouse": true
}

5. Detalle de Stock de un Artículo Concreto (GET)​

GET /products/{code}/stock

Devuelve la información detallada de stock de un artículo específico en todos los almacenes o en un almacén concreto.

Parámetros​

ParámetroUbicaciónTipoDescripción
codeRutastringCódigo o referencia única del artículo.
warehouseCodeQuerystringCódigo de almacén para filtrar el stock (opcional).
GET /products/CAB-FLEX-3G25/stock?warehouseCode=01 HTTP/1.1
Host: localhost:5000
X-Api-Key: tu-api-key-secreta

Ejemplo de Respuesta (200 OK)​

{
  "reference": "CAB-FLEX-3G25",
  "shortDescription": "Cable Manguera Flexible 3G 2.5 mm² Libre de Halógenos",
  "description": "Cable de cobre pulido clase 5 según UNE-EN 60228.",
  "barcode": "8435123456789",
  "isStockByWarehouse": true,
  "totalStock": 100.0,
  "totalReserved": 10.0,
  "totalFuture": 50.0,
  "totalAvailable": 90.0,
  "warehouses": [
    {
      "warehouseCode": "01",
      "location": "A-01",
      "stock": 100.0,
      "reserved": 10.0,
      "future": 50.0,
      "available": 90.0
    }
  ]
}