Fattura24

# Account Consumi MCP Restituisce le informazioni sui limiti di utilizzo e lo stato delle chiamate MCP per l'account corrente. ## Parametri Nessuno. ## Output Restituisce un JSON con: - `ambiente` - Ambiente corrente (produzione / sandbox) - `piano_abilitato` - Se il piano di abbonamento corrente consente l'uso del connettore MCP - `limite_giorni_mese` - Numero massimo di giorni di utilizzo del connettore nel mese corrente previsti dal piano (null se illimitato) - `giorni_utilizzati_mese` - Numero di giorni distinti, nel mese corrente, in cui il connettore è stato usato - `giorni_residui_mese` - Numero di giorni di utilizzo ancora disponibili questo mese (-1 se illimitato) - `messaggio` - Messaggio esplicativo se il piano non è abilitato o il limite mensile è stato raggiunto (null altrimenti) - `intervallo` - Periodo di riferimento del conteggio - `dal` - Primo giorno del mese corrente (formato YYYY-MM-DD) - `al` - Timestamp dell'ultima chiamata registrata nel mese corrente (null se nessuna chiamata)

# Account Dettagli Recupera i dati dell'account e del profilo dell'utente autenticato. ## Parametri Nessuno. ## Output Restituisce un JSON con i seguenti campi: - `nome` - Nome - `cognome` - Cognome - `id_profilo_utente` - ID utente - `tipo_utente` - Tipo utente (amministratore / collaboratore) - `tipo_abbonamento` - Tipo abbonamento (standard / Professional / Business / Complete) - `email` - Email - `ragione_sociale` - Ragione sociale - `codice_fiscale` - Codice fiscale - `denominazione` - Partita IVA - `ufficio` - Oggetto con indirizzo, citta, cap, provincia, paese - `data_creaz` - Data creazione (dd/MM/yyyy) - `scad_account` - Data scadenza account (dd/MM/yyyy) - solo se valorizzata - `scaduto_in_data` - Data scaduto (dd/MM/yyyy) - solo se valorizzata

# Download singolo esito SdI Questo tool restituisce le informazioni contenute nel file xml della singola ricevuta di esito originale trasmessa dal Sistema di Interscambio (SDI) in relazione ad un documento (ad esempio, una fattura elettronica) inviata dall'utente da dentro il gestionale Fattura24. E' quindi molto utile soprattutto nel caso di una fattura scartata, perché consente di conoscere i motivi dello scarto (o del rifiuto da parte di una PA) indicati dal SDI. Il tool non consente invece di scaricare il vero e proprio file della ricevuta. ## Parametri di ricerca in input I parametri da usare per la ricerca sono: - `id_documento`: obbligatorio, rappresenta l'identificativo univoco del documento (fattura elettronica, parcella, nota di credito, etc.) attribuito automaticamente da Fattura24 all'interno del gestionale Fattura24; - `file_name_esito`: obbligatorio, è il nome del file orignale della ricevuta trasmessa dal SDI. Il valore del parametro `id_documento` non deve essere confuso con il numero del documento (che è tutta un'altra cosa ed è deciso dall'utente). ## Output - struttura della risposta Il server MCP risponde con questa struttura: - `meta`: è un oggetto che contiene il valore dei parametri di ricerca utilizzati; - `esito`: è una stringa e rappresenta il codice/sigla dell'esito correlato all'invio effettuato dall'utente; - `dettaglio`: è un campo complesso, che sarà oggetto nel caso delle ricevute RC (consegna) e MC (mancato recapito), oppure un array nel caso della ricevuta NS (scarto). ### Campo `esito` Alcuni dei tipi di esito sono quelli tipici previsti dalle Specifiche Tecniche della fatturazione elettronica italiana (ad esempio, "RC", "NS", "MC", etc.), altri sono invece rappresentativi di uno stato interno in Fattura24 (ad esempio, "F24_SEND"). Il significato dei possibili valori che può avere questo campo sono quelli descritti nella descrizione del tool `ricerca_esito_sdi`, all'interno della spiegazione relativa al campo `tipo_esito` di quel tool; puoi quindi riferti a quella documentazione per descrivere all'utente il significato dei vari tipi di esito. In particolare, il tipo di esito "AT" viene trasmesso dal SDI al soggetto trasmittente per attestare l’avvenuta ricezione della fattura e però l’impossibilità per il SDI di recapitare il file alla PA destinatario (per mancata disponibilità tecnica di comunicazione con la PA). ### Campo `dettaglio` Questo campo è costituito da un oggetto, che può avere, a seconda dei casi, i seguenti sotto-campi: - `identificativo_sdi`: è il numero attribuito dal SDI al file del documento ricevuto (ad esempio, una fattura) e indicato dal SDI nel file XML originale della ricevuta di esito; - `data_ora_ricezione`: è una data temporale indicata all'interno della ricevuta XML trasmessa dal SDI e rappresenta la data (comprensiva anche dell'ora) in cui il file del documento (ad esempio una fattura) è stato ricevuto dal SDI; - `data_ora_consegna`: questo campo viene restituito solo nel caso di ricevuta di esito "RC - consegnata" e indica la data e l'ora in cui il file del documento inviato dall'utente (ad esempio una fattura) è stato consegnato dal SDI; - `data_messa_a_disposizione`: questo campo viene restituito solo nel caso di ricevuta di esito "MC - mancato recapito" e indica la data e l'ora in cui il file del documento inviato dall'utente (ad es. una fattura) è stato messo a disposizione da parte di SDI nell'area riservata del destintario in Fatture e Corrispettivi dell'Agenzia delle Entrate (il cd "cassetto fiscale"); - `descrizione_generale`: è un campo che è presente solo nel caso delle ricevute di esito "MC" (mancata consegna / impossibilità di recapito) e "DT" (quest'ultima tipica della fatturazione vs la PA) e viene usata dal SDI per indicare eventualmente o i motivi dell'impossibilità di recapito o i motivi della particolare notifica trasmessa; - `lista_errori`: è un campo complesso di tipo array, presente solo nel caso di una ricevuta di esito "NS - Scarto", che contiene l'elenco degli errori segnalati dal SDI nella ricevuta xml; - `esito_comunicato_da_pa`: è un campo che è presente solo quando l'esito è relativo alla fatturazione verso la PA e rappresenta la sigla identificativa della risposta data dalla PA così come comunicata dal SDI (che potrà essere "EC01" in caso di accettazione espressa e "EC02" in caso di rifiuto espresso); - `descrizione_esito_comunicato_da_pa`: è un campo che è presente solo quando l'esito è relativo alla fatturazione verso la PA e rappresenta la descrizione della risposta (accettazione o rifiuto) data dalla PA così come comunicata dal SDI. #### Contenuto del campo `lista_errori` Ogni item dell'elenco `lista_errori` può avere i seguenti campi: - `codice_errore`: è il codice che le Specifiche Tecniche dekla fatturazione elettronica attribuiscono allo specifico errore; - `descrizione_errore`: è la descrizione dell'errore che il SDI indica all'interno della ricevuta di scarto; - `suggerimento_errore`: è una nota di suggerimento aggiuntiva che il SDI può indicare (opzionale) all'interno della ricevuta di scarto. ## Quando puoi usare questo tool Puoi usare questo toll quando: - l'utente vuole approfondire un singolo esito già individuato (ad esempio, per leggere il preciso codice o la descrizione dell'errore in caso di una ricevuta di esito `NS` di scarto); - l'utente vuole il motivo per il quale la PA ha fatto trasmettere al SDI una ricevuta di rifuto espresso del documento (ricevuta NE-EC02). Per usare questo tool devi però prima usare il diverso tool di Fttura24 `ricerca_esito_sdi` (che restituisce la cronologia degli esiti SDI per ogni documento). Infatti, devi prima usare `ricerca_esito_sdi` per recuperare i valori da usare per i parametri di ricerca `id_documento` e `file_name_esito`. ## Quando non puoi usare questo tool Non puoi usare questo tool: - per ottenere l'elenco/cronologia degli esiti di un documento: in questo caso usa appunto `ricerca_esito_sdi`; - per cercare documenti per anno, stato o tipo: in questo caso usa `ricerca_documenti`. ## Esempio di utilizzo dei parametri di ricerca ```json { "id_documento": "1234567", "file_name_esito": "IT123456789_1B8h8_NS_001.xml" } ```

