Marcas

CRUD sobre las marcas (brands) que pueden asociarse a tus productos. Cada marca lleva su propio contenido localizado y multimedia para alimentar una página de marca en tu sitio público.

El objeto Brand

{
  "id":         "65b1a1b234567890abcdef00",
  "name":       "Polaroid",
  "slug":       "polaroid",
  "website":    "https://polaroid.com",
  "is_active":  true,
  "product_count": 42,
  "logo_url":   "https://cdn.fi-nova.com/…/polaroid-logo.png",
  "logo": {
    "asset_id":     "65e0a1b234567890abcdef11",
    "url":          "https://cdn.fi-nova.com/…/polaroid-logo.png",
    "name":         "Logo Polaroid",
    "content_type": "image/png"
  },
  "seo": {
    "seo_title":               "Polaroid — armazones premium",
    "seo_title_translations":  { "es": "Polaroid — armazones premium", "en": "Polaroid — premium frames" },
    "meta_description":              "Conoce el catálogo Polaroid en Óptica XYZ.",
    "meta_description_translations": { "es": "Conoce…", "en": "Discover…" },
    "meta_keywords":              "polaroid, armazones, premium",
    "meta_keywords_translations": { "es": "polaroid, premium", "en": "polaroid, premium" },
    "short_description":              "Resumen corto de la marca.",
    "short_description_translations": { "es": "Resumen corto…", "en": "Short blurb…" },
    "description":              "<p>Historia y catálogo de la marca…</p>",
    "description_translations": { "es": "<p>…</p>", "en": "<p>…</p>" },
    "og_title":               "Polaroid",
    "og_title_translations":  { "es": "Polaroid", "en": "Polaroid" },
    "og_description":              "Compártelo en redes.",
    "og_description_translations": { "es": "Compártelo…", "en": "Share it…" },
    "indexable": true,
    "og_image":  { "url": "https://cdn.fi-nova.com/…/polaroid-og.jpg", "alt_translations": {} },
    "banner":    { "url": "https://cdn.fi-nova.com/…/polaroid-banner.jpg" },
    "video":     {},
    "gallery":   [],
    "og_image_url": "https://cdn.fi-nova.com/…/polaroid-og.jpg",
    "banner_url":   "https://cdn.fi-nova.com/…/polaroid-banner.jpg",
    "gallery_urls": []
  },
  "fundada": 1937,
  "pais": "Estados Unidos",
  "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 marca.
slug	string	Identificador amigable. Define la URL pública (/marcas/<slug>). Se genera automáticamente del nombre si lo dejas vacío.
website	string	URL oficial de la marca (opcional).
is_active	bool	Si la marca está visible en tu sitio.
product_count	int	Número de productos no eliminados que apuntan a esta marca en tu empresa. En GET /brands se calcula con una sola agregación por página (no una consulta por marca).
logo_url	string | null	URL del logo de la marca (para chips y la cabecera de la página de marca). null si no hay logo.
logo	object | null	Media item completo del logo: { asset_id, url, name, content_type, size_bytes, file_filename, alt_translations }. null si no hay logo.
seo	object	Mismo shape de El objeto SEO de Product.
(campos personalizados)	any	Se devuelven aplanados como claves de primer nivel de la marca (ej. "fundada": 1937), no dentro de un array custom_properties. Se escriben pasando el array custom_properties dentro de data (reemplazo completo; [] los borra). Mismo shape, tipos y reglas de clave reservada que los campos personalizados de Product.
created_at / updated_at	string	ISO 8601 UTC.

Cache denormalizado en productos

Cada Product lleva brand.name y brand.slug espejeados desde el Brand al que apunta vía brand_id. Cuando renombras o re-sluguifies una marca, todos los productos relacionados se re-sincronizan en background.

---

Listar marcas

GET/api/v1/brandsread-brands

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

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

---

Obtener una marca

GET/api/v1/brands/:idread-brands

El segmento :id acepta el id (ObjectId) o el slug de la marca (las marcas no tienen sku). Ver Identificar un recurso.

# Por id o por slug — equivalentes:
curl 'https://developers.fi-nova.com/api/v1/brands/65b1a1b234567890abcdef00' \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'
curl 'https://developers.fi-nova.com/api/v1/brands/polaroid' \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'

---

Crear una marca

POST/api/v1/brandscreate-brands

Campos aceptados en data: name, slug, website, is_active, un objeto anidado seo, el array custom_properties (ver Campos personalizados), y el logo.

Logo. Puedes mandar el logo de dos formas (equivalentes): como logo_url (string con la URL) o como logo (media item { asset_id, url, … }). Mandar logo_url: "" o logo: null borra el logo. La respuesta siempre incluye logo_url (derivado) y logo (el media item completo).

curl -X POST https://developers.fi-nova.com/api/v1/brands \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "name":    "Polaroid",
      "website": "https://polaroid.com",
      "is_active": true,
      "seo": {
        "seo_title_translations": {
          "es": "Polaroid — armazones premium",
          "en": "Polaroid — premium frames"
        },
        "meta_description_translations": {
          "es": "Conoce el catálogo Polaroid en Óptica XYZ.",
          "en": "Discover the Polaroid lineup at XYZ Optics."
        },
        "indexable": true,
        "og_image_url": "https://cdn.fi-nova.com/.../polaroid-og.jpg"
      }
    }
  }'

---

Actualizar una marca

PATCH/api/v1/brands/:idupdate-brands

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

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

---

Eliminar una marca

DELETE/api/v1/brands/:iddelete-brands

Devuelve 204 No Content. Los productos que apuntan a la marca no se borran: simplemente pierden la referencia (brand_id, brand_name, brand_slug quedan 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.