Chiavi API & API pubblica
Lumabill offre un'API REST pubblica che permette di automatizzare fatturazione, spese, contabilita e altro. L'API e disponibile per gli abbonati Pro e Lifetime.
L'API e una funzionalita Pro. Aggiorna il tuo piano in Abbonamento & Moduli per sbloccare l'accesso.
Creare una chiave API
- Vai su Impostazioni > API nella dashboard di Lumabill
- Clicca su Crea chiave API
- Inserisci un'etichetta (es. "Integrazione Zapier" o "Automazione n8n")
- Scegli la modalita di accesso:
- Lettura e Scrittura — accesso completo per creare, modificare ed eliminare dati
- Solo Lettura — puo solo leggere i dati, ideale per reporting o integrazioni AI/MCP
- Facoltativamente, limita la chiave a un profilo specifico
- Clicca su Crea — la chiave viene mostrata una sola volta. Copiala immediatamente e conservala in modo sicuro.
Puoi creare fino a 10 chiavi API per account. Solo il proprietario dell'account puo gestire le chiavi API.
Autenticazione
Tutte le richieste API richiedono un token Bearer nell'header Authorization:
Authorization: Bearer lmb_la_tua_chiave_api_qui
Le chiavi API iniziano con il prefisso lmb_.
Ambito del profilo
Se la tua chiave e associata a un profilo specifico, tutte le richieste utilizzano automaticamente quel profilo. Se la tua chiave ha accesso a tutti i profili, aggiungi l'header X-Profile-Id:
X-Profile-Id: il-tuo-uuid-profilo
Usa GET /v1/profiles per elencare i profili disponibili.
Valori predefiniti intelligenti
Quando si creano fatture o offerte, la maggior parte dei campi e opzionale. L'API li risolve automaticamente dalle impostazioni del profilo:
| Campo | Risolto automaticamente da |
|---|---|
| Numero fattura | Prefisso del profilo + contatore sequenziale (es. IV-010) |
| Data di emissione | Oggi |
| Data di scadenza | Data di emissione + termine di pagamento (30 giorni predefiniti) |
| Valuta | Valuta predefinita del profilo |
| Aliquota IVA | Aliquota IVA predefinita del profilo |
| Dati del mittente | Nome azienda, indirizzo, IBAN del profilo |
| Informazioni di pagamento | Modello di pagamento del profilo |
Esempio minimale — crea una fattura con solo un riferimento cliente e righe:
POST /v1/invoices
{
"client_id": "il-tuo-uuid-cliente",
"lines": [
{ "description": "Consulenza", "quantity": 2, "price": 150 }
]
}
Qualsiasi campo fornito esplicitamente sovrascrive il valore predefinito del profilo.
Limiti di frequenza
| Operazione | Limite |
|---|---|
| Letture (GET) | 60 richieste/minuto |
| Scritture (POST, PUT, DELETE) | 20 richieste/minuto |
In caso di superamento, l'API restituisce 429 Too Many Requests con un header Retry-After.
Documentazione API
La documentazione interattiva completa (Swagger UI) e disponibile su:
La documentazione copre tutti gli endpoint, gli schemi di richiesta/risposta, i codici di errore e include esempi per le operazioni comuni.
Endpoint disponibili
| Risorsa | Elencare | Ottenere | Creare | Modificare | Eliminare |
|---|---|---|---|---|---|
| Fatture | GET | GET | POST | PUT | DELETE |
| Clienti | GET | GET | POST | PUT | DELETE |
| Spese | GET | GET | POST | PUT | DELETE |
| Registrazioni | GET | GET | POST | PUT | DELETE |
| Fornitori | GET | GET | POST | PUT | DELETE |
| Fatture ricorrenti | GET | GET | POST | PUT | DELETE |
| Offerte | GET | GET | POST | PUT | DELETE |
| Catalogo | GET | GET | POST | PUT | DELETE |
| Conti bancari | GET | GET | POST | PUT | DELETE |
| Profili | GET | GET | — | — | — |
| Rapporti | GET | GET | — | — | — |
| Entrate | GET | — | — | — | — |
Revocare una chiave
- Vai su Impostazioni > API
- Trova la chiave nella lista
- Clicca su Revoca e conferma
Le chiavi revocate vengono immediatamente invalidate. Le richieste con una chiave revocata riceveranno una risposta 401 Unauthorized.
Best practice di sicurezza
- Non condividere mai le chiavi API nel codice lato client, repository pubblici o JavaScript del browser
- Usa chiavi in sola lettura per integrazioni che devono solo leggere dati
- Limita le chiavi a un singolo profilo quando l'integrazione necessita accesso a una sola azienda
- Ruota le chiavi periodicamente — revoca le vecchie e creane di nuove
- Conserva le chiavi in variabili d'ambiente o in un gestore di segreti, mai in file di testo