# Report Analisi IVA Restituisce, mese per mese, l’IVA sulle vendite (IVA a debito) e sugli acquisti (IVA a credito) per l’anno indicato, in formato JSON. ## Quando usarlo Usa questo tool quando l'utente chiede: - l'analisi o il riepilogo dell'IVA dell'anno - l'andamento mensile dell'IVA su entrate e uscite - il confronto tra IVA a debito e IVA a credito ## Esempi di richieste utente - "Mostrami l'analisi IVA del 2026" - "Quanta IVA ho a debito e a credito quest'anno?" - "Andamento mensile dell'IVA su vendite e acquisti 2026" - "Ci sono mesi con differenze rilevanti tra IVA a debito e a credito?" ## Quando non usarlo - per la liquidazione IVA o gli adempimenti: il tool è solo di consultazione - per ricavi, costi e margini: usa `report_bilancino` ## Parametri - **anno**: Anno di riferimento (es. "2026") - **esigibilita**: Tipo di esigibilità IVA da considerare. Valori ammessi: - `qualsiasi`: considera qualsiasi tipo di esigibilità - `solo_split_payment`: considera solo le operazioni in split payment (scissione dei pagamenti) ## Esempio di risposta ```json [ { "tipo": "entrate", "mese": 1, "importo": 1234.56 }, { "tipo": "uscite", "mese": 1, "importo": 789.01 } ]

Restituisce l'analisi geografica delle vendite per anno, aggregata per città, provincia, regione o paese. Usa questo tool quando l'utente vuole visualizzare la distribuzione geografica dei clienti o analizzare le vendite per territorio. ## Parametri - **anno** Anno di riferimento (es: 2026) - **raggruppa_per** Livello di aggregazione geografica: - `"Città"` = dettaglio massimo, con coordinate GPS - `"Provincia"` = aggregazione per provincia italiana - `"Regione"` = aggregazione per regione/area geografica - `"Paese"` = solo nazione, senza coordinate ## Esempi di richieste utente:** - Mostrami la mappa delle vendite 2026 per città - Quali sono le province con più clienti nel 2025? - Analisi geografica delle vendite 2026 per regione - Distribuzione geografica clienti 2025 (tutti i risultati senza paginazione) ## Non usare per: - report temporali comparativi (ultimi anni) - analisi per prodotto o servizio - dettaglio singola fattura

