GetbeelDocs

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: 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); 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 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

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}/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

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.

In questa pagina