URL di base
https://freebillgen.com/api/v1Autenticazione
Ogni richiesta usa un Bearer token. Creane uno in Impostazioni → Chiavi API, assegnagli gli ambiti di lettura o scrittura necessari per ogni risorsa, imposta una scadenza facoltativa e invialo a ogni richiesta:
Authorization: Bearer <la-tua-chiave-api>Le richieste vengono associate all'account che ha creato la chiave e controllate rispetto agli ambiti assegnati. Mantieni segreto il token e revocalo se viene esposto o non serve più.
Cosa puoi fare
- Leggere fatture, clienti, aziende, pagamenti e pianificazioni ricorrenti
- Crearli e aggiornarli (API di scrittura - Pro)
- Estrarre report IVA e di scadenziario in JSON
- Leggere la stessa coda limitata di azioni successive usata dalla dashboard
- Leggere i file di fatture elettroniche dei fornitori caricati manualmente nella casella in entrata (non è un endpoint di ricezione Peppol o email)
- Scaricare mappature generiche OASIS UBL e UN/CEFACT CII da esaminare (senza convalida del profilo)
- Registrare endpoint webhook per gli eventi di fattura e pagamento (Pro)
- Idempotency-Key nelle scritture supportate: se i dati cambiano usando la stessa chiave, la risposta è 409
- Paginazione a cursore tramite links.next, regolabile con per_page (max 100)
- Permettere agli agenti AI di leggere qualsiasi fattura condivisa - schema.org/Invoice JSON-LD, più Accept: application/json o text/markdown su ogni link di condivisione firmato
- Server MCP di sola lettura e senza autenticazione all'indirizzo https://freebillgen.com/api/mcp (get_invoice, verify_invoice) per gli agenti AI
Convenzioni
- Idempotenza
- Nelle chiamate di creazione e azione supportate, invia una Idempotency-Key univoca. Se ripeti gli stessi dati, viene restituito il successo originale; se i dati cambiano, la risposta è 409.
- Paginazione
- Gli elenchi di risorse persistenti usano la paginazione a cursore: segui links.next (o passa ?cursor=...) e regola ?per_page= (max 100). Il feed limitato delle azioni indica il proprio limite e se è stato troncato.
- Importi
- Gli importi monetari sono stringhe JSON esatte, formattate con il numero di decimali previsto dalla valuta ISO 4217, per esempio "121.00" per EUR o "500" per JPY. I prezzi unitari possono mantenere la precisione aggiuntiva presente nei dati inseriti.
- ID
- Ogni risorsa è indirizzata da un id opaco, mai da un numero sequenziale.
Esempio: elenca le tue fatture
curl https://freebillgen.com/api/v1/invoices \
-H "Authorization: Bearer $FREEBILLGEN_API_KEY"Apri il riferimento API interattivo completo →
Domande sull'API di fatturazione
L'API di fatturazione è gratuita?
Sì. L'API di lettura è inclusa gratuitamente. L'API di scrittura e i webhook in uscita sono inclusi in Lifetime Pro, che costa 49 € imposte incluse: un solo pagamento, senza canone mensile o rinnovo annuale.
Come mi autentico?
Crea un bearer token in Impostazioni -> Chiavi API, assegnagli gli ambiti di lettura/scrittura per risorsa e invialo come header Authorization: Bearer a ogni richiesta. Le chiavi sono limitate al tuo account e possono essere revocate o fatte scadere.
Posso creare fatture in modo programmatico?
Sì, tramite l'API di scrittura inclusa nel componente aggiuntivo Pro. Produce le stesse fatture professionali dell'app web, con numerazione sequenziale e gestione configurabile dell'IVA applicate sul server. L'API non certifica la conformità alle leggi locali.
Come evito di creare fatture duplicate in caso di ritentativo?
Invia una Idempotency-Key univoca nella chiamata di creazione. Se ripeti gli stessi dati con quella chiave, ricevi il risultato originale. Se riusi la chiave con dati diversi, la risposta è 409 invece di riprodurre in silenzio una fattura differente.
Posso leggere le fatture che ho ricevuto?
Sì, gratis. GET /api/v1/inbox elenca i file UBL/CII supportati dei fornitori che hai caricato manualmente e che FreeBillGen ha analizzato, conservando l'originale per la verifica; GET /api/v1/inbox/{id} ne restituisce uno. Il riconoscimento della sintassi non equivale alla convalida del profilo e questi endpoint non trasformano FreeBillGen in un punto di ricezione Peppol, di una rete pubblica o delle email.
Un agente AI può leggere una fattura senza un account?
Sì. Ogni fattura condivisa tramite il suo link pubblico firmato può essere letta dagli agenti sullo stesso URL: la pagina incorpora schema.org/Invoice in JSON-LD, Accept: application/json restituisce una fattura strutturata con parti, voci, totali, saldo e opzioni di pagamento, mentre Accept: text/markdown offre una versione chiara e compatta. È disponibile anche un server Model Context Protocol (MCP) di sola lettura e senza autenticazione all'indirizzo https://freebillgen.com/api/mcp, con gli strumenti get_invoice e verify_invoice. La firma del link è il token di accesso. Tratta l'URL completo come un segreto, perché chiunque lo riceva può aprire la fattura.