Create a draft invoice
Creates a draft issued invoice (fattura emessa). Totals are computed by getbeel. The number defaults to the next one (separate sequences for test and live keys) and the date to today in Italy. Live keys need an SDI plan, the pay-per-use rate card or an SDI add-on, and count toward its monthly quota (402 sdi_addon_required or sdi_quota_exhausted otherwise); test keys create sandbox invoices for free.
Creates a draft issued invoice (fattura emessa). Totals are computed by getbeel. The number defaults to the next one (separate sequences for test and live keys) and the date to today in Italy. Live keys need an SDI plan, the pay-per-use rate card or an SDI add-on, and count toward its monthly quota (402 sdi_addon_required or sdi_quota_exhausted otherwise); test keys create sandbox invoices for free.
apiKeyAuthorizationBearer <token>API key: gb_test_… or gb_live_…
Idempotency-Key?stringRecommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.
length <= 255Getbeel-Company?stringAct on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.
uuidapplication/json- body
customer*The buyer (CessionarioCommittente): denominazione, or nome and cognome; partita_iva or codice_fiscale; address; codice_destinatario or pec for delivery
tipo_documento*stringTD01 invoice, TD04 credit note, …
"TD01""TD01""TD02""TD04""TD05""TD06""TD24""TD25"number?stringInvoice number. Omit to use the next number (test and live keys have separate sequences).
^(?=.*\d)[A-Za-z0-9/._-]{1,20}$date?stringInvoice date (default: today in Italy)
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$dateseries_id?|Numbering series for the automatic number (GET /numbering-series). Omit for the team's default series; null for the default numbering. Ignored when number is sent.
related_invoice_id?stringWith tipo_documento TD04: the issued invoice this credit note credits (written to DatiFattureCollegate). POST /invoices/{id}/credit-notes copies the invoice for you.
1 <= length <= 100currency*stringISO 4217 currency code; default EUR
^[A-Z]{3}$"EUR"lines*array<>Invoice lines (DettaglioLinee), 1–200
1 <= items <= 200withholding?Ritenuta d'acconto: income tax the customer withholds from the payment and pays to the State on the issuer's behalf (DatiRitenuta). Omit when there is none.
cassa_previdenziale?Cassa previdenziale: the professional's social-security contribution charged to the customer (DatiCassaPrevidenziale), e.g. the 4% INPS rivalsa. Omit when there is none.
payment?Payment terms printed on the invoice (DatiPagamento): method, terms, due date and bank details
notes?stringPrinted on the invoice as its Causale
1 <= length <= 1000OK
application/json- response
object*stringid*stringlivemode*booleanfalse for sandbox invoices created with a test key
number*stringInvoice number with its suffix
tipo_documento*stringinvoice_date*string^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$datedue_date*|nullstatus*stringdraft → sending (XML being generated and submitted) → sent (accepted by SDI) → delivered (RC), not_delivered (MC) or rejected (NS)
"draft""sending""sent""delivered""not_delivered""rejected"is_proforma*booleancurrency*stringamount_subtotal*stringDecimal amount as a string
^-?\d+\.\d{2}$amount_tax*stringDecimal amount as a string
^-?\d+\.\d{2}$amount_total*stringDecimal amount as a string
^-?\d+\.\d{2}$customer*sdi*payment_status*stringunpaid → partially_paid → paid, from the payments recorded (POST /v1/invoices/{id}/payments, Stripe payment links)
"unpaid""partially_paid""paid"amount_due*stringWhat the customer pays: amount_total less the ritenuta d'acconto and less amount_credited
^-?\d+\.\d{2}$amount_credited*stringTotal of the credit notes (TD04) on this invoice that SDI accepted; a fully credited invoice counts as paid
^-?\d+\.\d{2}$withholdings*array<>DatiRitenuta blocks: what the customer withholds and pays to the State or the fund (amount_due is net of all of them)
related_invoice_id*|Credit notes: the invoice they credit
series_id*|Numbering series (GET /numbering-series); null = the default numbering
amount_paid*stringDecimal amount as a string
^-?\d+\.\d{2}$paid_at*|Date of the payment that settled it
overdue*booleanIssued, not paid and due_date before today (Italian time)
payment_link_url*|Stripe payment link (POST /v1/invoices/{id}/payment-link)
lines?array<>Only on GET /v1/invoices/{id}
created_at*string^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timeupdated_at*string^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timecurl -X POST 'https://www.getbeel.com/api/v1/invoices' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "country": "IT" }, "tipo_documento": "TD01", "currency": "EUR", "lines": [ { "description": "Consulenza ottobre 2026", "unit_price": "100.00" } ]}'{ "object": "invoice", "id": "fe_3f1c…", "livemode": true, "number": "string", "tipo_documento": "TD01", "invoice_date": "2026-10-29", "due_date": "2026-10-29", "status": "draft", "is_proforma": true, "currency": "string", "amount_subtotal": "122.00", "amount_tax": "122.00", "amount_total": "122.00", "customer": { "name": "string", "vat_number": "string", "codice_fiscale": "string", "codice_destinatario": "string", "pec": "string", "email": "string", "country": "string", "address": "string", "postal_code": "string", "city": "string", "province": "string" }, "sdi": { "identificativo_sdi": "string", "file_name": "string", "error_message": "string", "error_codes": [ "00404" ], "errors": [ { "code": "00305", "description": "1.4.1.1.2 <IdCodice> non valido" } ], "available_since": "2026-10-31", "updated_at": "2019-08-24T14:15:22Z" }, "payment_status": "unpaid", "amount_due": "122.00", "amount_credited": "122.00", "withholdings": [ { "type": "RT01", "rate": "122.00", "amount": "122.00", "reason": "A" } ], "related_invoice_id": "string", "series_id": "0f6582ac-1e7e-41dc-a63a-24fccd074d0c", "amount_paid": "122.00", "paid_at": "2026-10-29", "overdue": true, "payment_link_url": "string", "lines": [ { "description": "string", "quantity": "1", "unit_price": "100.00", "amount": "122.00", "vat_rate": "22.00", "natura": "N2.2" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z"}