# Registri IVA e liquidazioni (https://docs.getbeel.com/it/api/vat-registers)

I registri IVA vendite e acquisti, la liquidazione IVA mensile o trimestrale con il suo F24 e il file della LIPE, preparati dai documenti in Getbeel.

Getbeel costruisce i **registri IVA** (vendite e acquisti) di un mese o di un trimestre dalle fatture emesse, dalle fatture fornitore e dalle autofatture che ha già, calcola la **liquidazione IVA** del periodo nelle righe della LIPE (VP2–VP14) e, da lì, prepara l'**F24** e il file della **LIPE**. Sono le stesse pagine dell'app **Tasse → Registri IVA** e **Tasse → Liquidazioni**.

Scope: `taxes:read` per leggere, `taxes:write` per salvare una liquidazione o preparare la LIPE (con [Adempimenti](/it/api/filings)). Solo aziende italiane con IVA: forfettari e minimi ricevono `400 vat_not_applicable`.

<Callout title="Da verificare" type="warn">
  Registri e liquidazioni contano solo i documenti presenti in Getbeel.
  `reliable` è sempre `false`: Getbeel non conosce la detraibilità (art.
  19-bis.1), il pro-rata, i documenti tenuti fuori, i versamenti VP10 e i
  crediti d'imposta VP11. Controlla con il commercialista prima di pagare o
  inviare. Getbeel non firma, non paga e non invia nulla.
</Callout>

Prima di tutto scegli nell'app (**Tasse → Impostazioni**) se l'azienda liquida l'IVA **mensilmente** o **trimestralmente**: senza questa scelta la liquidazione risponde `400 settings_missing`, e un periodo nel formato sbagliato (un mese per un trimestrale) risponde `400 parameter_invalid`.

## I registri IVA [#i-registri-iva]

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

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

**Registro vendite** (art. 23 DPR 633/1972):

- Fatture emesse in Getbeel e accettate dallo SDI (consegnate o non consegnate), per data del documento. Imponibile e IVA per aliquota e natura sono quelli del `DatiRiepilogo` dell'XML. Conta come emesso anche un documento il cui invio lo SDI ha scartato con `00404` perché ne aveva già accettato una copia: la riga è segnalata `needs_review` finché l'assistenza non collega l'invio accettato ([ciclo di vita SDI](/it/api/sdi-lifecycle)).
- Le note di credito (TD04, TD08) sono negative.
- Split payment (art. 17-ter): registrata ma non dovuta (`vat_counted` 0, flag `split_payment`).
- IVA a esigibilità differita (`EsigibilitaIVA` D): dovuta all'incasso (art. 6, c. 5 DPR 633/1972) e, con l'IVA per cassa, comunque dopo un anno dall'operazione (art. 32-bis DL 83/2012); la riga conta in quel periodo (`deferred_vat_collected`). Una riga che arriva al limite di un anno senza incasso è segnalata `needs_review`: il limite non vale per le cessioni dell'art. 6, c. 5, e la fattura elettronica non dice di quale caso si tratta.
- Autofatture in reverse charge TD16–TD19 e TD28 (art. 17 DPR 633/1972; artt. 46–47 DL 331/1993): l'IVA è a debito qui e, di norma, in detrazione negli acquisti, quindi compaiono in **entrambi** i registri (flag `reverse_charge`).

**Registro acquisti** (art. 25 DPR 633/1972):

- Fatture fornitore appena l'AI le ha lette, comprese quelle ricevute dallo SDI. Contano anche quelle che non hai ancora verificato, con il flag `unreviewed` sulla riga; `totals.to_review` conta le righe da controllare. I documenti rifiutati non contano mai.
- Periodo: quello di ricezione. Una fattura ricevuta entro il 15 del mese dopo l'operazione conta nel periodo dell'operazione, ma mai a cavallo d'anno (art. 1, c. 1, DPR 100/1998). La data di ricezione è nota per le fatture arrivate dallo SDI; per le altre si usa la data del documento (`late_receipt` segnala le fatture ricevute dopo).
- L'IVA addebitata da fornitori esteri non è IVA italiana: conta 0 (`foreign_vat`); la porta l'autofattura. Un fornitore di cui non si capisce il paese (nessun paese, un identificativo né italiano né con il prefisso di un paese noto) non è considerato italiano: la sua IVA conta 0, flag `country_unknown`.
- Le autofatture in reverse charge, come sopra.

