# Getbeel > Getbeel is an API and MCP server for Italian e-invoicing (FatturaPA, SDI): create, validate and send invoices, follow SDI receipts with webhooks, and test every outcome in a free sandbox. - Markdown of any page: add `.md` to its URL, e.g. https://docs.getbeel.com/en/api/quickstart.md - All pages in one file: https://docs.getbeel.com/en/llms-full.txt - OpenAPI document: https://docs.getbeel.com/openapi.json - Docs MCP server (list_pages, get_page, search): https://docs.getbeel.com/api/mcp - Italian version: https://docs.getbeel.com/it/llms.txt # Docs - API: For developers - [Introduction](/en/api): The Getbeel REST API and MCP server for Italian e-invoicing. - [Quickstart](/en/api/quickstart): Create a test key, make your first call, validate an XML and send an invoice in the sandbox. - **Concepts** - [Authentication](/en/api/authentication): Test and live API keys, scopes and good practice. - [Errors](/en/api/errors): The error shape, HTTP statuses and every code the API can return, with what to do. - [Rate limits](/en/api/rate-limits): 120 requests per minute per key, with RateLimit and Retry-After headers. - [Idempotency](/en/api/idempotency): Safely retry requests that create or send invoices with the Idempotency-Key header. - [SDI lifecycle](/en/api/sdi-lifecycle): The statuses of an issued invoice, what each SDI outcome means and what to do. - [Pagination](/en/api/pagination): Lists use cursor pagination with limit, cursor, has_more and next_cursor. - [Sandbox](/en/api/sandbox): Test keys send to an SDI simulated by getbeel. Here is how to trigger every outcome. - [Pricing, balance and usage](/en/api/pricing): Pay as you go from a prepaid balance. The price list, the balance, top-ups, usage and the 402 insufficient_balance error. - [Multiple companies (multi-company)](/en/api/companies): Software houses, marketplaces and accountants manage their clients' companies from one account, with one API key. - **Integrations** - [Receiving from SDI](/en/api/sdi-receiving): Receive supplier invoices from the Sistema di Interscambio, with codice destinatario, checklist and sandbox. - [Received invoices](/en/api/received-invoices): List and review supplier invoices, upload one for the AI to read, and manage the categories and AI rules that file them. - [Autofatture](/en/api/autofatture): Read a reverse-charge autofattura (TD17, TD18, TD19) and send it to SDI, exactly like the Send to SDI button. - [Email, payments and reminders](/en/api/invoice-collection): Email the invoice to your customer, record payments, create a Stripe payment link and send reminders. - [Recurring invoices](/en/api/recurring-invoices): Repeat an invoice every month, quarter or year, optionally sending it to SDI. - [Credit notes, quotes, items and numbering](/en/api/invoicing): Credit an invoice with a TD04 credit note, turn a quote into an invoice, save items and number with series. - [Bank & reconciliation](/en/api/bank-reconciliation): Upload a bank statement, let the AI match its payments to your received invoices, then review the matches. - [Bank connections](/en/api/bank-connections): Automatic bank transactions through Enable Banking, using your company's own Enable Banking application. - [Connections](/en/api/connections): Connect mailboxes and Stripe, scan for supplier invoices and review the documents collected. - [Drive](/en/api/drive): Read the company's Drive by month or folder, download a file, upload documents and manage folders. - [Taxes and deadlines](/en/api/taxes): Your Italian company's tax calendar, as JSON or as an .ics calendar, and the VAT position estimate. - [VAT registers and settlements](/en/api/vat-registers): The sales and purchase VAT registers, the monthly or quarterly VAT settlement (liquidazione) with its F24, and the LIPE file, prepared from the documents in Getbeel. - [Reports and export for the accountant](/en/api/reports): Profit and loss, cash flow and receivables aging from the data in Getbeel, and the ZIP with XML, VAT journal and registers for the accountant. - [Advisors (your accountant)](/en/api/advisors): Invite a commercialista with read-only access, list who has access, revoke an invitation or remove them. - [Filings (F24, LIPE, VAT return)](/en/api/filings): Prepare the F24 for stamp duty, withholdings or VAT, the LIPE file or the annual VAT return data, with the values to copy, the link to the Agenzia delle Entrate page and email drafts, then record the receipt. - [Tax rules](/en/api/tax-rules): The rule values and proroghe behind the tax calendar and estimates, with their official sources; for getbeel administrators, the proposals of the weekly rules watch. - [Fixed assets, estimates and POS–RT](/en/api/tax-tools): Fixed assets and depreciation with the libro cespiti, the tax estimate (IRES, IRAP, IRPEF, forfettario, minimi, INPS) and POS–RT links with the Agenzia delle Entrate CSV. - [Withholding tax (ritenute)](/en/api/withholdings): Invoices with ritenuta and cassa previdenziale, withholdings owed as sostituto d'imposta, F24 code 1040 and data for the Certificazione Unica and the 770. - [Webhooks](/en/api/webhooks): Get an event for every SDI receipt and verify the Getbeel-Signature header. - [MCP server](/en/api/mcp): Connect Claude, ChatGPT, Cursor and other MCP clients to Getbeel. - **SDKs and CLI** - [TypeScript SDK](/en/api/sdk-typescript): The official Node.js and TypeScript client, generated from the OpenAPI spec. - [Python SDK](/en/api/sdk-python): The official Python client, typed, with one dependency (httpx). - [CLI](/en/api/cli): Send invoices, upload bank statements and check deadlines from the terminal. - **Reference** - API reference - [API reference](/en/api/reference): Every endpoint, generated from the OpenAPI document, with the playground. - Billing: Pay as you go: the platform, sandbox, API, MCP and webhooks are free; SDI sends, received invoices, AI document reads, bank feeds and prepared filings are paid from one prepaid EUR balance per billing account. A billable call the balance does not cover answers 402 insufficient_balance (application/problem+json, with topup_url). Amounts are EUR cents, net of VAT. - [The prepaid balance](/en/api/reference/billing/getBillingBalance): Spendable balance (expired credit excluded), credit expiring in 30 days, auto top-up and low-balance alert settings (the alert email starts once there is paid credit: a top-up), pricing, and welcome_credit: whether the €1 welcome credit was granted and, if not, why (card_already_used: it applies only once per card). pricing is pay_as_you_go for an account that signed up on or after 13 November 2026, or legacy_plan for one that signed up before: it keeps its plan and everything it includes, nothing is paid from a balance, the amounts are 0 and topup_url is null. A client company (Getbeel-Company) sees its gestore’s balance with billed_to_parent true. Usage, top-ups and card links answer 409 not_pay_as_you_go for a legacy_plan account. - [Usage of a month](/en/api/reference/billing/getBillingUsage): Quantity and amount per item, the next unit price at this month’s tier, and per client company for a gestore. - [The price list](/en/api/reference/billing/getBillingPrices): Every billable item with its unit and tiers (per billing account per calendar month). The same list as the pricing page. - [Add credits (payment link)](/en/api/reference/billing/createBillingTopup): Returns a Stripe Checkout link for a person to pay (VAT added at checkout, one invoice per top-up); the API never charges a card. Checkout opens in the key creator’s language (else the owner’s, else Italian for an Italian company) and offers only the current default card. Live keys, billing:write, created by someone who can manage billing; not for a client company. - [Change the card (setup link)](/en/api/reference/billing/createBillingCardLink): Returns a Stripe Checkout link (setup mode, nothing is charged) for a person to enter a new card; it becomes the default card and the one auto top-ups charge. The same card saved twice is kept once. Live keys, billing:write, created by someone who can manage billing; not for a client company; 409 no_card (application/problem+json, the same shape as the 402) when no card is saved yet. The Checkout opens in the key creator’s language (else the owner’s, else Italian for an Italian company). - A I rules: Plain-language instructions the AI follows, in order, when it reads received invoices (invoice_scan) or drafts issued invoices from Stripe payments (fattura_emessa). The same rules as Settings → AI rules. - [List AI rules](/en/api/reference/ai-rules/listAiRules): The team's AI rules, by type and in the order the AI reads them (only active ones are followed). Filter with type; without it, the rules of every type the key can read. The scope follows the rule type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes. Both key modes. - [Add an AI rule](/en/api/reference/ai-rules/createAiRule): Adds a rule at the end of its type (default invoice_scan), active unless active is false. It applies to the next invoices the AI reads; invoices already read stay as they are. The scope follows the rule type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes. Live keys only. - [Change or pause an AI rule](/en/api/reference/ai-rules/updateAiRule): Changes the text, or pauses (active false) or resumes the rule; the type stays. The scope follows the rule type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes. Live keys only. - [Delete an AI rule](/en/api/reference/ai-rules/deleteAiRule): Deletes the rule and returns it as it was. To stop it for a while, pause it instead. The scope follows the rule type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes. Live keys only. - Tax rules: The rules behind the tax calendar and estimates that change by year or by law: versioned rule values (INPS minimale and rates, forfettario thresholds, impatriati shares…) and proroghe (published extensions that move deadlines). Each carries its official source. A weekly watch reads the official sources (Agenzia delle Entrate, MEF Finanze, Gazzetta Ufficiale, INPS) and proposes changes with a quote; getbeel administrators approve them. Customers read the rules in force. - [Tax rules in force](/en/api/reference/tax-rules/getTaxRules): Every rule value by date (origin code: shipped with getbeel; db: added since), the values missing in the next 13 months, and the proroghe in force. pending (the proposals of the rules watch) and watch_runs are null unless the key is a live key of a getbeel administrator. Both key modes. - [Add a rule value](/en/api/reference/tax-rules/createTaxRuleValue): Adds a value of a known key for its dates. status active puts it in force at once, only with an official source (agenziaentrate.gov.it, mef.gov.it, finanze.gov.it, gazzettaufficiale.it, inps.it, normattiva.it, fatturapa.gov.it; 400 official_source_required otherwise); pending (default) waits for approval. Two active values of a key never overlap (409 rule_value_overlap). Tax rules apply to every company: only getbeel administrators change them, with a live key that has the admin-only tax_rules:admin scope (created in the admin page; 403 insufficient_scope otherwise, 403 live_key_required with a test key, 403 super_admin_required when its creator is no longer an administrator). Recorded in the audit log. - [Add a proroga](/en/api/reference/tax-rules/createTaxCalendarOverride): Moves the deadlines of deadline_kind (all: every tax deadline; never the EU OSS return or the bilancio deposit) whose legal date is in nominal_from–nominal_to to new_due_date, from valid_from. status active applies it at once (official source required), updates prepared unpaid filings and tells the teams it affects in the app; pending (default) waits for approval. Tax rules apply to every company: only getbeel administrators change them, with a live key that has the admin-only tax_rules:admin scope (created in the admin page; 403 insufficient_scope otherwise, 403 live_key_required with a test key, 403 super_admin_required when its creator is no longer an administrator). Recorded in the audit log. - [Approve or reject a proposal](/en/api/reference/tax-rules/decideTaxRule): Approves (in force at once) or rejects a pending rule value or proroga. Through the API only a proposal with an official source can be approved, and a rules-watch proposal only when its quote was found word for word in the source (400 quote_not_verified: a PDF; approve it in the admin page after reading it). 404 proposal_not_found when it was already decided. Tax rules apply to every company: only getbeel administrators change them, with a live key that has the admin-only tax_rules:admin scope (created in the admin page; 403 insufficient_scope otherwise, 403 live_key_required with a test key, 403 super_admin_required when its creator is no longer an administrator). Recorded in the audit log. - Received invoices - [Receiving from SDI: status and readiness](/en/api/reference/received-invoices/getSdiReceiving): Whether the company receives its supplier invoices through getbeel's SDI channel (openapi.com), the codice destinatario to give suppliers and register as indirizzo telematico in the AdE area, a readiness checklist (company data, SDI add-on, receiving on, indirizzo telematico confirmed, conservazione) and the AdE conservazione status. Received invoices appear in GET /received-invoices with source sdi. Both key modes. - [Turn on receiving from SDI](/en/api/reference/received-invoices/enableSdiReceiving): Configures the company on the SDI provider so its supplier invoices reach getbeel, and returns the status with the codice destinatario. Then register the code as indirizzo telematico in the AdE area (Fatture e Corrispettivi) and confirm it in the app. Safe to call again. Live keys only (403 livemode_required); test keys use POST /sandbox/inbound-invoices. - [Turn off receiving from SDI](/en/api/reference/received-invoices/disableSdiReceiving): Stops the SDI provider receiving the company's supplier invoices (sending to SDI is untouched; invoices already received stay) and returns the status. Change or remove the indirizzo telematico in the AdE area afterwards, or new invoices only reach the cassetto fiscale. Safe to call again. Receiving also turns off by itself when the SDI add-on or rate card ends. Live keys only (403 livemode_required). - [Receive an invoice in the sandbox](/en/api/reference/received-invoices/createSandboxInboundInvoice): Test keys only (403 test_mode_required with a live key). Receives a FatturaPA (your XML or base64 .p7m, or a sample addressed to your company when the body is empty) as if a supplier sent it through SDI: it is parsed like a real one, listed by GET /received-invoices with the test key (source sdi, status pending_review) and fires received_invoice.created to test webhook endpoints. Nothing reaches the app. - [Upload a supplier invoice or receipt](/en/api/reference/received-invoices/uploadReceivedInvoice): Uploads a document (PDF, JPEG, PNG or WEBP, up to 50 MB; the type is read from the file, not its name) by file_url (public https, no redirects) or file_base64 with file_name. The AI reads it as an upload in the app does: the invoice then appears in GET /received-invoices with status pending_review. Check progress with GET /received-invoices/uploads/{id}. Uses one invoice credit per file. Live keys only (403 livemode_required). - [Status of an upload](/en/api/reference/received-invoices/getReceivedInvoiceUpload): Where an upload is: pending or processing while the AI reads it, completed (the invoice is in GET /received-invoices), or failed with the error. - [List invoice categories](/en/api/reference/received-invoices/listCategories): The team's categories for received invoices (expense categories), in the app's order. The slug is what received invoices carry in category. Both key modes. - [Add a category](/en/api/reference/received-invoices/createCategory): Adds a category; its slug comes from the label (made unique in the team) and, without a colour, it gets the next preset. Live keys only. - [Rename or recolour a category](/en/api/reference/received-invoices/updateCategory): Changes the label or colour; the slug stays. Live keys only. - [Delete a category](/en/api/reference/received-invoices/deleteCategory): Deletes a category and moves its invoices to "other". Default categories cannot be deleted (409 default_category). Live keys only. - [Set the category of a received invoice](/en/api/reference/received-invoices/setReceivedInvoiceCategory): Sets a received invoice's category to one of the team's (a slug from GET /categories; 422 unknown_category otherwise). Live keys only. - [List received (supplier) invoices, newest invoice_date first](/en/api/reference/received-invoices/listReceivedInvoices): Invoices received through SDI (source sdi) and collected from email, forwarding or uploads. With a test key: only the invoices received in the sandbox (POST /sandbox/inbound-invoices). - [Approve a collected document (status verified)](/en/api/reference/received-invoices/approveReceivedInvoice): Moves a received invoice from pending_review (or rejected) to verified, like reviewing it in the app. Already verified: no change. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Reject a collected document (status rejected)](/en/api/reference/received-invoices/rejectReceivedInvoice): Moves a received invoice from pending_review (or verified) to rejected. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - Taxes: Italian tax calendar (scadenzario), VAT registers and liquidazioni, withholdings owed as sostituto d’imposta with CU and 770 data, prepared filings (F24 for bollo, withholdings and VAT; the LIPE file, checked against the official XSD; the data sheet of the annual VAT return), the VAT position estimate, management reports (P&L, cash flow, receivables aging), the export for the accountant, fixed assets and depreciation (libro cespiti), tax estimates (IRES, IRAP, forfettario, INPS) and POS–RT links (the AdE bulk CSV). getbeel prepares; the client pays or files in their own AdE area or bank. - [Remove a VAT register adjustment](/en/api/reference/taxes/deleteVatAdjustment): The row counts as getbeel computed it again. deleted is false when it had no adjustment. Live keys only. - [Exclude or correct a VAT register row](/en/api/reference/taxes/setVatAdjustment): The same as Rettifica in Tasse → Registri IVA: exclude keeps the row out of the liquidazione; adjust sets the VAT that counts (vat_amount), for example the deductible share of a car or phone cost. A reason is required and kept with the row for the accountant. It replaces an earlier adjustment of the row. GET vat-registers and vat-settlements show the effect; a liquidazione already saved stays as it was until it is prepared again (POST /filings, type vat_payment). Live keys only. - [The company's Italian tax deadlines](/en/api/reference/taxes/getTaxCalendar): Deadlines between from and to (default: 90 days ago to a year ahead), already moved off weekends, holidays and 1–20 August: imposta di bollo on e-invoices (amount computed from the issued invoices), withholding taxes (1040), VAT payments, VAT advance and balance, LIPE, the annual VAT return, the OSS return (never moved), and for companies (IRES subjects) the income-tax saldo and acconti (IRES/IRAP), the Redditi SC and IRAP returns, the diritto camerale and the bilancio deposit. Each has its legal source. Deadlines that depend on settings the app cannot infer (VAT monthly or quarterly, withholding agent, OSS registration, the income-tax answers saved in Stima imposte) appear once they are set in the app (missing_settings). Companies outside Italy get applicable false and no deadlines. - [The tax calendar as an iCal feed](/en/api/reference/taxes/getTaxCalendarIcs): For Google, Outlook or Apple calendars. Authenticated by the secret feed token from the app (Taxes → Add to calendar), not by an API key; rotating it there cuts off old subscriptions. Unknown tokens get 404. - [VAT for a month or quarter (estimate)](/en/api/reference/taxes/getVatPosition): Sales VAT from the issued e-invoices accepted by SDI (credit notes subtract, split payment left out, deferred VAT apart) and an estimate of purchase VAT from reviewed supplier invoices in euros. reliable is always false: deductibility, the month of receipt and reverse charge are not known, so treat it as an estimate to check with the accountant ("da verificare"). It is never used for an F24. - [Draft of the quarterly OSS return](/en/api/reference/taxes/getOssReturn): For a company registered in the OSS union scheme: per Member State of the consumer, the taxable amount and the VAT of the quarter from the issued invoices with Natura N7 to EU consumers, at each State's standard rate on the invoice date (VAT rounded per line, then added up; vat_country_level shows the per-country computation, rounding_gap when they differ by more than €0.01). Credit notes on earlier quarters are corrections; a State's negative balance is refunded, never offset. doubtful lists the invoices that need a decision (reason). deadline is the nominal date, never moved; reference is the payment reference. Free and read-only: the return is entered and paid in the AdE Portale OSS with the company's own credentials, never with F24. reliable is always false (reduced rates and goods are not modelled). - [VAT registers of a month or quarter](/en/api/reference/taxes/getVatRegisters): Registro IVA vendite and acquisti, row by row with the amounts per rate and natura: issued e-invoices accepted by SDI (credit notes subtract; split payment recorded but not due; deferred VAT counted when paid or after a year), supplier invoices as soon as the AI has read them, those not reviewed yet flagged unreviewed (by the period of receipt; foreign VAT never counts) and autofatture TD16–TD19/TD28 on both sides (reverse charge). vat_counted is what enters the liquidazione after the user's exclusions and adjustments (made in the app, with a reason). missing lists the documents of the period not in the registers yet. Always to check ("da verificare"). - [VAT settlement (liquidazione) of a month or quarter](/en/api/reference/taxes/getVatSettlement): The liquidazione IVA computed now from the VAT registers, in the rows of the LIPE (VP2–VP14): VAT due and deducted, debt up to €100 or credit carried from the previous period of the same year (saved, or else computed by getbeel from its registers: see previous), prior-year credit used, 1% interest for quarterly payers, acconto in December/Q4. amount_to_pay is what the F24 pays now. The period must match the VAT periodicity set in the app. saved is the version last saved with POST /v1/filings (type vat_payment), which the LIPE reports. Always to check ("da verificare"). - [Management report: P&L, cash flow or receivables aging](/en/api/reference/taxes/getReport): Management figures from the invoices and bank movements in getbeel, net of VAT: NOT the statutory financial statements (bilancio), always to check with the accountant ("da verificare"). profit-and-loss: revenue from issued e-invoices accepted by SDI and costs from reviewed supplier invoices, by document date as the competence date (art. 2423-bis c.c.); credit notes subtract; autofatture and other VAT-only documents (TD16–TD23, TD27–TD29) are left out; TD26 (fixed-asset sales) and documents still at SDI or not reviewed are listed in not_included. cash-flow: money in and out of the bank accounts (uploaded statements and connected banks) by booking date, outflows by the category of the matched supplier invoice; payments recorded on issued invoices are shown apart. aging: what customers still owe on issued invoices today, by days past the due date (not due, 1–30, 31–60, 61–90, over 90); without a due date, 30 days after the invoice date (art. 4 D.Lgs. 231/2002). period, from and to are ignored. period is a year (2026), quarter (2026-Q3) or month (2026-10), or send from and to (at most two years); default the current year. - [ZIP for the accountant (XML, prima nota, VAT registers)](/en/api/reference/taxes/getAccountantExport): Everything an accountant imports for a year, quarter or month: the FatturaPA XML files of issued invoices (as sent to SDI), of received invoices (as received, or the attached file) and of the autofatture getbeel sent; prima-nota-iva.csv (one line per document and VAT rate or natura, with the XML file name); the VAT registers of each settlement period (CSV); bank movements (CSV); and LEGGIMI.txt listing any file that could not be read. Accounting packages (TeamSystem, Zucchetti, Profis and others) import the XML files with their e-invoice import; no vendor-specific layout is produced. CSV: semicolon, decimal comma, UTF-8. Italian companies only. Needs the invoices:read, received_invoices:read and bank:read scopes too. 422 too_many_documents when the period is too large for one file: ask for a quarter or a month. - [List prepared filings, latest due date first](/en/api/reference/taxes/listFilings) - [Prepare a filing (F24, LIPE or VAT return data)](/en/api/reference/taxes/prepareFiling): 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. - [A filing with its F24 lines and next steps](/en/api/reference/taxes/getFiling) - [The F24 reminder PDF, the LIPE XML or the VAT return data](/en/api/reference/taxes/getFilingFile): A "promemoria F24": the values to enter in F24 web or home banking, not the ministerial form. For a lipe filing, the XML file (IVP18) to check with the AdE control software, sign and upload in "Fatture e corrispettivi". For a vat_return, the data sheet (format csv, xlsx or json): rows, points to check and periods, to copy into the AdE "Iva" software or the accountant's. - [Upload the receipt and mark the filing paid or filed](/en/api/reference/taxes/uploadFilingReceipt): Multipart `file`: the F24 quietanza or AdE receipt, PDF, PNG or JPEG up to 10 MB. The filing becomes paid (a LIPE or VAT return becomes filed; webhook filing.filed). The receipt is stored, not read. Live keys only. Pay as you go: the filing is charged once, now, from the prepaid balance (prices in GET /billing/prices). - [Move a filing in the commercialista review](/en/api/reference/taxes/setFilingStatus): approved (visto bueno: approved_at, approved_by), changes_requested (reason required; only the commercialista, who reviews in the app), skipped (not to be done: reason required; never prepared automatically again, never charged), needs_review (back to review, or reopen a skipped filing: one skipped before it was prepared goes back to to_prepare), filed (a LIPE, annual VAT return or Redditi PF return sent: reference = its protocol number). When the team requires the commercialista's approval (tax settings require_accountant_approval), an API key cannot approve and a receipt waits for the approval (409 approval_required). Every change goes in the history (/filings/{id}/events), the audit log and webhooks filing.needs_review, filing.changes_requested, filing.approved, filing.skipped and filing.filed. Pay as you go: filed completes the filing and charges it once from the prepaid balance, with the same charge as its receipt (never twice); approving, changes_requested, skipping and reopening are free. Live keys only. - [Mark a deadline as not to be done](/en/api/reference/taxes/skipFiling): For a type and period (prepared or not): skipped, with the reason. getbeel never prepares it automatically afterwards and never charges it; reminders and funds alerts stop. Reopen with POST /filings/{id}/status needs_review. Webhook filing.skipped. Live keys only. - [The history of a filing (comments and status changes)](/en/api/reference/taxes/listFilingEvents) - [Comment on a filing](/en/api/reference/taxes/commentFiling): Adds a comment to the history, read by the team and the commercialista. Live keys only. - [List withholdings (ritenute owed), newest first](/en/api/reference/taxes/listWithholdings): Ritenute d’acconto the company withholds as sostituto d’imposta on fees paid to professionals and agents, one per received fee. Fees on professionals’ invoices received from SDI (DatiRitenuta RT01/RT02) are recorded on arrival; set paid_on when you pay the fee: the ritenuta is then due with F24 code 1040 by the 16th of the next month (art. 25 DPR 600/1973, art. 18 D.Lgs. 241/1997). - [Record a fee subject to withholding](/en/api/reference/taxes/createWithholding): A fee not received through SDI (paper invoice, notula of occasional work). withheld_amount is computed when left out. Live keys only (403 livemode_required). Free. - [A withholding](/en/api/reference/taxes/getWithholding) - [Change a withholding (e.g. the day the fee was paid)](/en/api/reference/taxes/updateWithholding): Changing the rate or the amounts recomputes withheld_amount unless you send it. 409 withholding_remitted once an F24 recorded in getbeel paid it (the CU and the 770 rely on it). Live keys only (403 livemode_required). Free. - [Delete a withholding](/en/api/reference/taxes/deleteWithholding): 409 withholding_remitted once an F24 paid it. Live keys only (403 livemode_required). Free. - [Read withholdings from received SDI invoices](/en/api/reference/taxes/syncWithholdings): Reads the invoices received from SDI that have no withholding yet and records those with DatiRitenuta RT01/RT02. Up to 100 per call; call again while has_more. Live keys only (403 livemode_required). Free. - [CU and 770 data of a year](/en/api/reference/taxes/getWithholdingsCu): Per percipiente and causale, the fees paid in the year (cash principle) as the Certificazione Unica (lavoro autonomo, provvigioni e redditi diversi) reports them: punto 4 gross, 7 not subject, 8 taxable, 9 ritenute; the 770 quadro ST lines per month (codice 1040). Deadlines from the CU 2026 instructions: CU to each percipiente by 16 March; to the AdE by 16 March, or 30 April for lavoro autonomo abituale and non-occasional provvigioni; 770 by 31 October. format=csv returns a spreadsheet (text/csv). Not the telematic file. - [Get the tax settings](/en/api/reference/taxes/getTaxSettings): VAT periodicity and whether the company is a withholding agent, as Tasse → Impostazioni. null means not set: the deadlines that depend on it are left out of the tax calendar (missing_settings). Both key modes. - [Change the tax settings](/en/api/reference/taxes/updateTaxSettings): Changes only what it sends. The VAT periodicity decides the VAT periods (months or quarters) of the registers, liquidazioni and F24: change it only as the company actually settles VAT (ask the accountant). Live keys only. - [Get the tax profile](/en/api/reference/taxes/getTaxProfile): Which taxes apply to the company: legal form, regime, VAT periodicity, withholding agent, employees, foreign suppliers, Intrastat, OSS (sales evidence and the registration), liquidation, first tax year, social security and special income tax regimes, each with its `effect` for the current year (rate or taxed share, until when, F24 codes, the official source of each number) and `regime_warnings`. Each value is yours (sources: user) or a high-confidence detection (detected), with the evidence in `detection`; low-confidence values are never applied and come back in `questions` to ask the user once. Both key modes. Free. - [Change the tax profile](/en/api/reference/taxes/updateTaxProfile): Changes only what it sends and marks it confirmed; null clears a value (back to the detection); `confirm` confirms detected values as they are; `regimes` replaces the special income tax regimes; their `params` are typed per kind and getbeel computes the numbers from them. A value you set always wins over the detection and changes which deadlines the tax calendar lists. Ask the user, never guess. Recorded in the audit log. Live keys only. - [Detect the tax profile now](/en/api/reference/taxes/detectTaxProfile): Re-runs the detection from the company data (name, regime, issued and received invoices, recorded withholdings), stores it and returns it with the profile. It never changes a value you set. New obligations (e.g. B2C sales above the OSS threshold) also add a notice in the app. getbeel runs it every month by itself. Live keys only. - [Depreciation categories and coefficients](/en/api/reference/taxes/listFixedAssetCategories): The ministerial coefficients of DM 31 December 1988 (as amended by DM 28 March 1996) for the groups most small companies and professionals use ("Attività non precedentemente specificate – Altre attività", hotels and restaurants, personal services), and the art. 103 TUIR limits for software, patents, trademarks and goodwill. Any other coefficient can be given by hand when creating an asset. - [List fixed assets (cespiti)](/en/api/reference/taxes/listFixedAssets): Newest purchase first, each with its tax depreciation schedule, status, fondo and residual at the end of year (default: this year). - [Register a fixed asset](/en/api/reference/taxes/createFixedAsset): Registers a bene strumentale, often bought with a received invoice (received_invoice_id fills purchase date, supplier and number). Depreciation starts in the year it enters into function (art. 102 c. 1 TUIR) at most at the ministerial coefficient, halved in the first year (c. 2); a tangible asset up to 516.46 can be deducted in full (c. 5). The asset’s cost is then left out of the year’s costs in the tax estimate. Live keys only (403 livemode_required). Free. - [A fixed asset with its schedule](/en/api/reference/taxes/getFixedAsset) - [Change a fixed asset or record its disposal](/en/api/reference/taxes/updateFixedAsset): Send only what changes. disposal_date and disposal_amount record a sale or elimination: the gain or loss is price minus the cost not yet depreciated (art. 86 and 101 TUIR); no quota is computed in the disposal year. depreciation_overrides records smaller deductions of past years. Live keys only (403 livemode_required). Free. - [Delete a fixed asset](/en/api/reference/taxes/deleteFixedAsset): Removes it from the register. Live keys only (403 livemode_required). Free. - [Libro cespiti of a year](/en/api/reference/taxes/getFixedAssetsRegister): Every asset owned during the year with the fondo at 1 January and 31 December, the quota of the year and any disposal; totals per category and a summary of the closing entries for the accountant (no general ledger is kept). format=csv or xlsx returns the file. Always to check ("da verificare"). - [Tax estimate of a year (stima)](/en/api/reference/taxes/getTaxEstimate): An estimate, to check with the accountant: for a company (società di capitali) IRES 24% and IRAP (3.9% or the regional rate given); for the regime forfettario the imposta sostitutiva (15%, or 5% for start-ups) on revenue × the ATECO group coefficient minus contributions, and the INPS contributions (gestione separata 26.07%, artigiani/commercianti with the 2026 minimale). Figures come from getbeel: issued invoices (or payments recorded, for forfettari), reviewed received invoices without the fixed assets, depreciation and gains of the year. installments lists acconti and saldo with F24 codes and dates (art. 17 DPR 435/2001); dates not yet confirmed by a source in force are confirmed false. - [Save the inputs of the tax estimate](/en/api/reference/taxes/saveTaxEstimate): The figures getbeel cannot know (legal form, ATECO, personnel costs, INPS scheme, last year’s taxes for the acconti…), stored per year and merged over the saved ones; returns the recomputed estimate. Next year starts from these answers. Live keys only (403 livemode_required); saving the inputs is free (nothing is charged to the balance). - [List POS–RT links](/en/api/reference/taxes/listPosRtLinks): Each payment terminal linked to a registratore telematico, with its status (to_file, filed, end_to_file, ended) and, when something is still to communicate, the window of provv. AdE 424470/2025 (from the 6th to the last working day of the second month after the change). - [Record a POS linked to an RT](/en/api/reference/taxes/createPosRtLink): The fields of the AdE bulk CSV: RT matricola, acquirer (codice fiscale, name, IT or ES), POS type (00 physical with its TerminalId, 01 virtual), contract number, address of the unità locale or itinerant, and the first day of use. Live keys only (403 livemode_required). Free. - [A POS–RT link](/en/api/reference/taxes/getPosRtLink) - [Change or end a POS–RT link](/en/api/reference/taxes/updatePosRtLink): Before the link is communicated anything can change. After, only label and ended_on: setting ended_on (last day of use) makes the end the next thing to communicate (operation C, DataFine). 409 link_already_filed otherwise. Live keys only (403 livemode_required). Free. - [Delete a POS–RT link not communicated yet](/en/api/reference/taxes/deletePosRtLink): A communicated link is ended instead (409 link_already_filed). Live keys only (403 livemode_required). Free. - [The bulk CSV for the AdE portal](/en/api/reference/taxes/exportPosRtLinks): Everything still to communicate (I to associate, C to end) in the 15 columns of the AdE "Manuale operativo" (April 2026), at most 1,000 rows per file (part). The separator, encoding and header names are not in any official document: the template downloadable in the portal is the reference, and tsv has the same rows to paste into it. next_steps has the path in Fatture e Corrispettivi. getbeel never uploads it for you. format=csv returns the file. - [Mark links communicated](/en/api/reference/taxes/markPosRtLinksFiled): After the AdE processed the upload ("Storico richieste massive"): the pending operation of each link becomes filed (associations, then ends). Live keys only (403 livemode_required). Free. - Autofatture: Reverse-charge autofatture (TD17, TD18, TD19) of foreign purchases, as on the Autofatture page: read one and send it to SDI. - [An autofattura with its SDI status](/en/api/reference/autofatture/getAutofattura): The autofattura of a foreign purchase: TD type, number, whether the XML is ready, and the SDI status (null until sent, then queued, sent_to_sdi, consegnata, scartata…). Both key modes. - [Send an autofattura to SDI](/en/api/reference/autofatture/sendAutofattura): Sends a generated autofattura to SDI, exactly like the Send to SDI button: the XML must be generated, and the send is paid from the prepaid balance at the SDI send price (402 insufficient_balance when it does not cover it). It is queued and returns the autofattura with sdi.status = queued; read it again for the SDI answer. Safe to repeat: a second call never sends or charges again (409 autofattura_already_queued or autofattura_already_sent). A corrected resend after an SDI rejection is not charged again. Live keys only. - Drive: The company's Drive, as in the app: received invoices' files, uploaded bank statements and uploaded documents, by month and folder. - [List a month or folder of the Drive](/en/api/reference/drive/getDrive): The folders and files of one month (month=2026-10: invoice files by invoice date, statements and uploads by upload date) or of one uploads folder (folder=contratti or 2026-10/contratti), newest first. Invoice files also need received_invoices:read and bank statements bank:read; without them they are left out. Both key modes. - [Upload a document to the Drive](/en/api/reference/drive/uploadDriveFile): Uploads a document into a folder that takes uploads (writable true in GET /drive: a month, documents or a custom folder; a month folder is created if missing), by public https file_url or file_base64. PDF, PNG, JPEG, DOC or DOCX, up to 25 MB, the type read from the content (413 payload_too_large, 415 unsupported_file_type). It is only stored: to have the AI read a supplier invoice, use POST /received-invoices/uploads. Live keys only. - [Download a Drive file](/en/api/reference/drive/downloadDriveFile): A private link to the file (id from GET /drive), valid 15 minutes. Invoice files also need received_invoices:read and bank statements bank:read; without them they are left out. - [Delete a Drive file](/en/api/reference/drive/deleteDriveFile): Deletes the file (id from GET /drive) for good, as Delete in the Drive page: a received invoice’s file (the invoice stays, without its file; also needs received_invoices:write), an uploaded bank statement (also needs bank:write) or an uploaded document. A statement holding autofatture that are or may be at SDI cannot be deleted (409 statement_has_sent_autofatture). Live keys only. - [Create a Drive folder](/en/api/reference/drive/createDriveFolder): A new uploads folder at the root or inside a month (that month’s folder is created if missing). Its path comes from the name; a name shaped like a month is refused. 409 folder_exists when one with that name is already there. Live keys only. - [Delete a Drive folder](/en/api/reference/drive/deleteDriveFolder): Deletes a custom folder (path from GET /drive, kind custom) and every file in it, for good. Month and system folders cannot be deleted. Live keys only. - Bank connections: Automatic bank feeds through Enable Banking, with your own Enable Banking application - [List bank connections](/en/api/reference/bank-connections/listBankConnections): Banks connected for automatic transaction feeds, with their accounts, balances, consent expiry and last sync. Synced transactions appear in GET /bank-statements (source open_banking, one statement per account and month) and GET /bank-transactions. - [Connect a bank](/en/api/reference/bank-connections/createBankConnection): Checks the Enable Banking application (a real call with your key), saves it and starts the bank login. Open authorization_url in a browser: a getbeel page names your team, the user continues to the bank, logs in and lands in the getbeel app, and the first sync (last 90 days) starts right away. Add getbeel's redirect URL (https://getbeel.com/api/open-banking/callback) to your application's allowed redirect URLs first. Pay as you go: €2.00 per connected bank account per month and €0.02 per imported movement, from the prepaid balance (402 insufficient_balance when it does not cover them). Each team uses its own Enable Banking application (application id + RSA private key from the Enable Banking control panel); getbeel stores the key encrypted and never returns it. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Get a bank connection](/en/api/reference/bank-connections/getBankConnection) - [Disconnect a bank](/en/api/reference/bank-connections/deleteBankConnection): Closes the consent at the bank and deletes the stored key. Synced statements, transactions and matches stay. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Reconnect a bank](/en/api/reference/bank-connections/reconnectBankConnection): Starts a new bank login for a connection whose consent is expiring (expires_soon), expired or revoked (status requires_reconnect), or whose first login was never finished. Open authorization_url in a browser: a getbeel page names your team, then the user gives the bank a new consent and lands in the getbeel app; the old consent is closed and the first sync runs right away. Banks end a consent after at most 180 days (PSD2), so plan one reconnect per bank every few months; getbeel emails the owners and sends the bank_connection.expiring webhook 7 days before. Pay as you go (402 insufficient_balance when the prepaid balance does not cover the account month). Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Sync a bank connection now](/en/api/reference/bank-connections/syncBankConnection): getbeel already syncs every 6 hours. Banks allow about four unattended fetches a day, and this call counts as one (429 bank_daily_limit when they are used up). New transactions are deduplicated, added to the month's synced statement and matched in the background (webhooks bank_statement.parsed, then reconciliation.completed). New movements cost €0.02 each, from the prepaid balance. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - Companies: Client companies of a parent account (software houses, marketplaces, commercialisti) - [The account and its client companies](/en/api/reference/companies/listCompanies): The account the key belongs to, then the client companies the key can act on (its member must manage them). The Getbeel-Company header does not apply to /companies. - [Add a client company](/en/api/reference/companies/createCompany): Creates a client company under the key's account with its company data. The key's member becomes its owner, so the same key can act on it at once with the Getbeel-Company header. A client company cannot have client companies (409 company_nesting_not_allowed). Each company has its own plan: live SDI sends from a client company need its own SDI add-on. Live keys only (403 livemode_required with a test key): companies are real accounts, there is no sandbox for them. - [Get the account or one of its client companies](/en/api/reference/companies/getCompany) - [Change company data](/en/api/reference/companies/updateCompany): Changes only the fields sent. sdi_readiness shows what is still missing to issue invoices through SDI. Live keys only (403 livemode_required with a test key): company data is real, there is no sandbox for it. - Account - [The account, company and API key making the request](/en/api/reference/account/getAccount) - [This month's SDI usage and plan](/en/api/reference/account/getUsage): Live SDI transactions, sent and received, one per document (the sandbox and documents collected from email are not counted), the plan, and on the pay-per-use rate card (new accounts: sends €0.10 / €0.06 / €0.035 with the first 10 a month free; receiving from SDI €0.10 per invoice) the free allowance and the estimated amounts, sent and received separately. A client company (Getbeel-Company) is billed to its parent: it sees its own transactions and billed_to; the parent sees the total and the split per company. - Invoices: Issued invoices (fatture emesse) - [List issued invoices, newest invoice_date first](/en/api/reference/invoices/listInvoices) - [Create a draft invoice](/en/api/reference/invoices/createInvoice): 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. - [Retrieve an issued invoice with its lines](/en/api/reference/invoices/getInvoice) - [Edit a draft invoice](/en/api/reference/invoices/updateInvoice): Changes a draft with the same rules as the app's edit form and as create (a 0% line needs a natura, totals are recomputed). Each field sent replaces that part: lines replaces every line, customer and payment are sent whole. When the draft has a withholding or cassa and you change lines, withholding or cassa_previdenziale, send them again (null removes them). A number from a numbering series and the type of a credit note cannot change. Only drafts: a rejected invoice is reopened first (POST /invoices/{id}/reopen); a sent one is corrected with a credit note. - [Reopen a rejected invoice for correction](/en/api/reference/invoices/reopenInvoice): An invoice SDI rejected (status rejected) goes back to draft with the same number and date, as AdE advises for a scartata (it counts as never issued; resend it with the same number and date). The SDI errors stay on the invoice until it is sent again. Then PATCH /invoices/{id} to correct it and POST /invoices/{id}/send. Works the same with test keys for sandbox rejections. - [Send a draft invoice to SDI](/en/api/reference/invoices/sendInvoice): Generates the FatturaPA XML, validates it and sends it to SDI. Test key: the sandbox answers at once (200, status sent) and the outcome follows a few seconds later (webhook invoice.delivered, invoice.not_delivered or invoice.rejected). Live key: the real submission is queued (202, status sending, then sent). - [Email the invoice to the customer](/en/api/reference/invoices/emailInvoice): Sends the PDF courtesy copy (copia di cortesia; the legal invoice is the one SDI delivers) and optionally the FatturaPA XML to the customer (default: the customer's email on the invoice), with the payment link when the invoice has one. Only issued invoices (sent to SDI) and proformas. The attempt is stored (GET /invoices/{id}/deliveries) and sent to webhooks (invoice.emailed or invoice.email_failed); a failed send answers 502 email_failed. Test keys (gb_test_…) only reach sandbox invoices, and their emails go to the team owner only, never to the customer (sent_to shows where it went). - [Invoice and reminder emails sent for an invoice](/en/api/reference/invoices/listInvoiceDeliveries) - [Payments recorded on an invoice, oldest first](/en/api/reference/invoices/listInvoicePayments) - [Record a payment (mark as paid)](/en/api/reference/invoices/recordInvoicePayment): Records a payment on an issued invoice (or proforma). Without amount it records everything still due (amount_due − amount_paid) and the invoice becomes paid (webhook invoice.paid); a smaller amount makes it partially_paid. amount_due is the total less the ritenuta d'acconto. - [Create a Stripe payment link](/en/api/reference/invoices/createPaymentLink): A Stripe payment link for what is still due, on the team's connected Stripe account (Stripe Connect). Returns the existing link (200) when the invoice has one. Invoice emails and reminders include it while the invoice is unpaid; payments made through it are recorded within the hour. Sandbox invoices need a Stripe test-mode connection. - [Email a payment reminder (sollecito)](/en/api/reference/invoices/sendPaymentReminder): Emails a payment reminder for an unpaid issued invoice, with the PDF and the payment link. Automatic reminders (days after the due date) are set per company in the app. Test keys (gb_test_…) only reach sandbox invoices, and their emails go to the team owner only, never to the customer (sent_to shows where it went). - [Validate a FatturaPA XML without sending it](/en/api/reference/invoices/validateInvoice): Validates locally against the official FatturaPA XSD (v1.2.3) and the SDI content controls of Allegato A v1.9.1 (Appendice 1) that depend on the file alone, the same check that runs before every send (no SDI call, nothing stored). Errors carry the AdE code and wording (00200 for XSD errors, with the line). Not checked: signatures, AdE registries (partita IVA, codice destinatario), duplicates. Returns 200 with `valid` and `errors` for any FatturaPA document; 413 above 5 MB. - [List the credit notes of an invoice](/en/api/reference/invoices/listCreditNotes) - [Create a credit note (TD04) for an invoice](/en/api/reference/invoices/createCreditNote): Copies an invoice SDI accepted into a TD04 draft that credits all its lines or the ones you pick (optionally with a smaller quantity), with the invoice's number and date in DatiFattureCollegate. Numbered in the team's credit-note series, else the invoice's series. Send it with POST /invoices/{id}/send. Once SDI accepts it, the invoice's amount_credited grows and its amount_due, payment status, reminders and overdue events take it into account. Credit notes (not rejected) can add up to the invoice total at most. - [Get the payment reminder settings](/en/api/reference/invoices/getReminderSettings): Automatic payment reminders (solleciti): off by default; days after the due date when they go out. Both key modes. - [Change the payment reminder settings](/en/api/reference/invoices/updateReminderSettings): Changes only what it sends. When on, getbeel emails the customer of each live overdue invoice the latest step reached, once. They apply to invoices due on or after the day they were switched on (enabled_at), so switching them on never mails every customer with an old unpaid invoice. Live keys only. - Recurring invoices: Invoices repeated every month, quarter or year - [List recurring invoices, newest first](/en/api/reference/recurring-invoices/listRecurringInvoices) - [Make an invoice recurring](/en/api/reference/recurring-invoices/createRecurringInvoice): Copies the invoice into a new draft every month, quarter or year (daily at about 08:00 Italian time), dated that day, with the next number and the same payment term. With auto_send the draft is also sent to SDI (sandbox for test keys). One schedule per invoice. - [Retrieve a recurring invoice](/en/api/reference/recurring-invoices/getRecurringInvoice) - [Change interval, next date, auto_send or active](/en/api/reference/recurring-invoices/updateRecurringInvoice) - [Delete a schedule (the invoices it created stay)](/en/api/reference/recurring-invoices/deleteRecurringInvoice) - [Pause a schedule](/en/api/reference/recurring-invoices/pauseRecurringInvoice) - [Resume a schedule](/en/api/reference/recurring-invoices/resumeRecurringInvoice): A next_date in the past moves to the next date of the series: no catch-up invoices. - Bank reconciliation: Bank statements, their transactions and the AI matching to received invoices - [List bank statements, newest first](/en/api/reference/bank-reconciliation/listBankStatements) - [Upload a bank statement and reconcile it](/en/api/reference/bank-reconciliation/uploadBankStatement): Multipart `file` (PDF, CSV or TXT, or a bank file: CBI (Italian RH flat file), CAMT.053 (ISO 20022 XML) or MT940; up to 50 MB; export spreadsheets as CSV) with optional `currency`, or JSON `{ file_url }` for a public https file. Starts reading the statement and matching its payments to received invoices, like an upload in the app: CBI, CAMT.053 and MT940 files are recognised by their content and read exactly (no AI); PDF and CSV are read with AI. Answers 202 with status pending, then parsed (webhook bank_statement.parsed) and review (webhook reconciliation.completed). A movement already imported for the same bank account (the same file again, an overlapping period) is not saved again, and a movement already imported is not charged again: transactions.total counts the new movements this statement saved, and a file with nothing new ends with 0, not an error. A statement whose bank account is not recognised (no bank name or last 4 digits) saves every movement. Idempotency-Key is honoured (multipart uploads are identified by the file's SHA-256, name and currency). Request bodies are limited to about 4 MB by the hosting platform: send larger files with file_url. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Retrieve a bank statement with its balances](/en/api/reference/bank-reconciliation/getBankStatement) - [List bank transactions, newest first](/en/api/reference/bank-reconciliation/listBankTransactions): Filter by statement, date range and reconciliation state (status). - [Run the AI matching of a statement again](/en/api/reference/bank-reconciliation/createReconciliation): For a statement in review, completed or failed: re-reads it and matches its transactions again (the previous transactions and matches are replaced), like Retry in the app. A new upload is reconciled automatically. 202; webhook reconciliation.completed when done. Refused (409) while a run is in progress or when an autofattura of the statement was sent to SDI. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Retrieve a reconciliation (id = statement id)](/en/api/reference/bank-reconciliation/getReconciliation) - [List the matches of a reconciliation](/en/api/reference/bank-reconciliation/listReconciliationMatches): One row per transaction, newest transaction first: the invoice found (exact, fuzzy or manual) with its confidence, or unmatched. - [Link a received invoice to a transaction by hand](/en/api/reference/bank-reconciliation/createManualMatch): Replaces the transaction's match with the given received invoice (match_type manual, review_status modified). Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Approve a match](/en/api/reference/bank-reconciliation/approveMatch): Confirms the invoice found; for an unmatched payment, confirms that no invoice is needed. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Reject a match](/en/api/reference/bank-reconciliation/rejectMatch): The suggested invoice is wrong. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Payments without an invoice](/en/api/reference/bank-reconciliation/listUnmatchedPayments): Money out from the uploaded statements with no invoice found and not marked as needing none: the documents to collect. - [Invoices without a payment](/en/api/reference/bank-reconciliation/listUnmatchedInvoices): Received invoices (pending_review, verified or exported) that no bank transaction is matched to. - Connections: Mailboxes, forwarding address and Stripe - [List mailbox, forwarding and Stripe connections](/en/api/reference/connections/listConnections) - [Connect a mailbox](/en/api/reference/connections/createEmailConnection): gmail / outlook: 200 with a link to the OAuth consent; the user opens it in a browser signed in to getbeel and lands back in the app (the connection then shows in GET /connections). imap: tests the login (port 993, TLS) and saves the mailbox, 201. Counts toward the plan mailbox limit (402). Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Scan a mailbox for invoices in a date range](/en/api/reference/connections/scanMailbox): Gmail, Outlook or IMAP; at most 366 days. Runs in the background (202); found invoices appear in GET /received-invoices with source email (webhook received_invoice.created). Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [The address to forward supplier invoices to](/en/api/reference/connections/getForwardingAddress) - [Link to connect Stripe](/en/api/reference/connections/createStripeConnection): Returns a link to Stripe Connect; the user opens it signed in to getbeel and lands back on the fatture emesse page. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - [Import Stripe invoices as fatture emesse](/en/api/reference/connections/syncStripe): Like Sync in the app (default: the last 30 days). Needs an SDI plan (rate card or add-on) and its quota; with auto_send_sdi on, the invoices are also sent to SDI. 202, runs in the background. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it. - Quotes: Quotes (preventivi): draft, sent, accepted, declined or expired; converted into an invoice draft - [List quotes, newest first](/en/api/reference/quotes/listQuotes) - [Create a quote](/en/api/reference/quotes/createQuote): Same customer, lines, payment and notes as POST /invoices, plus valid_until. Numbered per year (12/2026), separately for test and live keys. - [Retrieve a quote](/en/api/reference/quotes/getQuote) - [Update a quote](/en/api/reference/quotes/updateQuote): Not after it was converted (quote_converted) or accepted (quote_not_editable). - [Delete a quote (its invoice, if any, stays)](/en/api/reference/quotes/deleteQuote) - [Email the quote PDF to the customer](/en/api/reference/quotes/sendQuote): Marks a draft quote sent. Test keys: the email goes to the team owner only, with a [TEST] subject. - [Mark a quote accepted](/en/api/reference/quotes/acceptQuote) - [Mark a quote declined](/en/api/reference/quotes/declineQuote) - [Turn a quote into an invoice draft](/en/api/reference/quotes/convertQuote): Creates the invoice draft (today unless date is sent; same rules as POST /invoices: live keys need an SDI plan and reserve quota) and marks the quote accepted. A quote converts once (409 quote_converted). - [Download the quote PDF](/en/api/reference/quotes/getQuotePdf) - Items: Saved items and services (articoli) for invoice lines - [List saved items, by name](/en/api/reference/items/listItems) - [Save an item or service](/en/api/reference/items/createItem) - [Retrieve an item](/en/api/reference/items/getItem) - [Update an item (past invoices keep their values)](/en/api/reference/items/updateItem) - [Delete an item](/en/api/reference/items/deleteItem) - Numbering series: Numbering series (sezionali): prefix, suffix, yearly reset, defaults for invoices and credit notes - [List numbering series with their next number](/en/api/reference/numbering-series/listNumberingSeries): Next numbers are for today in the key's mode (test and live keys number separately). default_numbering is the numbering used without a series: plain numbers (1, 2, 3, no suffix) that restart every calendar year, or one sequence across years if yearly_reset is false. The number shown is always the XML Numero. - [Create a numbering series](/en/api/reference/numbering-series/createNumberingSeries): A prefix and/or suffix ("FT-", "/A"), restarting every year unless yearly_reset is false. Live keys only (403 livemode_required). - [Retrieve a numbering series](/en/api/reference/numbering-series/getNumberingSeries) - [Rename, set as default or archive a series](/en/api/reference/numbering-series/updateNumberingSeries): prefix, suffix and yearly_reset change only while no invoice uses the series (409 numbering_series_in_use). Live keys only. - Advisors: The company’s commercialista: a team member with read-only access (role auditor) who reads and exports invoices, received invoices, bank movements and taxes and changes nothing - [List the commercialisti with access](/en/api/reference/advisors/listAdvisors): Active advisors (id mem_…, members with the auditor role) and pending invitations (id inv_…). Not paginated: has_more is always false. - [Invite a commercialista](/en/api/reference/advisors/createAdvisor): Emails the standard team invitation with the read-only auditor role (201); the advisor appears with status invited until they accept. An address that already has a pending advisor invitation gets it back (200) and no second email. 409 already_member for an address already in the team, already_invited for one invited to another role. Live keys only (403 livemode_required). The key’s member needs the invites.manage permission (to invite or revoke) or members.manage (to remove a member), the same rules as the app; otherwise 403. - [Invite a commercialista to several companies](/en/api/reference/advisors/inviteAdvisorToCompanies): Invites one commercialista (read-only auditor role) to this account and/or several of its client companies at once (company_ids, at most 25; without them, the company of the Getbeel-Company header, else this account). Each company is invited exactly like POST /advisors, with its own permissions and invitation policies. Always 200 with one result per company: invited, already_invited (the pending invitation, no second email), or failed with the reason (company_not_found for an id that is not this account or a client company you manage, already_member, invite_not_allowed, subscription_required, credits_exhausted, rate_limited, invite_failed). One company failing never stops the others. A test key gets 403 livemode_required before anything is sent. Live keys only (403 livemode_required). The key’s member needs the invites.manage permission (to invite or revoke) or members.manage (to remove a member), the same rules as the app; otherwise 403. - [Revoke an invitation or remove a commercialista](/en/api/reference/advisors/deleteAdvisor): inv_… revokes the pending invitation; mem_… removes the member from the team, who loses access at once. Live keys only (403 livemode_required). The key’s member needs the invites.manage permission (to invite or revoke) or members.manage (to remove a member), the same rules as the app; otherwise 403. - Unknown - [invoice.sent](/en/api/reference/unknown/invoice.sent): SDI accepted the invoice (it has an identificativo_sdi). Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [invoice.delivered](/en/api/reference/unknown/invoice.delivered): SDI delivered the invoice to the customer (RC). Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [invoice.not_delivered](/en/api/reference/unknown/invoice.not_delivered): SDI could not deliver it (MC): the invoice is issued and waits in the customer's fiscal drawer; tell your customer. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [invoice.rejected](/en/api/reference/unknown/invoice.rejected): SDI rejected the invoice (NS); sdi.error_codes lists the codes. Fix it and create a new invoice. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [bank_statement.parsed](/en/api/reference/unknown/bank_statement.parsed): A bank statement was read: its transactions are saved and AI matching starts. data.object is the BankStatement. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [reconciliation.completed](/en/api/reference/unknown/reconciliation.completed): AI matching of a statement finished (status review): the matches can be reviewed. data.object is the Reconciliation. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [received_invoice.created](/en/api/reference/unknown/received_invoice.created): A supplier invoice was received through SDI (source sdi) or collected (mailbox scan, forwarding, upload). data.object is the ReceivedInvoice. Live endpoints; test endpoints get the sandbox ones (POST /sandbox/inbound-invoices). Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [invoice.emailed](/en/api/reference/unknown/invoice.emailed): An invoice or reminder email was sent. data.object is the InvoiceEmail. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [invoice.email_failed](/en/api/reference/unknown/invoice.email_failed): An invoice or reminder email could not be sent. data.object is the InvoiceEmail (error says why). Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [invoice.paid](/en/api/reference/unknown/invoice.paid): The payments recorded cover what is due (app, API or Stripe payment link). data.object is the Invoice. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [invoice.overdue](/en/api/reference/unknown/invoice.overdue): The day after the due date, once per invoice, when it is not paid. data.object is the Invoice. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [filing.ready](/en/api/reference/unknown/filing.ready): A filing was prepared or recomputed (F24 ready to pay). data.object is the Filing. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [filing.filed](/en/api/reference/unknown/filing.filed): The receipt of a filing was uploaded: it is paid. data.object is the Filing. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [tax_deadline.upcoming](/en/api/reference/unknown/tax_deadline.upcoming): A tax deadline is 7 days or 1 day away and not paid yet (once each). data.object is the TaxDeadline with reminder_days_before. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [tax_deadline.insufficient_funds](/en/api/reference/unknown/tax_deadline.insufficient_funds): Within 5 working days of an F24 due date, the F24 payments due that day are higher than the balance of every connected bank account (once per due date). data.object is the F24FundsAlert. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [bank_connection.expiring](/en/api/reference/unknown/bank_connection.expiring): The consent of a bank connection ends within 7 days (once per consent): reconnect it with POST /bank-connections/{id}/reconnect. data.object is the BankConnection. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - [bank_connection.expired](/en/api/reference/unknown/bank_connection.expired): The consent of a bank connection ended or was revoked (status requires_reconnect; once per consent): automatic updates stopped until it is reconnected. data.object is the BankConnection. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=,v1=." keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days. - Reference data - [Tipo documento (TD)](/en/api/reference-data/tipo-documento): The tipo_documento values FatturaPA allows, from TD01 to TD29. - [Natura IVA (N)](/en/api/reference-data/natura): The natura codes for lines without VAT, N1 to N7 with sub-codes. - [Regime fiscale (RF)](/en/api/reference-data/regime-fiscale): The regime_fiscale values of the seller, RF01 to RF20. - [Modalità di pagamento (MP)](/en/api/reference-data/modalita-pagamento): The FatturaPA ModalitaPagamento values, MP01 to MP23. - [SDI rejection codes](/en/api/reference-data/sdi-errors): Every code in SDI rejection receipts, with its cause and how to fix it. - [Changelog](/en/api/changelog): Changes to the Getbeel API that can affect an integration, newest first. - For you: Guides to using Getbeel - [Getbeel in your AI assistant](/en/guide): Look up and prepare Italian e-invoices from Claude, ChatGPT or Cursor, without writing code. - **Using getbeel** - Getting started - [Getting started](/en/guide/getting-started): What Getbeel does and where to begin: company details, mailboxes, bank and your first e-invoice. - [Quick start](/en/guide/getting-started/quick-start): Set up your company, connect a mailbox and issue your first e-invoice, in the order of the Overview's "Get started" list. - [Issue and send an invoice](/en/guide/emettere-fatture): From draft to SDI in a minute, and how to read the outcome. - Received invoices - [Invoice management](/en/guide/invoice-management): Collect supplier invoices from email, uploads and SDI: the AI reads and classifies them. - [Email connections](/en/guide/invoice-management/gmail-integration): Connect Gmail, Outlook, IMAP or email forwarding: Getbeel finds supplier invoices in your mailbox. - [AI data extraction](/en/guide/invoice-management/ai-extraction): What Getbeel's AI reads from each invoice, and how to upload files by hand. - [Invoice workflow](/en/guide/invoice-management/invoice-workflow): From the invoice the AI read to the export for your accountant: check, approve and export received invoices. - [Categories and AI rules](/en/guide/invoice-management/categories-rules): Organize expenses with categories and give the AI plain-language instructions for reading invoices. - [Autofatture](/en/guide/autofatture): Purchases from foreign suppliers, from the bank statement to the self-invoice sent to SDI. - Reconciliation - [Bank reconciliation](/en/guide/bank-reconciliation): Upload a bank statement or connect your bank: Getbeel matches each payment to the supplier invoice and you confirm. - [Statement upload](/en/guide/bank-reconciliation/statement-upload): Upload a bank statement (CSV, PDF, Excel, text, CBI, CAMT.053 or MT940): Getbeel reads the transactions and matches them to invoices. - [AI transaction matching](/en/guide/bank-reconciliation/ai-matching): The rules Getbeel uses to match each payment out of your account to a received invoice, and when it confirms on its own. - [Review workflow](/en/guide/bank-reconciliation/review-workflow): Confirm the suggested matches, resolve missing invoices and complete the reconciliation of a bank statement. - [Connect your bank](/en/guide/collega-la-banca): Your account transactions arrive in Getbeel on their own, without uploading statements. Step-by-step guide. - Analytics - [Analytics and dashboard](/en/guide/analytics): Where to see your company's numbers: the Overview, the list of received invoices and the Analytics of bank transactions. - [Overview](/en/guide/analytics/dashboard): The app's first page: the month's activity, the Get started list and the next tax deadlines. - [Spending analytics](/en/guide/analytics/spending-analytics): The Analytics page: spending, earnings, vendors and profit and loss by period, calculated from the bank transactions in Reconciliation. - [Invoice list and search](/en/guide/analytics/invoice-list): Find a received invoice, filter by period, category and source, and export the list to CSV, Excel or ZIP. - [Reports and your accountant](/en/guide/report-e-commercialista): Profit and loss, cash flow and receivables aging; the export for your accountant and how to invite them read-only. - Team - [Team collaboration](/en/guide/team-collaboration): Each company is a team with its own members: Owner, Member or Accountant, each with their own permissions. - [Roles and permissions](/en/guide/team-collaboration/roles-permissions): What the Owner, Member and Accountant can do, and how to change a person’s role. - [Team invitations](/en/guide/team-collaboration/team-invitations): Invite people to the team by email with a role, and manage pending invitations: role, renewal and removal. - **AI assistant** - [Connect Claude, ChatGPT or Cursor](/en/guide/connect-ai): How to connect your AI assistant to Getbeel, step by step. - [Example prompts](/en/guide/example-prompts): What to ask your assistant once it is connected to Getbeel. - **E-invoicing** - [Codice destinatario](/en/guide/codice-destinatario): What the codice destinatario is, how to register it with the Agenzia delle Entrate, and what changes with Getbeel. - [Invoice numbering](/en/guide/numerazione-fatture): How Getbeel numbers issued invoices: 1, 2, 3… restarting at 1 every year, as the Agenzia delle Entrate allows. - [Free conservazione by the Agenzia delle Entrate](/en/guide/conservazione): E-invoices must be preserved to legal standards. The Agenzia delle Entrate offers a free service: here is how to switch it on. - **Taxes** - [Taxes](/en/guide/tasse): Deadlines, VAT registers and settlements kept up to date from your invoices. Getbeel prepares the F24; you check and pay. - [Annual VAT return](/en/guide/dichiarazione-iva): The data of your annual VAT return from Getbeel's VAT registers, the LIPE checked against the official schema, and what you or your accountant still do. - [Withholding tax (ritenute)](/en/guide/ritenute): Invoices with ritenuta and cassa previdenziale, withholdings to pay when you pay a professional, F24 code 1040 and data for the Certificazione Unica. - [Fixed assets and depreciation](/en/guide/cespiti): Register business assets, also from a received invoice: Getbeel computes the tax depreciation, disposals and the year's libro cespiti. - [Tax estimate](/en/guide/stima-imposte): How much to set aside for IRES and IRAP (companies), IRPEF and its surcharges (individuals in the ordinary regime), the forfettario or minimi substitute tax, and INPS, with the dates of advances and balance. An estimate to check with your accountant. - [Linking POS terminals to telematic tills](/en/guide/collegamento-pos-rt): Since 2026 every POS must be linked to the till (RT) in the Agenzia delle Entrate portal. Getbeel keeps the links, tells you when to communicate them and prepares the CSV for the bulk upload.