GetbeelDocs

Prepare a filing (F24, LIPE or VAT return data)

Prepares a filing for a period, or recomputes it while it is not paid or filed: bollo for a closed quarter (amount computed from the issued invoices; 422 nothing_due when no invoice needs it), withholdings for a month (the ritenute of the fees recorded in /withholdings and paid in that month, codice 1040; or send amount for fees outside getbeel; 422 nothing_due when none; the receipt locks the fees it paid), vat_payment for a closed month or quarter (saves the liquidazione computed from the VAT registers and returns its F24; 422 nothing_due, with the liquidazione saved and an unpaid F24 of the period deleted, for a credit, for up to €100 carried forward and for Q4 of quarterly payers; 409 filing_completed once the F24 is paid or the LIPE of the quarter is filed), lipe for a closed quarter (the XML of the Comunicazione liquidazioni periodiche IVA from the saved liquidazioni; 400 settlements_missing until they are saved; companies send declarant_fiscal_code; the file is checked against the official IVP18 XSD, reported in checks.xsd), vat_return for a closed year (period 2026: the data sheet of the Dichiarazione IVA, quadri VE, VF, VJ, VL and VX in whole euros, from the registers of every settlement period, the saved liquidazioni and the VAT F24 marked paid, with issues to check; previous_year_credit fills VL25; amount is the VX1 balance, F24 6099; not the telematic file). checks.ade_control_software is always not_run: the AdE control software is a desktop program the client runs. Returns next_steps (file, AdE page, values to copy, email drafts). Nothing is paid, signed or sent. Webhook filing.ready. Live keys only (403 livemode_required). Preparing is free: the filing is charged once, when it is paid or filed.

POST
/filings

Prepares a filing for a period, or recomputes it while it is not paid or filed: bollo for a closed quarter (amount computed from the issued invoices; 422 nothing_due when no invoice needs it), withholdings for a month (the ritenute of the fees recorded in /withholdings and paid in that month, codice 1040; or send amount for fees outside getbeel; 422 nothing_due when none; the receipt locks the fees it paid), vat_payment for a closed month or quarter (saves the liquidazione computed from the VAT registers and returns its F24; 422 nothing_due, with the liquidazione saved and an unpaid F24 of the period deleted, for a credit, for up to €100 carried forward and for Q4 of quarterly payers; 409 filing_completed once the F24 is paid or the LIPE of the quarter is filed), lipe for a closed quarter (the XML of the Comunicazione liquidazioni periodiche IVA from the saved liquidazioni; 400 settlements_missing until they are saved; companies send declarant_fiscal_code; the file is checked against the official IVP18 XSD, reported in checks.xsd), vat_return for a closed year (period 2026: the data sheet of the Dichiarazione IVA, quadri VE, VF, VJ, VL and VX in whole euros, from the registers of every settlement period, the saved liquidazioni and the VAT F24 marked paid, with issues to check; previous_year_credit fills VL25; amount is the VX1 balance, F24 6099; not the telematic file). checks.ade_control_software is always not_run: the AdE control software is a desktop program the client runs. Returns next_steps (file, AdE page, values to copy, email drafts). Nothing is paid, signed or sent. Webhook filing.ready. Live keys only (403 livemode_required). Preparing is free: the filing is charged once, when it is paid or filed.

Autorizzazione

apiKey
headerAuthorizationBearer <token>

API key: gb_test_… or gb_live_…

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
application/json
  1. body
type*string

bollo: stamp duty on e-invoices for a closed quarter (computed from your issued invoices). withholdings: ritenute on professionals’ fees paid in a month (codice tributo 1040), from the fees recorded in /withholdings, or the amount you send. vat_payment: the periodic VAT liquidazione of a closed month or quarter (matching the VAT periodicity), computed from the VAT registers and saved; the F24 (6001–6012, 6031–6033). lipe: the Comunicazione liquidazioni periodiche IVA of a closed quarter, from the saved liquidazioni (XML checked against the official XSD; check, sign and send it yourself). vat_return: the data sheet of the annual VAT return (Dichiarazione IVA) of a closed year: quadri VE, VF, VJ, VL, VX from the VAT registers and the saved liquidazioni, with the points to check (not the telematic file). redditi_pf: the data sheet of the Redditi PF return of a persona fisica for a closed year: the tax estimate (Tasse → Stima imposte: forfettario, irpef or minimi) placed on the quadri LM, RE, RN, RV and RR, with the saldo/acconti F24 codes (not the telematic file)

