Note di credito, preventivi, articoli e numerazione
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
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:
linessostituisce tutte le righe (inviale tutte),customerepaymentsi inviano interi,notes: nulltoglie la causale. - Se la bozza ha una ritenuta o una cassa previdenziale e cambi
lines,withholdingocassa_previdenziale, invia di nuovo anche quelle (nullle toglie): i loro importi dipendono dalle righe. Altrimenti400 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_draftdopo l'invio,409 invoice_send_in_progressdurante l'invio. Una fattura scartata si riapre prima (ciclo di vita SDI); una inviata si corregge con una nota di credito.
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)
Una nota di credito storna una fattura che lo SDI ha accettato: tutta, oppure solo alcune righe (anche con una quantità minore).
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
linesstorna 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 conPOST /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_idla 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
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.
# 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}/pdfscarica il PDF. Con una chiave di test l'email arriva solo al titolare dell'account.convertcrea la fattura con la data di oggi (odate) e il numero successivo, con le stesse regole diPOST /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}/acceptePOST /quotes/{id}/declineregistrano 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
Prodotti e servizi salvati con prezzo, IVA (o natura) e unità di misura, da scegliere nelle fatture e nei preventivi.
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)
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. 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.
# 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
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.