# Note di credito, preventivi, articoli e numerazione (https://docs.getbeel.com/it/api/invoicing)

Storna una fattura con una nota di credito TD04, trasforma un preventivo in fattura, salva articoli e numera con i sezionali.

Quattro strumenti per la fatturazione di tutti i giorni, con gli stessi servizi dell'app. Scrivono con lo scope `invoices:write`, leggono con `invoices:read`. Le chiavi di test lavorano sui dati sandbox (note di credito, preventivi e articoli propri), quelle live sui dati reali.

## Modificare una bozza [#modificare-una-bozza]

`PATCH /invoices/{id}` modifica una bozza con le stesse regole della creazione e del modulo di modifica dell'app; la risposta è la fattura con i totali ricalcolati.

- Invia solo quello che cambia. Ogni campo sostituisce quella parte: `lines` sostituisce tutte le righe (inviale tutte), `customer` e `payment` si inviano interi, `notes: null` toglie la causale.
- Se la bozza ha una ritenuta o una cassa previdenziale e cambi `lines`, `withholding` o `cassa_previdenziale`, invia di nuovo anche quelle (`null` le toglie): i loro importi dipendono dalle righe. Altrimenti `400 parameter_missing`.
- Il numero di un sezionale e il tipo di una nota di credito non cambiano: un valore diverso risponde `422 invoice_invalid` (lo stesso valore è accettato), e un numero di sezionale non può passare a un altro anno (`422 invoice_invalid`); un numero scritto a mano deve seguire la sequenza dell'anno (`422 invoice_number_out_of_sequence`).
- Solo bozze: `409 invoice_not_draft` dopo l'invio, `409 invoice_send_in_progress` durante l'invio. Una fattura scartata si riapre prima ([ciclo di vita SDI](/it/api/sdi-lifecycle#scartata-ns--rejected)); una inviata si corregge con una nota di credito.

```bash
curl -X PATCH https://www.getbeel.com/api/v1/invoices/$INVOICE \
  -H "Authorization: Bearer $GETBEEL_API_KEY" -H "Content-Type: application/json" \
  -d '{"lines": [{"description": "Consulenza novembre", "quantity": "3", "unit_price": "120.00", "vat_rate": "22"}], "notes": "Novembre 2026"}'
```

In MCP: `update_invoice_draft` e `reopen_rejected_invoice`.

## Note di credito (TD04) [#note-di-credito-td04]

Una nota di credito storna una fattura che lo SDI ha accettato: tutta, oppure solo alcune righe (anche con una quantità minore).

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/$FATTURA/credit-notes \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "lines": [{ "index": 0, "quantity": 2 }], "reason": "Reso merce" }'
```

- Senza `lines` storna l'intera fattura (ritenuta, cassa e sconti compresi). Uno storno parziale li esclude: vanno ripartiti a mano.
- La nota copia cliente e dati di pagamento, richiama la fattura in `DatiFattureCollegate` (numero e data) e nasce in **bozza**: inviala con `POST /invoices/{id}/send`, come ogni fattura. Gli eventi webhook sono quelli delle fatture (`invoice.sent`, `invoice.delivered`…).
- Numero: la numerazione predefinita per le note di credito, altrimenti quella della fattura. `series_id` la sceglie.
- Le note non scartate possono sommare al massimo il totale della fattura (`422 credit_exceeds_invoice`). Una bozza, una proforma o un'altra nota non si stornano (`409`).

Quando lo SDI accetta la nota, la fattura mostra `amount_credited` e il suo `amount_due` scende: se è stornata del tutto diventa `paid`, e solleciti e scadenze ne tengono conto. Una nota scartata smette di contare.

In alternativa, `POST /invoices` con `tipo_documento: "TD04"` e `related_invoice_id` crea una nota con righe libere.

Nell'app: apri una fattura inviata e scegli **Crea nota di credito**.

## Preventivi [#preventivi]

Un preventivo ha gli stessi campi di una fattura (cliente, righe, pagamento, note) più `valid_until`. Numero per anno (`12/2026`), stati `draft` → `sent` → `accepted` o `declined`; una bozza o un preventivo inviato oltre `valid_until` risulta `expired`.

```bash
# crea
curl -X POST https://www.getbeel.com/api/v1/quotes \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "denominazione": "Rossi S.r.l.", "partita_iva": "01234567890", "email": "amministrazione@rossi.it" },
    "lines": [{ "description": "Sito web", "unit_price": "2500", "vat_rate": "22" }],
    "valid_until": "2026-12-31"
  }'

