Products API: CRUD, Barcode Lookup, and Public Catalog

The /productos endpoints manage the hardware store product catalog. They offer three access levels: full CRUD for admins (including cost price and supplier data), read-only lookup for employees (no sensitive pricing), and a public catalog for the storefront. All authenticated endpoints require a JWT Bearer token in the Authorization header.

GET /api/productos

Returns all active products with full admin data, including purchase price and supplier name. Auth: ADMIN

Response `200 OK`

Returns an array of ProductoDTO objects.

Long

Internal product identifier.

sku

string

Unique stock-keeping unit code. Maximum 50 characters.

codigoBarras

string

EAN / barcode string. Maximum 100 characters. May be null if not assigned.

nombre

string

Display name of the product. Maximum 200 characters.

descripcion

string

Long-form product description (plain text). May be null.

precio

BigDecimal

Retail selling price. Precision 12,2. Never negative.

stockActual

Integer

Current units in stock.

stockMinimo

Integer

Minimum stock threshold. Products at or below this value appear in /stock-critico.

activo

boolean

true if the product is active; false if soft-deleted.

imagenUrl

string

URL to the product image. Maximum 500 characters. May be null.

nombreCategoria

string

Display name of the assigned category. May be null.

nombreProveedor

string

Display name of the assigned supplier. Admin-only field. May be null.

The precio field maps to the precio column on the Producto entity. There is no separate precioCompra field in ProductoDTO; supplier cost data is accessed through the nombreProveedor association.

GET /api/productos/{id}

Returns a single product by its internal ID. Auth: ADMIN

Path Parameters

Long

required

Internal product identifier.

Response `200 OK`

Returns a ProductoDTO. See GET /api/productos for field descriptions.

GET /api/productos/sku/{sku}

Looks up a product by its SKU code. Auth: ADMIN

Path Parameters

sku

string

required

The SKU to search. Case-sensitive, unique across the catalog.

Response `200 OK`

Returns a ProductoDTO.

GET /api/productos/barcode/{codigo}

Looks up a product by its barcode or EAN. Auth: ADMIN

Path Parameters

codigo

string

required

The barcode / EAN-13 string to search.

Response `200 OK`

Returns a ProductoDTO.

GET /api/productos/stock-critico

Returns all products whose stockActual is at or below their stockMinimo. Use this endpoint to drive low-stock alerts or reorder workflows. Auth: ADMIN

Response `200 OK`

Returns an array of ProductoDTO. The array is empty when no products are in a critical stock state.

GET /api/productos/publico

Returns the public product catalog. This endpoint requires no authentication and is intended for the Tienda storefront. It omits cost price, supplier data, and internal stock thresholds. Auth: None (public)

Response `200 OK`

Returns an array of ProductoPublicoDTO.

Long

Internal product identifier.

nombre

string

Product display name.

precio

BigDecimal

Retail selling price.

stockActual

Integer

Current units available.

imagenUrl

string

Product image URL. May be null.

nombreCategoria

string

Category display name. May be null.

Because this endpoint is unauthenticated, it is safe to call directly from browser JavaScript or a CDN-cached layer. Only active products (activo = true) are included.

GET /api/productos/empleado

Returns all active products without cost price or supplier data. Designed for POS terminal use where employees need pricing and stock but must not see purchasing cost. Auth: EMPLEADO

Response `200 OK`

Returns an array of ProductoEmpleadoDTO.

Long

Internal product identifier.

sku

string

Unique SKU code.

codigoBarras

string

Barcode / EAN string. May be null.

nombre

string

Product display name.

descripcion

string

Long-form description. May be null.

precio

BigDecimal

Retail selling price. Cost price is intentionally excluded.

stockActual

Integer

Current units in stock.

stockMinimo

Integer

Minimum stock threshold.

imagenUrl

string

Product image URL. May be null.

nombreCategoria

string

Category display name. May be null.

GET /api/productos/empleado/sku/{sku}

Looks up a single product by SKU for an authenticated employee. Auth: EMPLEADO

Path Parameters

sku

string

required

The SKU to search.

Response `200 OK`

Returns a ProductoEmpleadoDTO. See GET /api/productos/empleado for field descriptions.

GET /api/productos/empleado/barcode/{codigo}

Looks up a single product by barcode for an authenticated employee. Useful for scanning workflows at the POS terminal. Auth: EMPLEADO

Path Parameters

codigo

string

required

The barcode / EAN to search.

Response `200 OK`

Returns a ProductoEmpleadoDTO.

POST /api/productos

Creates a new product in the catalog. Auth: ADMIN

Request Body

sku

string

required

Unique SKU code. Maximum 50 characters. Must not already exist in the catalog.

nombre

string

required

Product display name. Maximum 200 characters.

precio

BigDecimal

required

Retail selling price. Must be ≥ 0.00.

codigoBarras

string