Value in"bollo""withholdings""vat_payment""lipe""vat_return""redditi_pf"
period*string

bollo, lipe: a quarter (2026-Q3); withholdings: a month (2026-10); vat_payment: a month or a quarter, as the company settles VAT; vat_return, redditi_pf: the tax year (2026)

Match^\d{4}(-(Q[1-4]|0[1-9]|1[0-2]))?$
amount?string

withholdings only: the total withheld, e.g. "200.00", for fees not recorded in getbeel. Omit to add up the recorded fees paid in the month

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

vat_payment: VAT credit of the previous period (LIPE VP8), only when that period was not saved in getbeel

previous_debt?|

vat_payment: VAT up to €100 not paid in the previous period (VP7), only when that period was not saved in getbeel

annual_credit_used?|

vat_payment: credit of the previous year used in this liquidazione (VP9)

advance?|

vat_payment, December or Q4 only: the acconto IVA due (VP13, at least 103.29)

advance_method?||||

Acconto method: 1 storico, 2 previsionale, 3 analitico, 4 special sectors

declarant_fiscal_code?|

lipe: codice fiscale of the person who signs; required for companies

declarant_role?|

lipe: codice carica of the signer (1 = legal representative, default)

previous_year_credit?|

vat_return: the VAT credit of the previous year's return still available (VL8 minus VL9; it goes in VL25)

Corpo della risposta

OK

application/json
  1. response
id*string
object*string
type*string
Value in"bollo""withholdings""vat_payment""lipe""vat_return""redditi_pf"
period*string
status*string

ready: prepared, no review asked; needs_review: waiting for the commercialista; changes_requested: sent back (see the history); approved: visto bueno (approved_at, approved_by); skipped: not to be done (skip_reason); filed: return sent (receipt or filed_reference); paid: F24 paid (receipt)

Value in"ready""needs_review""changes_requested""approved""skipped""filed""paid"
approved_at*|null
approved_by*|

User id of who approved it

skip_reason*string|null
filed_reference*|

Protocol number of a filed return (evidence without a file)

extension*|

Set when a published extension (proroga) gave the due date: the official source

file_spec*|

The official specification the filing file follows, stored when the filing was prepared (also in the Getbeel-File-Spec header of the file). null: no file (skipped before it was prepared)

due_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
amount*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
currency*string
f24_lines*array<>
details*
checks*

Checks getbeel ran on the file