# invia il PDF al cliente
curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/send \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# accettato: diventa una bozza di fattura
curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/convert \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

- `GET /quotes/{id}/pdf` scarica il PDF. Con una chiave di test l'email arriva solo al titolare dell'account.
- `convert` crea la fattura con la data di oggi (o `date`) e il numero successivo, con le stesse regole di `POST /invoices` (per le chiavi live servono il piano SDI e la quota), e segna il preventivo accettato. Un preventivo si converte una volta sola (`409 quote_converted`).
- `POST /quotes/{id}/accept` e `POST /quotes/{id}/decline` registrano la risposta del cliente.
- `GET /quotes/{id}` legge un preventivo; `PATCH /quotes/{id}` lo modifica finché non è convertito (`409 quote_converted`) o accettato (`409 quote_not_editable`); `DELETE /quotes/{id}` lo elimina (la sua fattura, se c'è, resta).

Nell'app: **Fatture emesse → Preventivi**.

## Articoli [#articoli]

Prodotti e servizi salvati con prezzo, IVA (o natura) e unità di misura, da scegliere nelle fatture e nei preventivi.

```bash
curl -X POST https://www.getbeel.com/api/v1/items \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Consulenza", "unit_price": "80", "unit": "ore", "vat_rate": "22" }'
```

`GET /items?search=consul`, `PATCH /items/{id}` e `DELETE /items/{id}`. Le fatture già fatte non cambiano quando modifichi un articolo.

## Numerazione (sezionali) [#numerazione-sezionali]

Senza sezionali Getbeel usa la numerazione Standard: numeri semplici senza suffisso (`1`, `2`, `3`…) che ripartono da 1 ogni anno solare, come consente l'Agenzia delle Entrate (Risoluzione 1/E del 2013); se l'azienda sceglie una sequenza unica negli anni, `default_numbering.yearly_reset` è `false`. Le fatture numerate prima restano con il numero inviato allo SdI (`45/`) e la successiva prosegue senza barra (`46`). Il campo `number` di una fattura è sempre esattamente il `Numero` dell'XML. Senza `number` in `POST /invoices` il numero è assegnato per l'anno della data; un `number` numerico può essere il prossimo o colmare un buco, non saltare avanti nella sequenza dell'anno (`422 invoice_number_out_of_sequence`). Vedi la [guida alla numerazione](/it/guide/numerazione-fatture). Un sezionale aggiunge un prefisso o un suffisso (`FT-12`, `12/A`), riparte da 1 ogni anno (se non imposti `yearly_reset: false`) e ha la sua sequenza, separata tra chiavi di test e live. Un numero non viene mai riassegnato.

```bash
# elenco con il prossimo numero
curl https://www.getbeel.com/api/v1/numbering-series \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# nuovo sezionale, predefinito per le fatture (solo chiavi live)
curl -X POST https://www.getbeel.com/api/v1/numbering-series \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Estero", "suffix": "/E", "default_for_invoices": true }'
```

`POST /invoices`, `POST /quotes/{id}/convert` e le note di credito accettano `series_id` (`null` = numerazione standard). Prefisso, suffisso e azzeramento annuale non cambiano dopo la prima fattura (`409 numbering_series_in_use`); `GET /numbering-series/{id}` legge un sezionale, e `PATCH /numbering-series/{id}` lo rinomina, lo rende predefinito o lo archivia (`{ "archived": true }`), con una chiave live.

Nell'app: **Fatture emesse → Preventivi → Numerazione**, e il menu **Numerazione** nel modulo della nuova fattura.

## Con un assistente AI [#con-un-assistente-ai]

Strumenti MCP: `list_quotes`, `create_quote`, `send_quote`, `convert_quote_to_invoice`, `create_credit_note`, `list_credit_notes` e `list_items`. L'assistente chiede conferma prima di inviare un'email o di creare una nota di credito; nulla va allo SDI senza `send_invoice`.
