# Tasse e scadenze (https://docs.getbeel.com/it/api/taxes)

Lo scadenzario fiscale della tua azienda italiana, come JSON o come calendario .ics, e la stima della posizione IVA.

Getbeel calcola le scadenze fiscali dell'azienda a partire dal profilo (paese, regime fiscale) e da due impostazioni che scegli una volta, nell'app (**Tasse**) o con `PATCH /companies/me/tax-settings`: IVA mensile o trimestrale (`vat_periodicity`), se l'azienda paga compensi a professionisti con ritenuta (`withholding_agent`) e, per chi è iscritto all'OSS (IVA sulle vendite B2C a consumatori di altri Paesi UE), le date dell'iscrizione (`oss_from`, `oss_until`; `null` le cancella). È la stessa lista della pagina **Tasse → Scadenze**.

Scope: `taxes:read`. Disponibile solo per aziende italiane.

```bash
curl -X PATCH https://www.getbeel.com/api/v1/companies/me/tax-settings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vat_periodicity": "quarterly" }'
```

Per cambiarle servono `taxes:write` e una chiave live; un `PATCH` cambia solo quello che invia, e `GET /companies/me/tax-settings` le legge (`null` = non ancora impostata). Imposta la periodicità come l'azienda liquida davvero l'IVA: decide i periodi IVA dei registri, delle liquidazioni e degli F24. Strumenti MCP: `get_tax_settings`, `update_tax_settings`.

<Callout title="Getbeel prepara, tu paghi">
  Getbeel non accede mai alla tua area riservata dell'Agenzia delle Entrate e
  non paga per te. Prepara gli importi e l'F24 (vedi
  [Adempimenti](/it/api/filings)); il pagamento lo fai tu, in F24 web o dalla
  tua banca.
</Callout>

## Profilo fiscale [#profilo-fiscale]

Ogni azienda paga tasse diverse. Il profilo fiscale dice quali si applicano e perché: forma giuridica, regime fiscale, periodicità IVA, sostituto d'imposta, dipendenti, fornitori esteri (reverse charge), Intrastat, OSS, liquidazione, primo anno d'imposta e, per le persone fisiche, previdenza e regimi speciali (forfettario, impatriati, rientro docenti, neo-residenti). È la stessa scheda di **Tasse → Il tuo profilo fiscale** nell'app. Gratuito con ogni piano.

