Categorías

Las categorías permiten organizar los productos del catálogo de forma jerárquica. Puedes obtenerlas como lista plana o como árbol anidado.

Listar categorías

GET /api/v1/categories

Retorna las categorías de la tienda. Si se envía el parámetro tree=true, la respuesta es un árbol jerárquico anidado.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`tree`	boolean	No	Si es `true`, retorna el árbol completo de categorías (ignora paginación)
`parentId`	UUID	No	Filtra por categoría padre. Por defecto retorna categorías raíz (`null`)
`page`	number	No	Número de página (default: `1`)
`limit`	number	No	Resultados por página (default: `50`)

Ejemplo — lista plana

GET /api/v1/categories?page=1&limit=20
x-api-token: sk_live_abc123

Respuesta 200 OK:

{
  "categories": [
    {
      "id": "uuid",
      "parentId": null,
      "order": 0,
      "name": "Ropa",
      "slug": "ropa",
      "description": null,
      "imageId": null,
      "metadata": null,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 20
}

Ejemplo — árbol jerárquico

GET /api/v1/categories?tree=true
x-api-token: sk_live_abc123

Respuesta 200 OK:

[
  {
    "id": "uuid",
    "name": "Ropa",
    "slug": "ropa",
    "children": [
      {
        "id": "uuid",
        "name": "Poleras",
        "slug": "poleras",
        "children": []
      },
      {
        "id": "uuid",
        "name": "Pantalones",
        "slug": "pantalones",
        "children": []
      }
    ]
  }
]

Obtener categoría por slug

GET /api/v1/categories/:slug

Retorna el detalle de una categoría, incluyendo su categoría padre y sus hijos directos.

Parámetros de ruta

Parámetro	Tipo	Descripción
`slug`	string	Slug único de la categoría

Ejemplo

GET /api/v1/categories/ropa
x-api-token: sk_live_abc123

Respuesta `200 OK`

{
  "id": "uuid",
  "parentId": null,
  "order": 0,
  "name": "Ropa",
  "slug": "ropa",
  "description": "Toda nuestra línea de vestuario",
  "imageId": null,
  "metadata": null,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z",
  "parent": null,
  "children": [
    { "id": "uuid", "name": "Poleras", "slug": "poleras" },
    { "id": "uuid", "name": "Pantalones", "slug": "pantalones" }
  ]
}

Errores

Código	Descripción
`404`	La categoría con ese slug no existe en la tienda