# Adempimenti (F24, LIPE, dichiarazione IVA) (https://docs.getbeel.com/it/api/filings)

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](/it/api/taxes): 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.

<Callout title="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).
</Callout>

## Cosa prepara Getbeel (v1) [#cosa-prepara-getbeel-v1]

| `type`         | Periodo                                        | Importo                                                                                                                                                                     |
| -------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bollo`        | Trimestre (`2026-Q3`)                          | Calcolato da Getbeel: 2 € per fattura emessa con bollo virtuale, o senza ma con bollo dovuto (vedi sotto)                                                                   |
| `withholdings` | Mese (`2026-10`)                               | La somma delle [ritenute](/it/api/withholdings) sui compensi pagati nel mese (cod. 1040), o `amount` se non li registri in Getbeel                                          |
| `vat_payment`  | Mese o trimestre, come l'azienda liquida l'IVA | La liquidazione IVA calcolata dai [registri IVA](/it/api/vat-registers) e salvata (codici tributo 6001–6012, 6031–6033)                                                     |
| `lipe`         | Trimestre (`2026-Q3`)                          | Nessun pagamento: il file XML della Comunicazione liquidazioni periodiche IVA, dalle liquidazioni salvate del trimestre, controllato con lo schema XSD ufficiale            |
| `vat_return`   | Anno (`2026`), quando è finito                 | Il prospetto dei dati della dichiarazione IVA annuale: `amount` è il saldo da versare (VX1, codice tributo 6099). Non è il file da inviare                                  |
| `redditi_pf`   | Anno (`2026`), quando è finito                 | Solo persone fisiche: il prospetto del Modello Redditi PF dalla [stima delle imposte](/it/api/tax-tools) 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 [#preparare-un-f24]

```bash
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" }'
```

```bash
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`](/it/api/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](/it/api/vat-registers).

## LIPE: il controllo dello schema [#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](https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/liquidazioni-periodiche-iva/st-comunicazione-delle-liquidazioni-periodiche-iva); 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 [#dichiarazione-iva]

```bash
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](/it/api/vat-registers) 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.

| Quadro | Righi compilati da Getbeel                                                                                                                                              | Da dove                                        |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| VE     | VE20–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                               |
| VF     | VF2, VF3, VF11, VF13 per aliquota, VF18, VF25–VF27, VF71 (IVA ammessa in detrazione)                                                                                    | Registro acquisti e autofatture                |
| VJ     | VJ1 (TD28), VJ3 (TD17, TD19), VJ9 (TD18), VJ19                                                                                                                          | Autofatture (reverse charge)                   |
| VL     | VL1–VL4, VL23, VL25, VL30 (campi 1–3), VL32, VL33, VL36, VL38, VL39                                                                                                     | Quanto sopra, liquidazioni salvate, F24 pagati |
| VX     | VX1 (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](https://www.agenziaentrate.gov.it/portale/iva-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) [#redditi-pf-persone-fisiche]

Per una persona fisica la cui [stima delle imposte](/it/api/tax-tools) dell'anno è `forfettario`, `irpef` o `minimi`:

```bash
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):

| Regime        | Righi                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forfettario` | LM22 col. 3 ricavi, LM34 col. 3 reddito, LM35 col. 2 contributi, LM38 imponibile, LM39 imposta sostitutiva                                              |
| `minimi`      | LM2, LM5 col. 5, LM6, LM7 col. 2, LM49, LM9 col. 3, LM10, LM11 (5%)                                                                                     |
| `irpef`       | RE21 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 |
| INPS          | RR5 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 [#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.id`       | File                                  | Documento ufficiale                                                                        | Formato ufficiale        |
| -------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------ |
| `lipe:IVP18`         | XML della LIPE                        | Specifiche tecniche e XSD IVP18 (Versione 1.0), provv. AdE prot. 125654 del 14 marzo 2024  | sì                       |
| `vat_return:IVA2026` | Prospetto della dichiarazione IVA     | Modello IVA 2026 (anno d'imposta 2025), provv. AdE prot. 51732 del 15 gennaio 2026         | no: i righi da riportare |
| `redditi_pf:PF2026`  | Prospetto Redditi PF                  | Modello Redditi PF 2026 (anno d'imposta 2025), provv. AdE prot. 72078 del 27 febbraio 2026 | no: i righi da riportare |
| `f24:F24-2013`       | Promemoria F24 (bollo, ritenute, IVA) | Modello "MOD. F24 – 2013 EURO", provv. AdE del 19 giugno 2013                              | no: 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 [#i-passi-successivi]

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

| Campo         | Cosa                                                                                                                                                |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file_url`    | Il PDF promemoria F24 (`GET /filings/{id}/file`): i valori da inserire, non il modello ministeriale; per una `lipe`, il file XML                    |
| `deep_link`   | La 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_values` | I valori da copiare uno per uno: codice fiscale, codice tributo, anno, importo, saldo                                                               |
| `drafts`      | Bozze email (in italiano) per la banca o il commercialista. Getbeel non le invia: le rivedi e le mandi tu                                           |
| `steps`       | I passi, in ordine                                                                                                                                  |

## Registrare la quietanza [#registrare-la-quietanza]

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

```bash
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 [#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](https://www.cbi-org.eu/Servizi/Standard), 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 [#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`.

| Stato               | Significato                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `ready`             | Preparato, nessuna revisione richiesta                                      |
| `needs_review`      | Aspetta il commercialista                                                   |
| `changes_requested` | Rimandato indietro: vedi la cronologia                                      |
| `approved`          | Approvato: `approved_at`, `approved_by`                                     |
| `skipped`           | Da non fare: `skip_reason`; mai preparato in automatico, mai addebitato     |
| `filed`             | LIPE o dichiarazione IVA inviata: ricevuta o `filed_reference` (protocollo) |
| `paid`              | F24 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) [#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](/it/api/mcp).
