Products

Gestión de Productos

Los endpoints de productos permiten crear, consultar, actualizar y eliminar productos del inventario (módulo Store).

Convención de nombres

Los campos JSON usan camelCase (imageUrl, costCents, categoryIds, minStockThreshold, maxStockThreshold, priceCents). El campo SKU va en mayúsculas tal cual.

GET /products

Obtiene todos los productos.

Authorization: products_read

cURL Example:

curl -X GET http://127.0.0.1:9154/products \
  -H "Cookie: accessToken=$ACCESS_TOKEN" \
  -H "Cookie: refreshToken=$REFRESH_TOKEN"

Response Body (Éxito - 200 OK):

[
  {
    "id": "b5a6...",
    "SKU": "SKU-0001",
    "name": "Café americano",
    "description": "Taza de café 240ml",
    "imageUrl": null,
    "costCents": 5000,
    "categoryIds": ["9f5c..."],
    "quantity": 10,
    "minStockThreshold": 5,
    "maxStockThreshold": 100,
    "priceCents": 25000
  }
]

Response Body (Lista vacía - 200 OK):

"No products found"

GET /products/{id}

Obtiene un producto por su ID.

Authorization: products_read

Path Parameters:

• id (string).

cURL Example:

curl -X GET http://127.0.0.1:9154/products/b5a6... \
  -H "Cookie: accessToken=$ACCESS_TOKEN" \
  -H "Cookie: refreshToken=$REFRESH_TOKEN"

Response Body (No encontrado - 404 Not Found):

"Product not found"

POST /products

Crea un nuevo producto.

Authorization: products_create

Request Body:

{
  "SKU": "SKU-0001",
  "name": "Café americano",
  "description": "Taza de café 240ml",
  "imageUrl": null,
  "costCents": 5000,
  "categoryIds": ["9f5c..."],
  "quantity": 10,
  "minStockThreshold": 5,
  "maxStockThreshold": 100,
  "priceCents": 25000
}

cURL Example:

curl -X POST http://127.0.0.1:9154/products \
  -H 'Content-Type: application/json' \
  -H "Cookie: accessToken=$ACCESS_TOKEN" \
  -d '{
    "SKU": "SKU-0001",
    "name": "Café americano",
    "costCents": 5000,
    "categoryIds": ["9f5c..."],
    "quantity": 10,
    "minStockThreshold": 5,
    "maxStockThreshold": 100,
    "priceCents": 25000
  }'

Response Body (Éxito - 201 Created):

{
  "id": "b5a6...",
  "message": "Product added successfully"
}

Response Body (Datos inválidos - 400 Bad Request):

{
  "message": "Invalid product data"
}

Response Body (SKU duplicado - 409 Conflict):

{
  "message": "SKU already exists"
}

PUT /products/{id}

Actualiza un producto existente.

Authorization: products_update

Path Parameters:

• id (string).

Request Body: igual al de creación, con los campos actualizados.

Response Body (Éxito - 200 OK):

{
  "id": "b5a6...",
  "message": "Product updated successfully"
}

Response Body (No encontrado - 404 Not Found):

{
  "message": "Product with ID b5a6... not found"
}

Response Body (SKU duplicado - 409 Conflict):

{
  "message": "SKU already exists"
}

POST /products/stock

Ajusta el stock de uno o más productos. quantity puede ser negativo para decrementar.

Authorization: orders_create

Request Body:

[
  { "productId": "b5a6...", "quantity": 10 },
  { "productId": "c7d8...", "quantity": -3 }
]

cURL Example:

curl -X POST http://127.0.0.1:9154/products/stock \
  -H 'Content-Type: application/json' \
  -H "Cookie: accessToken=$ACCESS_TOKEN" \
  -d '[{ "productId": "b5a6...", "quantity": 10 }]'

Response Body (Éxito - 200 OK):

{
  "message": "Stock adjusted successfully"
}

Response Body (Stock insuficiente - 400 Bad Request):

"Invalid or insufficient stock"

DELETE /products/{id}

Elimina (borrado lógico) un producto.

Authorization: products_delete

Path Parameters:

• id (string).

Response: 204 No Content (sin cuerpo).

Notas

Modelo de producto

Campos requeridos: name, costCents, priceCents, quantity, minStockThreshold, maxStockThreshold. Opcionales: SKU, description, imageUrl. categoryIds es un array de UUIDs (puede estar vacío). En esta versión no existen variantes de producto ni bundles.

consejo

• costCents y priceCents se expresan en centavos.
• El borrado es lógico (is_deleted = 1).