Barcode / EAN string. Maximum 100 characters. Optional.

descripcion

string

Long-form product description. Optional.

precioCompra

BigDecimal

Supplier purchase cost. Optional; stored but not exposed to non-admin roles.

stockMinimo

Integer

Minimum stock alert threshold. Defaults to 0 if omitted.

imagenUrl

string

URL of the product image. Optional.

categoriaId

Long

ID of an existing category. Optional.

proveedorId

Long

ID of an existing supplier. Optional.

Response `201 Created`

Returns the newly created ProductoDTO.

curl -X POST http://localhost:8081/api/productos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "FRX-TALADRO-01",
    "nombre": "Taladro Percutor 750W",
    "descripcion": "Taladro percutor profesional con maletín y 15 brocas",
    "codigoBarras": "7790001234567",
    "precio": 84999.99,
    "precioCompra": 52000.00,
    "stockMinimo": 3,
    "categoriaId": 4,
    "proveedorId": 2,
    "imagenUrl": "https://cdn.ferromax.com.ar/productos/taladro-750w.jpg"
  }'

PUT /api/productos/{id}

Updates an existing product. Only the fields included in the request body are changed; omitted fields retain their current values. Auth: ADMIN

Path Parameters

Long

required

Internal product identifier.

Request Body

nombre

string

New display name. Maximum 200 characters.

precio

BigDecimal

New retail selling price. Must be ≥ 0.00 if provided.

stockMinimo

Integer

New minimum stock threshold.

imagenUrl

string

New product image URL. Maximum 500 characters.

codigoBarras

string

New barcode / EAN. Maximum 100 characters.

Response `200 OK`

Returns the updated ProductoDTO.

DELETE /api/productos/{id}

Soft-deletes (deactivates) a product by setting activo = false. The product record and all associated stock movement history are preserved in the database and can be restored by an admin at the database level. Auth: ADMIN

Path Parameters

Long

required

Internal product identifier.

Response `204 No Content`

Empty body. The product no longer appears in any active product listing.

Soft-deleted products remain visible via the /stock-critico endpoint if their stock was below the minimum at the time of deletion. Ensure any open orders referencing the product are resolved before deactivating it.

Overview

Endpoints

Products API: CRUD, Barcode Lookup, and Public Catalog

GET /api/productos

Response `200 OK`

GET /api/productos/{id}

Path Parameters

Response `200 OK`

GET /api/productos/sku/{sku}

Path Parameters

Response `200 OK`

GET /api/productos/barcode/{codigo}

Path Parameters

Response `200 OK`

GET /api/productos/stock-critico

Response `200 OK`

GET /api/productos/publico

Response `200 OK`

GET /api/productos/empleado

Response `200 OK`

GET /api/productos/empleado/sku/{sku}

Path Parameters

Response `200 OK`

GET /api/productos/empleado/barcode/{codigo}

Path Parameters

Response `200 OK`

POST /api/productos

Request Body

Response `201 Created`

PUT /api/productos/{id}

Path Parameters

Request Body

Response `200 OK`

DELETE /api/productos/{id}

Path Parameters

Response `204 No Content`

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/productos

​Response 200 OK

​GET /api/productos/{id}

​Path Parameters

​Response 200 OK

​GET /api/productos/sku/{sku}

​Path Parameters

​Response 200 OK

​GET /api/productos/barcode/{codigo}

​Path Parameters

​Response 200 OK

​GET /api/productos/stock-critico

​Response 200 OK

​GET /api/productos/publico

​Response 200 OK

​GET /api/productos/empleado

​Response 200 OK

​GET /api/productos/empleado/sku/{sku}

​Path Parameters

​Response 200 OK

​GET /api/productos/empleado/barcode/{codigo}

​Path Parameters

​Response 200 OK

​POST /api/productos

​Request Body

​Response 201 Created

​PUT /api/productos/{id}

​Path Parameters

​Request Body

​Response 200 OK

​DELETE /api/productos/{id}

​Path Parameters

​Response 204 No Content

Build docs developers (and LLMs) love

GET /api/productos

Response `200 OK`

GET /api/productos/{id}

Path Parameters

Response `200 OK`

GET /api/productos/sku/{sku}

Path Parameters

Response `200 OK`

GET /api/productos/barcode/{codigo}

Path Parameters

Response `200 OK`

GET /api/productos/stock-critico

Response `200 OK`

GET /api/productos/publico

Response `200 OK`

GET /api/productos/empleado

Response `200 OK`

GET /api/productos/empleado/sku/{sku}

Path Parameters

Response `200 OK`

GET /api/productos/empleado/barcode/{codigo}

Path Parameters

Response `200 OK`

POST /api/productos

Request Body

Response `201 Created`

PUT /api/productos/{id}

Path Parameters

Request Body

Response `200 OK`

DELETE /api/productos/{id}

Path Parameters

Response `204 No Content`