# Report ed export per il commercialista (https://docs.getbeel.com/it/api/reports)

Conto economico, flussi di cassa e crediti per scadenza dai dati in Getbeel, e lo ZIP con XML, prima nota IVA e registri da dare al commercialista.

Getbeel calcola tre **report gestionali** dalle fatture e dai movimenti bancari che ha già, e prepara uno **ZIP per il commercialista** con le fatture elettroniche XML, la prima nota IVA e i registri. Sono le stesse sezioni dell'app **Tasse → IVA e report**.

Scope: `taxes:read`. L'export contiene tutte le fatture e i movimenti bancari del periodo, quindi chiede anche `invoices:read`, `received_invoices:read` e `bank:read`.

<Callout title="Dati gestionali, non il bilancio" type="warn">
  I report non sono il bilancio d'esercizio (artt. 2423 e seguenti c.c.):
  importi al netto dell'IVA, senza ratei e risconti, ammortamenti, personale,
  magazzino e imposte. `management_figures` è sempre `true` e `reliable` sempre
  `false`: mostrali come dati da verificare con il commercialista.
</Callout>

## Report [#report]

```bash
curl "https://www.getbeel.com/api/v1/companies/me/reports/profit-and-loss?period=2026" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

`GET /companies/me/reports/{type}`: `type` è `profit-and-loss`, `cash-flow` o `aging`. `period` è un anno (`2026`), un trimestre (`2026-Q3`) o un mese (`2026-10`); in alternativa `from` e `to` (al massimo due anni). Senza nulla, l'anno in corso.

La risposta ha `object: "report"`, `type`, `period`, `start`, `end`, `currency: "EUR"`, una `note` e uno fra `profit_and_loss`, `cash_flow` e `aging`. Gli importi sono stringhe decimali (`"1234.50"`).

### Conto economico (`profit-and-loss`) [#conto-economico-profit-and-loss]

- **Ricavi**: fatture emesse accettate dallo SDI (consegnate o non consegnate), per data del documento. L'importo è l'imponibile del `DatiRiepilogo` (cassa previdenziale compresa, IVA e bollo esclusi), come nei [registri IVA](/it/api/vat-registers). Le note di credito (TD04, TD08) sottraggono.
- **Costi**: fatture fornitore verificate, per data del documento, al netto dell'IVA (in euro, o al cambio per le altre valute), divise per `category`. Le note di credito sottraggono.
- **Competenza**: art. 2423-bis, c. 1, n. 3 c.c. ("si deve tener conto dei proventi e degli oneri di competenza dell'esercizio, indipendentemente dalla data dell'incasso o del pagamento"). La data del documento fa da data di competenza: è la data dell'operazione per la fattura immediata (art. 21, c. 4 DPR 633/1972) e la fine del mese per la differita (TD24, TD25). Un servizio a cavallo di due periodi non viene ripartito.
- **Non sono ricavi**: TD16–TD19 e TD28 (integrazioni in reverse charge: solo IVA, il costo è la fattura del fornitore), TD20 (autofattura di regolarizzazione: è un costo), TD21–TD23 (splafonamento, deposito IVA: solo IVA), TD26 (cessione di beni ammortizzabili: è ricavo la plusvalenza, che richiede il valore contabile), TD27 (autoconsumo e cessioni gratuite), TD29.
- `not_included` elenca quello che resta fuori: fatture ancora allo SDI, fatture fornitore da verificare, cessioni TD26, documenti in valuta senza cambio.
- `by_month` dà ricavi, costi e risultato di ogni mese.

L'IVA indetraibile, che in contabilità è un costo, non è nota a Getbeel e non viene aggiunta.

### Flussi di cassa (`cash-flow`) [#flussi-di-cassa-cash-flow]

Entrate e uscite dei conti in Getbeel (estratti conto caricati e banche collegate) per data contabile, mese per mese. Le uscite abbinate a una fattura fornitore (abbinamento approvato) sono raggruppate per la sua categoria, le altre in `unmatched`. `invoice_payments_recorded` riporta gli incassi registrati sulle fatture emesse (app, Stripe, API): sono mostrati a parte, mai sommati ai movimenti bancari.

### Crediti per scadenza (`aging`) [#crediti-per-scadenza-aging]

Quanto devono ancora i clienti **oggi** sulle fatture emesse, per giorni di ritardo: `not_due`, `overdue_1_30`, `overdue_31_60`, `overdue_61_90`, `overdue_over_90`. `period`, `from` e `to` non si usano.

- Residuo = totale del documento meno la ritenuta trattenuta dal cliente e le note di credito emesse (l'`ImportoPagamento`), meno l'IVA delle fatture in split payment, che la versa l'ente pubblico (art. 17-ter DPR 633/1972), meno gli incassi registrati.
- Senza scadenza in fattura: 30 giorni dalla data della fattura (art. 4, c. 2, lett. a, D.Lgs. 231/2002, "trenta giorni dalla data di ricevimento da parte del debitore della fattura"; la data della fattura sta per quella di ricevimento). Queste righe hanno `due_date_assumed: true`.
- `customers` somma per cliente; `invoices` elenca le fatture, le più in ritardo prima (al massimo 1.000, poi `has_more`).

## Export per il commercialista [#export-per-il-commercialista]

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

`period` è un anno, un trimestre o un mese. Solo aziende italiane. Lo ZIP contiene:

| Cartella o file               | Contenuto                                                                                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fatture-emesse/`             | Gli XML FatturaPA delle fatture emesse accettate o in attesa dello SDI, come trasmessi (nome file SDI)                                                                                     |
| `fatture-ricevute/`           | Gli XML delle fatture fornitore del periodo (per data del documento o di ricezione), come ricevuti dallo SDI o allegati; PDF e immagini in `altri-documenti/`                              |
| `autofatture/`                | Gli XML delle autofatture TD16–TD19 inviate da Getbeel                                                                                                                                     |
| `prima-nota-iva.csv`          | Una riga per documento e aliquota o natura: registro, date, numero, tipo documento, controparte, `AliquotaIVA`, `Natura`, `ImponibileImporto`, `Imposta`, totale, stato, nome del file XML |
| `registri-iva/`               | Registri IVA vendite e acquisti di ogni periodo di liquidazione (CSV), se l'azienda applica l'IVA                                                                                          |
| `banca/movimenti-bancari.csv` | I movimenti bancari del periodo con la fattura abbinata                                                                                                                                    |
| `LEGGIMI.txt`                 | Cosa c'è dentro e i file che non è stato possibile leggere                                                                                                                                 |

I CSV usano il punto e virgola, la virgola per i decimali e UTF-8 con BOM, così Excel li apre direttamente.

**Formati dei gestionali.** I gestionali dei commercialisti (TeamSystem, Zucchetti, Profis di Sistemi e gli altri) importano le fatture elettroniche dai file XML FatturaPA (Specifiche tecniche, Allegato A v1.9.1): è il formato che hanno tutti in comune. Nessuno dei tre pubblica il tracciato del proprio import di prima nota, quindi Getbeel non produce un formato proprietario e non lo inventa.

Un periodo con più di 3.000 file o 250 MB risponde `422 too_many_documents`: chiedi un trimestre o un mese.

## MCP e SDK [#mcp-e-sdk]

- MCP: `get_report` con `type` e `period` (o `from`/`to`). L'export ZIP non è uno strumento MCP: è un file binario.
- SDK TypeScript: `getbeel.taxes.report('profit-and-loss', { period: '2026' })`, `getbeel.taxes.accountantExport('2026-Q3')` (un `Blob`).
- SDK Python: `client.taxes.report("aging")`, `client.taxes.accountant_export("2026-Q3")` (byte).
- CLI: `getbeel taxes report --type cash-flow --period 2026-Q3`.
