Documentación de la API de Finoview

API REST sobre JSON para conectar tu software con Finoview en las dos direcciones: leer los datos de tus empresas e importar empresas hacia Finoview. Autenticación por API key, aislada por cuenta. Base: https://api.finoview.com/api/v1.

Introducción

Hay dos formas de integrarte, y eliges la que necesites:

Guía rápida

1. Genera una API key en Finoview (Perfil → Desarrolladores / API). Para importar, marca "permitir escritura".

2. Lee tus empresas:

curl https://api.finoview.com/api/v1/companies \
  -H "Authorization: Bearer fv_live_…"

3. (Opcional) Importa una empresa:

curl -X POST https://api.finoview.com/api/v1/companies \
  -H "Authorization: Bearer fv_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name":"ACME SL","cif":"B12345678","source":"MI_SOFTWARE",
        "years":[{ "year":2025,"accounts":{ "700":1500000 } }] }'

Autenticación

Envía la API key en cada petición:

Authorization: Bearer fv_live_xxxxxxxxxxxx

También se acepta la cabecera X-API-Key: fv_live_…. Cada key tiene un permiso:

Trata la key como una contraseña. Puedes revocarla en cualquier momento; deja de funcionar al instante.

Convenciones

• Versión en la ruta (/api/v1); los cambios incompatibles irán en /v2.
• JSON en petición y respuesta. Etiquetas en ?lang=es (def.) o ?lang=en.
• Aislamiento por cuenta: una key solo ve/escribe los datos de su dueño.
• Origen (source): cada empresa lleva su procedencia. Al importar, indicas tu software; los internos INFONIF/EDGAR/BORME/HOLDED están reservados.
• Idempotencia: una empresa se identifica por (cuenta, CIF, origen) y cada año por su número. Reenviar actualiza, no duplica.
• Límites: hay un límite de peticiones por key (429 si se supera) y máximo 50 ejercicios por importación.

Empresas

GET https://api.finoview.com/api/v1/companies
Authorization: Bearer fv_live_…

{ "data": [
  { "id": "6a1c…", "companyName": "ACME SL", "cif": "B12345678",
    "source": "MI_SOFTWARE", "years": [2023, 2024, 2025] }
] }

Una sola empresa: GET /api/v1/companies/{id} (404 si no es de tu cuenta).

Estados financieros

Partidas (items) y ratios (ratios) por ejercicio, con nombre legible.

GET https://api.finoview.com/api/v1/companies/<ID>/financials?year=2025&lang=es
Authorization: Bearer fv_live_…

• Sin year → todos los años. ?year=2025 → ese ejercicio. ?year=latest → el más reciente.

{ "companyId": "6a1c…", "lang": "es", "data": [
  { "year": 2025, "source": "MI_SOFTWARE",
    "items":  [ { "key": "item01", "label": "Importe neto de la cifra de negocios", "value": 1500000 } ],
    "ratios": [ { "key": "r1", "label": "ROE (%)", "value": 18.4 } ] }
] }

Catálogo de datos

Para saber qué clave coger para enlazar, lista todo lo disponible agrupado por estado (público, sin key):

GET https://api.finoview.com/api/v1/catalog?lang=es

Devuelve secciones (Información, Activo, Pasivo + PN, Cuenta de Resultados, Cash Flow, Ratios), cada una con sus { key, label }. En tu BI: enlaza por key (estable) y muestra el label.

Importar datos (escritura)

Requiere una key con permiso de escritura (si no, 403).

Crear/recuperar empresa (idempotente por CIF+origen) y, opcional, cargar ejercicios:

POST https://api.finoview.com/api/v1/companies
Authorization: Bearer fv_live_…

{ "name":"ACME SL", "cif":"B12345678", "source":"MI_SOFTWARE",
  "years":[ { "year":2024, "accounts":{ "700":1500000, "430":250000 } } ] }

Cargar/actualizar años de una empresa existente (idempotente por año):

POST https://api.finoview.com/api/v1/companies/<ID>/financials
{ "years":[ { "year":2025, "accounts":{ "700":1720000 } } ] }

Dos formas de mandar cada año (elige una):

Reglas para que no falle: no pre-calcules el signo; no sumes los padres; un solo formato por año; valores numéricos; source propio (no reservado). Las cuentas no reconocidas se ignoran y se devuelven en unmappedAccounts.

Normalización y validación automáticas. Aceptamos Sumas y Saldos abiertas o cerradas: si la mandas abierta (sin la cuenta de resultado y con grupos 6-7), Finoview imputa el resultado del ejercicio al Patrimonio Neto (cuenta 129) y el Balance cuadra solo. Si ya envías la 129, no se toca. Cada año de la respuesta incluye un informe validation:

"validation": {
  "balanced": true,                 // el Balance cuadra (Activo = Pasivo + PN)
  "imbalance": 0,                    // descuadre residual
  "result": 680750,                 // resultado del ejercicio
  "resultImputedToEquity": 680750,  // imputado al PN; null si no hizo falta
  "signWarning": "…"                // solo si el resultado no cuadra (signo / cuentas sin mapear)
}

Guía para integradores (partners)

Quién emite la key (bring-your-own-key): 1 API key ↔ 1 cuenta ↔ 1 silo de datos. La key la emite siempre la cuenta de Finoview que recibe los datos; tu app es el consumidor. No necesitas registrar tu app: en tu UI añade un campo "pega tu API key de Finoview" y el usuario la genera en su perfil.

Contrato account-native: una Sumas y Saldos por ejercicio en accounts, con saldo = Σdebe − Σhaber (signo natural). Finoview aplica el signo, suma los padres y calcula los ratios.

Reglas críticas: (1) saldo = debe − haber; (2) una Sumas y Saldos por año (no el diario, no P&L acumulada); (3) datos genuinos, no round-trip (no reexportes empresas venidas de Finoview); (4) source propio.

Protocolo de alta: 1 empresa real con CIF → POST → verificar con GET …/financials que cuadra → escalar → montar el botón en tu UI al final.

Conectar desde Power BI / Excel

La API devuelve JSON, así que cualquier herramienta de BI puede leerla, sin programar.

1. Power BI: Obtener datos → Web → Avanzadas. URL: https://api.finoview.com/api/v1/companies/<ID>/financials?year=latest.
2. En "Parámetros de encabezado HTTP" añade Authorization = Bearer fv_live_….
3. Expande data → items / ratios (cada fila: key, label, value).

Excel: Datos → Obtener datos → Desde web → misma URL y la misma cabecera.

OpenAPI / Postman

El contrato completo está disponible como OpenAPI 3.0 (público, sin key):

GET https://api.finoview.com/api/v1/openapi.json

Impórtalo en Postman o pégalo en editor.swagger.io para explorar y generar clientes.

Errores

¿List@ para empezar? Crea tu cuenta gratis y genera tu API key.