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.
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.
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
type*stringbollo: 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)
"bollo""withholdings""vat_payment""lipe""vat_return""redditi_pf"period*stringbollo, 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)
^\d{4}(-(Q[1-4]|0[1-9]|1[0-2]))?$amount?stringwithholdings 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
^-?\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)
OK
application/json- response
id*stringobject*stringtype*string"bollo""withholdings""vat_payment""lipe""vat_return""redditi_pf"period*stringstatus*stringready: 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)
"ready""needs_review""changes_requested""approved""skipped""filed""paid"approved_at*|nullapproved_by*|User id of who approved it
skip_reason*string|nullfiled_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^(?:(?:\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])))$dateamount*stringDecimal amount as a string
^-?\d+\.\d{2}$currency*stringf24_lines*array<>details*checks*Checks getbeel ran on the file
needs_review*booleanreceipt*|nullcompleted_at*|nullcreated_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-timenext_steps*curl -X POST 'https://www.getbeel.com/api/v1/filings' \ -H 'Content-Type: application/json' \ -d '{ "type": "bollo", "period": "2026-Q3"}'{ "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" ] }}