Categorías de producto

CRUD sobre las categorías de catálogo (product categories) con las que organizas tus productos. Soportan jerarquía (categoría padre / hijas), un ícono y una imagen para alimentar la navegación y las páginas de categoría de tu sitio público.

Catálogo ≠ Finanzas

Esta es la taxonomía de catálogo de productos. No la confundas con la categoría financiera que verás en category_name dentro de Ingresos y Egresos: esa clasifica el movimiento contable, no el producto. Son taxonomías distintas que coinciden en el nombre del campo por herencia histórica.

El category_name (y el objeto product_category) de un Product sí corresponde a este recurso.

El objeto ProductCategory

{
  "id":            "65c2b2c234567890abcdef22",
  "name":          "Lentes",
  "slug":          "lentes",
  "parent_id":     null,
  "icon":          "visibility",
  "image_url":     "https://cdn.fi-nova.com/…/lentes.jpg",
  "product_count": 42,
  "is_active":     true,
  "position":      1,
  "created_at":    "2026-04-02T11:00:00Z",
  "updated_at":    "2026-05-14T09:01:42Z"
}

Campos

Campo	Tipo	Descripción
id	string	ObjectId.
name	string	Nombre de la categoría.
slug	string	Identificador amigable. Define la URL pública (/categorias/<slug>). Se genera automáticamente del nombre si lo dejas vacío.
parent_id	string | null	id de la categoría padre, o null si es raíz. Permite jerarquías.
icon	string | null	Nombre de un Material Symbol (ej. category, checkroom) para chips/avatares. null si no hay ícono.
image_url	string | null	URL de la imagen de la categoría (hero/landing). null si no hay imagen.
product_count	integer	Número de productos activos que apuntan a esta categoría.
is_active	bool	Si la categoría está visible en tu sitio.
position	integer	Orden de presentación (menor primero).
created_at / updated_at	string	ISO 8601 UTC.

Cache denormalizado en productos

Cada Product lleva category_name y product_category.slug espejeados desde la ProductCategory a la que apunta vía product_category_id. Cuando renombras o re-sluguificas una categoría, todos los productos relacionados se re-sincronizan en background.

---

Listar categorías

GET/api/v1/product-categoriesread-product_categories

Lista paginada de las categorías de tu empresa. Misma paginación que /products — ver guía de paginación.

curl 'https://developers.fi-nova.com/api/v1/product-categories?limit=25' \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'

---

Obtener una categoría

GET/api/v1/product-categories/:idread-product_categories

El segmento :id acepta el id (ObjectId) o el slug de la categoría (no tienen sku). Ver Identificar un recurso.

# Por id o por slug — equivalentes:
curl 'https://developers.fi-nova.com/api/v1/product-categories/65c2b2c234567890abcdef22' \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'
curl 'https://developers.fi-nova.com/api/v1/product-categories/lentes' \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'

---

Crear una categoría

POST/api/v1/product-categoriescreate-product_categories

Campos aceptados en data: name, slug, description, parent_id, icon, is_active, position, tags, y la imagen.

Imagen. Puedes mandar la imagen de dos formas (equivalentes): como image_url (string con la URL) o como image (media item { asset_id, url, … }). Mandar image_url: "" o image: null borra la imagen. La respuesta siempre incluye image_url (derivado).

curl -X POST https://developers.fi-nova.com/api/v1/product-categories \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "name":      "Lentes",
      "icon":      "visibility",
      "is_active": true,
      "position":  1,
      "image_url": "https://cdn.fi-nova.com/.../lentes.jpg"
    }
  }'

---

Actualizar una categoría

PATCH/api/v1/product-categories/:idupdate-product_categories

Acepta los mismos campos que create. Solo se actualizan los que mandes.

curl -X PATCH https://developers.fi-nova.com/api/v1/product-categories/65c2b2c234567890abcdef22 \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{ "data": { "is_active": false } }'

---

Eliminar una categoría

DELETE/api/v1/product-categories/:iddelete-product_categories

Devuelve 204 No Content. Los productos que apuntan a la categoría no se borran: simplemente pierden la referencia (product_category queda en null).

---

Errores específicos

error	Cuándo
validation_failed (422)	El payload no pasa validaciones (nombre vacío, etc.).
not_found (404)	El id no existe o pertenece a otra empresa.
insufficient_scope (403)	La API key no tiene el scope requerido por el endpoint.