Fatturazione automatica per il tuo SaaS
A fine mese il backend trova o crea il cliente con findCustomer() e createCustomer(), poi crea la fattura numerata con createInvoice(). L'invio allo SdI resta una tua decisione.
Client PHP e server MCP per fatture, clienti e scadenze F24. Dal tuo backend, da Claude o da ChatGPT.
Progetto non ufficiale. fiscozen-api è open source (licenza MIT) e indipendente: non è sviluppato, approvato né supportato da Fiscozen S.p.A. Ti servono un tuo account Fiscozen e le tue credenziali.
Una libreria PHP per il tuo software e un server MCP per gli assistenti AI. Il client PHP e il server MCP comunicano direttamente con app.fiscozen.it. Se usi un assistente AI, i dati che restituisce possono essere elaborati anche dal suo fornitore.
A fine mese il backend trova o crea il cliente con findCustomer() e createCustomer(), poi crea la fattura numerata con createInvoice(). L'invio allo SdI resta una tua decisione.
"Quanto ho fatturato quest'anno e cosa devo incassare?" Claude o ChatGPT rispondono con get_year_stats e list_invoices, mostrando fatture e incassi dell'anno. La verifica dei requisiti del forfettario richiede anche altri dati.
Puoi programmare un'attività giornaliera che legge taxPayments() e taxForecasts() e ti avvisa su Slack o via email delle scadenze dei prossimi 30 giorni.
invoicePdf(), invoiceXml() e downloadDocument() scaricano PDF, XML in formato FatturaPA e altri documenti, che puoi poi archiviare su Drive, S3 o nel gestionale.
Quando Stripe o la banca confermano un pagamento, markInvoicePaid() sposta la fattura da "da incassare" all'archivio con data e metodo.
Prima di creare la fattura, checkInvoice() controlla partita IVA e codice fiscale, codice destinatario, PEC o CUU, termine dei 12 giorni e bollo. Dopo l'invio, sdiProblems() elenca scartate e non consegnate, con il termine di 5 giorni per rinviare.
archiveInvoices() salva PDF e XML FatturaPA dell'anno con un manifest di impronte SHA-256. È una copia di sicurezza: la conservazione a norma per 10 anni richiede un servizio accreditato.
allInvoices(), allExpenses() e allCustomers() restituiscono tutto, pagina dopo pagina, pronto per un foglio di calcolo.
L'account Fiscozen usa la verifica in due passaggi. fiscozen-api non la aggira e non la disattiva: al primo accesso e ogni volta che la sessione scade serve il codice che arriva sul tuo telefono.
.session.json e vale finché Fiscozen non la fa scadere. Sui sistemi con permessi POSIX il file è leggibile solo dal proprietario (0600).login_start, ti chiede il codice e lo conferma con login_verify.Prova con sei cifre inventate: è una simulazione, non inserire un vero codice SMS.
Ogni funzione è disponibile come metodo PHP e come strumento MCP (qui i nomi MCP; in PHP cambiano leggermente). Le operazioni di scrittura sono segnalate al client: se chiedere conferma dipende dal client e dalle sue impostazioni.
login_startaccessologin_verifyaccessoauth_statusletturaget_profileletturaget_year_statsletturalist_invoicesletturaget_invoiceletturaget_invoice_pdfletturaget_invoice_xmlletturaget_invoice_numberingletturapreview_invoiceletturacreate_invoicescritturaupdate_invoicescritturadelete_invoicescritturamark_invoice_paidscritturasend_invoice_to_sdiirreversibilelist_customersletturafind_customerletturacreate_customerscritturaupdate_customerscritturadelete_customerscritturalist_providersletturalist_credit_notesletturalist_expensesletturalist_tax_paymentsletturaget_tax_forecastsletturalist_documentsletturaget_documentletturaget_sdi_statusletturalist_sdi_problemsletturaget_sdi_summaryletturacheck_customer_for_sdiletturacheck_invoiceletturavalidate_tax_idletturalist_received_einvoicesletturasearchletturafetchletturalist_vat_codesletturalist_payment_methodsletturaCompila le righe: l'anteprima calcola il totale, aggiunge la marca da bollo da 2 € quando l'importo supera 77,47 €, inserisce la dicitura del forfettario e scrive il codice da incollare.
Anteprima locale nel browser: nessun dato lascia questa pagina. L'invio al Sistema di Interscambio (SdI) non si può annullare dal client e nel server MCP va abilitato esplicitamente.
No. È un progetto open source indipendente, non affiliato a Fiscozen S.p.A. e non approvato da Fiscozen. Il nome indica solo il servizio con cui il software è compatibile.
Usa le stesse API private della web app: se Fiscozen le cambia, il client può smettere di funzionare senza preavviso. Prima di usarlo verifica che le condizioni del tuo contratto lo consentano.
Solo quando la sessione scade. Il client invia il codice una volta e salva la sessione; non registra il dispositivo come fidato, quindi alla scadenza successiva servirà un nuovo SMS.
Credenziali e sessione restano in file sul tuo computer o sul tuo server e servono solo ad autenticarti su Fiscozen; nel repository sono già esclusi da Git, nei tuoi progetti assicurati di fare lo stesso. Non c'è un servizio intermedio. Se usi un assistente AI, verifica quali dati gli vengono trasmessi.
Solo se lo abiliti. Creare una fattura non la invia. Nel server MCP l'invio compare solo con FISCOZEN_MCP_ALLOW_SDI=1 e richiede confirm: true. Una fattura accettata dallo SdI si corregge solo con una nota di credito.
Con i client MCP compatibili con i trasporti supportati. In locale via stdio: Claude Desktop, Claude Code, Codex CLI, Cursor. In remoto via HTTP con token: ChatGPT, l'API Responses di OpenAI e il connettore MCP dell'API di Claude.
Sì, è rilasciato con licenza MIT: puoi usarlo, modificarlo e redistribuirlo anche in progetti commerciali, mantenendo l'avviso di copyright. È fornito senza garanzie.
Scrivi a gabriele@windroses.world per domande, aiuto nella configurazione o segnalazioni. Per i bug puoi anche aprire una issue su GitHub. Non inviare mai password, codici SMS o il file .session.json con la tua sessione.
Per problemi con il tuo account Fiscozen (accesso, fatture, scarti SdI, abbonamento) contatta direttamente Fiscozen: questo progetto non è il loro supporto.
Tutti i metodi di lettura e i download, creazione, modifica ed eliminazione di clienti e fatture, e il server MCP su entrambi i trasporti. Non sono stati provati dal vivo l'invio allo SdI, il segna-come-incassata e l'anteprima XML.
Domande, configurazione, segnalazioni: rispondo via email. Per i bug c'è anche il tracker su GitHub.