API fatture gratuita per sviluppatori

URL di base

https://freebillgen.com/api/v1

Autenticazione

Ogni richiesta utilizza un token Bearer. Creane uno in Impostazioni → Chiavi API, assegnagli gli ambiti di lettura/scrittura per risorsa necessari, imposta una scadenza facoltativa e invialo con ogni richiesta:

Authorization: Bearer <your-api-key>

Le richieste vengono autenticate sull'account che ha creato la chiave e verificate rispetto agli ambiti assegnati. Mantieni il token segreto e revocalo se viene esposto o non è più necessario.

Cosa puoi fare

Leggi fatture, clienti, aziende, pagamenti e pianificazioni ricorrenti
Crea e aggiorna (API di scrittura - Pro)
Scarica report IVA e scadenzario in formato JSON
Leggi la stessa coda limitata di Azioni successive utilizzata dalla dashboard
Leggi i file di fatture elettroniche dei fornitori caricati manualmente nella Posta in arrivo (non è un endpoint di ricezione Peppol/e-mail)
Scarica le mappature generiche OASIS UBL e UN/CEFACT CII per la revisione (non validate per profilo)
Registra endpoint webhook per eventi di fatturazione e pagamento (Pro)
Idempotency-Key sulle scritture supportate: dati della richiesta modificati con la stessa chiave restituiscono 409
Paginazione a cursore tramite links.next, regolabile con per_page (max 100)
Consenti agli agenti IA di leggere qualsiasi fattura condivisa: schema.org/Invoice JSON-LD, oltre ad Accept: application/json o text/markdown su ogni link di condivisione firmato
Server MCP di sola lettura senza autenticazione su https://freebillgen.com/api/mcp (get_invoice, verify_invoice) per agenti IA

Convenzioni

Idempotenza: Nelle chiamate di creazione e azione supportate, invia un Idempotency-Key univoco. Riprovare con dati della richiesta identici riproduce il successo originale; dati della richiesta modificati restituiscono 409.
Paginazione: Gli elenchi di risorse persistenti sono impaginati tramite cursore: seguire links.next (oppure passare ?cursor=...) e regolare ?per_page= (max 100). Il feed azioni limitato riporta il proprio limite e lo stato di troncamento.
Importi: Gli importi monetari sono stringhe JSON esatte formattate secondo la scala ISO 4217 della valuta, ad esempio "121.00" per EUR o "500" per JPY. I prezzi unitari possono mantenere una precisione di input aggiuntiva.
ID: Ogni risorsa è identificata da un id opaco, mai da un numero sequenziale.

Esempio: elenco delle fatture

curl https://freebillgen.com/api/v1/invoices \
  -H "Authorization: Bearer $FREEBILLGEN_API_KEY"

Apri il riferimento API interattivo completo →

Domande sull'API delle fatture

L'API delle fatture è gratuita?

Sì: l'API di lettura è inclusa nel piano gratuito senza alcun costo. L'API di scrittura e i webhook in uscita sono inclusi nel piano Lifetime Pro a 49 € imposte incluse: un unico pagamento, senza canone mensile né rinnovo annuale.

Come mi autentico?

Creare un token Bearer in Impostazioni -> Chiavi API, assegnare gli ambiti di lettura/scrittura per risorsa e inviarlo come header Authorization: Bearer in ogni richiesta. Le chiavi sono limitate al proprio account e possono essere revocate o scadere.

Posso creare fatture in modo programmatico?

Sì, tramite l'API di scrittura, inclusa nell'add-on Pro. Genera le stesse fatture professionali dell'app web, con numerazione sequenziale e gestione dell'IVA configurabile applicata lato server. L'API non certifica la conformità alla normativa locale.

Come evito di creare fatture duplicate in caso di nuovo tentativo?

Inviare un Idempotency-Key univoco nella chiamata di creazione. Riprovare con dati di richiesta identici e la stessa chiave restituisce il risultato originale. Riutilizzarla con dati di richiesta modificati restituisce 409 anziché riprodurre silenziosamente una fattura diversa.

Posso leggere le fatture che ho ricevuto?

Sì, gratuitamente. GET /api/v1/inbox elenca i file fornitore UBL/CII supportati caricati manualmente e analizzati da FreeBillGen, con l'originale conservato per audit; GET /api/v1/inbox/{id} ne restituisce uno. Il riconoscimento della sintassi non è una convalida del profilo e questi endpoint non rendono FreeBillGen un endpoint di ricezione Peppol, di rete governativa o e-mail.

Un agente AI può leggere una fattura senza un account?

Sì. Ogni fattura condivisa tramite il relativo link pubblico firmato è leggibile da un agente allo stesso URL: la pagina incorpora JSON-LD schema.org/Invoice e inviando Accept: application/json si ottiene una fattura strutturata (parti, voci, totali, saldo dovuto, opzioni di pagamento), mentre Accept: text/markdown restituisce una resa pulita a basso numero di token. È inoltre disponibile un server Model Context Protocol (MCP) in sola lettura e senza autenticazione all'indirizzo https://freebillgen.com/api/mcp con gli strumenti get_invoice e verify_invoice. La firma del link funge da token di accesso. Trattare l'URL completo come un segreto, poiché chiunque lo riceva può aprire la fattura.