API Reference

XIQUIL espone un’API REST completa per integrare e automatizzare la gestione finanziaria.

Per gli sviluppatori ci sono due superfici API distinte:

• API core sotto /api/, usata dal frontend XIQUIL e dalle integrazioni esterne;
• API plugin sotto /api/plugins/{nome_plugin}/, montata dinamicamente dai plugin abilitati.

Autenticazione

L’API supporta due metodi di autenticazione:

1. JWT (Cookie-based)

Usato dall’interfaccia web. Login via POST, token in cookie HTTP-only.

# Login
curl -X POST https://localhost/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "password"}' \
  -c cookies.txt

# Richiesta autenticata
curl https://localhost/api/uscite/ -b cookies.txt

Il token di accesso dura 15 minuti. Il refresh token dura 30 giorni e viene rinnovato automaticamente.

2. API Key

Per integrazioni programmatiche. Genera una chiave dalla pagina Impostazioni.

curl https://localhost/api/uscite/ \
  -H "Authorization: Bearer cs_la_tua_api_key"

Le API key hanno il prefisso cs_ e non richiedono CSRF token.

Protezione CSRF

Le richieste mutanti (POST, PUT, DELETE) con autenticazione cookie richiedono un token CSRF:

1. Leggi il cookie csrftoken
2. Invia il valore come header X-CSRF-Token

Le API key non richiedono CSRF.

Endpoint principali

Tutti gli endpoint sono sotto il prefisso /api/.

Risorsa	Metodo	Endpoint	Descrizione
Ambiti	GET	/api/ambiti/	Lista ambiti accessibili
	POST	/api/ambiti/	Crea ambito
	GET	/api/ambiti/{id}	Dettaglio ambito
Soggetti	GET	/api/soggetti/	Lista soggetti
Fornitori	GET	/api/fornitori/	Lista fornitori
Clienti	GET	/api/clienti/	Lista clienti
Fondi	GET	/api/fondi/	Lista fondi
	GET	/api/fondi/{id}/saldo	Saldo corrente
Uscite	GET	/api/uscite/	Lista uscite (paginata)
	POST	/api/uscite/	Crea uscita
	GET	/api/uscite/{id}	Dettaglio con voci/scadenze
Entrate	GET	/api/entrate/	Lista entrate (paginata)
	POST	/api/entrate/	Crea entrata
Transazioni	GET	/api/transazioni/	Lista transazioni
Scadenze	GET	/api/scadenze/	Lista scadenze
	POST	/api/scadenze/{id}/paga	Paga scadenza
Budget	GET	/api/budget/	Lista budget
Finanziamenti	GET	/api/finanziamenti/	Lista finanziamenti
Calendario	GET	/api/calendario/	Eventi calendario
Notifiche	GET	/api/notifiche/	Notifiche utente
Impostazioni	GET	/api/impostazioni/	Impostazioni globali

Endpoint plugin

I plugin che dichiarano provides_routes: true espongono le proprie API sotto:

/api/plugins/{nome_plugin}/...

Esempio:

curl https://localhost/api/plugins/xq_bank_reconciliation/ping \
  -H "Authorization: Bearer cs_la_tua_api_key"

Le route plugin sono FastAPI standard e usano le stesse regole del core:

• autenticazione cookie o API key;
• permission dependency del core quando leggono o modificano dati XIQUIL;
• scope per ambito quando lavorano su risorse legate ad ambiti, fondi, uscite o entrate;
• risposta JSON con codici HTTP coerenti.

Per creare un plugin API-first, parti da Creare un plugin e dalla reference Plugin SDK Python.

Gestione plugin via API

Le API di gestione dei plugin vivono sotto /api/system/plugins. Quasi tutte richiedono un utente admin; /manifest richiede solo un utente autenticato, perche serve al frontend per costruire la navigazione.

Metodo	Endpoint	Descrizione
GET	/api/system/plugins/	Lista plugin installati e scoperti
GET	/api/system/plugins/manifest	Manifest frontend per utenti autenticati
GET	/api/system/plugins/catalog	Catalogo Hub con stato locale
POST	/api/system/plugins/{name}/install	Installa dal Marketplace
POST	/api/system/plugins/{name}/update-from-hub	Aggiorna dal Marketplace
POST	/api/system/plugins/{name}/update	Aggiorna manualmente da upload .tar.gz
POST	/api/system/plugins/{name}/toggle	Abilita o disabilita
DELETE	/api/system/plugins/{name}	Disinstalla
POST	/api/system/plugins/upload	Upload .tar.gz in developer mode
POST	/api/system/plugins/install-url	Installa da URL in developer mode
POST	/api/system/plugins/restart	Riavvia per applicare modifiche

Gli endpoint upload e install-url sono disponibili solo con licenza plugin_developer=true oppure PLUGIN_DEVELOPER_MODE=True.

Paginazione

Le liste supportano paginazione server-side:

GET /api/uscite/?offset=0&limit=25&sort_by=-data_documento

Parametro	Default	Descrizione
offset	0	Quanti record saltare
limit	25	Quanti record restituire (max 500)
sort_by	varia	Campo di ordinamento (prefisso - per desc)

Risposta:

{
  "items": [...],
  "total": 142
}

Rate limiting

L’API applica limiti di frequenza:

• API generiche: 30 richieste/secondo
• Upload file: 2 richieste/secondo
• Login: 10 tentativi in 15 minuti per email

Superando il limite, ricevi HTTP 429 (Too Many Requests).

Swagger UI

Se il server e in modalita debug (DEBUG=True), la documentazione interattiva Swagger e disponibile su:

https://localhost/api/docs

Attenzione

Attenzione: non abilitare DEBUG in produzione. Swagger espone tutti gli endpoint e i loro schemi.

Codici di errore

Codice	Significato
200	Successo
201	Creato
400	Richiesta non valida (dati mancanti o errati)
401	Non autenticato
403	Non autorizzato (permessi insufficienti) o CSRF mancante
404	Risorsa non trovata
429	Troppi tentativi
500	Errore interno del server