Documentació de l'API de Finoview

API REST sobre JSON per connectar el teu programari amb Finoview en les dues direccions: llegir les dades de les teves empreses i importar empreses cap a Finoview. Autenticació per clau d'API, aïllada per compte. Base: https://api.finoview.com/api/v1.

Introducció

Hi ha dues maneres d'integrar-te, i tries la que necessitis:

Guia ràpida

1. Genera una clau d'API a Finoview (Perfil → Desenvolupadors / API). Per importar, marca "permetre escriptura".

2. Llegeix les teves empreses:

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ó

Envia la clau d'API a cada petició:

Authorization: Bearer fv_live_xxxxxxxxxxxx

També s'accepta la capçalera X-API-Key: fv_live_…. Cada clau té un permís:

Tracta la clau com una contrasenya. La pots revocar en qualsevol moment; deixa de funcionar a l'instant.

Convencions

• Versió a la ruta (/api/v1); els canvis incompatibles aniran a /v2.
• JSON a la petició i a la resposta. Etiquetes amb ?lang=es (per defecte) o ?lang=en.
• Aïllament per compte: una clau només veu/escriu les dades del seu propietari.
• Origen (source): cada empresa porta la seva procedència. En importar, indiques el teu programari; els interns INFONIF/EDGAR/BORME/HOLDED estan reservats.
• Idempotència: una empresa s'identifica per (compte, CIF, origen) i cada any pel seu número. Tornar a enviar actualitza, no duplica.
• Límits: hi ha un límit de peticions per clau (429 si se supera) i un màxim de 50 exercicis per importació.

Empreses

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 és del teu compte).

Estats financers

Partides (items) i ràtios (ratios) per exercici, amb nom llegible.

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

• Sense year → tots els anys. ?year=2025 → aquell exercici. ?year=latest → el més recent.

{ "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àleg de dades

Per saber quina clau agafar per enllaçar, llista tot el que hi ha disponible agrupat per estat (públic, sense clau):

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

Retorna seccions (Informació, Actiu, Passiu + PN, Compte de Resultats, Cash Flow, Ràtios), cadascuna amb les seves { key, label }. Al teu BI: enllaça per key (estable) i mostra el label.

Importar dades (escriptura)

Requereix una clau amb permís d'escriptura (si no, 403).

Crear/recuperar empresa (idempotent per CIF+origen) i, opcionalment, carregar exercicis:

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 } } ] }

Carregar/actualitzar anys d'una empresa existent (idempotent per any):

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

Dues maneres d'enviar cada any (tria'n una):

Regles perquè no falli: no precalculis el signe; no sumis els pares; un sol format per any; valors numèrics; source propi (no reservat). Els comptes no reconeguts s'ignoren i es retornen a unmappedAccounts.

Normalització i validació automàtiques. Acceptem Sumes i Saldos obertes o tancades: si l'envies oberta (sense el compte de resultat i amb grups 6-7), Finoview imputa el resultat de l'exercici al Patrimoni Net (compte 129) i el Balanç quadra sol. Si ja envies el 129, no es toca. Cada any de la resposta inclou un informe validation:

"validation": {
  "balanced": true,                 // el Balanç quadra (Actiu = Passiu + PN)
  "imbalance": 0,                    // desquadrament residual
  "result": 680750,                 // resultat de l'exercici
  "resultImputedToEquity": 680750,  // imputat al PN; null si no ha calgut
  "signWarning": "…"                // només si el resultat no quadra (signe / comptes sense mapejar)
}

Guia per a integradors (partners)

Qui emet la clau (bring-your-own-key): 1 clau d'API ↔ 1 compte ↔ 1 sitja de dades. La clau l'emet sempre el compte de Finoview que rep les dades; la teva app és el consumidor. No cal que registris la teva app: a la teva UI afegeix un camp "enganxa la teva clau d'API de Finoview" i l'usuari la genera al seu perfil.

Contracte account-native: unes Sumes i Saldos per exercici a accounts, amb saldo = Σdeure − Σhaver (signe natural). Finoview aplica el signe, suma els pares i calcula les ràtios.

Regles crítiques: (1) saldo = deure − haver; (2) unes Sumes i Saldos per any (no el diari, no un P&L acumulat); (3) dades genuïnes, sense round-trip (no reexportis empreses que vinguin de Finoview); (4) source propi.

Protocol d'alta: 1 empresa real amb CIF → POST → verificar amb GET …/financials que quadra → escalar → muntar el botó a la teva UI al final.

Connectar des de Power BI / Excel

L'API retorna JSON, així que qualsevol eina de BI la pot llegir, sense programar.

1. Power BI: Obtenir dades → Web → Avançat. URL: https://api.finoview.com/api/v1/companies/<ID>/financials?year=latest.
2. A "Paràmetres de capçalera HTTP" afegeix Authorization = Bearer fv_live_….
3. Expandeix data → items / ratios (cada fila: key, label, value).

Excel: Dades → Obtén dades → Des del web → la mateixa URL i la mateixa capçalera.

OpenAPI / Postman

El contracte complet està disponible com a OpenAPI 3.0 (públic, sense clau):

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

Importa'l a Postman o enganxa'l a editor.swagger.io per explorar-lo i generar clients.

Errors

A punt per començar? Crea el teu compte gratis i genera la teva clau d'API.