GetbeelDocs

Credit notes, quotes, items and numbering

Credit an invoice with a TD04 credit note, turn a quote into an invoice, save items and number with series.

Four everyday invoicing tools, on the same services as the app. Writes need the invoices:write scope, reads invoices:read. Test keys work on sandbox data (their own credit notes, quotes and items), live keys on real data.

Edit a draft

PATCH /invoices/{id} changes a draft with the same rules as create and the app's edit form; the answer is the invoice with its totals recomputed.

  • Send only what changes. Each field replaces that part: lines replaces every line (send them all), customer and payment are sent whole, notes: null removes the causale.
  • If the draft has a withholding or a cassa previdenziale and you change lines, withholding or cassa_previdenziale, send those again too (null removes them): their amounts depend on the lines. Otherwise 400 parameter_missing.
  • A number from a numbering series and the type of a credit note do not change: sending a different value answers 422 invoice_invalid (the same value is accepted), and a series number cannot move to another year (422 invoice_invalid); a typed number must fit the year's sequence (422 invoice_number_out_of_sequence).
  • Only drafts: 409 invoice_not_draft once it is sent, 409 invoice_send_in_progress while it is being sent. A rejected invoice is reopened first (SDI lifecycle); a sent one is corrected with a credit note.
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 and reopen_rejected_invoice.

Credit notes (TD04)

A credit note credits an invoice SDI accepted: all of it, or some lines (also with a smaller quantity).

curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE/credit-notes \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "lines": [{ "index": 0, "quantity": 2 }], "reason": "Returned goods" }'
  • Without lines it credits the whole invoice (ritenuta, cassa and discounts included). A partial credit leaves those out: split them by hand.
  • The note copies the customer and payment data, refers to the invoice in DatiFattureCollegate (number and date) and starts as a draft: send it with POST /invoices/{id}/send, like any invoice. Webhook events are the invoice ones (invoice.sent, invoice.delivered…).
  • Number: the default series for credit notes, else the invoice's series. series_id picks one.
  • Credit notes that were not rejected can add up to the invoice total at most (422 credit_exceeds_invoice). Drafts, proformas and other notes cannot be credited (409).

Once SDI accepts the note, the invoice shows amount_credited and its amount_due goes down: fully credited, it becomes paid, and reminders and overdue events take it into account. A rejected note stops counting.

Alternatively, POST /invoices with tipo_documento: "TD04" and related_invoice_id creates a note with free lines.

In the app: open a sent invoice and choose Create credit note.

Quotes

A quote has the same fields as an invoice (customer, lines, payment, notes) plus valid_until. Numbered per year (12/2026), statuses draft → sent → accepted or declined; a draft or sent quote past valid_until reads as expired.

# create
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": "accounts@rossi.it" },
    "lines": [{ "description": "Website", "unit_price": "2500", "vat_rate": "22" }],
    "valid_until": "2026-12-31"
  }'

# email the PDF to the customer
curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/send \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# accepted: it becomes an invoice draft
curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/convert \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
  • GET /quotes/{id}/pdf downloads the PDF. With a test key the email goes to the account owner only.
  • convert creates the invoice dated today (or date) with the next number, under the same rules as POST /invoices (live keys need the SDI plan and quota), and marks the quote accepted. A quote converts once (409 quote_converted).
  • POST /quotes/{id}/accept and POST /quotes/{id}/decline record the customer's answer.
  • GET /quotes/{id} reads a quote; PATCH /quotes/{id} changes it until it is converted (409 quote_converted) or accepted (409 quote_not_editable); DELETE /quotes/{id} removes it (its invoice, if any, stays).

In the app: Issued invoices → Quotes.

Items

Saved products and services with price, VAT (or natura) and unit, to pick in invoices and quotes.

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

GET /items?search=consult, PATCH /items/{id} and DELETE /items/{id}. Invoices already made do not change when you edit an item.

Numbering (series)

Without series Getbeel uses Standard numbering: plain numbers without a suffix (1, 2, 3…) restarting at 1 every calendar year, as the Agenzia delle Entrate allows (Risoluzione 1/E of 2013); if the company chose one sequence across years, default_numbering.yearly_reset is false. Invoices numbered before keep the number sent to SdI (45/) and the next one continues without the slash (46). An invoice's number is always exactly the XML Numero. Without number, POST /invoices assigns it for the year of the date; a numeric number may be the next one or fill a gap, never skip ahead of its year's sequence (422 invoice_number_out_of_sequence). See the numbering guide. A series adds a prefix or suffix (FT-12, 12/A), restarts from 1 every year (unless yearly_reset: false) and has its own sequence, separate for test and live keys. A number is never assigned twice.

# list with the next number
curl https://www.getbeel.com/api/v1/numbering-series \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# new series, default for invoices (live keys only)
curl -X POST https://www.getbeel.com/api/v1/numbering-series \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Foreign", "suffix": "/E", "default_for_invoices": true }'

POST /invoices, POST /quotes/{id}/convert and credit notes take series_id (null = the standard numbering). Prefix, suffix and yearly restart cannot change after the first invoice (409 numbering_series_in_use); GET /numbering-series/{id} reads one series, and PATCH /numbering-series/{id} renames it, makes it the default or archives it ({ "archived": true }), with a live key.

In the app: Issued invoices → Quotes → Numbering, and the Numbering menu in the new-invoice form.

With an AI assistant

MCP tools: list_quotes, create_quote, send_quote, convert_quote_to_invoice, create_credit_note, list_credit_notes and list_items. The assistant asks before sending an email or creating a credit note; nothing goes to SDI without send_invoice.

On this page