```bash
curl https://www.getbeel.com/api/v1/companies/me/tax-profile \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Getbeel rileva quello che può dai dati che ha già, e mostra la prova in `detection.fields.<campo>` (`value`, `confidence`, `evidence.key` ed `evidence.params`):

| Campo                      | Rilevato da                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| `legal_form`               | La ragione sociale (S.r.l., S.p.A., …); un codice fiscale personale è solo un indizio    |
| `regime_fiscale`           | Il profilo aziendale (il codice RF di ogni fattura emessa)                               |
| `vat_periodicity`          | Il volume d'affari dell'anno prima: oltre 800.000 € è mensile (art. 7 DPR 542/1999)      |
| `withholding_agent`        | Ritenute registrate negli ultimi 12 mesi                                                 |
| `reverse_charge_suppliers` | Fatture ricevute da fornitori fuori Italia                                               |
| `intrastat`                | Vendite a imprese di altri Paesi UE                                                      |
| `oss_suggested`            | Vendite a consumatori di altri Paesi UE oltre 10.000 € l'anno (art. 7-octies DPR 633/72) |
| `in_liquidation`           | "in liquidazione" nella ragione sociale                                                  |

Mai un'ipotesi silenziosa: un valore che imposti tu vince sempre (`sources.<campo>` = `user`); una rilevazione ad alta confidenza viene usata (`detected`); tutto il resto resta `null` ed è elencato in `questions`, ciascuno con una domanda semplice da fare una volta all'utente. Dipendenti, iscrizione all'OSS, previdenza e regimi speciali non vengono mai presi da una rilevazione: si chiedono sempre.

```bash
curl -X PATCH https://www.getbeel.com/api/v1/companies/me/tax-profile \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "has_employees": true, "oss_registered": true, "confirm": ["legal_form"] }'
```

Un `PATCH` cambia solo quello che invia e lo segna come confermato; `null` riporta un valore alla rilevazione; `confirm` conferma i valori rilevati così come sono; `regimes` sostituisce i regimi speciali (`[]`: nessuno). `POST /companies/me/tax-profile/detect` ripete subito la rilevazione.

Ogni mese (il giorno 2) getbeel ripete la rilevazione per ogni azienda che l'ha già fatta. Un nuovo obbligo (ritenute, fornitori esteri, Intrastat) viene applicato e segnalato nell'app ("Nuovo obbligo: …"). Una modifica che toglierebbe o cambierebbe una scadenza (per esempio nessuna ritenuta negli ultimi 12 mesi, IVA mensile invece che trimestrale, o una forma giuridica diversa) **non viene mai applicata da una rilevazione**, mensile o `POST …/detect`: resta il valore precedente e il campo riporta `held` (`value`, `confidence`, `evidence`, `since`: cosa dicono i nuovi dati). Il titolare riceve un avviso nella sua lingua e l'app mostra il campo come "Da verificare". Solo la tua risposta lo cambia: un `PATCH` con il valore, o `confirm` per tenere quello precedente. Per cambiare il profilo e ripetere la rilevazione servono `taxes:write` e una chiave live; ogni modifica va nel registro attività con la chiave e il canale (API o MCP). Strumenti MCP: `get_tax_profile`, `update_tax_profile`, `detect_tax_profile`.

Quando un regime speciale finisce entro un anno (l'ultimo giorno è `effect.ends_year` di ogni regime, o il suo `valid_until` se prima), i titolari e i commercialisti ricevono un'email e l'app mostra un avviso ("Impatriati (regime precedente al 2024): finisce il 31 dicembre 2027, dal 2028 non si applica più"): una volta circa un anno prima e una volta un mese prima. La fine dell'aliquota ridotta del forfettario è annunciata allo stesso modo, con le due aliquote dai valori delle regole (oggi 5% e poi 15%).

Il profilo cambia lo scadenzario: le scadenze che non si applicano non compaiono, e ognuna dice perché si applica in `applies_because`.

## Lo scadenzario [#lo-scadenzario]

```bash
curl "https://www.getbeel.com/api/v1/companies/me/tax-calendar?from=2026-10-01&to=2027-03-31" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Senza `from` e `to`: da 90 giorni fa a un anno da oggi (al massimo tre anni).

| Tipo (`kind`)        | Cosa                                                                                          | Codici tributo                                         | Fonte                                                        |
| -------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| `bollo`              | Imposta di bollo sulle fatture elettroniche, trimestre                                        | 2521–2524                                              | Art. 6 DM 17/06/2014; Ris. AdE 42/E/2019                     |
| `withholdings`       | Ritenute sui compensi ai professionisti e, con dipendenti, sugli stipendi, mese               | 1040; 1001                                             | Artt. 23, 25 DPR 600/1973; art. 18 D.Lgs. 241/97             |
| `vat_payment`        | Versamento IVA mensile o trimestrale                                                          | 6001–6012, 6031–6033                                   | DPR 100/1998; art. 7 DPR 542/1999                            |
| `vat_advance`        | Acconto IVA (27 dicembre)                                                                     | 6013, 6035                                             | Art. 6 L. 405/1990                                           |
| `vat_annual_balance` | Saldo IVA annuale (16 marzo)                                                                  | 6099                                                   | Art. 6 DPR 542/1999                                          |
| `lipe`               | Comunicazione liquidazioni periodiche IVA                                                     | –                                                      | Art. 21-bis DL 78/2010                                       |
| `vat_return`         | Dichiarazione IVA annuale (30 aprile)                                                         | –                                                      | Art. 8 DPR 322/1998                                          |
| `pf_tax_return`      | Dichiarazione Redditi PF di una persona fisica (31 ottobre; 2 novembre 2026)                  | –                                                      | Art. 2 c. 1 DPR 322/1998                                     |
| `pf_tax_balance`     | Persona fisica: saldo + primo acconto (30 giugno; 20 luglio 2026 per ISA, forfettari, minimi) | 4001, 3801, 3844, 4033, 3843 / 1792, 1790 / 1795, 1793 | Art. 17 DPR 435/2001; DL 89/2026 art. 6                      |
| `pf_tax_advance`     | Persona fisica: secondo acconto (30 novembre)                                                 | 4034 / 1791 / 1794                                     | Art. 17 c. 3 DPR 435/2001                                    |
| `oss_return`         | Dichiarazione e versamento OSS, per trimestre (solo OSS)                                      | – (Portale OSS)                                        | Artt. 369f, 369i Dir. 2006/112/CE; art. 74-sexies DPR 633/72 |

