Categories

Category management endpoints for organizing products

Get All Categories

GET /api/categories

Retrieves all product categories. Supports hierarchical or flat structure.

Query Parameters

flat · boolean · default: "false"

If set to true, returns categories in a flat list. Otherwise, returns hierarchical structure with parent-child relationships.

Response

success · boolean · required

Indicates if the request was successful

data · array · required

Array of category objects

id · number

Category ID

nombre · string

Category name

padreId · number

Parent category ID (null for top-level categories)

subcategorias · array

Child categories (only in hierarchical mode)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "nombre": "Hardware",
      "padreId": null,
      "subcategorias": [
        {
          "id": 2,
          "nombre": "Graphics Cards",
          "padreId": 1,
          "subcategorias": []
        },
        {
          "id": 3,
          "nombre": "Processors",
          "padreId": 1,
          "subcategorias": []
        }
      ]
    },
    {
      "id": 4,
      "nombre": "Peripherals",
      "padreId": null,
      "subcategorias": []
    }
  ]
}

---

Get Category by ID

GET /api/categories/:id

Retrieves a specific category by its ID.

Path Parameters

id · number · required

The unique identifier of the category

Response

success · boolean · required

Indicates if the request was successful

data · object

Category object

id · number

Category ID

nombre · string

Category name

padreId · number

Parent category ID

{
  "success": true,
  "data": {
    "id": 2,
    "nombre": "Graphics Cards",
    "padreId": 1
  }
}

Error Responses

{
  "success": false,
  "error": "Categoría no encontrada"
}

---

Create Category

POST /api/categories

Creates a new product category.

Authentication

Note: This endpoint requires appropriate permissions to create categories.

Request Body

nombre · string · required

Name of the category

padreId · number

Parent category ID (optional, omit for top-level categories)

{
  "nombre": "Motherboards",
  "padreId": 1
}

Response

success · boolean · required

Indicates if the request was successful

data · object

Created category object

id · number

Category ID

nombre · string

Category name

padreId · number

Parent category ID

{
  "success": true,
  "data": {
    "id": 5,
    "nombre": "Motherboards",
    "padreId": 1
  }
}

Error Responses

{
  "success": false,
  "error": "Nombre requerido"
}

---

Delete Category

DELETE /api/categories/:id

Deletes a category. Categories with associated products or subcategories cannot be deleted.

Authentication

Note: This endpoint requires appropriate permissions to delete categories.

Path Parameters

id · number · required

The unique identifier of the category to delete

Response

success · boolean · required

Indicates if the request was successful

message · string

Success message

error · string

Error message if deletion failed (e.g., category has products or subcategories)

{
  "success": true,
  "message": "Categoría eliminada"
}

Error Responses

{
  "success": false,
  "error": "Cannot delete category with existing products"
}