GetbeelDocs

Adempimenti (F24, LIPE, dichiarazione IVA)

Prepara l'F24 dell'imposta di bollo, delle ritenute o dell'IVA, il file della LIPE o i dati della dichiarazione IVA annuale, con i valori da copiare, il link alla pagina dell'Agenzia delle Entrate e le bozze email, poi registra la quietanza.

Un adempimento (filing) è un pagamento preparato da Getbeel per una scadenza: l'importo, le righe dell'F24, un PDF promemoria e i passi successivi. Il pagamento lo fai tu, in F24 web o dalla banca; poi carichi la quietanza e l'adempimento risulta pagato.

Scope: taxes:read per leggere, taxes:write per preparare e caricare la quietanza.

Solo chiavi live

Le scadenze fiscali sono dati reali: non c'è una sandbox. Le chiavi di test possono leggere; preparare e caricare richiede una chiave live (403 livemode_required). Preparare è gratis; l'adempimento si paga una volta, quando è pagato o inviato (402 insufficient_balance se il saldo non basta).

Cosa prepara Getbeel (v1)

typePeriodoImporto
bolloTrimestre (2026-Q3)Calcolato da Getbeel: 2 € per fattura emessa con bollo virtuale, o senza ma con bollo dovuto (vedi sotto)
withholdingsMese (2026-10)La somma delle ritenute sui compensi pagati nel mese (cod. 1040), o amount se non li registri in Getbeel
vat_paymentMese o trimestre, come l'azienda liquida l'IVALa liquidazione IVA calcolata dai registri IVA e salvata (codici tributo 6001–6012, 6031–6033)
lipeTrimestre (2026-Q3)Nessun pagamento: il file XML della Comunicazione liquidazioni periodiche IVA, dalle liquidazioni salvate del trimestre, controllato con lo schema XSD ufficiale
vat_returnAnno (2026), quando è finitoIl prospetto dei dati della dichiarazione IVA annuale: amount è il saldo da versare (VX1, codice tributo 6099). Non è il file da inviare
redditi_pfAnno (2026), quando è finitoSolo persone fisiche: il prospetto del Modello Redditi PF dalla stima delle imposte dell'anno: amount è il saldo dell'anno. Non è il file da inviare

Per il bollo Getbeel segue le regole dell'Agenzia delle Entrate per gli elenchi del trimestre:

  • Elenco A: fatture inviate con bollo virtuale.
  • Elenco B: fatture senza bollo virtuale ma con righe esenti o non imponibili (Natura N2.1, N2.2, N3.5, N3.6, N4) per più di 77,47 € in totale: il bollo è dovuto sulla parte non soggetta a IVA. L'Agenzia le addebita comunque: Getbeel le conta e te le segnala (invoices_without_bollo_flag, needs_review). Se una non lo richiede, toglila dall'elenco nel portale "Fatture e corrispettivi".
  • Il trimestre è quello della consegna SDI. Le fatture ancora in attesa di esito sono in pending_invoices e non sono contate.
  • Importi piccoli: il bollo del 1° trimestre sotto i 5.000 € si può pagare entro il 30 settembre, e 1° + 2° sotto i 5.000 € entro il 30 novembre (deferral). Getbeel mantiene la scadenza normale e te lo segnala soltanto.

Non sono contate le fatture emesse fuori da Getbeel, quelle cartacee e le autofatture.

Preparare un F24

curl -X POST https://www.getbeel.com/api/v1/filings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "type": "bollo", "period": "2026-Q3" }'
curl -X POST https://www.getbeel.com/api/v1/filings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "withholdings", "period": "2026-10" }'

Per le ritenute Getbeel somma i compensi registrati in /withholdings con paid_on nel mese (la ritenuta si opera al pagamento, art. 25 DPR 600/1973) e li elenca in details.withholdings; quando carichi la quietanza quei compensi risultano versati e non si possono più modificare. Se non li registri in Getbeel invia amount con il totale trattenuto. Senza compensi né amount la risposta è 422 nothing_due.

Risposta 201 con l'adempimento in stato ready (webhook filing.ready). Chiamare di nuovo per lo stesso periodo lo ricalcola finché non è pagato; dopo risponde 409 filing_completed. Il bollo si prepara solo a trimestre chiuso (period_not_closed) e se c'è qualcosa da pagare (nothing_due).

Anche vat_payment e lipe si preparano a periodo chiuso. vat_payment salva la liquidazione anche quando non c'è niente da pagare (credito, importo fino a 100 € rinviato, 4° trimestre dei trimestrali) e risponde 422 nothing_due; lipe risponde 400 settlements_missing finché non sono salvate tutte le liquidazioni del trimestre, e le società indicano declarant_fiscal_code e declarant_role. I dati in ingresso e le regole sono in Registri IVA e liquidazioni.