Ogni scadenza ha:

- `due_date`: la data vera. Sabato, domenica e festivi slittano al primo giorno lavorativo; dal 1° al 20 agosto si paga entro il 20 agosto. `nominal_due_date` è la data indicata dalla legge. Quando una proroga pubblicata sposta la scadenza, `due_date` è la nuova data ed `extension` riporta la fonte ufficiale (`source_title`, `source_url`); altrimenti `extension` è `null`.
- `amount` e `amount_status`: l'imposta di bollo è calcolata dalle fatture emesse (`provisional` finché il trimestre non è chiuso). Gli importi IVA sono `null` finché non salvi la liquidazione; una liquidazione salvata senza niente da pagare rende la scadenza `not_due`.
- `status`: `to_prepare`, `ready` (F24 preparato), `paid`, `filed` o `not_due` (nessun bollo dovuto nel trimestre, o niente IVA da versare).
- `can_prepare` e `filing_type`: se Getbeel può preparare l'adempimento: F24 di bollo, ritenute e IVA (`vat_payment`, a periodo chiuso) e il file LIPE (`lipe`).
- `needs_review`: per i regimi IVA speciali la regola generale potrebbe non valere. Controllala ("da verificare").
- `source`: la norma da cui viene la scadenza.
- `applies_because`: perché si applica a questa azienda, dal profilo fiscale, come chiavi con parametri: `issues_e_invoices`, `vat_monthly`, `vat_quarterly`, `vat_payer` (`regime`), `withholding_agent`, `has_employees`, `oss_registered`, `oss_sales` (`countries`).
- `review_key`: `in_liquidation` quando l'azienda è in liquidazione e la scadenza cade da quella data: verificala con il liquidatore ("da verificare").
- La dichiarazione OSS mantiene la data anche di sabato o domenica (regola UE) e in quel caso è segnata `needs_review`; si paga dal Portale OSS, non con F24.

`missing_settings` elenca le impostazioni ancora da scegliere nell'app: finché mancano, le scadenze che ne dipendono non compaiono. Forfettari (RF19) e minimi (RF02) non hanno scadenze IVA.

### OSS (vendite B2C nell'UE) [#oss-vendite-b2c-nellue]

Con `oss_from` impostato, lo scadenzario aggiunge `oss_return` per ogni trimestre dell'iscrizione: la dichiarazione OSS trimestrale e il relativo versamento, entro l'**ultimo giorno del mese successivo al trimestre** (30 aprile, 31 luglio, 31 ottobre, 31 gennaio), anche senza vendite (dichiarazione a zero). Fonti: Direttiva 2006/112/CE artt. 369f e 369i, Regolamento (UE) 282/2011 art. 59a, DPR 633/72 artt. 74-quinquies e 74-sexies.

- La data **non slitta** nei fine settimana o festivi: lo dice la pagina OSS della Commissione europea. L'Agenzia non dice altro, quindi quando cade in un giorno non lavorativo la scadenza ha `needs_review: true` ("da verificare").
- Si paga dal Portale OSS dell'Agenzia con addebito diretto o bonifico con riferimento `IT/<partita IVA>/Qn.AAAA`, **non con l'F24**, e non si può compensare con crediti.
- Dal 2027 le regole passano al Testo unico IVA (D.Lgs. 10/2026, artt. 149–153); le date dovrebbero restare le stesse (da verificare).