# Report Bilancino Questo tool è di tipo aggregato e restituisce il report analitico dei ricavi conseguiti e dei costi sostenuti dall'utente nel corso di un anno, e viene composto dal server MCP di Fattura24 in base alle voci di centro di ricavo e di centro di costo che lo stesso utente ha caricato, nel gestionale Fattura24, all'interno dei documenti da lui creati, di vendita e di acquisto. Questo strumento, per la precisione, consente all'utente di analizzare, sulla base del Piano dei Conti che lo stesso utente ha creato all'interno del gestionale Fattura24, l'andamento di: - ricavi; - costi variabili; - costi fissi; - costi totali; - margine di contribuzione (MDC); - margine operativo lordo o EBITDA. Per ricavare l'MDC Fattura24 effettua l'operazione ricavi meno costi variabili. ## Parametri di ricerca in input I parametri da usare sono: - `anno`: è obbligatorio, rappresenta l'anno di competenza e deve essere espresso nel formato YYYY. ## Requisiti prelininari perché il tool dia risultati utili Il tool `report_bilancino` restituirà risultati utili solo se: - l'utente ha un abbonamento "Complete" a Fattura24; - l'utente ha costruito nel gestionale Fattura24 un suo "Piano dei conti" e lo ha correttamente applicato di volta in volta alle sue fatture di vendita e di acquisto. ## Criteri funzionali e temporali usati dal tool per restituire i risultati Il server MCP di Fattura24, per controllare se (e in che misura) uno specifico centro di ricavo o centro di costo è stato conseguito o sostenuto nel corso di un dato anno, va a vedere i seguenti documenti: - fatture (elettroniche ed analogiche); - parcelle; - ricevute; - corrispettivi; - buste paga. Questo tool non considera invece i Tributi: se l'utente vuole sapere quanti sono i tributi pagati nel corso di un anno, devi usare il diverso tool `report_tributi`. Tieni conto che l'utente in Fattura24 può però esludere (nella sezione "configurazione/avanzate/report") alcune classi documentali dalla composizione dei report; se ad esempio in quella sezione di configurazione ha escluso le ricevuite di vendita, allora i report di Fattura24, compreso questo tool, non prenderanno in considerazione gli importi contenuti nelle ricevute di vendita. Gli importi considerati: - sono naturalmente quelli al netto dell'IVA; - per quanto riguarda le buste paga, sono determinati considerando l'importo che l'utente indica nel campo "Importo lordo" della scheda della busta paga; - sono considerati per il solo fatto di essere presenti nei documenti creati dall'utente, a prescindere quindi se sono stati effettivamente pagati o meno (o se sono stati pagati solo in parte, anche eventualmente a seguito dell'applicazione di uno sconto generale a valle del totale netto a pagare della fattura). Per vedere infine se il documento in cui è caricato il centro di ricavo o di costo rientra nell'anno richiesto dall'utente (ad esempio, il "2026"), il server controlla se quell'anno è quello indicato nel campo "Data competenza" del documento: il criterio temporale utilizzato è quindi quello della data competenza indicata dall'utente all'interno del documento. ## Output - struttura di risposta La risposta JSON ha una struttura composta dai seguenti campi complessi: - `meta`; - `dettagli`; - `totali`; - `indicatori`. ### Campo `dettagli` Questo campo è un array composto da tutte le voci di centro di ricavo o di costo dell'utente costruite da lui nel Piano dei Conti. Ognuno degli item ha i seguenti campi: - `id_pdc`: è l'identificativo dello specifico centro di ricavo o di costo nel gestionale Fattura24; - `codice_pdc`: è il codice dato dallo stesso utente allo pecifico centro di ricavo o di costo; - `descrizione_pdc`: è il nome dato dallo stesso utente allo pecifico centro di ricavo o di costo;; - `tipo_voce`: specifica se si tratta di un centro di ricavo o di un centro di costo, con valori che possono essere `ricavo`, `costo_fisso` o `costo_variabile`; - `totale_consuntivo_annuale`: indica, in Euro, il totale annuale degli importi conseguiti o sostenuti dall'utente per lo specifico centro di ricavo o di costo; - `consuntivo_mensile`: è un campo di tipo oggetto, che al suo interno contiene 12 campi, uno per ogni mese dell'anno, i cui valori sono gli importi mensili in Euro relativi allo specifico centro di ricvo o di costo. Il campo complesso do tipo oggetto `consuntivo_mensile` ha la seguente struttura: - `gennaio` - `febbraio` - `marzo` - `aprile` - `maggio` - `giugno` - `luglio` - `agosto` - `settembre` - `ottobre` - `novembre` - `dicembre` #### Composizione dei singoli valori mensili - non sono valori progressivi ATTENZIONE: i valori mensili di ogni voce sono calcolati a sé stanti e non rappresentano quindi un cumulato progressivo. Ad esempio, se per una particolare voce di centro di ricavo il valore di aprile è "1200", significa che l'utente nel solo mese di aprile ha conseguito ricavi, per quella voce di centro di ricavo, pari a Euro 1200,00 (e ciò a prescindere appunto da quanto ha conseguito per la stessa voce nei mesi precedenti). ### Campo `totali` Questo campo è un oggetto che contiene i totali progressivi annuali e mensili, inseriti nei seguenti ulteriori campi complessi: - `totale_ricavi`; - `totale_costi_variabili`; - `totale_costi_fissi`; - `totale_costi`; - `mdc`; - `ebitda`. Ognuno dei detti campi riporta il totale annuale e i totali dei singoli mesi dell'anno, con la seguenti struttura: - `totale_annuale`: è un valore numerico in Euro; - `mensile`: è un oggetto con all'interno 12 campi, uno per ogni mese dell'anno, ognuno con il relativo valore numerico espresso in Euro (i singoli valori sono a sé stanti e non sono progressivi). #### Nota sul campo complesso ebitda I valori rappresentano il "margine operativo lordo", che può essere considerato come Ebitda se ricavato come risultato dopo gli accantonamenti (dpiende da come l'utente usa il gestionale Fattura24); in ogni caso, i valori sono considerars il risultato prima di ammortamenti, svalutazioni, oneri finanziari e imposte. ### Campo `indicatori` E' un oggetto che è composto da 3 campi che servono ad indicare 3 importanti indicatori economici, ricavati dai dati del bilancino: - `rapporto_costi_variabili_su_ricavi`: indica quanto è elevato il livello dei costi variabili rispetto al totale dei ricavi; - `rapporto_mdc_su_ricavi`: indica quanto è elevato il margine operativo lordo o Ebitda, in percentuale, rispetto al totale dei ricavi; - `rapporto_ebitda_su_ricavi`: indica quanto è elevato il margine operativo lordo o Ebitda, in percentuale, rispetto al totale dei ricavi. ## Quando devi usare questo tool Usa questo tool quando l'utente chiede: - il bilancino dell'anno; - l'andamento mensile di ricavi e costi; - il totale progressivo di ricavi, costi, MDC o EBITDA; - un'analisi del conto economico basata sul Piano dei Conti costruiito dall'utente; - il dettaglio per voce di ricavo o di costo. ## Quando non devi usare questo tool Non dovresti usare questo tool se l'utente ti chiede quali sono le sue vendite annuali in base ai "nomi" dei prodotti o servizi venduti o erogati che lo stesso utente ha creato nella sezione "Prodotti e Servizi" del gestionale Fattura24 (per questa richiesta c'è un tool specifico che si chiama `report_prodotti_servizi`). Infatti, questa sarebbe una ricerca diversa da quella soddisfatta con il presente tool, che è relativo invece, come indicato sopra, alla suddivisione per "centri di ricavo" e "centri di costo" facenti parte del Piano dei Conti. Inoltre, non devi usare questo tool per fare un confronto tra budget prefissato dall'utente e risultti da lui realemente conseguiti; per questa richiesta, infatti, c'è un tool ad hoc, che si chiama `report_forecast`. ## Esempio di struttura ```json { "meta": { "report": "bilancino_analitico", "anno": 2026, "filtro_pdc_descrizione": null, "costi_fissi_in_dodicesimi": true, "valuta": "EUR" }, "dettagli": [ { "id_pdc": 211235, "codice_pdc": "000", "descrizione_pdc": "TEST FEDE2", "tipo_voce": "ricavo", "totale_consuntivo_annuale": 0.0, "consuntivo_mensile": { "gennaio": 0.0, "febbraio": 0.0, "marzo": 0.0, "aprile": 0.0, "maggio": 0.0, "giugno": 0.0, "luglio": 0.0, "agosto": 0.0, "settembre": 0.0, "ottobre": 0.0, "novembre": 0.0, "dicembre": 0.0 } } ], "totali": { "totale_ricavi": { "totale_annuale": 0.0, "mensile": {} }, "totale_costi_variabili": { "totale_annuale": 0.0, "mensile": {} }, "totale_costi_fissi": { "totale_annuale": 0.0, "mensile": {} }, "totale_costi": { "totale_annuale": 0.0, "mensile": {} }, "mdc": { "totale_annuale": 0.0, "mensile": {} }, "ebitda": { "totale_annuale": 0.0, "mensile": {} } }, "indicatori": { "rapporto_costi_variabili_su_ricavi": 0.0, "rapporto_mdc_su_ricavi": 0.0, "rapporto_ebitda_su_ricavi": 0.0 } }

