fiscozen-api

Fiscozen,
da codice

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.

2 € bollo

Le tue fatture, dove lavori già

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.

Claude ChatGPT Il tuo backend fiscozen-api PHP · MCP Fiscozen il tuo account

A cosa serve

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.

Un assistente che conosce i tuoi numeri

"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.

Scadenze F24 senza sorprese

Puoi programmare un'attività giornaliera che legge taxPayments() e taxForecasts() e ti avvisa su Slack o via email delle scadenze dei prossimi 30 giorni.

Archivio di PDF e XML dove vuoi

invoicePdf(), invoiceXml() e downloadDocument() scaricano PDF, XML in formato FatturaPA e altri documenti, che puoi poi archiviare su Drive, S3 o nel gestionale.

Incassi aggiornati dal tuo software

Quando Stripe o la banca confermano un pagamento, markInvoicePaid() sposta la fattura da "da incassare" all'archivio con data e metodo.

Meno scarti dallo SdI

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.

Copia d'archivio di fine anno

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.

Report e dashboard su misura

allInvoices(), allExpenses() e allCustomers() restituiscono tutto, pagina dopo pagina, pronto per un foglio di calcolo.

Come si usa

terminalefiscozen-api

SMS a ogni accesso

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.

  • Alla domanda "ricordare questo dispositivo?" il client risponde no: nessun dispositivo fidato viene registrato sul tuo account.
  • La sessione è salvata in .session.json e vale finché Fiscozen non la fa scadere. Sui sistemi con permessi POSIX il file è leggibile solo dal proprietario (0600).
  • Un'automazione senza presidio si ferma alla scadenza: qualcuno deve inserire il nuovo codice.
  • Dal server MCP l'assistente chiama login_start, ti chiede il codice e lo conferma con login_verify.
Messaggi Il tuo codice di accesso è valido per pochi minuti. Inserisci il codice

Prova con sei cifre inventate: è una simulazione, non inserire un vero codice SMS.

Tutte le funzioni

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.

Accesso e profilo

  • login_startaccesso
  • login_verifyaccesso
  • auth_statuslettura
  • get_profilelettura
  • get_year_statslettura

Fatture emesse

  • list_invoiceslettura
  • get_invoicelettura
  • get_invoice_pdflettura
  • get_invoice_xmllettura
  • get_invoice_numberinglettura

Emissione

  • preview_invoicelettura
  • create_invoicescrittura
  • update_invoicescrittura
  • delete_invoicescrittura
  • mark_invoice_paidscrittura
  • send_invoice_to_sdiirreversibile

Clienti e fornitori

  • list_customerslettura
  • find_customerlettura
  • create_customerscrittura
  • update_customerscrittura
  • delete_customerscrittura
  • list_providerslettura

Documenti e tasse

  • list_credit_noteslettura
  • list_expenseslettura
  • list_tax_paymentslettura
  • get_tax_forecastslettura
  • list_documentslettura
  • get_documentlettura

Sistema di Interscambio

  • get_sdi_statuslettura
  • list_sdi_problemslettura
  • get_sdi_summarylettura
  • check_customer_for_sdilettura
  • check_invoicelettura
  • validate_tax_idlettura
  • list_received_einvoiceslettura

Per gli assistenti

  • searchlettura
  • fetchlettura
  • list_vat_codeslettura
  • list_payment_methodslettura

Prepara la prima fattura

Compila 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.

Nuova fatturaregime forfettario
Imponibile0,00 €
Marca da bollonon dovuta
Totale0,00 €
Apri il repository

Domande

È un servizio di Fiscozen?

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.

Devo inserire il codice SMS ogni volta?

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.

Dove finiscono password e dati?

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.

Può inviare fatture allo SdI da solo?

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 quali assistenti funziona?

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.

Posso usarlo e modificarlo?

Sì, è rilasciato con licenza MIT: puoi usarlo, modificarlo e redistribuirlo anche in progetti commerciali, mantenendo l'avviso di copyright. È fornito senza garanzie.

Dove chiedo aiuto?

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.

Cosa è stato provato davvero?

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.

Aiuto e supporto

Domande, configurazione, segnalazioni: rispondo via email. Per i bug c'è anche il tracker su GitHub.