LIPE: il controllo dello schema

Quando prepara una lipe, Getbeel valida l'XML con lo schema ufficiale IVP18 dell'Agenzia delle Entrate ("Specifiche IVP2018_SchemaIV18.zip", schema versione 1.0, dalla pagina delle specifiche tecniche; il provvedimento del 14 marzo 2024 non lo ha cambiato). Il risultato è in checks.xsd. Un file che non passa non viene mai salvato: la risposta è 500 file_invalid (un errore di Getbeel, segnalacelo).

checks.ade_control_software è sempre not_run. Il software di controllo dell'Agenzia ("Software di controllo Liquidazioni periodiche Iva" per la LIPE, la "procedura di controllo" per la dichiarazione IVA) è un programma Java desktop, avviato con Java Web Start, che si aggiorna a ogni avvio. Non ha una modalità da riga di comando documentata, e l'Agenzia non pubblica un servizio che controlli un file senza l'accesso del contribuente, né condizioni che permettano di usarlo come servizio per altri. Getbeel quindi non può eseguirlo per te in modo onesto: controlla ciò che può (lo schema per la LIPE; le regole aritmetiche delle specifiche per la dichiarazione IVA, sotto) e i passi ti dicono di usare il software di controllo prima dell'invio.

Dichiarazione IVA

curl -X POST https://www.getbeel.com/api/v1/filings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "vat_return", "period": "2026", "previous_year_credit": "1200.00" }'

Getbeel somma i registri IVA di ogni periodo di liquidazione dell'anno (12 mesi o 4 trimestri), le liquidazioni salvate e gli F24 IVA segnati come pagati, e restituisce i righi della dichiarazione in details.vat_return, in unità di euro come in dichiarazione, con il codice del campo delle specifiche tecniche (VE023001 = quadro VE, rigo 23, campo 1). previous_year_credit è il credito della dichiarazione dell'anno scorso ancora disponibile (VX5 meno quanto già compensato): va nel rigo VL25. Scarica il prospetto con GET /filings/{id}/file?format=csv|xlsx|json (CSV se non indichi nulla).

Non è il file da inviare. La dichiarazione telematica è un file a record di lunghezza fissa (record A, B, D, Z di 1.900 caratteri) con molte parti che Getbeel non conosce (frontespizio, VA, VC, VO, VT, firme). Compilala con il "Software di compilazione Iva" gratuito dell'Agenzia o con il software del commercialista, controllala con la procedura di controllo e inviala dalla tua area riservata o tramite un intermediario, tra il 1° febbraio e il 30 aprile (art. 8 DPR 322/1998). Il saldo si versa entro il 16 marzo con il codice tributo 6099.