# Churn rate - Tasso di abbandono clienti Il **Churn rate** rientra nella categoria dei KPI (*Key Performance Indicator*), indicatori utilizzati per monitorare l’andamento dei processi aziendali e valutare lo stato di salute del business. Il churn rate misura la percentuale di clienti che interrompono il rapporto con l’azienda in un determinato periodo temporale. L’analisi di questo indicatore consente di identificare eventuali livelli critici di perdita clienti e supporta decisioni gestionali finalizzate alla riduzione del tasso di abbandono. ## Quando usarlo Usa questo tool quando l'utente chiede del **tasso di abbandono dei clienti** in un periodo, ad esempio: - quanti clienti ha perso - qual è il suo churn rate - come è cambiata la base clienti tra inizio e fine periodo ## Esempi di richieste utente - "Qual è il mio tasso di abbandono clienti nel 2026?" - "Quanti clienti ho perso quest'anno?" - "Calcola il churn rate degli ultimi 12 mesi" ## Parametri Questo tool non richiede parametri di input: il periodo di analisi è determinato automaticamente dal connettore e non è selezionabile. L'intervallo effettivamente considerato viene restituito nei campi `data_da` e `data_a` della risposta. ## Dati restituiti Il tool restituisce un oggetto JSON contenente: * Intervallo temporale analizzato (`data_da`, `data_a`) * Numero di clienti presenti all’inizio del periodo * Numero di clienti presenti alla fine del periodo * Numero di clienti persi nel periodo * Percentuale di churn rate sul periodo ## Logica di calcolo I valori vengono determinati considerando: * Clienti attivi all’inizio del periodo * Clienti attivi alla fine del periodo * Differenza tra i due valori, corrispondente ai clienti persi La percentuale di churn viene calcolata come: `(clienti_persi / clienti_iniziali) * 100` ## Finalità Il JSON restituito può essere utilizzato per: * Dashboard KPI * Analisi di controllo di gestione * Monitoraggio della retention clienti * Integrazioni applicative e workflow automatizzati