### Imposte sui redditi (società) [#imposte-sui-redditi-società]

Per una società che paga l'IRES (SRL, SpA), con esercizio coincidente con l'anno solare e bilancio approvato entro 120 giorni, lo scadenzario elenca anche:

| `kind`                 | Scadenza                                                                                             | Codici F24             | Fonte                                          |
| ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------- |
| `income_tax_balance`   | Saldo IRES e IRAP + primo acconto: 30 giugno (soggetti ISA, solo 2026: 20 luglio, DL 89/2026 art. 6) | 2003, 2001, 3800, 3812 | art. 17 c. 1-2 DPR 435/2001                    |
| `chamber_fee`          | Diritto annuale camerale, con il primo acconto                                                       | 3850                   | art. 6 DM 21/04/2011                           |
| `income_tax_advance`   | Secondo acconto: 30 novembre (60%, oppure 50% per i soggetti ISA)                                    | 2002, 3813             | art. 17 c. 3 DPR 435/2001; art. 58 DL 124/2019 |
| `income_tax_return`    | Dichiarazioni Redditi SC e IRAP: 31 ottobre (2 novembre nel 2026)                                    | —                      | art. 2 c. 2 DPR 322/1998                       |
| `financial_statements` | Deposito del bilancio: 30 maggio (non slitta: è un termine civilistico)                              | —                      | artt. 2435 e 2478-bis c.c.                     |

Se la società paga l'IRES e applica gli ISA lo dice **Tasse → Stima imposte**, per anno d'imposta (`settings.income_tax`). Finché non è salvato lì non si indovina nulla: le scadenze non compaiono e `missing_settings` contiene `income_tax`. I soggetti ISA pagano entro il 21 luglio nel 2025 (DL 84/2025 art. 13) e il 20 luglio nel 2026. Le scadenze sono `needs_review` dal 2027, perché le regole dei versamenti passano al Testo unico versamenti (D.Lgs. 33/2025) e si assumono le stesse date. Il codice 3813 (secondo acconto IRAP) è nella tabella dei codici tributo dell'Agenzia (11 novembre 2026), e la dichiarazione IRAP scade lo stesso giorno di Redditi SC (DM 11 settembre 2008, art. 2 DPR 322/1998). Gli importi qui non sono ancora calcolati: vedi la stima delle imposte.

### Contributi INPS (persone fisiche con partita IVA) [#contributi-inps-persone-fisiche-con-partita-iva]

Per una persona fisica il calendario aggiunge le scadenze INPS della gestione indicata nel profilo fiscale (`social_security`):

| `kind`                   | Scadenza                                                                                                                                                                   | Causale F24                            | Fonte                                                 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------- |
| `inps_fixed`             | Artigiani / commercianti, contributi fissi sul minimale: 16 maggio, 16 agosto (pagabile entro il 20 agosto), 16 novembre, 16 febbraio dell'anno dopo. `period` è `YYYY-Qn` | AF / CF                                | art. 18 c. 1-2 D.Lgs. 241/1997; circ. INPS 14/2026 §9 |
| `inps_balance`           | Saldo dell'anno precedente + primo acconto: 30 giugno (30 luglio con lo 0,40%)                                                                                             | AP / CP; PXX o P10 (gestione separata) | art. 18 c. 4 D.Lgs. 241/1997; circ. INPS 62/2026 §3   |
| `inps_advance`           | Secondo acconto: 30 novembre                                                                                                                                               | AP / CP; PXX o P10                     | art. 18 c. 4 D.Lgs. 241/1997; circ. INPS 62/2026 §3   |
| `inps_reduction_request` | Forfettari artigiani / commercianti: domanda di riduzione del 35% entro il 28 febbraio (non slitta; `needs_review` se non è un giorno lavorativo)                          | —                                      | art. 1 c. 83 L. 190/2014; circ. INPS 14/2026 §8       |