QuadroRighi compilati da GetbeelDa dove
VEVE20–VE23 per aliquota (4, 5, 10, 22%), VE24–VE26, VE30–VE35 per natura, VE37 (IVA esigibile negli anni successivi), VE38 (split payment), VE39, VE50 (volume d'affari)Registro vendite
VFVF2, VF3, VF11, VF13 per aliquota, VF18, VF25–VF27, VF71 (IVA ammessa in detrazione)Registro acquisti e autofatture
VJVJ1 (TD28), VJ3 (TD17, TD19), VJ9 (TD18), VJ19Autofatture (reverse charge)
VLVL1–VL4, VL23, VL25, VL30 (campi 1–3), VL32, VL33, VL36, VL38, VL39Quanto sopra, liquidazioni salvate, F24 pagati
VXVX1 (da versare, non sotto 10,33 €), VX2 (a credito)VL38, VL39

La colonna 2 di VE20–VE23 e VF2–VF13 è l'aliquota per la colonna 1, come chiedono le specifiche; la differenza con l'IVA dei registri va in VE25 e VF26. details.vat_return.checks elenca i controlli delle specifiche che Getbeel esegue sul prospetto (tornano per costruzione; se uno fallisce è un errore di Getbeel).

Quando carichi la ricevuta la dichiarazione passa a filed, e da quel momento vat_payment e lipe di quell'anno rispondono 409 filing_completed: una modifica dopo l'invio è una dichiarazione integrativa, per il commercialista. Le vendite con IVA rettificata nei registri contano con l'IVA rettificata, come nelle liquidazioni (la differenza va in VE25). L'IVA del reverse charge interno (TD16) è nel totale VJ19 e nel saldo; il rigo lo scegli tu.

details.vat_return.issues elenca cosa controllare prima di copiare: documenti che mancano nei registri, operazioni senza un solo rigo (natura N2.2, N5, N7, acquisti senza IVA), reverse charge interno (TD16) il cui rigo VJ dipende dal caso, fornitori esteri senza autofattura, IVA indetraibile (va in VF21/VF22, Getbeel la lascia in VF1–VF13), liquidazioni non salvate, l'acconto IVA pagato fuori da Getbeel.

Quale modello. A novembre 2026 il modello per l'anno d'imposta 2026 ("IVA 2027") non è pubblicato, nemmeno in bozza. I righi seguono l'ultimo, "IVA 2026, periodo d'imposta 2025", approvato con provvedimento prot. 51732 del 15 gennaio 2026 (modello e istruzioni), con le specifiche tecniche del provvedimento prot. 50925 dell'11 febbraio 2026. details.vat_return.model dice quale; il prospetto passerà al modello 2027 quando sarà pubblicato.

Non da una fonte ufficiale (lettura di Getbeel, da verificare con il commercialista): in quale rigo va ogni codice natura (N2.1 → VE34, N3.1–N3.4 → VE30 campi 2–5, N3.5 → VE31, N3.6 → VE32, N4 → VE33, N6.1–N6.8 → VE35 campi 2–9, N6.9 → VE35 campo 1), in quale rigo VJ va ogni tipo di autofattura, e le operazioni in split payment solo in VE38 (letto dalla formula di VE50, che altrimenti le conterebbe due volte). Le istruzioni non nominano i codici FatturaPA.

Redditi PF (persone fisiche)

Per una persona fisica la cui stima delle imposte dell'anno è forfettario, irpef o minimi:

curl -X POST https://getbeel.com/api/v1/filings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "redditi_pf", "period": "2025" }'

details.redditi_pf.lines mette la stima sui righi del Modello Redditi PF 2026 (anno d'imposta 2025), come nelle istruzioni dell'Agenzia (Fascicoli 1–3):

RegimeRighi
forfettarioLM22 col. 3 ricavi, LM34 col. 3 reddito, LM35 col. 2 contributi, LM38 imponibile, LM39 imposta sostitutiva
minimiLM2, LM5 col. 5, LM6, LM7 col. 2, LM49, LM9 col. 3, LM10, LM11 (5%)
irpefRE21 col. 5 reddito (un'impresa usa il quadro RG: nessun rigo), RN1 col. 5, RN3, RN4, RN5, RN7 col. 4, RN26, RN33 col. 4, RN34, RV2 col. 2, RV10 col. 2
INPSRR5 col. 15 (gestione separata); artigiani e commercianti lo dividono nei righi RR2/RR3, quindi rigo è null
  • rigo: null vuol dire che la voce non sta in un solo rigo: l'importo è mostrato con il suo significato.
  • payments elenca saldo e acconti con i codici tributo F24; amount è il saldo dell'anno.
  • È una stima: altri redditi, familiari e oneri non sono in Getbeel. GET /filings/{id}/file?format=csv|json scarica il prospetto.
  • Una società riceve 400 redditi_pf_not_applicable.
  • Si completa come presentata con la ricevuta dell'Agenzia o il numero di protocollo (addebitata una volta, vedi Prezzi).

Quale specifica segue ogni file

Ogni adempimento preparato conserva la specifica ufficiale che segue il suo file, in file_spec (anche nell'header Getbeel-File-Spec di GET /v1/filings/{id}/file, e in MCP get_filing_file):

file_spec.idFileDocumento ufficialeFormato ufficiale
lipe:IVP18XML della LIPESpecifiche tecniche e XSD IVP18 (Versione 1.0), provv. AdE prot. 125654 del 14 marzo 2024sì
vat_return:IVA2026Prospetto della dichiarazione IVAModello IVA 2026 (anno d'imposta 2025), provv. AdE prot. 51732 del 15 gennaio 2026no: i righi da riportare
redditi_pf:PF2026Prospetto Redditi PFModello Redditi PF 2026 (anno d'imposta 2025), provv. AdE prot. 72078 del 27 febbraio 2026no: i righi da riportare
f24:F24-2013Promemoria F24 (bollo, ritenute, IVA)Modello "MOD. F24 – 2013 EURO", provv. AdE del 19 giugno 2013no: un promemoria

file_spec riporta anche nome, versione, l'atto che l'ha approvata, la pagina ufficiale (source_url) other_tax_year (una dichiarazione sul modello di un altro anno d'imposta: verifica i righi con il modello di quell'anno) e provisional (è il modello precedente perché il nuovo non è ancora pubblicato: da verificare quando esce). L'id si salva quando l'adempimento viene preparato; un file si genera solo su quella specifica, mai su un'altra versione: quando Getbeel passa a una nuova continua a generare la vecchia per gli adempimenti che la usano, e una specifica che non genera più risponde 409 file_spec_outdated. Un adempimento saltato prima di essere preparato non ha file: file_spec è null e il file risponde 409 filing_file_missing.

I passi successivi

GET /filings/{id} restituisce f24_lines (sezione Erario: codice tributo, mese e anno di riferimento, importo) e next_steps:

CampoCosa
file_urlIl PDF promemoria F24 (GET /filings/{id}/file): i valori da inserire, non il modello ministeriale; per una lipe, il file XML
deep_linkLa pagina dell'Agenzia da aprire: "Fatture e corrispettivi" per il bollo, l'area riservata (F24 web) per le ritenute. Accedi tu con SPID, CIE o CNS
copy_valuesI valori da copiare uno per uno: codice fiscale, codice tributo, anno, importo, saldo
draftsBozze email (in italiano) per la banca o il commercialista. Getbeel non le invia: le rivedi e le mandi tu
stepsI passi, in ordine

Registrare la quietanza

Dopo il pagamento carica la quietanza (PDF, PNG o JPEG, fino a 10 MB):

curl -X POST https://www.getbeel.com/api/v1/filings/$FILING_ID/receipt \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -F "file=@quietanza-f24.pdf"

L'adempimento passa a paid; una LIPE o una dichiarazione IVA, con la ricevuta dell'Agenzia, passa a filed (webhook filing.filed). La quietanza viene conservata, non letta: controlla di caricare quella giusta.

Niente file CBI F24, per ora

Le aziende con il corporate banking possono importare gli F24 come file CBI. Getbeel non lo produce: lo standard CBI "Pagamenti F24" (CBI-F24-001) è distribuito solo agli utenti registrati su cbi-org.eu, con la policy IPR del CBI, e l'unica copia pubblica trovata è un mirror di terzi non aggiornato (versione 6.15 del 2015). Il file richiede anche il codice SIA della tua azienda e un servizio F24 concordato con la banca. Finché Getbeel non lo costruisce dalla versione distribuita dal CBI, usa i valori da copiare, il promemoria PDF o la bozza email per la banca.

Revisione con il commercialista

Invita il commercialista (POST /v1/advisors o Tasse → Il tuo commercialista): da quel momento ogni adempimento preparato parte da needs_review. Il commercialista lo apre nell'app e lo approva (approved, con chi e quando), lo rimanda indietro (changes_requested, con un commento) o lo segna da non fare (skipped, con il motivo). Senza commercialista un adempimento preparato è ready.

StatoSignificato
readyPreparato, nessuna revisione richiesta
needs_reviewAspetta il commercialista
changes_requestedRimandato indietro: vedi la cronologia
approvedApprovato: approved_at, approved_by
skippedDa non fare: skip_reason; mai preparato in automatico, mai addebitato
filedLIPE o dichiarazione IVA inviata: ricevuta o filed_reference (protocollo)
paidF24 pagato: la quietanza
  • POST /v1/filings/{id}/status con status approved, skipped, needs_review (di nuovo in revisione, o riapre un adempimento saltato) o filed (con reference). Una chiave API agisce come il team: changes_requested è del commercialista, nell'app.
  • POST /v1/filings/skip con type, period e reason per una scadenza mai preparata.
  • GET /v1/filings/{id}/events è la cronologia (commenti e cambi di stato, chi e perché); POST aggiunge un commento.
  • Con approvazione del commercialista obbligatoria (impostazione require_accountant_approval, decisa da un titolare) solo il commercialista approva, e ricevuta o protocollo aspettano l'approvazione (409 approval_required).

Ogni passaggio compare anche nelle notifiche dell'app e arriva per email:

  • un adempimento da rivedere (quando viene preparato, o quando attivi l'approvazione del commercialista) → il commercialista;
  • modifiche richieste, con il commento intero → i titolari e chi ha preparato l'adempimento;
  • approvato dal commercialista → i titolari;
  • con l'approvazione del commercialista obbligatoria, un adempimento che scade entro 5 giorni lavorativi e non è ancora approvato (da rivedere, o rimandato con modifiche) → il commercialista e i titolari, una volta per adempimento e scadenza (di nuovo solo se una proroga sposta la data).

Ogni email è nella lingua di chi la riceve, porta all'adempimento e non va mai a chi ha fatto il cambiamento. Un'approvazione di un membro del team e un "da non fare" restano solo nell'app.

Webhook: filing.needs_review, filing.changes_requested, filing.approved, filing.skipped, filing.approval_due, filing.filed. MCP: get_filing, set_filing_status, skip_filing, comment_filing, list_filing_events.

Con un assistente AI (MCP)

get_tax_calendar, prepare_filing, get_filing_next_steps, record_filing_receipt, get_vat_position, get_vat_registers, get_vat_settlement e ask_accountant_question (i dati dell'azienda per una domanda fiscale, le fonti ufficiali e se serve il commercialista: Getbeel non scrive la risposta, la scrive l'assistente da quei dati). L'assistente chiede conferma prima di preparare un F24 o registrare una quietanza, e non paga né invia nulla. Vedi Server MCP.

In questa pagina