# Report Fatturato Questo tool è di tipo aggregato e restituisce un report che mostra diversi valori riepilogativi relativi a quello che è stato l'andamento dell'attività dell'utente nel corso dell'anno specificato, su base mensile. I dati più importanti mostrati sono quelli relativi al fatturato, ovverosia agli importi oggetto delle fatture di vendita e di acquisto emesse e ricevute dall'utente; vengono però mostrati anche altri diversi e importanti valori (te lo spiego meglio poco più avanti). L'output è un array JSON di 12 elementi, uno per ciascun mese dell'anno; ogni elemento ha diverse voci, ognuna con un suo significato. Se in un particolare anno non vi sono dati nell'account dell'utente, la response di questo tool restituirà comunque un array di 12 elementi, con tutte le props con valori pari a zero. ## Parametri di ricerca in input I parametri da usare sono: - `anno`: è l'anno di riferimento del report (ad esempio, 2026). Se l'utente non specifica l'anno, usa l'anno corrente. ## Criterio temporale usato dal tool per restituire i risultati Sotto il profilo del criterio temporale utilizzato, i documenti considerati da Fattura24 per estrarre i dati sono quelli che, al loro interno (nel campo "Competenza"), hanno lo stesso anno specificato dall'utente nella richiesta che ti formula. ## Output - informazioni fondamentali su struttura e significato delle voci restituite dal report La response di questo tool contiene, per ogni item della lista di risposta, le voci che ti indico di seguito; per farti capire meglio il loro significato, te le suddivido per gruppi. Devi sempre far presente all'utente il significato delle diverse voci, soprattutto se è l'utente stesso a chiederti delucidazioni sul significato di alcune voci o di importi oggetto di questo tool. ### Voci relative ai dati di "fatturato" Queste voci sono le stesse che l'utente può vedere nel Report chiamato "Fatturato" presente nel suo account in Fattura24. Le voci sono: - `vendite_imponibile`: costituisce la somma degli importi (al netto di IVA) delle righe-documento (contenute nei documenti di vendita) classificate dallo stesso utente in Fattura24 come "imponibili reddito" (ai fini irpef/ires), ivi incluse quelle con Iva allo 0%; - `vendite_non_imponibile`: costituisce invece la somma degli importi (al netto di IVA) delle righe-documento (contenute nei documenti di vendita) classificate dallo stesso utente in Fattura24 come "NON imponibili reddito" (ai fini irpef/ires); - `vendite_inps`: costituisce la somma dei contributi integrativi Inps (al netto di IVA) caricati dall'utente nei documenti di vendita a titolo di rivalsa Inps; - `vendite_cassa`: costituisce la somma dei contributi integrativi per Cassa privata (al netto di IVA) caricati dall'utente nei documenti di vendita (ad esempio, per la Cassa forense); - `acquisti_imponibile`: costituisce la somma degli importi (al netto di IVA) delle buste paga e delle righe-documento (contenute nei documenti di acquisto) classificate come "imponibili reddito" (ai fini irpef/ires), ivi incluse quelle con Iva allo 0%; - `acquisti_non_imponibile`: costituisce invece la somma degli importi (al netto di IVA) delle righe-documento (contenute nei documenti di acquisto) classificate come "NON imponibili reddito" (ai fini irpef/ires); - `acquisti_inps`: costituisce la somma dei contributi integrativi Inps (al netto di IVA) caricati dai fornitori nei documenti di acquisto a titolo di rivalsa Inps; - `acquisti_cassa`: costituisce la somma dei contributi integrativi per Cassa privata (al netto di IVA) caricati dai fornitori nei documenti di acquisto (ad esempio, per la Cassa forense). Queste voci appena descritte possono essere sommate per individuare il totale onnicomprensivo del "fatturato", sia lato vendite, sia lato acquisti (sempre al netto di IVA, si intende). Gli importi mostrati: - sono naturalmente quelli al netto dell'IVA; - sono al netto delle note di credito create nel periodo. #### Perché queste voci sono relative a dati di "fatturato" Le voci sopra indicate sono relative al "fatturato", e ciò perché sono compilate dal tool con gli importi "fatturati" (dallo stesso utente o dai suoi fornitori), ovverosia quegli importi di imponibile inseriti nei documenti presenti nell'account dell'utente in fattura24 a prescindere se gli stessi importi sono stati poi effettivamente pagati o meno (dal cliente dell'utente verso l'utente, oppure dall'utente verso il suo fornitor o dipendente). #### Documenti dai quali Fattura24 deriva gli importi Gli importi considerati da Fattura24 per comporre le voci suindicate sono quelli contenuti nei documenti di vendita e di acquisto/costo seguenti: - fatture elettroncihe, fatture analogiche e parcelle; - ricevute; - note di credito; - corrispettivi; - buste paga. Tieni conto che l'utente in Fattura24 può però esludere (nella sezione "configurazione/avanzate/report") alcune classi documentali dalla composizione dei report; se ad esempio in quella sezione di configurazione ha escluso le ricevuite di vendita, allora i report di Fattura24, compreso questo tool, non prenderanno in considerazione gli importi contenuti nelle ricevute di vendita. Per comporre queste voci, non sono considerati invece mai gli importi relativi alle regitrazioni che l'utente ha fatto nella sezione Tributi di Fattura24. ### Voci accessorie relative agli "incassi", ai "pagamenti" monetari "effettivi" e all'iva Nella response del tool trovi anche delle voci che non riguardano per nulla il concetto di "fatturato", ma che sono molto importanti per l'utente per capire quale è la situazione della sua attività sotto il profilo della "cassa". Queste voci sono: - `vendite_entrate`: costituisce la somma degli incassi realmente conseguiti dall'utente, costituiti dai pagamenti che hanno effettuato i suoi clienti; - `acquisti_uscite`: costituisce la somma dei pagamenti effettuati dall'utente a favore dei suoi fornitori; - `buste_paga_uscite`: costituisce la somma dei pagamenti effettuati dall'utente a favore dei suoi dipendenti; - `tributi_uscite`: costituisce la somma dei pagamenti effettuati dall'utente in relazione alle registrazioni che lo stesso utente ha effettuato nella sezione Tributi di Fattura24. Queste voci sono dunque relative a importi che, proprio perché relativi a movimenti reali di cassa, devono essere intesi comprensivi di IVA. Mostra questi valori solo se l'utente te lo chiede espressamente. ### Altre voci accessorie La response di questo tool ritorna poi, ancora, altre voci accessorie, che non riguardano per nulla il concetto di "fatturato", ma che possono comunque essere utili all'utente per visualizzare dati importanti relativi alla sua attività. Le voci sono: - `vendite_ra`: la somma delle ritenute di acconto caricate dall'utente nei suoi documenti di vendita; - `vendite_rp`: la somma delle ritenute previdenziali caricate dall'utente nei suoi documenti di vendita; - `acquisti_ra`: la somma delle ritenute di acconto lato-acquisti, caricate dai fornitori dell'utente nelle loro fatture; - `acquisti_rp`: la somma delle ritenute previdenziali lato-acquisti, caricate dai fornitori dell'utente nelle loro fatture. - `tributi`: la somma degli importi delle registrazioni che l'utente ha effettuato nella sezione Tributi di Fattura24, a prescindere se gli stessi sono stati segnati come pagati o no. Mostra questi valori solo se l'utente te lo chiede espressamente. ### Altre voci accessorie non utilizzabili e che non devi mai considerare La response di questo tool ritorna infine altre voci accessorie, che non solo non riguardano per nulla il concetto di "fatturato", ma che non devi mai riferire o riportare all'utente e che non devi mai prendere in. considerazione per rispondere a domande dell'utente: in sostanza, devi considerare come se non facessero parte per nulla di questo tool (i motivi sono sia tecnici, sia legati al fatto che esistono altri tool speciali). Queste voci sono: - `vendite_imponibile_fe`; - `vendite_non_imponibile_fe`; - `vendite_iva`; - `acquisti_iva`. Se l'utente chiede specificamente informazioni o dati di riepilogo relativi alle sole fatture elettroniche (escludendo quindi altri tipi di documenti, come le ricevute, le fatture analogiche o i corrispettivi), devi riferire che questo tool non restituisce questo tipo di dati e che semmai l'utente può utilizzare il diverso tool `ricerca_documenti`. Se l'utente chiede invece, specificamente, i dati dell'IVA relativa alle vendite e agli acquisti registrati su Fattura24, devi, come detto, far presente che non fanno parte di questo tool e consigliare l'utente di usare il tool `report_analisi_iva`. ## Come mostrare gli importi La response di questo tool restituisce gli importi sempre in euro, con il punto come separatore decimale; tu presentali all'utente in Euro, ma con la formattazione italiana, usando quindi la virgola come separatore decimale. ## Quando usare questo tool Usa questo tool quando l'utente ti chiede i dati di fatturato di **un singolo anno**, e/o quando ti formula domande del tipo: - l'andamento mensile del fatturato di un anno; - vendite, acquisti e relativo saldo di un anno; - il totale fatturato di un anno con il dettaglio dei 12 mesi. Se l'utente non specifica l'anno, usa l'anno corrente. ## Esempi di richieste che può fare l'utente - "Mostrami il fatturato del 2026"; - "Mostrami il fatturato mese per mese del 2026"; - "Com'è andato il fatturato quest'anno mese per mese?" - "Quanto ho fatturato nel 2026?" - "Qual è stato il mese migliore e quello peggiore del 2026?" ## Quando non usare questo tool Non usare questo tool: - per confrontare più anni o per mostrare il saldo progressivo: in questo caso usa invece il tool `report_fatturato_confronto`; - per elencare singole fatture o documenti: in questo caso usa invece il tool `ricerca_documenti`; - quando l'utente ti chiede di mostrare i suoi ricavi, costi e margini in base alle specifiche voci di Piano dei Conti (centri di ricavo e centri di costo): in questo caso usa invece il tool `report_bilancino`. ## Esempio di utilizzo ```json { "anno": "2026" } ## Esempio di output Di seguito trovi l'esempio; è mostrato solo il primo elemento. Il campo "mese" che troverai nei singoli item dell'array sta ad indicare il mese (ad esempio,troverai scritto "GENNAIO". [ { "mese": "GENNAIO", "vendite_imponibile": 5506.82, "vendite_non_imponibile": 0.0, "vendite_imponibile_fe": 0.0, "vendite_non_imponibile_fe": 0.0, "vendite_iva": 1211.5, "vendite_inps": 0.0, "vendite_cassa": 0.0, "vendite_ra": 0.0, "vendite_rp": 0.0, "vendite_entrate": 3000.0, "acquisti_imponibile": 420.0, "acquisti_non_imponibile": 0.0, "acquisti_iva": 92.4, "acquisti_inps": 0.0, "acquisti_cassa": 0.0, "acquisti_ra": 0.0, "acquisti_rp": 0.0, "acquisti_uscite": 250.0, "tributi": 0.0, "buste_paga_uscite": 0.0, "tributi_uscite": 0.0 } ]

