Introducción

La API de Finova for Developers te permite leer y escribir los datos de tu workspace de Finova desde cualquier sitio, ERP o aplicación. Recursos disponibles:

Catálogo

• Productos (/api/v1/products) — catálogo: servicios, productos simples, con variantes y compuestos.
• Categorías de producto (/api/v1/product-categories) — taxonomía de catálogo con la que organizas tus productos.
• Marcas (/api/v1/brands) — marcas asociables a productos, con su propio contenido y multimedia.

CRM

• Clientes (/api/v1/customers) — directorio de clientes con contacto, notas y estatus.
• Leads (/api/v1/leads) — prospectos del módulo de Prospección, ideales para registrar formularios de contacto.
• Formularios (/api/v1/forms) — lee la definición de un formulario multi-idioma para renderizarlo en tu sitio y envía las respuestas de vuelta.
• Automatizaciones (/api/v1/automations) — listar y togglear flujos automatizados.

Finanzas

• Cuentas (/api/v1/accounts), Ingresos (/api/v1/incomes) y Egresos (/api/v1/expenses) — movimientos con los mismos efectos que en la app (balances, inventario, period locking).
• Reportes (/api/v1/reports/*) — balance general, estado de resultados y flujo de efectivo (solo lectura).

Calendario y agendas

• Eventos (/api/v1/calendar/events), Ligas de agenda (/api/v1/calendar/booking-links) y Reservas (/api/v1/calendar/bookings).

Equipo y empresa

• Usuarios (/api/v1/users) y Empresa (/api/v1/company) — miembros del equipo y datos de tu workspace.

Proyectos y facturación. Tu actividad como developer se organiza en proyectos: un proyecto es tuyo y agrupa una o varias empresas (modelo de agencia). El uso se atribuye al proyecto y se desglosa por empresa, y se emite una sola factura/CFDI por proyecto al mes que cubre todas sus empresas. Las API keys pertenecen a cada empresa; los proyectos no son un recurso de la API pública.

URL base

https://developers.fi-nova.com/api/v1

Todas las rutas de esta documentación son relativas a esa base.

Autenticación

Las requests llevan un Authorization: Bearer finova_sk_<secret> en el header. Cada secret se genera desde Configuración → Finova for Developers dentro de tu cuenta y se muestra UNA sola vez al momento de crearlo. No se persiste en texto plano — si lo pierdes, revócalo y crea otro.

Ver: Autenticación.

Formato de las respuestas

Las respuestas son JSON con esta envolvente:

{
  "data": { ... },
  "meta": { "limit": 25, "has_more": true, "next_cursor": "65a0c0f1234567890abcdef0", "previous_cursor": "65a0c0e0fedcba9876543210" }
}

meta aparece solo en las rutas que paginan listas. Los errores siguen otro formato:

{
  "error": "validation_failed",
  "message": "name no puede estar en blanco",
  "errors": { "name": ["no puede estar en blanco"] }
}

Ver: Errores.

Identificar un recurso (id, slug o sku)

Los endpoints de detalle (GET /{recurso}/:id) aceptan tres tipos de identificador en el mismo segmento de la URL, y se resuelven en este orden:

1. id — el ObjectId del recurso (siempre disponible).
2. slug — solo en recursos que tienen slug (ej. productos, categorías de producto, marcas, booking links). Ideal para URLs amigables / SEO (/catalog/lentes-premium).
3. sku — solo en recursos que tienen sku (ej. productos).

No necesitas un endpoint distinto: pasa el id, el slug o el sku donde normalmente va el :id.

# Estos tres resuelven el mismo producto:
curl https://developers.fi-nova.com/api/v1/products/65a0c0f1234567890abcdef0   # por id
curl https://developers.fi-nova.com/api/v1/products/lentes-premium             # por slug
curl https://developers.fi-nova.com/api/v1/products/LEN-PREM-001               # por sku

La resolución siempre está acotada a tu empresa: un slug/sku que exista en otra empresa devuelve 404 not_found. Si ningún identificador coincide, recibes 404 not_found. Cada recurso documenta si soporta slug y/o sku en su sección.

Versiones

La API actual es v1. La forma de cada recurso es un contrato estable: podemos agregar campos sin previo aviso, pero renombrar o eliminar un campo siempre será un cambio de versión. Para que tu integración no se rompa, no hagas validaciones estrictas sobre el conjunto de campos — usa los que necesites y ignora el resto.

Ver: Versionado.

Costos

El uso se cobra pay-as-you-go, directo en MXN: pagas exactamente lo que consumes, sin créditos prepagados ni planes con tier. Cada llamada se cobra por las consultas a la base de datos que ejecutó (incluyendo la validación de credencial, empresa y permisos) — verás el desglose en el panel de uso. Se factura mensualmente (NET 30, con IVA del 16%) a la tarjeta registrada en tu proyecto; cada proyecto recibe una sola factura que cubre todas sus empresas.

Soporte

¿Algo no cuadra? Escríbenos a developers@fi-nova.com. Incluye:

• El prefix + last_four de la key (NUNCA el secret completo).
• El timestamp del request.
• El error.code que recibiste.

Eso nos basta para encontrar tu request en los logs sin información sensible.