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. En Fase 1 se exponen cuatro recursos:

• Productos (/api/v1/products) — catálogo: servicios, productos simples, con variantes y compuestos.
• 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.
• Automatizaciones (/api/v1/automations) — listar y togglear flujos automatizados.

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": { "page": 1, "limit": 25, "total": 42, "total_pages": 2 }
}

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.

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

Durante la beta el uso es gratis. Cuando entremos a GA cobraremos pay-as-you-go directo en MXN — pagas exactamente lo que consumes, sin créditos prepagados ni planes con tier. Los detalles llegarán a tu cuenta antes del cambio.

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.