# Report Fatturato Confronto Questo tool è di tipo aggregato e consente di confrontare l'andamento dell'attività dell'utente tra due o più anni. A seconda del valore del parametro di ricerca `tipoDocumento` che si invia al server, il tool restituisce tre diversi tipi di resoconto, alternativi tra loro: - "fatturato" in entrata proveniente dalle vendite; - oppure, "fatturato" in uscita proveniente dagli acquisti; - oppure, importi in uscita provenienti dai tributi. Il tool restituisce i dati di ciascun resoconto suddivisi per mesi. ## Parametri di ricerca in input I parametri di ricerca sono: - `anni`: obbligatorio, rappresenta la lista degli anni separati da virgola, sotto forma di stringa (ad esempio, "2026,2025,2024"); - `tipoDocumento`: opzionale (di default il valore è `vendita`); - `mostra_saldo_progressivo`: opzionale. ### Parametro `tipoDocumento` I possibili valori sono: - `vendita`: fa restituire i valori relativi alle vendite; - `acquisto`: fa restituire i valori relativi agli acquisti (cone anche le buste paga); - `tax`: fa restituire i valori relativi ai tributi. ### Parametro `mostra_saldo_progressivo` Può avere i seguenti valori: - `no`: fa restituire i valori mensili "secchi" (cioè quelli conswguiti nel singolo mese in sé considerato); - `si`: fa restituire i valori mensili "progressivi" (cioè il valore di ogni singolo mese è determinato sommando gli importi relativi a quel mese all'importo totale dei mesi precedenti); Il valore di default considerato dal tool è (in caso di assenza o irregolarità del parametro) `no`. Se usi il valore `si`, fai presente sempre all'utente nelle tue risposte che i valori che gli mostri sono appunto quelli "progressivi" mese per mese e non quelli secchi dei singoli mesi in sé considerati. ## Criteri funzionali e temporali usati dal tool per restituire i risultati Il server MCP di Fattura24, per compilare i singoli anni, estrae i dati dai seguenti documenti presenti nell'account dell'utente nel gestionale Fattura24: - fatture (elettroniche ed analogiche); - parcelle; - ricevute; - corrispettivi; - buste paga (queste, naturalmente, considerate solo per i dati del fatturato acquisti); - tributi (considerati solo per il resoconto sui tributi) Tieni conto che l'utente in Fattura24 può però esludere (nella sezione "configurazione/avanzate/report") alcune classi documentali dalla composizione dei report; se ad esempio in quella sezione di configurazione ha escluso le ricevute di vendita, allora i report di Fattura24, compreso questo tool, non prenderanno in considerazione gli importi contenuti nelle ricevute di vendita. Gli importi considerati: - sono naturalmente quelli al netto dell'IVA; - per quanto riguarda le buste paga, sono determinati considerando l'importo che l'utente indica nel campo "Importo lordo" della scheda della busta paga. Il server, infine, per decidere se estrarre i dati da un certo documento verifica se l'anno che l'utente ha indicato nel campo "competenza" del documento è lo stesso dell'anno richiesto con il parametro `anni` (non considera quindi la semplice data del documento). ### Perché il tool si chiama "fatturato" Il tool si chiama così perché considera e mostra degli importi per il solo fatto di essere stati "fatturati" (dallo stesso utente o dai suoi fornitori), ovverosia inseriti in documenti presenti nell'account dell'utente in fattura24 (se rientranti in uno degli anni indicati nella ricerca). Ciò significa che i dati vengono mostrati a prescindere se gli importi indicati in un documento sono stati poi effettivamente pagati o meno (dal cliente dell'utente verso l'utente, oppure dall'utente verso il suo fornitore). Anche gli importi dei tributi sono considerati a prescindere se l'utente ha indicato o meno la data di saldo. ## Output - struttura di risposta La risposta JSON ha una struttura che contiene un array, che, all'itnerno, ha 12 item, uno per ogni mese dell'anno. Ogni item (si chiama `mese`) han i seguenti sotto-campi: - `numero`: ad esempio, "1" sta per Gennaio; - `nome`: il nome del mese (ad esempio, "Gennaio"); - `valori`: è un array, con all'interno un valore (espresso in Euro) per ognuno degli anni oggetto del parametro di ricerca `anni`. ## Quando puoi usare questo tool Puoi usare questo tool quando l'utente ti chiede di mostrargli il confronto tra due o più anni dei suoi dati "riepilogativi" di fatturato (lato vendite o lato acquisti). ## Quando non devi usare questo tool Se l'utente ti chiede un report relativo al suo fatturato (vendite e acquisti) che, però, chiarisca anche la composizione interna dei dati (importi imponibili reddito, importi non imponibili reddito, importi dei contributi Inps o della Cassa), allora devi usare il diverso tool `report_fatturato`, che mostra i dati solo anno per anno, ma che, appunto, chiarisce quali sono le sotto-componenti degli importi totali (mese per mese) di fatturato. Inoltre, non devi usare questo tool, quando l'utente ti chiede di mostrare i suoi ricavi, costi e margini in base alle specifiche voci di Piano dei Conti (centri di ricavo e centri di costo): in questo caso usa invece il tool `report_bilancino` (sempre che l'utente abbia almeno un abbonamento Compelte a Fattura24 e abbia correttamente applicato le voci di piano dei conti alle singole linee in fattura). ## Esempio di utilizzo ```json { "anni": "2026, 2025, 2024", "tipo_documento": "vendita", "mostra_saldo_progressivo": "si" } Esempio con solo il 2026: { "anni": "2026" } Esempio con saldo progressivo: { "anni": "2026, 2025", "mostra_saldo_progressivo": "si" } { "mese": [ { "numero": 1, "nome": "Gennaio", "valori": [5506.82, 4200.15, 3800.00] }, { "numero": 2, "nome": "Febbraio", "valori": [4800.50, 3900.25, 4100.75] } ], "legenda": ["2026", "2025", "2024"] }