- Una **cassa professionale** ha un proprio calendario: non viene elencato nulla. Senza gestione nel profilo non si indovina nulla.
- Nel primo anno di attività non ci sono il saldo dell'anno prima, il secondo acconto e la domanda del 28 febbraio (una nuova attività chiede il 35% all'iscrizione). Le quattro rate fisse sono elencate: se inizi durante l'anno sono dovuti solo i mesi dall'iscrizione (circ. INPS 14/2026 §2), e il calendario, che conosce solo l'anno, non può dire quali.
- Gli importi sono nel Cassetto previdenziale INPS (rate fisse, codeline). Sopra il minimale dipendono dal reddito: vedi la stima imposte.
- PXX è l'aliquota del 26,07%, P10 quella del 24% per pensionati e iscritti ad altra forma obbligatoria. Soggetti ISA e forfettari: che la proroga 2026 al 20 luglio (DL 89/2026 art. 6) valga anche per i contributi non è confermato dall'INPS, quindi si mostra il 30 giugno.
- Dal 2027 si assumono le stesse date, segnalate (`needs_review`): le regole di versamento passano al D.Lgs. 33/2025 e i commi della L. 190/2014 sul regime del 35% sono abrogati dal D.Lgs. 117/2026.

### Preparazione automatica [#preparazione-automatica]

Attiva per impostazione predefinita (`auto_prepare: true` nelle impostazioni fiscali): ogni mattina getbeel prepara l'F24 di bollo, ritenute e IVA periodica in scadenza entro `auto_prepare_days` giorni (5 di default), quando il periodo è chiuso e l'importo è noto. È come premere **Prepara** (stessi controlli, stesso webhook `filing.ready`), più una notifica nell'app. Tu controlli l'F24 e lo paghi, e puoi sempre ricalcolarlo, prepararlo a mano o caricare la quietanza. La LIPE e la dichiarazione IVA annuale richiedono chi firma e le tue risposte, quindi non vengono mai preparate in automatico; nemmeno le scadenze con `needs_review` e l'IVA di dicembre dei mensili finché l'acconto IVA non è salvato nella liquidazione. L'IVA si prepara con i dati salvati nella liquidazione (crediti riportati, acconto). Per disattivarla: `PATCH /companies/me/tax-settings` con `{"auto_prepare": false}` (oppure in **Tasse → Impostazioni**, o con lo strumento MCP `update_tax_settings`): ricevi solo i promemoria.

## Nel calendario (.ics) [#nel-calendario-ics]

Nell'app, **Tasse → Aggiungi al calendario** mostra un indirizzo privato da aggiungere a Google Calendar, Outlook o Apple Calendar:

```
https://www.getbeel.com/api/v1/companies/me/tax-calendar.ics?token=…
```

Il token sostituisce la chiave API (i calendari non possono inviare header). Chi ha l'indirizzo vede le scadenze: se lo hai condiviso per errore, rigeneralo nell'app e il vecchio smette di funzionare.

## Posizione IVA (stima) [#posizione-iva-stima]

```bash
curl "https://www.getbeel.com/api/v1/companies/me/vat-position?period=2026-Q3" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

`period` è un mese (`2026-10`) o un trimestre (`2026-Q3`).

- `sales_vat`: IVA delle fatture emesse accettate dallo SDI nel periodo. Le note di credito sottraggono; lo split payment è escluso (`split_payment_invoices`); l'IVA a esigibilità differita è a parte (`deferred_sales_vat`).
- `purchase_vat_estimate`: IVA delle fatture fornitore verificate, in euro.
- `balance_estimate`: positivo da versare, negativo a credito.

<Callout title="È una stima" type="warn">
  `reliable` è sempre `false`: Getbeel non conosce la detraibilità, il mese di
  ricezione delle fatture d'acquisto né le autofatture in reverse charge. Usala
  per farti un'idea e verificala con il commercialista. Getbeel non prepara un
  F24 IVA da questa stima.
</Callout>

Per la liquidazione vera, con il suo F24 e la LIPE, usa i [registri IVA e le liquidazioni](/it/api/vat-registers).

Conto economico, flussi di cassa, crediti per scadenza e lo ZIP per il commercialista: [Report ed export](/it/api/reports).

## Dichiarazione OSS (bozza) [#dichiarazione-oss-bozza]

Per un'azienda iscritta all'OSS, regime dell'Unione (impostazioni `oss_from` / `oss_until`), la bozza della dichiarazione trimestrale, da riportare nel Portale OSS dell'Agenzia delle Entrate:

```bash
curl "https://www.getbeel.com/api/v1/companies/me/oss-return?period=2026-Q3" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