Ogni riga ha `breakdown` (per aliquota e natura), `taxable`, `vat`, `vat_counted` (l'IVA che entra nella liquidazione), `counted`, `flags` e `adjustment`. I totali di ciascun registro sono in `totals` (anche per aliquota, `by_rate`).

```json
{
  "object": "vat_registers",
  "period": "2026-Q3",
  "start": "2026-07-01",
  "end": "2026-09-30",
  "currency": "EUR",
  "sales": {
    "rows": [
      {
        "key": "sales:issued_invoice:fe_3f2a…",
        "source": "issued_invoice",
        "document_id": "fe_3f2a…",
        "number": "42",
        "date": "2026-07-15",
        "received_date": null,
        "counterparty_name": "Rossi S.r.l.",
        "counterparty_vat": "IT01234567897",
        "tipo_documento": "TD01",
        "breakdown": [
          {
            "rate": "22.00",
            "natura": null,
            "taxable": "1000.00",
            "vat": "220.00"
          }
        ],
        "taxable": "1000.00",
        "vat": "220.00",
        "vat_counted": "220.00",
        "counted": true,
        "flags": [],
        "adjustment": null
      }
    ],
    "totals": {
      "documents": 1,
      "taxable": "1000.00",
      "vat": "220.00",
      "vat_counted": "220.00",
      "excluded": 0,
      "adjusted": 0,
      "by_rate": []
    }
  },
  "purchases": {
    "rows": [],
    "totals": {
      "documents": 0,
      "taxable": "0.00",
      "vat": "0.00",
      "vat_counted": "0.00",
      "excluded": 0,
      "adjusted": 0,
      "by_rate": []
    }
  },
  "missing": [
    {
      "source": "received_invoice",
      "id": "inv_…",
      "number": "A/17",
      "date": "2026-09-28",
      "name": "Fornitore S.p.A.",
      "reason": "processing"
    }
  ],
  "reliable": false,
  "note": "To check (da verificare): …"
}
```

`missing` elenca i documenti del periodo non ancora nei registri: `processing` (l'AI la sta ancora leggendo; entra da sola), `no_vat_data` (importi in valuta senza controvalore in euro), `pending_sdi` (fattura emessa ancora in attesa di esito), `autofattura_pending`, `autofattura_unreadable`, `autofattura_missing` (acquisto estero il cui TD17/TD18/TD19 non è ancora stato inviato allo SDI: entro il 15 del mese successivo; solo acquisti ricevuti da quando esistono le proposte automatiche, e non quando un TD17/TD18/TD19 inviato per lo stesso fornitore ha lo stesso numero di fattura o un importo vicino nello stesso mese o in quello adiacente).

### Escludere o correggere una riga [#escludere-o-correggere-una-riga]

Getbeel non può sapere se un acquisto è detraibile solo in parte (auto aziendali, telefonia, pro-rata) o se vuoi detrarlo più avanti. Nell'app (**Tasse → Registri IVA → Modifica**) puoi escludere una riga dalla liquidazione o indicare l'IVA che conta, sempre con un motivo. La riga mostra `adjustment` e `vat_counted` cambia di conseguenza. Per un acquisto con IVA indetraibile indica IVA 0 invece di escluderlo: le istruzioni LIPE contano gli acquisti con IVA indetraibile tra le operazioni passive (VP3). Escludi solo i documenti che non riguardano il periodo o l'azienda. Una riga a esigibilità differita non ancora dovuta non si modifica: si modifica nel periodo in cui è dovuta.

La stessa correzione dall'API, sulla `key` della riga (`register:source:document_id`). Servono `taxes:write` e una chiave live:

```bash
curl -X PUT "https://www.getbeel.com/api/v1/companies/me/vat-adjustments/purchases:received_invoice:$INVOICE_ID" \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "adjust", "vat_amount": "8.80", "reason": "Auto aziendale, IVA detraibile al 40%" }'
```

`action` è `exclude` o `adjust` (con `vat_amount`, l'IVA che conta); `reason` è obbligatorio. `DELETE /companies/me/vat-adjustments/{key}` toglie la correzione. Una riga che non è di questa azienda risponde `404`, una fonte nel registro sbagliato `400`. Una liquidazione già salvata mantiene i suoi numeri finché non la prepari di nuovo. Strumenti MCP: `set_vat_adjustment`, `remove_vat_adjustment`.

### Esportare [#esportare]

Dall'app ogni registro si scarica in CSV, Excel (XLSX) o PDF, per te o per il commercialista.

## La liquidazione IVA [#la-liquidazione-iva]

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

`period` è un mese per chi liquida mensilmente, un trimestre per chi liquida trimestralmente. La liquidazione è calcolata al momento dai registri, nelle righe della LIPE (`lipe`):

| Campo                                      | Rigo LIPE | Cosa                                                                        |
| ------------------------------------------ | --------- | --------------------------------------------------------------------------- |
| `operations_active` / `operations_passive` | VP2 / VP3 | Imponibile delle vendite e degli acquisti (senza le esclusioni art. 15, N1) |
| `vat_due` / `vat_deducted`                 | VP4 / VP5 | IVA esigibile e IVA detratta (`vat_counted` dei registri)                   |
| `vat_balance_debit` / `vat_balance_credit` | VP6       | Differenza a debito o a credito                                             |
| `previous_debt`                            | VP7       | Debito fino a 100 € del periodo precedente, non versato                     |
| `previous_credit`                          | VP8       | Credito del periodo precedente (non nel primo periodo dell'anno)            |
| `annual_credit`                            | VP9       | Credito dell'anno precedente usato in questa liquidazione                   |
| `car_payments` / `tax_credits`             | VP10/VP11 | Non noti a Getbeel: sempre `0.00`                                           |
| `interest`                                 | VP12      | Interessi dell'1% per i trimestrali (1°–3° trimestre)                       |
| `advance`, `advance_method`                | VP13      | Acconto IVA, solo a dicembre o nel 4° trimestre                             |
| `amount_due` / `amount_credit`             | VP14      | Importo da versare o a credito (`null` nel 4° trimestre dei trimestrali)    |

Le regole che Getbeel applica:

- **Minimo di versamento**: fino a 100 € non si versa e passa al periodo dopo (`carried_debt`, nota `below_minimum_carried`), ma va comunque pagato entro il 16 dicembre (mensili) o il 16 novembre (trimestrali): l'IVA di novembre, di dicembre e del 3° e 4° trimestre non si rinvia mai (art. 1, c. 4, DPR 100/1998; art. 7 DPR 542/1999, come modificati dal D.Lgs. 1/2024).
- **Credito**: un risultato negativo passa al periodo dopo (`carried_credit`, VP8 della liquidazione successiva) all'interno dello stesso anno.
- **Periodo precedente**: VP7 e VP8 vengono dal periodo precedente dello stesso anno: la sua liquidazione salvata oppure, se non è salvata, quella che Getbeel calcola dai suoi registri, risalendo l'anno. `previous` dice quale (`source`: `saved`, `computed` o `input`). Solo quando Getbeel non ha dati precedenti in quell'anno li passi tu (`previous_debt`, `previous_credit`) e trovi la nota `previous_missing`. Gli importi che passi sostituiscono quelli calcolati.
- **Interessi trimestrali**: 1% sull'importo dovuto del 1°, 2° e 3° trimestre (art. 7 DPR 542/1999), nota `interest_added`.
- **4° trimestre dei trimestrali**: si versa con il saldo annuale (cod. 6099, entro il 16 marzo, con l'1%): `amount_to_pay` è `0.00` e la nota è `paid_with_annual_balance`.
- **Acconto** (art. 6 L. 405/1990): a dicembre o nel 4° trimestre indica l'acconto versato (`advance`, almeno 103,29 €) e il metodo (`advance_method`: 1 storico, 2 previsionale, 3 analitico, 4 settori speciali).

`amount_to_pay` è quello che paga l'F24 adesso; `tax_code` e `due_date` sono il codice tributo (6001–6012 per i mesi, 6031–6033 per i trimestri) e la scadenza. `saved` è la versione salvata, con `outdated: true` se i registri sono cambiati da allora.

```json
{
  "object": "vat_settlement",
  "period": "2026-10",
  "periodicity": "monthly",
  "start": "2026-10-01",
  "end": "2026-10-31",
  "currency": "EUR",
  "lipe": {
    "operations_active": "12000.00",
    "operations_passive": "4000.00",
    "vat_due": "2640.00",
    "vat_deducted": "880.00",
    "vat_balance_debit": "1760.00",
    "vat_balance_credit": "0.00",
    "previous_debt": "0.00",
    "previous_credit": "300.00",
    "annual_credit": "0.00",
    "car_payments": "0.00",
    "tax_credits": "0.00",
    "interest": "0.00",
    "advance": "0.00",
    "advance_method": null,
    "amount_due": "1460.00",
    "amount_credit": "0.00"
  },
  "result": "1460.00",
  "amount_to_pay": "1460.00",
  "carried_debt": "0.00",
  "carried_credit": "0.00",
  "tax_code": "6010",
  "due_date": "2026-11-16",
  "notes": [],
  "inputs": {
    "previous_credit": null,
    "previous_debt": null,
    "annual_credit_used": null,
    "advance": null,
    "advance_method": null
  },
  "registers": {
    "sales": { "documents": 14, "…": "…" },
    "purchases": { "documents": 6, "…": "…" },
    "missing": 0
  },
  "saved": null,
  "reliable": false,
  "note": "To check (da verificare): …"
}
```

## Salvare la liquidazione e preparare l'F24 [#salvare-la-liquidazione-e-preparare-lf24]

Quando il periodo è chiuso, salva la liquidazione con [`POST /v1/filings`](/it/api/filings) e `type: vat_payment`:

```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": "vat_payment", "period": "2026-10" }'
```

Facoltativi: `previous_credit`, `previous_debt` (per sostituire il riporto calcolato, o quando Getbeel non ha dati precedenti in quell'anno), `annual_credit_used`, `advance` e `advance_method` (dicembre o 4° trimestre). La risposta è l'adempimento con la riga F24 e `details.settlement` (le righe LIPE). Se non c'è niente da pagare (credito, importo fino a 100 € rinviato, 4° trimestre dei trimestrali) la liquidazione viene **comunque salvata**, l'F24 preparato prima per il periodo e non pagato viene eliminato, e la risposta è `422 nothing_due`. Finché l'F24 non è pagato puoi ricalcolarla; dopo risponde `409 filing_completed`, così come quando la LIPE del trimestre è già inviata (una modifica va allora in una LIPE correttiva). `previous_debt` (VP7) è al massimo 100,00.

## La LIPE [#la-lipe]

La Comunicazione delle liquidazioni periodiche IVA (art. 21-bis DL 78/2010) si invia ogni trimestre: entro il 31 maggio, il 30 settembre, il 30 novembre e la fine di febbraio dell'anno dopo. Getbeel prepara il file XML dalle liquidazioni **salvate** del trimestre (i tre mesi, o il trimestre):

```bash
curl -X POST https://www.getbeel.com/api/v1/filings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "lipe", "period": "2026-Q3", "declarant_fiscal_code": "RSSMRA80A01F205X", "declarant_role": 1 }'
```

- Le società indicano chi firma: `declarant_fiscal_code` (codice fiscale di 16 caratteri) e `declarant_role` (codice carica, 1 = rappresentante legale).
- Se manca una liquidazione del trimestre risponde `400 settlements_missing`; codice fiscale o partita IVA dell'azienda non validi: `fiscal_code_invalid`, `vat_number_invalid`.
- Il file segue le specifiche tecniche dell'Agenzia (fornitura `IVP18`): un modulo per mese o uno per il trimestre; il 4° trimestre dei trimestrali è indicato come trimestre `5`, senza interessi né VP14. Nome del file: `IT{codice fiscale}_LI_{5 caratteri}.xml`, diverso per ogni file. Le specifiche chiedono il codice fiscale di chi trasmette: Getbeel usa quello dell'azienda, perché lo carichi dall'area dell'azienda; il commercialista che lo invia lo rinomina con il proprio.

`GET /filings/{id}/file` restituisce l'XML (`application/xml`). Poi tu lo controlli con il software di controllo dell'Agenzia, lo firmi e lo invii da "Fatture e corrispettivi" (o lo dai al commercialista). Quando carichi la ricevuta con `POST /filings/{id}/receipt` la LIPE risulta `filed` (webhook `filing.filed`).

## SDK, CLI e MCP [#sdk-cli-e-mcp]

```ts
const registers = await getbeel.taxes.vatRegisters('2026-Q3');
const settlement = await getbeel.taxes.vatSettlement('2026-10');
```

```python
registers = client.taxes.vat_registers("2026-Q3")
settlement = client.taxes.vat_settlement("2026-10")
```

```bash
getbeel taxes registers --period 2026-Q3
getbeel taxes settlement --period 2026-10
getbeel filings prepare --type vat_payment --period 2026-10
```

Con un assistente AI: `get_vat_registers`, `get_vat_settlement` e `prepare_filing` (tipi `vat_payment` e `lipe`). L'assistente mostra la liquidazione e chiede conferma prima di salvarla. Vedi [Server MCP](/it/api/mcp).

## Fonti [#fonti]

Le regole qui sopra seguono i testi ufficiali, letti il 2 novembre 2026. Verificale con il tuo commercialista: Getbeel prepara, tu invii.

- LIPE: specifiche tecniche `SpecificheIVP18_2024.pdf`, XSD `Specifiche IVP2018_SchemaIV18.zip` (versione 1.0) e istruzioni `IVA period_2024.pdf`, approvate con provvedimento dell'Agenzia delle Entrate prot. 125654 del 14 marzo 2024, su [agenziaentrate.gov.it](https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/liquidazioni-periodiche-iva). L'XSD e il software di controllo chiamano ancora VP10 `VersamentiAutoUE`; Getbeel non lo compila mai.
- Liquidazione mensile e soglia di 100 €: [art. 1 DPR 100/1998](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.del.presidente.della.repubblica:1998-03-23;100~art1) (come modificato dal D.Lgs. 1/2024).
- Liquidazione trimestrale e interessi dell'1%: [art. 7 DPR 542/1999](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.del.presidente.della.repubblica:1999-12-14;542~art7). L'1% è "calcolat[o] sugli importi da versare … relativamente alla liquidazione del trimestre" (istruzioni LIPE, rigo VP12): Getbeel lo applica all'importo del trimestre (VP6 − VP8 − VP9). Il debito riportato in VP7 resta fuori perché comprende già i suoi interessi: la soglia di 100 euro si verifica "comprensivo degli interessi dovuti dai contribuenti trimestrali" ([Istruzioni IVA 2026](https://www.agenziaentrate.gov.it/portale/iva-2026/modello-e-istruzioni), quadro VH).
- Acconto: art. 6 L. 405/1990 (entro il 27 dicembre); il minimo di 103,29 € è nelle istruzioni e nelle specifiche LIPE.
- Scadenze LIPE: art. 21-bis DL 78/2010.
- Registri e detrazione: artt. 19, 23 e 25 DPR 633/1972 (artt. 19 e 25 come modificati dal D.Lgs. 148/2026 dal 12 agosto 2026: detrazione al più tardi con la dichiarazione del secondo anno successivo); split payment art. 17-ter; esigibilità differita art. 6, c. 5 e [art. 32-bis DL 83/2012](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legge:2012-06-22;83~art32bis).
- Dal 1° gennaio 2027 gran parte di questi articoli passa al Testo unico IVA (D.Lgs. 10/2026) e al Testo unico adempimenti (D.Lgs. 141/2026); DPR 100/1998 e DPR 542/1999 restano.

Non da un testo ufficiale (da confermare con il commercialista): lasciare fuori da VP2 gli importi esclusi ex art. 15 (natura N1), e contare una vendita a esigibilità differita nel VP2 del solo periodo di emissione.
