GetbeelDocs

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.

POST
/invoices

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.

Authorization

apiKey
headerAuthorizationBearer <token>

API key: gb_test_… or gb_live_…

Header Parameters

Idempotency-Key?string

Recommended. 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.

Lengthlength <= 255
Getbeel-Company?string

Act 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.

Formatuuid

Request Body

application/json
  1. body
customer*

The buyer (CessionarioCommittente): denominazione, or nome and cognome; partita_iva or codice_fiscale; address; codice_destinatario or pec for delivery

tipo_documento*string

TD01 invoice, TD04 credit note, …

Default"TD01"
Value in"TD01""TD02""TD04""TD05""TD06""TD24""TD25"
number?string

Invoice number. Omit to use the next number (test and live keys have separate sequences).

Match^(?=.*\d)[A-Za-z0-9/._-]{1,20}$
date?string

Invoice date (default: today in Italy)

Match^(?:(?:\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])))$
Formatdate
series_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?string

With tipo_documento TD04: the issued invoice this credit note credits (written to DatiFattureCollegate). POST /invoices/{id}/credit-notes copies the invoice for you.

Length1 <= length <= 100
currency*string

ISO 4217 currency code; default EUR

Match^[A-Z]{3}$
Default"EUR"
lines*array<>

Invoice lines (DettaglioLinee), 1–200

Items1 <= items <= 200
withholding?

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?string

Printed on the invoice as its Causale

Length1 <= length <= 1000

Response Body

OK

application/json
  1. response
object*string
id*string
livemode*boolean

false for sandbox invoices created with a test key

number*string

Invoice number with its suffix

tipo_documento*string
invoice_date*string
Match^(?:(?:\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])))$
Formatdate
due_date*|null
status*string

draft → sending (XML being generated and submitted) → sent (accepted by SDI) → delivered (RC), not_delivered (MC) or rejected (NS)

Value in"draft""sending""sent""delivered""not_delivered""rejected"
is_proforma*boolean
currency*string
amount_subtotal*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
amount_tax*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
amount_total*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
customer*
sdi*
payment_status*string

unpaid → partially_paid → paid, from the payments recorded (POST /v1/invoices/{id}/payments, Stripe payment links)

Value in"unpaid""partially_paid""paid"
amount_due*string

What the customer pays: amount_total less the ritenuta d'acconto and less amount_credited

Match^-?\d+\.\d{2}$
amount_credited*string

Total of the credit notes (TD04) on this invoice that SDI accepted; a fully credited invoice counts as paid

Match^-?\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*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
paid_at*|

Date of the payment that settled it

overdue*boolean

Issued, 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
Match^(?:(?:\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))$
Formatdate-time
updated_at*string
Match^(?:(?:\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))$
Formatdate-time
Example Request
curl -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"    }  ]}'
Example Response
{  "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"}