# Getbeel > Getbeel è un’API e un server MCP per la fatturazione elettronica italiana (FatturaPA, SDI): crea, valida e invia fatture, segui le ricevute SDI con i webhook e prova ogni esito in una sandbox gratuita. - Markdown of any page: add `.md` to its URL, e.g. https://docs.getbeel.com/it/api/quickstart.md - All pages in one file: https://docs.getbeel.com/it/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 - English version: https://docs.getbeel.com/en/llms.txt # Docs - API: Per sviluppatori - [Introduzione](/it/api): L'API REST e il server MCP di Getbeel per la fatturazione elettronica italiana. - [Quickstart](/it/api/quickstart): Crea una chiave di test, fai la prima chiamata, valida un XML e invia una fattura nella sandbox. - **Concetti** - [Autenticazione](/it/api/authentication): Chiavi API di test e live, scope e buone pratiche. - [Errori](/it/api/errors): La forma degli errori, gli stati HTTP e ogni codice che l'API può restituire, con cosa fare. - [Limiti di richieste](/it/api/rate-limits): 120 richieste al minuto per chiave, con header RateLimit e Retry-After. - [Idempotenza](/it/api/idempotency): Ripeti in sicurezza le richieste che creano o inviano fatture con l'header Idempotency-Key. - [Ciclo di vita SDI](/it/api/sdi-lifecycle): Gli stati di una fattura emessa, cosa significa ogni esito dello SDI e cosa fare. - [Paginazione](/it/api/pagination): Gli elenchi usano una paginazione a cursore con limit, cursor, has_more e next_cursor. - [Sandbox](/it/api/sandbox): Le chiavi di test inviano a uno SDI simulato da getbeel. Ecco come ottenere ogni esito. - [Prezzi, saldo e consumi](/it/api/pricing): Paghi quanto usi da un saldo prepagato. Il listino, il saldo, le ricariche, i consumi e l'errore 402 insufficient_balance. - [Più aziende (multi-company)](/it/api/companies): Software house, marketplace e commercialisti gestiscono le aziende dei clienti da un solo account, con una sola chiave API. - **Integrazioni** - [Ricezione da SDI](/it/api/sdi-receiving): Ricevi le fatture dei fornitori dal Sistema di Interscambio, con codice destinatario, checklist e sandbox. - [Fatture ricevute](/it/api/received-invoices): Elenca e controlla le fatture dei fornitori, caricane una da far leggere all'AI e gestisci le categorie e le regole AI che le archiviano. - [Autofatture](/it/api/autofatture): Leggi un'autofattura in reverse charge (TD17, TD18, TD19) e inviala allo SdI, esattamente come il pulsante Invia allo SdI. - [Email, pagamenti e solleciti](/it/api/invoice-collection): Invia la fattura al cliente, registra i pagamenti, crea un link di pagamento Stripe e manda i solleciti. - [Fatture ricorrenti](/it/api/recurring-invoices): Ripeti una fattura ogni mese, trimestre o anno, con l'invio allo SDI facoltativo. - [Note di credito, preventivi, articoli e numerazione](/it/api/invoicing): Storna una fattura con una nota di credito TD04, trasforma un preventivo in fattura, salva articoli e numera con i sezionali. - [Banca e riconciliazione](/it/api/bank-reconciliation): Carica un estratto conto, lascia che l'AI abbini i pagamenti alle fatture ricevute e poi verifica gli abbinamenti. - [Collegamento banca](/it/api/bank-connections): Movimenti bancari automatici con Enable Banking, usando l'applicazione Enable Banking della tua azienda. - [Connessioni](/it/api/connections): Collega caselle email e Stripe, cerca le fatture dei fornitori e verifica i documenti raccolti. - [Drive](/it/api/drive): Leggi il Drive dell'azienda per mese o cartella, scarica un file, carica documenti e gestisci le cartelle. - [Tasse e scadenze](/it/api/taxes): Lo scadenzario fiscale della tua azienda italiana, come JSON o come calendario .ics, e la stima della posizione IVA. - [Registri IVA e liquidazioni](/it/api/vat-registers): I registri IVA vendite e acquisti, la liquidazione IVA mensile o trimestrale con il suo F24 e il file della LIPE, preparati dai documenti in Getbeel. - [Report ed export per il commercialista](/it/api/reports): Conto economico, flussi di cassa e crediti per scadenza dai dati in Getbeel, e lo ZIP con XML, prima nota IVA e registri da dare al commercialista. - [Commercialista (advisors)](/it/api/advisors): Invitare un commercialista con accesso in sola lettura, vedere chi ha accesso, revocare un invito o rimuoverlo. - [Adempimenti (F24, LIPE, dichiarazione IVA)](/it/api/filings): Prepara l'F24 dell'imposta di bollo, delle ritenute o dell'IVA, il file della LIPE o i dati della dichiarazione IVA annuale, con i valori da copiare, il link alla pagina dell'Agenzia delle Entrate e le bozze email, poi registra la quietanza. - [Regole fiscali](/it/api/tax-rules): I valori e le proroghe dietro lo scadenzario e le stime, con le fonti ufficiali; per gli amministratori di getbeel, le proposte del controllo settimanale delle fonti. - [Cespiti, stime e POS–RT](/it/api/tax-tools): Cespiti e ammortamenti con il libro cespiti, la stima delle imposte (IRES, IRAP, IRPEF, forfettario, minimi, INPS) e i collegamenti POS–RT con il file CSV dell'Agenzia delle Entrate. - [Ritenute d'acconto](/it/api/withholdings): Fatture con ritenuta e cassa previdenziale, ritenute dovute come sostituto d'imposta, F24 codice 1040 e dati per la Certificazione Unica e il 770. - [Webhook](/it/api/webhooks): Ricevi un evento per ogni ricevuta SDI e verifica la firma Getbeel-Signature. - [Server MCP](/it/api/mcp): Collega Claude, ChatGPT, Cursor e altri client MCP a Getbeel. - **SDK e CLI** - [SDK TypeScript](/it/api/sdk-typescript): Il client ufficiale per Node.js e TypeScript, generato dalla specifica OpenAPI. - [SDK Python](/it/api/sdk-python): Il client Python ufficiale, tipizzato, con una sola dipendenza (httpx). - [CLI](/it/api/cli): Invia fatture, carica estratti conto e controlla le scadenze dal terminale. - **Riferimento** - Riferimento API - [Riferimento API](/it/api/reference): Ogni endpoint, generato dal documento OpenAPI, con il 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](/it/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](/it/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](/it/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)](/it/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)](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/api/reference/received-invoices/updateCategory): Changes the label or colour; the slug stays. Live keys only. - [Delete a category](/it/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](/it/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](/it/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)](/it/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)](/it/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](/it/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](/it/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](/it/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](/it/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)](/it/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](/it/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](/it/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](/it/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](/it/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)](/it/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](/it/api/reference/taxes/listFilings) - [Prepare a filing (F24, LIPE or VAT return data)](/it/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](/it/api/reference/taxes/getFiling) - [The F24 reminder PDF, the LIPE XML or the VAT return data](/it/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](/it/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](/it/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](/it/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)](/it/api/reference/taxes/listFilingEvents) - [Comment on a filing](/it/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](/it/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](/it/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](/it/api/reference/taxes/getWithholding) - [Change a withholding (e.g. the day the fee was paid)](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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)](/it/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](/it/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](/it/api/reference/taxes/getFixedAsset) - [Change a fixed asset or record its disposal](/it/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](/it/api/reference/taxes/deleteFixedAsset): Removes it from the register. Live keys only (403 livemode_required). Free. - [Libro cespiti of a year](/it/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)](/it/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](/it/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](/it/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](/it/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](/it/api/reference/taxes/getPosRtLink) - [Change or end a POS–RT link](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/api/reference/bank-connections/getBankConnection) - [Disconnect a bank](/it/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](/it/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](/it/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](/it/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](/it/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](/it/api/reference/companies/getCompany) - [Change company data](/it/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](/it/api/reference/account/getAccount) - [This month's SDI usage and plan](/it/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](/it/api/reference/invoices/listInvoices) - [Create a draft invoice](/it/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](/it/api/reference/invoices/getInvoice) - [Edit a draft invoice](/it/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](/it/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](/it/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](/it/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](/it/api/reference/invoices/listInvoiceDeliveries) - [Payments recorded on an invoice, oldest first](/it/api/reference/invoices/listInvoicePayments) - [Record a payment (mark as paid)](/it/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](/it/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)](/it/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](/it/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](/it/api/reference/invoices/listCreditNotes) - [Create a credit note (TD04) for an invoice](/it/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](/it/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](/it/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](/it/api/reference/recurring-invoices/listRecurringInvoices) - [Make an invoice recurring](/it/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](/it/api/reference/recurring-invoices/getRecurringInvoice) - [Change interval, next date, auto_send or active](/it/api/reference/recurring-invoices/updateRecurringInvoice) - [Delete a schedule (the invoices it created stay)](/it/api/reference/recurring-invoices/deleteRecurringInvoice) - [Pause a schedule](/it/api/reference/recurring-invoices/pauseRecurringInvoice) - [Resume a schedule](/it/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](/it/api/reference/bank-reconciliation/listBankStatements) - [Upload a bank statement and reconcile it](/it/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](/it/api/reference/bank-reconciliation/getBankStatement) - [List bank transactions, newest first](/it/api/reference/bank-reconciliation/listBankTransactions): Filter by statement, date range and reconciliation state (status). - [Run the AI matching of a statement again](/it/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)](/it/api/reference/bank-reconciliation/getReconciliation) - [List the matches of a reconciliation](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/api/reference/connections/listConnections) - [Connect a mailbox](/it/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](/it/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](/it/api/reference/connections/getForwardingAddress) - [Link to connect Stripe](/it/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](/it/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](/it/api/reference/quotes/listQuotes) - [Create a quote](/it/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](/it/api/reference/quotes/getQuote) - [Update a quote](/it/api/reference/quotes/updateQuote): Not after it was converted (quote_converted) or accepted (quote_not_editable). - [Delete a quote (its invoice, if any, stays)](/it/api/reference/quotes/deleteQuote) - [Email the quote PDF to the customer](/it/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](/it/api/reference/quotes/acceptQuote) - [Mark a quote declined](/it/api/reference/quotes/declineQuote) - [Turn a quote into an invoice draft](/it/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](/it/api/reference/quotes/getQuotePdf) - Items: Saved items and services (articoli) for invoice lines - [List saved items, by name](/it/api/reference/items/listItems) - [Save an item or service](/it/api/reference/items/createItem) - [Retrieve an item](/it/api/reference/items/getItem) - [Update an item (past invoices keep their values)](/it/api/reference/items/updateItem) - [Delete an item](/it/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](/it/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](/it/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](/it/api/reference/numbering-series/getNumberingSeries) - [Rename, set as default or archive a series](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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](/it/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. - Dati di riferimento - [Tipo documento (TD)](/it/api/reference-data/tipo-documento): I valori di tipo_documento ammessi dalla FatturaPA, da TD01 a TD29. - [Natura IVA (N)](/it/api/reference-data/natura): I codici natura per le righe senza IVA, da N1 a N7 con i sottocodici. - [Regime fiscale (RF)](/it/api/reference-data/regime-fiscale): I valori di regime_fiscale del cedente/prestatore, da RF01 a RF20. - [Modalità di pagamento (MP)](/it/api/reference-data/modalita-pagamento): I valori di ModalitaPagamento della FatturaPA, da MP01 a MP23. - [Codici di scarto SDI](/it/api/reference-data/sdi-errors): Ogni codice delle ricevute di scarto dello SDI, con la causa e come correggerlo. - [Changelog](/it/api/changelog): Le modifiche all'API di Getbeel che possono toccare un'integrazione, dalla più recente. - Per te: Guide all'uso di Getbeel - [Getbeel nel tuo assistente AI](/it/guide): Consulta e prepara le fatture elettroniche da Claude, ChatGPT o Cursor, senza scrivere codice. - **Usare getbeel** - Per iniziare - [Per iniziare](/it/guide/getting-started): Cosa fa Getbeel e da dove partire: dati aziendali, caselle email, banca e prima fattura elettronica. - [Guida rapida](/it/guide/getting-started/quick-start): Configura l'azienda, collega una casella ed emetti la prima fattura elettronica, nell'ordine dell'elenco "Per iniziare" della Panoramica. - [Emettere e inviare una fattura](/it/guide/emettere-fatture): Dalla bozza allo SDI in un minuto, e come leggere l'esito. - Fatture ricevute - [Gestione delle fatture](/it/guide/invoice-management): Raccogli le fatture dei fornitori da email, caricamenti e SDI: l'AI le legge e le classifica. - [Connessioni email](/it/guide/invoice-management/gmail-integration): Collega Gmail, Outlook, IMAP o l’inoltro email: Getbeel trova le fatture dei fornitori nella casella. - [Estrazione dati con IA](/it/guide/invoice-management/ai-extraction): Cosa legge l'AI di Getbeel da ogni fattura, e come caricare i file a mano. - [Flusso delle fatture](/it/guide/invoice-management/invoice-workflow): Dalla fattura letta dall'AI all'export per il commercialista: controlla, approva ed esporta le fatture ricevute. - [Categorie e regole IA](/it/guide/invoice-management/categories-rules): Organizza le spese con le categorie e dai all'AI istruzioni in linguaggio naturale per leggere le fatture. - [Autofatture](/it/guide/autofatture): Gli acquisti da fornitori esteri, dall'estratto conto all'autofattura inviata allo SDI. - Riconciliazione - [Riconciliazione bancaria](/it/guide/bank-reconciliation): Carica un estratto conto o collega la banca: Getbeel abbina ogni uscita alla fattura del fornitore e tu confermi. - [Caricamento estratti conto](/it/guide/bank-reconciliation/statement-upload): Carica un estratto conto (CSV, PDF, Excel, testo, CBI, CAMT.053 o MT940): Getbeel legge i movimenti e li abbina alle fatture. - [Corrispondenza transazioni con IA](/it/guide/bank-reconciliation/ai-matching): Le regole con cui Getbeel abbina ogni uscita del conto a una fattura ricevuta, e quando conferma da solo. - [Flusso di revisione](/it/guide/bank-reconciliation/review-workflow): Conferma gli abbinamenti proposti, risolvi le fatture mancanti e completa la riconciliazione di un estratto conto. - [Collega la banca](/it/guide/collega-la-banca): I movimenti del conto arrivano da soli in Getbeel, senza caricare estratti conto. Guida passo per passo. - Analisi - [Analisi e dashboard](/it/guide/analytics): Dove vedere i numeri dell'azienda: la Panoramica, l'elenco delle fatture ricevute e l'Analisi dei movimenti bancari. - [Panoramica](/it/guide/analytics/dashboard): La prima pagina dell'app: l'attività del mese, l'elenco Per iniziare e le prossime scadenze fiscali. - [Analisi di spesa](/it/guide/analytics/spending-analytics): La pagina Analisi: spese, entrate, fornitori e conto economico per periodo, calcolati dai movimenti bancari in Riconciliazione. - [Lista fatture e ricerca](/it/guide/analytics/invoice-list): Trova una fattura ricevuta, filtra per periodo, categoria e fonte, ed esporta l'elenco in CSV, Excel o ZIP. - [Report e commercialista](/it/guide/report-e-commercialista): Conto economico, flussi di cassa e crediti per scadenza; l'export per il commercialista e come invitarlo in sola lettura. - Team - [Collaborazione del team](/it/guide/team-collaboration): Ogni azienda è un team con i suoi membri: Proprietario, Membro o Commercialista, ognuno con i suoi permessi. - [Ruoli e permessi](/it/guide/team-collaboration/roles-permissions): Cosa possono fare Proprietario, Membro e Commercialista, e come cambiare il ruolo di una persona. - [Inviti del team](/it/guide/team-collaboration/team-invitations): Invita persone nel team via email con un ruolo, e gestisci gli inviti in sospeso: ruolo, rinnovo e rimozione. - **Assistente AI** - [Collega Claude, ChatGPT o Cursor](/it/guide/connect-ai): Come collegare il tuo assistente AI a Getbeel, passo per passo. - [Esempi di richieste](/it/guide/example-prompts): Cosa chiedere al tuo assistente collegato a Getbeel. - **Fatture elettroniche** - [Codice destinatario](/it/guide/codice-destinatario): Cos'è il codice destinatario, come si registra presso l'Agenzia delle Entrate e cosa cambia con Getbeel. - [Numerazione delle fatture](/it/guide/numerazione-fatture): Come Getbeel numera le fatture emesse: 1, 2, 3… che ripartono da 1 ogni anno, come consente l'Agenzia delle Entrate. - [Conservazione gratuita dell'Agenzia delle Entrate](/it/guide/conservazione): Le fatture elettroniche vanno conservate a norma. L'Agenzia delle Entrate offre un servizio gratuito: ecco come attivarlo. - **Tasse** - [Tasse](/it/guide/tasse): Scadenze, registri IVA e liquidazioni aggiornati dalle tue fatture. Getbeel prepara l'F24; tu controlli e paghi. - [Dichiarazione IVA annuale](/it/guide/dichiarazione-iva): I dati della dichiarazione IVA dai registri IVA di Getbeel, la LIPE controllata con lo schema ufficiale, e cosa resta da fare a te o al commercialista. - [Ritenute d'acconto](/it/guide/ritenute): Fatture con ritenuta e cassa previdenziale, ritenute da versare quando paghi un professionista, F24 codice 1040 e dati per la Certificazione Unica. - [Cespiti e ammortamenti](/it/guide/cespiti): Registra i beni strumentali, anche da una fattura ricevuta: Getbeel calcola l'ammortamento fiscale, la cessione e il libro cespiti dell'anno. - [Stima delle imposte](/it/guide/stima-imposte): Quanto mettere da parte per IRES e IRAP (società), IRPEF e addizionali (persone fisiche in regime ordinario), imposta sostitutiva del forfettario o dei minimi e INPS, con le date di acconti e saldo. Una stima da verificare con il commercialista. - [Collegare i POS ai registratori telematici](/it/guide/collegamento-pos-rt): Dal 2026 ogni POS va collegato all'RT nel portale dell'Agenzia delle Entrate. Getbeel tiene i collegamenti, ti dice entro quando comunicarli e prepara il file CSV per il caricamento massivo.