Finova · Developers

Appearance

Notas de versión ​

Historial de cambios de la API pública de Finova for Developers. Cada release deja también su huella en las respuestas: todos los endpoints regresan los headers X-Finova-API-Version y X-Finova-API-Released-At, así sabes exactamente contra qué versión está corriendo la API cuando depuras una integración.

Si te interesa saber qué cambios pueden ocurrir sin avisar y cuáles requieren una versión nueva, lee la guía de Versionado.

1.0.04 — 2026-06-22 ​

Filtros de productos (marca/categoría), totales filtrados y conteo de productos por marca. Cambios aditivos — no afecta integraciones existentes.

Productos ​

  • Filtro por marca y categoría en GET /products:
    • brand (alias brand_id) y category (alias product_category_id).
    • Cada uno acepta un solo valor o una lista separada por comas que mezcla ObjectIds y slugs, ej. ?category=comida,bebidas o ?brand=acme,5f....
    • Trae los productos que pertenezcan a cualquiera de los valores listados. Un id/slug desconocido no aporta resultados — el filtro nunca se ignora silenciosamente.
  • ?include_filtered_total=true: agrega filtered_total y filtered_total_pages a meta con el conteo del resultado ya filtrado (por q/search, brand, category). Útil para "Mostrando X de Y" cuando filtras.
    • Distinto de include_total, que cuenta todo el catálogo e ignora los filtros.
    • El conteo está acotado a 10000 (si lo supera, se satura ahí y meta.filtered_total_capped viene en true); con q/search activo el tope es 100.

Marcas ​

  • Las marcas ahora exponen product_count: número de productos no eliminados que apuntan a esa marca en tu empresa. En GET /brands se calcula con una sola agregación por página (no una consulta por marca).

1.0.03 — 2026-06-09 ​

Formularios (Forms) multi-idioma. Cambios aditivos — no afecta integraciones existentes.

Formularios ​

  • Nuevo recurso Formularios: lee la definición de un formulario de Marketing para renderizarlo en tu sitio y envía las respuestas de vuelta.
    • GET /forms y GET /forms/:id (scope read-forms) — :id acepta ObjectId o slug.
    • GET /forms/:form_id/submissions y GET /forms/:form_id/submissions/:id (scope read-forms).
    • POST /forms/:form_id/submissions (scope create-form_submissions) — registra una respuesta; valida contra los campos del formulario y dispara las post-acciones (lead/cliente, email, notificación) en background.
  • Multi-idioma: el formulario declara locales + default_locale. Pasa ?locale= en los GET para recibir title/description y label/placeholder/options de cada campo ya resueltos en ese idioma; además siempre vienen los mapas *_translations con todos los idiomas. En POST de respuestas, data.locale (o ?locale=) guarda el idioma usado y determina, entre otras cosas, qué plantilla de email se envía.

1.0.02 — 2026-06-07 ​

Productos multi-moneda. ⚠️ Cambio incompatible (breaking change). Un producto ya no está atado a una sola moneda: ahora tiene un precio por divisa.

Productos ​

  • Eliminados los campos escalares currency y price_cents del objeto product, de cada variant, y extra_price_cents de cada component.
  • Nuevos campos de precio como mapa multi-moneda { <iso4217_lowercase>: <centavos> }:
    • product.prices_cents — ej. { "mxn": 450000, "usd": 25000 }.
    • variant.prices_cents — vacío cuando la variante hereda el precio del producto.
    • component.extra_prices_cents — ajuste de precio del componente por divisa.
  • En la escritura (POST/PATCH) se aceptan prices_cents / extra_prices_cents (objeto divisa→centavos) y ya no se aceptan los currency / price_cents / extra_price_cents escalares.
  • Cada producto debe tener al menos una divisa con precio.
  • extra_price_cents de los valores de opción (option_types[].values[]) se mantiene escalar (sin cambio).

Migración: si tu integración leía product.price_cents / product.currency, cámbiala a product.prices_cents[<divisa>]. Para escribir, manda prices_cents: { "mxn": 450000 } en lugar de price_cents + currency.

1.0.01 — 2026-06-06 ​

Imágenes de producto, campos personalizados, categorías de producto y búsqueda por slug/sku. Cambios aditivos — tus integraciones existentes siguen funcionando sin cambios.