needs_review*boolean
receipt*|null
completed_at*|null
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
next_steps*
Esempio di richiesta
curl -X POST 'https://www.getbeel.com/api/v1/filings' \  -H 'Content-Type: application/json' \  -d '{  "type": "bollo",  "period": "2026-Q3"}'
Esempio di risposta
{  "id": "fil_3f2a…",  "object": "filing",  "type": "bollo",  "period": "string",  "status": "ready",  "approved_at": "2019-08-24T14:15:22Z",  "approved_by": "string",  "skip_reason": "string",  "filed_reference": "string",  "extension": {    "source_title": "string",    "source_url": "string"  },  "file_spec": {    "id": "lipe:IVP18",    "file": "lipe_xml",    "name": "string",    "version": "IVP18 (schema Versione 1.0)",    "approved_by": "Provv. AdE prot. 125654 of 14 March 2024",    "source_url": "string",    "official_format": true,    "tax_year": -9007199254740991,    "other_tax_year": true,    "provisional": true  },  "due_date": "2026-10-29",  "amount": "122.00",  "currency": "EUR",  "f24_lines": [    {      "section": "erario",      "tax_code": "2523",      "reference_month": "string",      "reference_year": "2026",      "amount": "122.00"    }  ],  "details": {    "invoices": [      {        "id": "string",        "number": "string",        "date": "2026-10-29",        "list": "A"      }    ],    "pending_invoices": [      {        "id": "string",        "number": "string",        "date": "2026-10-29"      }    ],    "invoices_without_bollo_flag": -9007199254740991,    "bollo_threshold_confirmed": true,    "deferral": {      "pay_by": "september_30"    },    "settlement": {      "id": "string",      "lipe": {        "operations_active": "122.00",        "operations_passive": "122.00",        "vat_due": "122.00",        "vat_deducted": "122.00",        "vat_balance_debit": "122.00",        "vat_balance_credit": "122.00",        "previous_debt": "122.00",        "previous_credit": "122.00",        "annual_credit": "122.00",        "car_payments": "122.00",        "tax_credits": "122.00",        "interest": "122.00",        "advance": "122.00",        "advance_method": -9007199254740991,        "amount_due": "122.00",        "amount_credit": "122.00"      },      "notes": [        "string"      ]    },    "lipe": {      "year": -9007199254740991,      "quarter": -9007199254740991,      "declarant": {        "fiscal_code": "string",        "role": -9007199254740991      },      "modules": [        {          "month": -9007199254740991,          "quarter": -9007199254740991,          "lipe": {            "operations_active": "122.00",            "operations_passive": "122.00",            "vat_due": "122.00",            "vat_deducted": "122.00",            "vat_balance_debit": "122.00",            "vat_balance_credit": "122.00",            "previous_debt": "122.00",            "previous_credit": "122.00",            "annual_credit": "122.00",            "car_payments": "122.00",            "tax_credits": "122.00",            "interest": "122.00",            "advance": "122.00",            "advance_method": -9007199254740991,            "amount_due": "122.00",            "amount_credit": "122.00"          }        }      ]    },    "vat_return": {      "year": -9007199254740991,      "model": {        "name": "IVA 2026",        "tax_year": -9007199254740991,        "approved_by": "string",        "instructions_url": "string",        "technical_specs": "string"      },      "lines": [        {          "quadro": "VE",          "row": "VE23",          "field": -9007199254740991,          "code": "VE023001",          "label": "string",          "amount": -9007199254740991        }      ],      "balance": {        "to_pay": -9007199254740991,        "credit": -9007199254740991,        "tax_code": "6099"      },      "volume_d_affari": -9007199254740991,      "periods": [        {          "period": "string",          "settlement_saved": true,          "amount_to_pay": 0,          "advance": 0,          "paid": 0        }      ],      "issues": [        {          "code": "string",          "message": "string",          "items": [            "string"          ],          "taxable": 0,          "vat": 0        }      ],      "checks": [        {          "rule": "string",          "ok": true        }      ]    },    "redditi_pf": {      "year": -9007199254740991,      "entity": "forfettario",      "model": "Redditi PF 2026",      "lines": [        {          "quadro": "LM",          "rigo": "string",          "key": "string",          "label": "string",          "amount": "122.00"        }      ],      "payments": [        {          "property1": null,          "property2": null        }      ],      "balance_to_pay": 0,      "warnings": [        "string"      ],      "needs_review": true    },    "withholdings": [      {        "id": "string",        "recipient_name": "string",        "document_number": "string",        "paid_on": "2026-10-29",        "withheld_amount": "122.00"      }    ]  },  "checks": {    "xsd": {      "schema": "string",      "valid": true,      "issues": [        {          "message": "string",          "line": -9007199254740991        }      ]    },    "ade_control_software": "not_run"  },  "needs_review": true,  "receipt": {    "uploaded_at": "2019-08-24T14:15:22Z"  },  "completed_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "next_steps": {    "file_url": "string",    "deep_link": {      "url": "string",      "label": "string"    },    "other_links": [      {        "url": "string",        "label": "string"      }    ],    "copy_values": [      {        "key": "string",        "label": "string",        "value": "string"      }    ],    "drafts": [      {        "id": "bank",        "subject": "string",        "body": "string"      }    ],    "steps": [      "string"    ]  }}