Productos

CRUD sobre los productos de tu catálogo (servicios, productos simples, con variantes, compuestos). Todas las requests requieren Authorization: Bearer finova_sk_<secret>.

El objeto Product

{
  "id":                "65a0c0f1234567890abcdef0",
  "name":              "Servicio de página web",
  "slug":              "servicio-pagina-web",
  "sku":               "WEB-001",
  "description":       "Sitio one-page responsive con CMS.",
  "product_type":      "service",
  "is_active":         true,
  "tags":              ["servicio", "web"],
  "category_name":     "Servicios digitales",
  "currency":          "mxn",
  "price_cents":       1500000,
  "inventory_enabled": false,
  "inventory_mode":    "materials",
  "taxable":           true,
  "tax_rate_percent":  16.0,
  "created_at":        "2026-01-15T14:23:11Z",
  "updated_at":        "2026-05-14T09:01:42Z"
}

Campos

Campo	Tipo	Descripción
id	string	ObjectId.
name	string	Nombre comercial.
slug	string	Identificador amigable opcional.
sku	string	SKU principal (para simple / service).
description	string	Descripción libre.
product_type	enum	simple, service, variable, composite.
is_active	bool	Si está visible/comprable.
tags	string[]	Etiquetas libres.
category_name	string	Nombre de la categoría (denormalizado).
currency	string	ISO 4217 lowercase (mxn, usd).
price_cents	integer	Precio en centavos.
inventory_enabled	bool	Si lleva control de inventario.
inventory_mode	enum	materials, self, hybrid.
taxable	bool	Si causa impuesto.
tax_rate_percent	float	Tasa de impuesto (ej. 16.0).
created_at / updated_at	string	ISO 8601 UTC.

---

Listar productos

GET/api/v1/productsread-products

Lista paginada de los productos de tu empresa.

Query params

Param	Default	Detalle
page	1	Página.
limit	25	Items por página (máx 100).

cURL

curl 'https://developers.fi-nova.com/api/v1/products?page=1&limit=25' \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'

JavaScript

const res = await fetch(
  'https://developers.fi-nova.com/api/v1/products?page=1&limit=25',
  { headers: { Authorization: 'Bearer finova_sk_TU_SECRETO' } }
);
const { data, meta } = await res.json();

Ruby

uri = URI('https://developers.fi-nova.com/api/v1/products?page=1&limit=25')
req = Net::HTTP::Get.new(uri, 'Authorization' => 'Bearer finova_sk_TU_SECRETO')
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
JSON.parse(res.body)

---

Obtener un producto

GET/api/v1/products/:idread-products

Devuelve un único producto. Si el id no existe o pertenece a otra empresa, recibes 404 not_found.

---

Crear un producto

POST/api/v1/productscreate-products

Campos aceptados en data

name, slug, sku, description, product_type, is_active, category_name, currency, price_cents, inventory_enabled, inventory_mode, taxable, tax_rate_percent, tags.

Los campos company_id, owner_id se asignan automáticamente a partir de la API key autenticada.

cURL

curl -X POST https://developers.fi-nova.com/api/v1/products \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: prod-import-row-42' \
  -d '{
    "data": {
      "name": "Lentes oftálmicos premium",
      "sku":  "LEN-PREM-001",
      "product_type": "simple",
      "price_cents":  450000,
      "currency":     "mxn",
      "is_active":    true,
      "taxable":      true,
      "tax_rate_percent": 16
    }
  }'

JavaScript

await fetch('https://developers.fi-nova.com/api/v1/products', {
  method: 'POST',
  headers: {
    Authorization:    'Bearer finova_sk_TU_SECRETO',
    'Content-Type':   'application/json',
    'Idempotency-Key': 'prod-import-row-42',
  },
  body: JSON.stringify({
    data: {
      name: 'Lentes oftálmicos premium',
      sku:  'LEN-PREM-001',
      product_type: 'simple',
      price_cents:  450000,
      currency:     'mxn',
      is_active:    true,
      taxable:      true,
      tax_rate_percent: 16,
    },
  }),
});

---

Actualizar un producto

PATCH/api/v1/products/:idupdate-products

Acepta los mismos campos que create. Solo se actualizan los que mandes — los demás quedan intactos.

cURL

curl -X PATCH https://developers.fi-nova.com/api/v1/products/65a0c0f1234567890abcdef0 \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{ "data": { "price_cents": 480000 } }'

---

Eliminar un producto

DELETE/api/v1/products/:iddelete-products

Borra el producto. Devuelve 204 No Content. Los productos relacionados con ventas o movimientos de inventario existentes NO se pueden eliminar — recibirás 422 validation_failed y debes archivarlos desde la UI.

---

Errores específicos

error	Cuándo
validation_failed (422)	El payload no pasa validaciones (precio negativo, SKU duplicado, 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.