Productos ​

  • Nuevos campos en el producto: image_url, thumbnail_url y una galería images ([{ url, alt, position }]).
  • El detalle (GET /products/:id) ahora incluye variants, option_types, components e inventory — disponibilidad total y desglose por almacén/rack (solo cantidades, nunca costos).
  • Nuevos campos personalizados en productos y marcas: especificaciones/atributos estructurados definidos por el usuario (texto, número, booleano, listas, objetos, listas de objetos y archivos) para la tabla de specs de la ficha. En la lectura se devuelven aplanados como claves de primer nivel del recurso (ej. "voltaje": 110), no como un array custom_properties; en la escritura se pasan como el array custom_properties dentro de data. Las claves que coincidan con un campo reservado del recurso se descartan. Ver Campos personalizados.
  • Nuevos endpoints para gestionar imágenes (multipart): subir/eliminar la imagen principal del producto y la imagen de cada variante.
  • El CRUD acepta variants, option_types y components anidados (con semántica de crear/actualizar/eliminar por id + _destroy).
  • El objeto product ahora incluye product_category ({ id, name, slug }), la referencia estructurada a la categoría de catálogo. El campo category_name se mantiene (deprecado pero presente). La categoría de catálogo (en productos) es distinta de la categoría financiera (en ingresos/egresos), aunque compartan el nombre category_name.

Categorías de producto ​

  • Nuevo recurso /product-categories con CRUD completo: la taxonomía de catálogo con la que organizas tus productos (jerarquía padre/hijas, icon, imagen y product_count).
  • Cada categoría expone product_count (productos activos que apuntan a ella), icon (Material Symbol) e image_url.
  • Nuevo scope por credencial: read-product_categories (y create / update / delete).

Marcas ​

  • Nuevo logo_url (y el media item logo) en el objeto brand, editable desde la app o vía API (logo / logo_url). Útil para chips de marca y la cabecera de la página de marca.

Búsqueda por identificador ​

  • Los endpoints de detalle (GET /{recurso}/:id) aceptan ahora slug o sku además del id, resueltos dentro de tu empresa. Aplica a los recursos que tienen esos campos: productos (slug y sku), marcas, categorías de producto y ligas de agenda (slug). Ver Identificar un recurso.

1.0.0 — 2026-05-18 ​

Lanzamiento inicial de Finova for Developers.

Primera versión pública estable. La API y la forma de cada response es ahora un contrato — los cambios que rompan compatibilidad pasarán por una versión nueva (v2) con aviso por correo y al menos 12 meses corriendo en paralelo.

Lo que incluye ​

  • Endpoints disponibles: Productos, Clientes, Leads, Automatizaciones, Eventos del calendario, Ligas de agenda, Reservas, Usuarios y Empresa.
  • Autenticación con credenciales (finova_sk_...) y permisos a la medida por credencial. Lista blanca opcional de dominios desde donde se permite usar cada credencial.
  • Paginación tipo cursor (starting_after, ending_before) con tope automático para evitar páginas muy profundas. Detalles en la guía de Paginación.
  • Cache de respuestas opt-in (por cuenta) para endpoints de lectura, con invalidación automática cuando hay un cambio. Más en la guía de Cache.
  • Idempotencia: las llamadas que crean datos aceptan Idempotency-Key para que un reintento no duplique registros. Ver guía de Idempotencia.
  • Cobro por consulta real: cada llamada se factura por las consultas a la base de datos que ejecutó (incluyendo la validación de tu credencial, la verificación de que pertenezca a tu empresa y los permisos). Verás el conteo por llamada en el panel de uso, útil para optimizar tu integración.
  • Headers de versión: todas las respuestas incluyen X-Finova-API-Version y X-Finova-API-Released-At. Si más adelante necesitas reportar un problema, incluir estos dos valores ayuda a saber contra qué versión sucedió.

Cómo enterarte de cambios ​

  • Esta página se actualiza con cada release nuevo. Se ordena con la versión más reciente arriba.
  • Para cambios que rompen compatibilidad (siempre en una versión nueva, nunca dentro de v1), te llegará un correo al titular de la cuenta y verás un header Sunset en las respuestas de la versión que va a deprecarse.
  • Si exponemos algo en beta, lo verás con X-Finova-Beta: <feature> en la respuesta y un badge (beta) en la documentación. Sin esos marcadores, lo que estás usando es estable.

Hecho con cuidado por Finova.

© Finova. Todos los derechos reservados.