- **Cosa conta:** le fatture emesse nel trimestre a un consumatore (senza partita IVA) di un altro paese UE, righe con Natura N7 ("IVA assolta in altro stato UE").
- **`countries`:** per paese e aliquota, imponibile e IVA all'aliquota ordinaria di quel paese alla data della fattura (banca dati TEDB della Commissione europea). L'IVA si calcola riga per riga, arrotondata al centesimo, poi si somma; `vat_country_level` è la stessa IVA calcolata una volta sul totale del paese, come può fare il portale, e `rounding_gap` è true quando differiscono di più di €0,01.
- **`corrections`:** note di credito (TD04, TD08) su vendite di un trimestre precedente, come rettifiche di quel trimestre (entro tre anni). `balances` per paese; un saldo negativo lo rimborsa quel paese (`refunds`), non si compensa con gli altri; `total_due` non è mai negativo.
- **`deadline`:** l'ultimo giorno del mese dopo il trimestre, come dicono le regole UE. Getbeel non la sposta per sabati o festivi: verifica eventuali proroghe.
- **`reference`:** il riferimento del versamento `IT/IT{partita IVA}/Q{n}.{YYYY}`. Si paga dal portale (addebito SEPA) o con bonifico alla Banca d'Italia, mai con F24 né in compensazione.
- **`nil_return`:** nessuna vendita OSS e nessuna rettifica: la dichiarazione va presentata comunque, a zero.
- **`doubtful`:** le fatture su cui decidere, con il motivo (`reason`): `n7_not_eu_consumer`, `italian_vat_to_eu_consumer`, `outside_registration`, `foreign_currency` (serve il cambio BCE dell'ultimo giorno del trimestre), `rate_unknown`, `credit_note_unlinked`, `credit_note_before_sale`, `correction_too_old`. Restano fuori dai totali.

<Callout title="Una bozza da verificare" type="warn">
  `reliable` è sempre `false`: aliquote ridotte e beni non sono ancora gestiti
  (ogni vendita conta come servizio all'aliquota ordinaria). Getbeel non invia
  né paga la dichiarazione: la presenti tu nel Portale OSS con le tue
  credenziali (non sono ammessi intermediari). Gratuito. MCP: `get_oss_return`.
</Callout>

## Webhook [#webhook]

`tax_deadline.upcoming` arriva 7 giorni e 1 giorno prima di ogni scadenza non ancora pagata, una volta per ciascuna, solo agli endpoint live. `data.object` è la scadenza con `reminder_days_before`. Vedi [Webhook](/it/api/webhooks).

`tax_deadline.insufficient_funds` arriva una volta per data di scadenza, da 5 giorni lavorativi prima, quando gli F24 in scadenza quel giorno (compresi gli importi ancora stimati dai registri) superano il saldo di ogni conto bancario collegato in euro, con saldi aggiornati da non più di 3 giorni. Le scadenze si contano in ordine e gli F24 di ognuna escono dal saldo, quindi due date vicine che insieme lo superano vengono segnalate; il bollo dei trimestri piccoli conta nel giorno in cui si paga davvero (con il secondo o il terzo trimestre). Arriva un nuovo avviso quando cambia l'importo in scadenza quel giorno. `data.object` è un `f24_funds_alert` con `due_date`, `amount_due`, `available_balance`, `shortfall`, `deadline_ids` e `bank_account_id`. I titolari del team ricevono anche un'email e una notifica nell'app. Un F24 che la banca non riesce ad addebitare viene respinto e risulta pagato in ritardo (sanzioni, art. 13 D.Lgs. 471/1997).