# Report Forecast Questo tool è di tipo aggregato e restituisce il "Report Previsionale" della sezione "Bilancino" che l'utente ha a disposizione in Fattura24 (all'interno della macro-sezione di menu "Controllo di Gestione"). Questo strumento permette di confrontare, per ogni voce di centro di ricavo e di centro di costo creata dall'utente nel suo Piano dei Conti, in relazione ad uno specifico anno: - i valori di consuntivo reali conseguiti (actual); - i valori previsionali che lo stesso utente aveva predefinito (budget); - gli scostamenti tra consuntivo e budget. L'uso combinato del Piano dei Conti e di questo report consente quindi di confrontare l'andamento reale dell'attività rispetto alle previsioni impostate. ## Parametri di ricerca in input I parametri da usare sono: - `anno`: è obbligatorio, rappresenta l'anno di competenza e deve essere espresso nel formato YYYY. ## Requisiti prelininari perché il tool dia risultati utili Il tool `report_bilancino` restituirà risultati utili solo se: - l'utente ha un abbonamento "Complete" a Fattura24; - l'utente ha costruito nel gestionale Fattura24 un suo "Piano dei conti" e lo ha correttamente applicato di volta in volta alle sue fatture di vendita e di acquisto; - l'utente ha effettivamente pre compilato i dati previsionali. ## Output - struttura di risposta La risposta JSON ha una struttura composta dai seguenti campi complessi: - `meta`; - `dettagli`; - `totali`; - `indicatori`. ### Campo `dettagli` Questo campo è un array composto da tutte le voci di centro di ricavo o di costo dell'utente costruite da lui nel Piano dei Conti. Ognuno degli item ha i seguenti campi: - `id_pdc`: è l'identificativo dello specifico centro di ricavo o di costo nel gestionale Fattura24; - `codice_pdc`: è il codice dato dallo stesso utente allo pecifico centro di ricavo o di costo; - `descrizione_pdc`: è il nome dato dallo stesso utente allo pecifico centro di ricavo o di costo;; - `tipo_voce`: specifica se si tratta di un centro di ricavo o di un centro di costo, con valori che possono essere `ricavo`, `costo_fisso` o `costo_variabile`; - `totale_consuntivo_annuale`: indica, in Euro, il totale annuale degli importi conseguiti o sostenuti dall'utente per lo specifico centro di ricavo o di costo; - `consuntivo_mensile`: è un campo di tipo oggetto, che al suo interno contiene 12 campi, uno per ogn i mese dell'anno, i cui valori sono gli importi mensili in Euro relativi allo specifico centro di ricvo o di costo; - `totale_budget_annuale`: indica, in Euro, il totale annuale degli importi che l'utente aveva preventivato di conseguire o sostenere per lo specifico centro di ricavo o di costo; - `budget_mensile`: è un campo di tipo oggetto, che al suo interno contiene 12 campi, uno per ogni mese dell'anno, i cui valori sono gli importi mensili in Euro preventivati dall'utente come budget relativi allo specifico centro di ricvo o di costo; - `scostamento_annuale`: scostamento tra budget e consuntivo in relazione al volume complessivo nell'anno; - `scostamento_mensile`: scostamento tra budget e consuntivo in relazione al singolo mese. I campi complessi di tipo oggetto `consuntivo_mensile`, `budget_mensile` e `scostamento_mensile` hanno la seguente struttura: - `gennaio` - `febbraio` - `marzo` - `aprile` - `maggio` - `giugno` - `luglio` - `agosto` - `settembre` - `ottobre` - `novembre` - `dicembre` #### Composizione dei singoli valori mensili - non sono valori progressivi ATTENZIONE: i valori mensili di ogni voce sono calcolati a sé stanti e non rappresentano quindi un cumulato progressivo. Ad esempio, se per una particolare voce di centro di ricavo il valore di aprile è "1200", significa che l'utente nel solo mese di aprile ha conseguito ricavi, per quella voce di centro di ricavo, pari a Euro 1200,00 (e ciò a prescindere appunto da quanto ha conseguito per la stessa voce nei mesi precedenti). ### Campo `totali` Questo campo è un oggetto che contiene i totali progressivi annuali e mensili, inseriti nei seguenti ulteriori campi complessi: - `totale_ricavi`; - `totale_costi_variabili`; - `totale_costi_fissi`; - `totale_costi`; - `mdc`; - `ebitda`. Ognuno dei detti campi riporta il totale annuale e i totali dei singoli mesi dell'anno, con la seguenti struttura: - `totale_consuntivo_annuale`; - `consuntivo_mensile`; - `totale_budget_annuale`; - `budget_mensile`; - `scostamento_annuale`; - `scostamento_mensile`. #### Nota sul campo complesso ebitda I valori rappresentano il "margine operativo lordo", che può essere considerato come Ebitda se ricavato come risultato dopo gli accantonamenti (dpiende da come l'utente usa il gestionale Fattura24); in ogni caso, i valori sono considerars il risultato prima di ammortamenti, svalutazioni, oneri finanziari e imposte. ### Campo `indicatori` E' un oggetto che è composto da 3 campi che servono ad indicare 3 importanti indicatori economici (espressi in Euro), ricavati dai dati del report: - `scostamento_ricavi_su_budget`; - `scostamento_costi_su_budget`; - `scostamento_ebitda_su_budget`. ## Criteri funzionali e temporali usati dal tool per restituire i risultati Il server MCP di Fattura24, per compilare i dai di consuntivo e per controllare così se (e in che misura) uno specifico centro di ricavo o centro di costo è stato conseguito o sostenuto nel corso di un dato anno, va a vedere i seguenti documenti: - fatture (elettroniche ed analogiche); - parcelle; - ricevute; - corrispettivi; - buste paga. Questo tool non considera invece i Tributi: se l'utente vuole sapere quanti sono i tributi pagati nel corso di un anno, devi usare il diverso tool `report_tributi`. Tieni conto che l'utente in Fattura24 può però esludere (nella sezione "configurazione/avanzate/report") alcune classi documentali dalla composizione dei report; se ad esempio in quella sezione di configurazione ha escluso le ricevuite di vendita, allora i report di Fattura24, compreso questo tool, non prenderanno in considerazione gli importi contenuti nelle ricevute di vendita. Gli importi considerati: - sono naturalmente quelli al netto dell'IVA; - per quanto riguarda le buste paga, sono determinati considerando l'importo che l'utente indica nel campo "Importo lordo" della scheda della busta paga; - sono considerati per il solo fatto di essere presenti nei documenti creati dall'utente, a prescindere quindi se sono stati effettivamente pagati o meno (o se sono stati pagati solo in parte, anche eventualmente a seguito dell'applicazione di uno sconto generale a valle del totale netto a pagare della fattura). Per vedere infine se il documento in cui è caricato il centro di ricavo o di costo rientra nell'anno richiesto dall'utente (ad esempio, il "2026"), il server controlla se quell'anno è quello indicato nel campo "Data competenza" del documento: il criterio temporale utilizzato è quindi quello della data competenza indicata dall'utente all'interno del documento. ## Quando devi usare questo tool Usa questo tool quando l'utente chiede: - il report previsionale di bilancino; - il confronto tra valori attuali di consuntivo (actual) e quelli di budget; - gli scostamenti tra valori reali e previsionali; - il confronto mensile tra consuntivo e budget; - il dettaglio per voce PDC con budget associato. ## Quando non devi usarlo Non dovresti usare questo tool se l'utente ti chiede quali sono le sue vendite annuali in base ai "nomi" dei prodotti o servizi venduti o erogati che lo stesso utente ha creato nella sezione "Prodotti e Servizi" del gestionale Fattura24 (per questa richiesta c'è un tool specifico che si chiama `report_prodotti_servizi`). Infatti, questa sarebbe una ricerca diversa da quella soddisfatta con il presente tool, che è relativo invece, come indicato sopra, alla suddivisione per "centri di ricavo" e "centri di costo" facenti parte del Piano dei Conti. ## Esempio di risposta ```json { "meta": { "report": "bilancino_previsionale", "anno": 2026, "filtro_pdc_descrizione": null, "costi_fissi_in_dodicesimi": true, "valuta": "EUR" }, "dettagli": [ { "id_pdc": 211235, "codice_pdc": "000", "descrizione_pdc": "TEST FEDE2", "tipo_voce": "ricavo", "totale_consuntivo_annuale": 0.0, "consuntivo_mensile": { "gennaio": 0.0, "febbraio": 0.0, "marzo": 0.0, "aprile": 0.0, "maggio": 0.0, "giugno": 0.0, "luglio": 0.0, "agosto": 0.0, "settembre": 0.0, "ottobre": 0.0, "novembre": 0.0, "dicembre": 0.0 }, "totale_budget_annuale": 0.0, "budget_mensile": { "gennaio": 0.0, "febbraio": 0.0, "marzo": 0.0, "aprile": 0.0, "maggio": 0.0, "giugno": 0.0, "luglio": 0.0, "agosto": 0.0, "settembre": 0.0, "ottobre": 0.0, "novembre": 0.0, "dicembre": 0.0 }, "scostamento_annuale": 0.0, "scostamento_mensile": { "gennaio": 0.0, "febbraio": 0.0, "marzo": 0.0, "aprile": 0.0, "maggio": 0.0, "giugno": 0.0, "luglio": 0.0, "agosto": 0.0, "settembre": 0.0, "ottobre": 0.0, "novembre": 0.0, "dicembre": 0.0 } } ], "totali": { "totale_ricavi": { "totale_consuntivo_annuale": 0.0, "consuntivo_mensile": {}, "totale_budget_annuale": 0.0, "budget_mensile": {}, "scostamento_annuale": 0.0, "scostamento_mensile": {} }, "totale_costi_variabili": { "totale_consuntivo_annuale": 0.0, "consuntivo_mensile": {}, "totale_budget_annuale": 0.0, "budget_mensile": {}, "scostamento_annuale": 0.0, "scostamento_mensile": {} }, "totale_costi_fissi": { "totale_consuntivo_annuale": 0.0, "consuntivo_mensile": {}, "totale_budget_annuale": 0.0, "budget_mensile": {}, "scostamento_annuale": 0.0, "scostamento_mensile": {} }, "totale_costi": { "totale_consuntivo_annuale": 0.0, "consuntivo_mensile": {}, "totale_budget_annuale": 0.0, "budget_mensile": {}, "scostamento_annuale": 0.0, "scostamento_mensile": {} }, "mdc": { "totale_consuntivo_annuale": 0.0, "consuntivo_mensile": {}, "totale_budget_annuale": 0.0, "budget_mensile": {}, "scostamento_annuale": 0.0, "scostamento_mensile": {} }, "ebitda": { "totale_consuntivo_annuale": 0.0, "consuntivo_mensile": {}, "totale_budget_annuale": 0.0, "budget_mensile": {}, "scostamento_annuale": 0.0, "scostamento_mensile": {} } }, "indicatori": { "scostamento_ricavi_su_budget": 0.0, "scostamento_costi_su_budget": 0.0, "scostamento_ebitda_su_budget": 0.0 } }