GetbeelDocs

Server MCP

Collega Claude, ChatGPT, Cursor e altri client MCP a Getbeel.

Il server MCP di Getbeel dà agli agenti AI gli stessi poteri dell'API, con gli stessi controlli.

La pagina Chiavi API e MCP: chiavi di test e live, permessi e indirizzo del server MCP.

URLhttps://www.getbeel.com/api/mcp
TrasportoStreamable HTTP, senza sessioni (solo POST, risposte JSON)
AutenticazioneAccesso con OAuth 2.1, oppure Authorization: Bearer gb_test_… / gb_live_…

Accesso con OAuth (senza chiave)

Claude (web, desktop e Claude Code), ChatGPT, Cursor e gli altri client che seguono la specifica di autorizzazione MCP si collegano con l'accesso: aggiungi l'URL qui sopra, accedi a Getbeel e scegli:

  • Team: lo spazio di lavoro su cui lavora l'app (uno per collegamento).
  • Modalità: Test (predefinita: sandbox, nulla arriva allo SDI) o Live.
  • Permessi: gli stessi scope delle chiavi API. Di default tutti quelli di lettura, la validazione e la scrittura.

La schermata mostra esattamente dove ti porta Consenti: l'host completo (claude.ai) o l'app sul tuo dispositivo (localhost:6274, cursor://…). Qualunque app può registrarsi con qualunque nome, quindi risultano verificate solo Claude e ChatGPT, di cui Getbeel ha controllato la destinazione. Ogni altra app mostra Getbeel non ha verificato questa app: autorizzala solo se hai avviato tu il collegamento.

Da quel momento l'app agisce su quel team come te, come una chiave creata da te. La trovi in Impostazioni → Chiavi API e MCP → App collegate, con l'ultimo utilizzo, e da lì puoi revocarla: perde l'accesso subito.

In claude.ai o Claude Desktop: Impostazioni → Connettori → Aggiungi connettore personalizzato, nome Getbeel, URL https://www.getbeel.com/api/mcp. Scegli Connetti e accedi.

Per chi sviluppa un client: una richiesta senza credenziali riceve 401 con WWW-Authenticate: Bearer resource_metadata="https://www.getbeel.com/.well-known/oauth-protected-resource/api/mcp". Quel documento indica il server di autorizzazione https://www.getbeel.com/api/auth (metadati in /.well-known/oauth-authorization-server/api/auth): registrazione dinamica dei client, authorization code con PKCE (solo S256), refresh token (offline_access), risorsa https://www.getbeel.com/api/mcp. I token di accesso iniziano con gb_oat_ e durano un'ora.

Con una chiave API

I client che accettano solo un header usano una chiave creata in Impostazioni → Chiavi API e MCP. Inizia con una chiave di test: con quella nessuna fattura arriva allo SDI.

claude mcp add --transport http getbeel https://www.getbeel.com/api/mcp \
  --header "Authorization: Bearer $GETBEEL_API_KEY"

Ogni altro client che supporta server MCP remoti via HTTP con header personalizzati funziona allo stesso modo.

Strumenti

L'elenco qui sotto è generato dalle definizioni degli strumenti nel codice del server (pnpm --filter docs mcp-tools), quindi corrisponde a quello che il tuo client riceve con tools/list. Le descrizioni sono quelle che il server invia all'assistente, in inglese; il server aggiunge a ciascuna lo scope richiesto.

  • Scrive: vuoto per gli strumenti di sola lettura. invia ed elimina sono segnati come distruttivi (destructiveHint): un invio live è una trasmissione allo SDI con valore fiscale.
  • Tutti gli strumenti accettano anche company_id, non elencato nella tabella: l'id di un'azienda cliente (da list_companies) su cui agire al posto dell'account della chiave. list_companies lo accetta e lo ignora.
StrumentoScopeScriveArgomenti (* = obbligatorio)Descrizione
list_companiesaccount:readnessunoThe key's own account and its client companies (for software houses, marketplaces and commercialisti that manage several companies), with each company's fiscal data and SDI readiness. Pass a company's id as company_id to any other tool to act on it.
whoamiaccount:readnessunoThe getbeel account (team) this API key belongs to, its company profile (P.IVA, regime fiscale, SDI readiness) and the key mode (test or live) and scopes.
list_invoicesinvoices:readlimit: integer
cursor: string
status: "draft" | "sending" | "sent" | "delivered" | "not_delivered" | "rejected"
date_from: string (date)
date_to: string (date)
payment_status: "unpaid" | "partially_paid" | "paid"
overdue: "true" | "false"
search: string
Lists issued invoices (fatture emesse), newest invoice_date first. Filter by status (draft, sending, sent, delivered, not_delivered, rejected) and invoice_date range, or search by customer, subject or number. Amounts are decimal strings. Pass next_cursor as cursor to get the next page. Statuses: delivered = issued and delivered. not_delivered = SDI could not deliver it (ricevuta di impossibilità di recapito): the invoice IS issued and is in the customer's reserved area (cassetto fiscale) since sdi.available_since; tell the customer, never resend it (SDI would reject the copy as a duplicate). rejected = never issued: tell the user what sdi.errors says to fix, then reopen_rejected_invoice (back to draft, same number and date), update_invoice_draft with the correction and, once the user confirms, send_invoice again (or "Correggi e reinvia" in the app). sent with sdi.error_codes 00404 = SDI already holds an accepted copy: it is issued, do not resend.
get_invoiceinvoices:readid*: stringOne issued invoice by id (fe_…), with customer, SDI status and lines. Statuses: delivered = issued and delivered. not_delivered = SDI could not deliver it (ricevuta di impossibilità di recapito): the invoice IS issued and is in the customer's reserved area (cassetto fiscale) since sdi.available_since; tell the customer, never resend it (SDI would reject the copy as a duplicate). rejected = never issued: tell the user what sdi.errors says to fix, then reopen_rejected_invoice (back to draft, same number and date), update_invoice_draft with the correction and, once the user confirms, send_invoice again (or "Correggi e reinvia" in the app). sent with sdi.error_codes 00404 = SDI already holds an accepted copy: it is issued, do not resend.
list_received_invoicesreceived_invoices:readlimit: integer
cursor: string
search: string
source: "email" | "forwarded" | "manual" | "bank_transaction" | "sdi"
status: "processing" | "pending_review" | "verified" | "rejected" | "exported" | "missing_document"
date_from: string (date)
date_to: string (date)
Lists received (supplier) invoices, newest invoice_date first, with their source (sdi, email, forwarded, …). Filter by source and invoice_date range. Pass next_cursor as cursor to get the next page. With a test key: only invoices received in the sandbox.
validate_invoiceinvoices:validatexml*: stringChecks a FatturaPA XML against the official FatturaPA XSD and the SDI content controls (IVA and natura, totals with SDI tolerances, riepilogo, TipoDocumento rules) without sending it to SDI or storing it. Returns valid and a list of errors with their AdE codes and wording (00200 = XSD).
create_invoice_draftinvoices:writecreacustomer*: object
tipo_documento: "TD01" | "TD02" | "TD04" | "TD05" | "TD06" | "TD24" | "TD25"
number: string
date: string (date)
series_id: string
related_invoice_id: string
currency: string
lines*: object[]
withholding: object
cassa_previdenziale: object
payment: object
notes: string
idempotency_key: string
Creates a draft issued invoice (fattura emessa) for the customer and lines given. Nothing is sent: use send_invoice afterwards. Customer: denominazione (company) or nome + cognome (person); an Italian customer needs partita_iva or codice_fiscale; codice_destinatario (7 characters) or pec for delivery. Lines: description, quantity (default 1), unit_price, and vat_rate (e.g. "22") or natura for a 0% line (e.g. N2.2). Amounts are decimal strings; totals are computed by getbeel. The number defaults to the next free one and the date to today. With a test key (gb_test_) the draft is a sandbox invoice. Returns the invoice with its id, number, totals and status draft.
update_invoice_draftinvoices:writemodificaid*: string
customer: object
tipo_documento: "TD01" | "TD02" | "TD04" | "TD05" | "TD06" | "TD24" | "TD25"
number: string
date: string (date)
currency: string
lines: object[]
withholding: object
cassa_previdenziale: object
payment: object
notes: string
Changes a draft invoice (status draft) with the same rules as create_invoice_draft. Send only the fields to change; each one replaces that part: lines replaces every line (send them all), customer and payment are sent whole. If the draft has a withholding or cassa_previdenziale and you change lines, withholding or cassa_previdenziale, send them again too (null removes them): their amounts depend on the lines. A number from a numbering series and the type of a credit note cannot change. Nothing is sent to SDI. Returns the updated invoice with its recomputed totals; show it to the user. A rejected invoice is reopened first with reopen_rejected_invoice; a sent or delivered one cannot be edited (it is corrected with a credit note).
reopen_rejected_invoiceinvoices:writemodificaid*: stringPuts an invoice SDI rejected (status rejected, never issued) back to draft with the same number and date, as the Agenzia delle Entrate advises for a scartata, like "Correggi e reinvia" in the app. Its sdi.errors stay visible until it is sent again. Then fix what sdi.errors says with update_invoice_draft and, after the user confirms, call send_invoice. Only for status rejected: other invoices answer invoice_not_rejected.
send_invoiceinvoices:writeinviaid*: stringSends an existing draft invoice (by id, from create_invoice_draft or list_invoices) to SDI, the Italian e-invoicing exchange. BEFORE calling this tool, show the user the invoice (customer, number, date, lines and total, e.g. with get_invoice) and get their explicit OK to send it. Never send without that confirmation. With a live key (gb_live_) this is a real, legally binding transmission to the Agenzia delle Entrate and cannot be undone; the invoice comes back as sending, then sent. With a test key (gb_test_) it goes to the getbeel sandbox: nothing is transmitted, the invoice comes back as sent and a few seconds later becomes delivered (or rejected when the buyer partita IVA is 00000000000, not_delivered when the codice destinatario is MC00000). Check it with get_invoice.
email_invoice_to_customerinvoices:writeinviaid*: string
to: string[]
cc: string[]
language: "it" | "en"
message: string
attach_xml: boolean
Emails the PDF courtesy copy (copia di cortesia) of an issued invoice to the customer, with the Stripe payment link when the invoice has one. The legal invoice is still the one SDI delivered; this is a convenience copy. Recipients default to the customer's email on the invoice. BEFORE calling, tell the user who will receive it and get their OK. With a test key (gb_test_) the invoice is a sandbox one and the email goes only to the team owner, never to the customer. Returns the email record (status sent or failed).
mark_invoice_paidinvoices:writemodificaid*: string
amount: string | number
date: string (date)
method: "bank_transfer" | "card" | "cash" | "stripe" | "other"
note: string
Records a payment on an issued invoice. Without amount it records everything still due and the invoice becomes paid; with a smaller amount it becomes partially_paid. date defaults to today, method to bank_transfer. Confirm the amount and date with the user first.
list_overdue_invoicesinvoices:readlimit: integer
cursor: string
Issued invoices past their due date and not fully paid, newest invoice_date first, with amount_due, amount_paid and the customer. Pass next_cursor as cursor for the next page.
create_payment_linkinvoices:writecreaid*: stringCreates a Stripe payment link for what is still due on an invoice, on the team's connected Stripe account (returns the existing link if there is one). Later invoice emails and reminders include it. Fails with stripe_not_connected when Stripe is not connected: tell the user to connect it in the app.
send_payment_reminderinvoices:writeinviaid*: string
to: string[]
cc: string[]
language: "it" | "en"
message: string
Emails a payment reminder (sollecito) for an unpaid invoice to the customer, with the PDF and the payment link. Recipients default to the customer's email. BEFORE calling, tell the user who will receive it and get their OK. With a test key the email goes only to the team owner.
create_recurring_invoiceinvoices:writecreainvoice_id*: string
interval*: "monthly" | "quarterly" | "yearly"
start_date: string (date)
auto_send: boolean
Copies an existing invoice (invoice_id) into a new draft every month, quarter or year, dated the day it is created, with the next number. With auto_send the new invoice is also sent to SDI (a real transmission with a live key): only set it after the user explicitly asks for it. Confirm the interval and start date with the user first.
list_bank_statementsbank:readlimit: integer
cursor: string
status: "pending" | "processing" | "parsed" | "matching" | "review" | "completed" | "failed"
Lists uploaded bank statements, newest first, with status (pending, processing, parsed, matching, review = matched and ready for review, completed, failed), bank, period and transaction counts. The id is also the reconciliation id.
get_bank_statementbank:readid*: stringOne bank statement by id (from list_bank_statements), with its status, bank, period, balances and transaction counts, as GET /v1/bank-statements/{id}. For its matches use get_reconciliation with the same id.
upload_bank_statementbank:writecreafile_url: string
file_base64: string
file_name: string
currency: string
idempotency_key: string
Uploads a bank statement (PDF, CSV or TXT, or a CBI, CAMT.053 XML or MT940 bank file, up to 50 MB; export spreadsheets as CSV) and starts reading it and matching its payments to the received invoices, like an upload in the app. Bank files are read exactly; PDF and CSV with AI. Pass file_url (a public https link) or file_base64 with file_name (base64 only for files up to about 3 MB; larger files need file_url). The statement comes back with status pending; reading and matching take a minute or two, then call get_reconciliation with its id. 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 only the new ones (0 when nothing is new). Statements whose bank account is not recognised (no bank name or last 4 digits) save every movement. Confirm with the user first: it adds the statement to their real books and uses AI credits. Needs a live key (gb_live_).
get_reconciliationbank:readid*: string
limit: integer
cursor: string
state: "to_confirm" | "reconciled" | "missing_invoice" | "no_invoice_needed" | "rejected"
The reconciliation of a bank statement (id = statement id): status, counts per state and a page of matches. Each match pairs a bank transaction with a received invoice: state to_confirm (found by AI, needs approval), reconciled, missing_invoice (payment without invoice), no_invoice_needed or rejected; match_type exact, fuzzy, manual or unmatched; confidence 0–1. Filter by state; pass next_cursor as cursor for more.
list_unmatchedbank:readtype*: "payments" | "invoices"
limit: integer
cursor: string
from: string (date)
to: string (date)
type payments: money out with no invoice found (missing documents to collect). type invoices: received invoices with no matching bank payment. Newest first; optional from/to dates (YYYY-MM-DD).
approve_matchbank:writemodificareconciliation_id*: string
match_id*: string
decision: "approve" | "reject"
Approves a reconciliation match (the invoice found is right; for a payment without invoice: no invoice is needed) or rejects it (decision reject). Show the user the transaction and the invoice, and confirm with the user first. Needs a live key.
match_manuallybank:writemodificareconciliation_id*: string
transaction_id*: string
invoice_id*: string
Links a received invoice (id from list_unmatched type invoices or list_collected_documents) to a bank transaction of a reconciliation. Show the pair and confirm with the user first. Needs a live key.
list_connectionsconnections:readnessunoThe mailboxes (gmail, outlook, imap), the forwarding address and the Stripe account connected to getbeel, with health (healthy, reconnect_required, error).
connect_mailboxconnections:writecreaprovider*: "gmail" | "outlook"Returns a link to connect a Gmail or Outlook mailbox, so getbeel can find supplier invoices in it. Confirm with the user first, then give them the link: they open it signed in to getbeel, approve access and land back in the app. (IMAP mailboxes: use the app.) Needs a live key.
scan_mailboxconnections:writecreaconnection_id*: string
from*: string (date)
to*: string (date)
Scans a connected Gmail, Outlook or IMAP mailbox (connection id from list_connections) for supplier invoices between two dates (at most a year). Runs in the background and uses AI credits: confirm with the user first. Found invoices appear in list_collected_documents. Needs a live key.
list_collected_documentsreceived_invoices:readlimit: integer
cursor: string
search: string
source: "email" | "forwarded" | "manual" | "bank_transaction" | "sdi"
status: "processing" | "pending_review" | "verified" | "rejected" | "exported" | "missing_document"
date_from: string (date)
date_to: string (date)
Supplier invoices and receipts getbeel collected (source email, forwarded, manual, bank_transaction), newest first, with their review status (pending_review needs a person). Same list as list_received_invoices. Empty with a test key.
approve_collected_documentreceived_invoices:writemodificaid*: string
decision: "approve" | "reject"
Marks a collected document as verified (approve) or rejected (decision reject), like reviewing it in the app. Show the user the vendor, date and amount, and confirm with the user first. Needs a live key.
get_tax_calendartaxes:readfrom: string (date)
to: string (date)
The company's Italian tax deadlines (scadenzario) between from and to (default: 90 days ago to a year ahead): stamp duty on e-invoices (bollo), withholding taxes (ritenute, 1040), VAT payments, LIPE and the VAT return; for a company the IRES/IRAP saldo and acconti; for a person with partita IVA the INPS contributions of the scheme in the tax profile (inps_fixed AF/CF instalments, inps_balance and inps_advance with causale AP/CP or PXX/P10, one of the two, and the forfettario 35% request inps_reduction_request). Each deadline has due_date (already moved off weekends and holidays), amount when known (bollo from the issued invoices; a VAT payment without a saved liquidazione shows the VAT computed from the registers, amount_status provisional), status (to_prepare, ready, paid, filed, not_due), can_prepare and filing_id. missing_settings lists what the user must set in the app (Tasse) first. needs_review means the rule may not fit the company: tell the user to check it.
prepare_filingtaxes:writecreatype*: "bollo" | "withholdings" | "vat_payment" | "lipe" | "vat_return" | "redditi_pf"
period*: string
amount: string
previous_credit: string
previous_debt: string
annual_credit_used: string
advance: string
advance_method: "1" | "2" | "3" | "4"
declarant_fiscal_code: string
declarant_role: integer
previous_year_credit: string
idempotency_key: string
Prepares a filing for a deadline: type bollo (stamp duty on e-invoices, period a closed quarter like 2026-Q3, amount computed by getbeel from the issued invoices), withholdings (ritenute on professionals’ fees paid in a month, period like 2026-10, codice 1040: getbeel adds up the fees recorded with list_withholdings and paid in that month; pass amount only for fees not recorded in getbeel), vat_payment (the liquidazione IVA of a closed month or quarter, as the company settles VAT: saves it and returns its F24; call get_vat_settlement first and show it; optional previous_credit / previous_debt only to replace what getbeel computed for the previous period, or when it has no earlier data that year (note previous_missing), annual_credit_used, advance and advance_method for the December/Q4 acconto), lipe (the LIPE XML of a closed quarter from the saved liquidazioni, checked against the official XSD; companies pass declarant_fiscal_code of the signer and declarant_role, 1 = legal representative) or vat_return (period a closed year like 2026: the data sheet of the annual Dichiarazione IVA, quadri VE, VF, VJ, VL, VX in whole euros from the VAT registers and saved liquidazioni, with issues to check; optional previous_year_credit for VL25; not the telematic file, which the user or accountant fills with the AdE software) or redditi_pf (period a closed year: the data sheet of the Redditi PF return of a persona fisica, from the tax estimate of the year in Stima imposte, entity forfettario, irpef or minimi: lines of quadri LM, RE, RN, RV, RR and the saldo/acconti F24 codes; returns redditi_pf_not_applicable for a company; not the telematic file). vat_payment answers nothing_due (the liquidazione is still saved) for a credit, for up to €100 carried forward and for Q4 of quarterly payers; lipe answers settlements_missing until every month or the quarter is saved. Returns the filing with f24_lines (none for lipe and redditi_pf; 6099 for a vat_return balance), checks (xsd for the LIPE; the AdE control software is never run by getbeel) and next_steps (file link, AdE page, values to copy, email drafts). Nothing is paid, signed or sent: the user pays in F24 web or home banking, and checks, signs and uploads the LIPE in their AdE area. VAT figures are computed from the registers in getbeel and must be checked ("da verificare"). Tell the user the amount and period and get their OK first. Calling again before it is paid or filed recomputes it. Needs a live key. Pay as you go: each filing is charged once per type, period and company from the prepaid balance, when it is paid or filed (record_filing_receipt, or set_filing_status filed with the protocol number of a return); preparing it (by hand or automatically), preparing it again, the review (approving included) and skipping it are free: any F24 (bollo, withholdings, vat_payment) €1.00, LIPE €3.00, VAT return data €12.00, Redditi PF return €9.00. Tell the user the price before they mark it paid or filed.
get_filing_next_stepstaxes:readid*: stringOne prepared filing (id fil_… from get_tax_calendar or prepare_filing) with what the user does next: next_steps.file_url (F24 reminder PDF), deep_link (the AdE page to open; the user signs in with SPID/CIE), copy_values (codice tributo, year, amount…), drafts (emails to the bank or the commercialista, in Italian; never send them yourself) and steps.
record_filing_receipttaxes:writemodificaid*: string
file_url: string
file_base64: string
file_name: string
Attaches the receipt (F24 quietanza or the AdE receipt of a LIPE, PDF/PNG/JPEG up to 10 MB) to a ready filing and marks it paid (a LIPE: filed). Pass file_url (public https link) or file_base64 with file_name. ONLY after the user confirms they paid and that this is the receipt: ask first. Needs a live key. Pay as you go: each filing is charged once per type, period and company from the prepaid balance, when it is paid or filed (record_filing_receipt, or set_filing_status filed with the protocol number of a return); preparing it (by hand or automatically), preparing it again, the review (approving included) and skipping it are free: any F24 (bollo, withholdings, vat_payment) €1.00, LIPE €3.00, VAT return data €12.00, Redditi PF return €9.00. Tell the user the price before they mark it paid or filed.
get_vat_positiontaxes:readperiod*: stringVAT for a month (2026-10) or quarter (2026-Q3): sales VAT from the issued e-invoices and an ESTIMATE of purchase VAT from collected supplier invoices. reliable is always false: present it as an estimate to check with the accountant ("da verificare"), never as the amount to pay.
get_oss_returntaxes:readperiod*: stringDraft of the OSS return (union scheme) for a quarter (2026-Q3), as GET /v1/companies/me/oss-return: per Member State the taxable amount and VAT from the issued invoices with Natura N7 to EU consumers, at the standard rate of that State on the invoice date; corrections of earlier quarters from credit notes; total_due (a State with a negative balance refunds it, never offset); deadline (the nominal date: tell the user to verify any extension) and reference (the payment reference IT/IT{partita IVA}/Q{n}.{YYYY}). Tell the user about every doubtful invoice and its reason, and about rounding_gap. reliable is always false: present it as a draft to check ("da verificare"). getbeel never files or pays it: the user enters it in the AdE Portale OSS with their own credentials and pays from there (direct debit) or by bank transfer, never with F24. A nil return is still due when nil_return is true.
get_vat_registerstaxes:readperiod*: stringRegistro IVA vendite and acquisti of a month (2026-10) or quarter (2026-Q3), row by row: issued e-invoices accepted by SDI (credit notes negative, split payment recorded but not due, deferred VAT when collected), supplier invoices in the period they are deducted, as soon as the AI has read them (not reviewed yet: flagged unreviewed, tell the user to check them), and reverse-charge autofatture (TD16–TD19, TD28) on both registers. vat_counted is what enters the liquidazione after the user’s exclusions and adjustments; flags explain each row; missing lists documents of the period not in the registers yet (purchases the AI is still reading, invoices still at SDI): tell the user. reliable is always false: present it as prepared by getbeel, to check with the accountant ("da verificare").
get_vat_settlementtaxes:readperiod*: stringThe liquidazione IVA of a month or quarter (as the company settles VAT) computed now from the VAT registers, in the rows of the LIPE (lipe.vat_due VP4 … lipe.amount_due VP14): debt up to €100 or credit carried from the previous period of the same year (previous.source: saved, computed by getbeel from its registers, or input), 1% interest for quarterly payers, acconto in December/Q4. amount_to_pay is what the F24 pays now; carried_credit / carried_debt go to the next period; tax_code and due_date are the F24 values; saved is the version saved with prepare_filing (type vat_payment), with outdated true when the registers changed since. reliable is always false: show it as to check ("da verificare"). Nothing is saved: to save it and get the F24, call prepare_filing with type vat_payment after the user agrees.
get_reporttaxes:readtype*: "profit-and-loss" | "cash-flow" | "aging"
period: string
from: string (date)
to: string (date)
Management figures from the invoices and bank movements in getbeel, net of VAT. type profit-and-loss: revenue (issued e-invoices accepted by SDI) minus costs (reviewed supplier invoices, by category), by document date, with a monthly breakdown. cash-flow: money in and out of the bank accounts by month, outflows by the category of the matched supplier invoice. aging: what customers still owe today by days past due (not due, 1–30, 31–60, 61–90, over 90), per customer and invoice. period is a year (2026), quarter (2026-Q3) or month (2026-10), or send from and to; default the current year; aging ignores them. These are NOT the statutory financial statements (bilancio): say so, present the figures as to check with the accountant ("da verificare"), and mention what not_included lists (documents still at SDI, unreviewed supplier invoices).
list_withholdingstaxes:readlimit: integer
cursor: string
paid_in: string
status: "unpaid" | "withheld" | "remitted"
Fees paid (or to pay) to professionals and agents on which the company withholds the ritenuta d’acconto as sostituto d’imposta, one per received fee: recipient, CU causale, gross / not subject / taxable / withheld amounts, paid_on, status (unpaid: fee not paid yet; withheld: ritenuta to pay with F24 1040 by due_date; remitted: paid with an F24 recorded in getbeel), needs_review. Filter with paid_in (2026-10 or 2026) and status. Fees on invoices received from SDI with DatiRitenuta are recorded automatically; sync_withholdings reads older ones.
record_withholdingtaxes:writecrearecipient*: object
document: object
invoice_id: string
type: "RT01" | "RT02"
causale: "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "L1" | "M" | "M1" | "M2" | "N" | "O" | "O1" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "V1" | "V2" | "W" | "X" | "Y" | "Z" | "ZO"
rate*: string | number
gross_amount*: string | number
not_subject_amount: string | number
withheld_amount: string | number
paid_on: string (date)
notes: string
Records a fee not received through SDI (paper invoice, notula for occasional work, causale M): recipient name and codice fiscale (the CU needs it), causale, rate, gross_amount (fee net of VAT, without the contributo integrativo of the professional funds), not_subject_amount (e.g. expenses advanced for the company), paid_on (the day the fee was paid). withheld_amount is computed when left out. Show the user the figures and get their OK first. Needs a live key. Free.
update_withholdingtaxes:writemodificaid*: string
recipient: object
document: object
invoice_id: string
type: "RT01" | "RT02"
causale: "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "L1" | "M" | "M1" | "M2" | "N" | "O" | "O1" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "V1" | "V2" | "W" | "X" | "Y" | "Z" | "ZO"
rate: string | number
gross_amount: string | number
not_subject_amount: string | number
withheld_amount: string | number
paid_on: string (date)
notes: string
remitted: "true"
Changes a withholding (id wht_… from list_withholdings): most often paid_on, the day the company paid the fee, which makes the ritenuta due with F24 1040 by the 16th of the next month; also the codice fiscale, causale or amounts. A new rate or amount recomputes withheld_amount unless given. remitted: true links it to the month’s withholdings F24 already recorded as paid (only when the user says that F24 included it). Refused (withholding_remitted) once an F24 recorded in getbeel paid it. Confirm with the user first. Needs a live key. Free.
delete_withholdingtaxes:writeeliminaid*: stringDeletes a withholding recorded by mistake (id wht_… from list_withholdings), as DELETE /v1/withholdings/{id}. Refused (409 withholding_remitted) once an F24 recorded in getbeel paid it. Confirm with the user first. Needs a live key. Free.
sync_withholdingstaxes:writemodificanessunoReads the invoices received from SDI that have no withholding yet and records those with a ritenuta (DatiRitenuta RT01/RT02). Up to 100 per call; call again while has_more. Needs a live key. Free.
get_withholdings_cutaxes:readyear*: integerFor the Certificazione Unica (lavoro autonomo, provvigioni e redditi diversi) of a year: per recipient and causale, the fees paid in that year (cash principle) with CU punto 4 gross, 7 not subject, 8 taxable, 9 ritenute; recipients without a codice fiscale (missing_fiscal_code); deadlines (CU to each recipient by 16 March; to the AdE by 16 March or 30 April for lavoro autonomo abituale and non-occasional provvigioni; 770 by 31 October); form_770 with the ritenute per month and the F24 paid (quadro ST). This is data to check and give to whoever files the CU and the 770 (often the commercialista): getbeel does not produce the telematic file.
list_bank_connectionsbank:readnessunoThe banks connected for automatic transaction feeds (Enable Banking): bank, status (active, pending, requires_reconnect), consent expiry, last sync, and each bank account with IBAN, balance and number of synced transactions. Each account also lists the movements the bank still reports as pending (not booked, not matched). If a consent expires soon (expires_soon) or needs reconnecting (requires_reconnect), offer reconnect_bank_connection.
sync_bank_connectionbank:writemodificaconnection_id*: stringFetches new transactions from a connected bank now (connection id from list_bank_connections). getbeel already syncs every 6 hours and banks allow about four unattended fetches a day, so only do this when the user asks for fresh data; confirm with the user first. New transactions are matched to invoices in the background (see list_bank_statements and get_reconciliation). Needs a live key.
reconnect_bank_connectionbank:writemodificaconnection_id*: string
language: "it" | "en" | "es" | "fr"
Starts a new bank login for a connection whose consent expires soon, has expired or was revoked (connection id from list_bank_connections). Returns authorization_url: give it to the user to open in their browser (valid 30 minutes; never open it yourself). It opens a getbeel page naming the team, then the bank login. The first sync runs once they finish. Needs a live key.
delete_bank_connectionbank:writeeliminaconnection_id*: stringDisconnects a bank (connection id from list_bank_connections): getbeel stops syncing it and revokes the consent. Transactions already synced stay. It cannot be undone (connecting again needs the user in the app): confirm with the user first. Needs a live key.
get_sdi_receiving_statusreceived_invoices:readnessunoWhether the company receives its supplier e-invoices through getbeel (SDI), the codice destinatario to give suppliers and register as indirizzo telematico in the AdE area, the readiness checklist (company_data, sdi_addon, receiving_enabled, indirizzo_telematico, conservazione) and the AdE conservazione status. Explain missing steps to the user: they turn receiving on in the getbeel app (Fatture ricevute → Ricezione SDI) and register the code themselves in the AdE portal (Fatture e Corrispettivi).
enable_sdi_receivingreceived_invoices:writemodificanessunoTurns on receiving supplier e-invoices from SDI for the company (needs the SDI add-on or the rate card; received invoices are billed). Returns the status with the codice destinatario: tell the user to register it as indirizzo telematico in the AdE portal (Fatture e Corrispettivi), which they must do themselves. If the status is awaiting_approval, the P.IVA could not be verified in VIES: tell the user a getbeel operator checks it and receiving then turns on by itself (no codice yet). Confirm with the user first. Needs a live key.
disable_sdi_receivingreceived_invoices:writemodificanessunoTurns off receiving supplier e-invoices from SDI for the company: getbeel stops receiving for its P.IVA (sending to SDI is untouched; invoices already received stay). Tell the user to change or remove the indirizzo telematico in the AdE portal, or new invoices only reach the cassetto fiscale. Confirm with the user first. Needs a live key.
create_sandbox_inbound_invoicereceived_invoices:writecreaxml: string
idempotency_key: string
Test keys only (gb_test_…): receives a supplier invoice in the sandbox, as POST /v1/sandbox/inbound-invoices, so an integration can try list_received_invoices and the received_invoice.created webhook without SDI. Pass a FatturaPA XML, or nothing for a sample invoice addressed to the company. With a live key: 403 test_mode_required.
list_quotesinvoices:readstatus: "draft" | "sent" | "accepted" | "declined" | "expired"
limit: integer
Quotes (preventivi), newest first, with number, status (draft, sent, accepted, declined, expired), customer, total and the invoice id once converted. Filter with status.
create_quoteinvoices:writecreacustomer*: object
date: string (date)
currency: string
lines*: object[]
withholding: object
cassa_previdenziale: object
payment: object
notes: string
valid_until: string (date)
idempotency_key: string
Creates a draft quote (preventivo) for a customer: same customer and lines as create_invoice_draft, plus valid_until. Nothing is sent: the user can review it in the app, email it with send_quote, and turn it into an invoice with convert_quote_to_invoice. Lines: description, quantity (default 1), unit_price, vat_rate (e.g. "22") or natura for a 0% line. Use list_items for the saved items and services and their prices.
send_quoteinvoices:writeinviaid*: string
to: string[]
cc: string[]
language: "it" | "en"
message: string
Emails the quote PDF to the customer (default: the customer's email on the quote) and marks it sent. BEFORE calling, tell the user who will receive it and get their OK. With a test key the email goes only to the team owner.
convert_quote_to_invoiceinvoices:writecreaid*: string
series_id: string
date: string (date)
idempotency_key: string
Creates an invoice draft from a quote (dated today unless date is given, next number) and marks the quote accepted. Nothing is sent to SDI: show the draft to the user and use send_invoice only after their explicit OK. A quote converts once.
create_credit_noteinvoices:writecreainvoice_id*: string
lines: object[]
series_id: string
date: string (date)
reason: string
idempotency_key: string
Creates a credit note (nota di credito, TD04) draft for an invoice SDI accepted: the whole invoice, or some lines (index from get_invoice lines, optional smaller quantity). It refers to the invoice (DatiFattureCollegate) and is numbered automatically. Confirm with the user which lines and amounts to credit first. Nothing is sent: use send_invoice with the credit note id after the user explicitly OKs it. Once SDI accepts it, the invoice amount due goes down by the credit.
list_credit_notesinvoices:readinvoice_id*: stringThe credit notes (TD04) that refer to an issued invoice, drafts included, with their SDI status, as GET /v1/invoices/{id}/credit-notes. Only credit notes SDI accepted lower the amount due.
list_itemsinvoices:readsearch: string
include_archived: "true" | "false"
limit: integer
Saved items and services (articoli) with unit price, VAT rate or natura and unit, to reuse in quotes and invoices. search filters by name.
get_quoteinvoices:readid*: stringOne quote (preventivo) with its customer, lines, totals, status and validity, and the invoice id once converted.
update_quoteinvoices:writemodificaid*: string
customer: object
currency: string
lines: object[]
withholding: object
cassa_previdenziale: object
payment: object
notes: string
valid_until: string (date)
Replaces the customer, lines or validity of a quote that is not converted yet (same fields as create_quote). Confirm the changes with the user first.
delete_quoteinvoices:writeeliminaid*: stringDeletes a quote that was not converted to an invoice. It cannot be undone: confirm with the user first.
accept_quoteinvoices:writemodificaid*: stringRecords that the customer accepted the quote (status accepted). It does not create the invoice: use convert_quote_to_invoice for that.
decline_quoteinvoices:writemodificaid*: stringRecords that the customer declined the quote.
get_quote_pdfinvoices:readid*: stringRenders the quote as a PDF and returns download_url, a private link valid 15 minutes. Give the link to the user; do not fetch it yourself.
create_iteminvoices:writecreaname*: string
description: string
code: string
unit_price*: string | number
unit: string
vat_rate: string | number
natura: string
Saves a product or service (description, unit price, VAT rate or natura) for reuse in invoices and quotes.
update_iteminvoices:writemodificaid*: string
name: string
description: string
code: string
unit_price: string | number
unit: string
vat_rate: string | number
natura: string
archived: boolean
Changes a saved item (id from list_items).
delete_iteminvoices:writeeliminaid*: stringDeletes a saved item (id from list_items). Invoices that used it keep their lines. Confirm with the user first.
list_numbering_seriesinvoices:readnessunoThe numbering series of invoices and quotes (sezionali): prefix or suffix, the next number and which document types use them.
create_numbering_seriesinvoices:writecreaname*: string
prefix: string
suffix: string
yearly_reset: boolean
default_for_invoices: boolean
default_for_credit_notes: boolean
Adds a numbering series (sezionale). Numbering is fiscal: confirm the series, suffix and starting number with the user first. Needs a live key.
update_numbering_seriesinvoices:writemodificaid*: string
name: string
prefix: string
suffix: string
yearly_reset: boolean
default_for_invoices: boolean
default_for_credit_notes: boolean
archived: boolean
Changes a numbering series (id from list_numbering_series). Numbering is fiscal: confirm with the user first. Needs a live key.
list_recurring_invoicesinvoices:readlimit: integerThe recurring invoices: the source invoice, interval (monthly, quarterly, yearly), next date, whether new ones are sent to SDI automatically (auto_send) and whether it is active or paused.
get_recurring_invoiceinvoices:readid*: stringOne recurring invoice with its schedule and status.
update_recurring_invoiceinvoices:writemodificaid*: string
interval: "monthly" | "quarterly" | "yearly"
next_date: string (date)
auto_send: boolean
Changes the interval, the next date or auto_send. auto_send makes every new invoice a real SDI transmission with a live key: only turn it on when the user explicitly asks. Confirm with the user first.
pause_recurring_invoiceinvoices:writemodificaid*: stringNo new invoices are created until it is resumed.
resume_recurring_invoiceinvoices:writemodificaid*: stringStarts creating invoices again from the next date. Confirm the next date with the user first.
delete_recurring_invoiceinvoices:writeeliminaid*: stringStops and removes the schedule. Invoices already created stay. Confirm with the user first.
get_usageaccount:readperiod: stringThis month's (or period's) live SDI transactions (sent and received), the plan (rate card, SDI add-on or none), the free sends used and left, the estimated amount on the rate card, or the quota on an SDI add-on. Same as GET /v1/usage.
get_accountant_exporttaxes:readperiod*: stringBuilds the ZIP for the commercialista for a year (2026), quarter (2026-Q3) or month (2026-10): FatturaPA XML of issued and received invoices and autofatture, the prima nota IVA, the VAT registers and the bank movements. Returns download_url, a private link valid 15 minutes: give it to the user, never fetch it yourself. It holds every invoice and bank movement of the period, so the key also needs invoices:read, received_invoices:read and bank:read.
get_forwarding_addressconnections:readnessunoThe email address that receives invoices forwarded to getbeel (from suppliers or the user), and whether it is active. Null when none is set up: it is created in the app.
get_stripe_connect_linkconnections:writecreanessunoReturns a link to connect the Stripe account in the getbeel app (the user opens it and logs in to Stripe; never open it yourself). Once connected, sync_stripe_invoices turns Stripe invoices into fatture emesse.
sync_stripe_invoicesconnections:writecreafrom: string (date)
to: string (date)
Imports the Stripe invoices of a date range as draft fatture emesse (the same as Sync in the app): each one is drafted by AI (each draft is an AI document read, charged to the prepaid balance). Drafts are sent to SDI only if the Stripe connection has auto-send on. Confirm the range with the user first. Needs a live key.
get_billing_balanceaccount:readnessunoThe prepaid balance in EUR cents (net of VAT), 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 (pay_as_you_go; or legacy_plan: signed up before 13 November 2026, the account keeps its plan and everything it includes, nothing is paid from a balance, the amounts are 0 and topup_url is null), welcome_credit (granted, or not_granted_reason: card_already_used means the card already got it on another team, as it applies only once per card), and topup_url (the Billing & usage page). Billable actions (SDI sends, AI document reads, bank syncs, filings) stop when it cannot cover them; receiving invoices never stops. Same as GET /v1/billing/balance.
get_billing_usageaccount:readmonth: stringA month's pay-as-you-go usage: quantity and amount per item (meter) and, for a gestore, per client company, in EUR cents net of VAT. Same as GET /v1/billing/usage.
get_billing_pricesaccount:readnessunoThe pay-as-you-go prices (EUR cents, net of VAT) per item, with the monthly tiers of SDI sends. The platform, sandbox, API, MCP and webhooks are free. Same as GET /v1/billing/prices.
create_billing_topupbilling:writecreaamount_cents*: integerCreates a Stripe Checkout link to add amount_cents of credit (net of VAT; VAT is added at checkout). Give checkout_url to the user to pay in the browser: this tool never charges a card. Live keys with the billing:write scope only. Same as POST /v1/billing/topups.
create_billing_card_linkbilling:writecreanessunoCreates a Stripe Checkout link (setup mode: nothing is charged) where the user enters a new card; it becomes the default card and the one auto top-ups charge. Give checkout_url to the user to open in the browser. Needs a card already saved (409 no_card). Live keys with the billing:write scope only. Same as POST /v1/billing/payment-method.
list_fixed_assetstaxes:readlimit: integer
cursor: string
year: integer
The company’s fixed assets, newest purchase first, each with its tax depreciation schedule (year, max_amount, amount deducted, fondo, residual), status and residual value at the end of year (default this year). Prepared by getbeel: to check with the accountant.
register_fixed_assettaxes:writecreaname*: string
category_code: "altre.edifici" | "altre.fabbricati_gdo" | "altre.costruzioni_leggere" | "altre.sollevamento" | "altre.macchinari" | "altre.stigliatura" | "altre.arredamento" | "altre.banconi_blindati" | "altre.allarme" | "altre.comunicazione" | "altre.depurazione" | "altre.mobili_ufficio" | "altre.macchine_ufficio_elettroniche" | "altre.autoveicoli_trasporto" | "altre.autovetture" | "alberghi.edifici" | "alberghi.costruzioni_leggere" | "alberghi.mobili_arredamento" | "alberghi.biancheria" | "alberghi.attrezzatura" | "alberghi.impianti_generici" | "alberghi.impianti_specifici" | "alberghi.macchine_ufficio_elettroniche" | "alberghi.autoveicoli_trasporto" | "alberghi.autovetture" | "persona.edifici" | "persona.costruzioni_leggere" | "persona.mobili_arredamento" | "persona.biancheria" | "persona.impianti_specifici" | "persona.attrezzatura" | "persona.mobili_ufficio" | "persona.macchine_ufficio_elettroniche" | "persona.autoveicoli_trasporto" | "persona.autovetture" | "immateriali.software_brevetti" | "immateriali.marchi" | "immateriali.avviamento"
category_label: string
coefficient: number
kind: "tangible" | "intangible"
cost*: string
purchase_date: string (date)
in_service_date: string (date)
first_year_half: boolean
expense_in_full: boolean
depreciation_overrides: object
received_invoice_id: string
supplier_name: string
document_number: string
notes: string
disposal_date: string (date)
disposal_amount: string | "0.00"
idempotency_key: string
Registers a bene strumentale so its cost is depreciated instead of counted as a cost of the year. Typical case: a received invoice for a computer, a machine or furniture (pass received_invoice_id; purchase date, supplier and number come from it). category_code picks the ministerial coefficient (DM 31/12/1988; see the codes in the input schema, e.g. altre.macchine_ufficio_elettroniche 20%, altre.mobili_ufficio 12%, altre.autovetture 25%, immateriali.software_brevetti 50%); otherwise give category_label and coefficient. cost is net of deductible VAT. in_service_date starts depreciation (half rate the first year); a tangible asset up to 516.46 may be deducted in full (expense_in_full). Tell the user what you will register and get their OK. Needs a live key. Free.
update_fixed_assettaxes:writemodificaid*: string
name: string
category_code: "altre.edifici" | "altre.fabbricati_gdo" | "altre.costruzioni_leggere" | "altre.sollevamento" | "altre.macchinari" | "altre.stigliatura" | "altre.arredamento" | "altre.banconi_blindati" | "altre.allarme" | "altre.comunicazione" | "altre.depurazione" | "altre.mobili_ufficio" | "altre.macchine_ufficio_elettroniche" | "altre.autoveicoli_trasporto" | "altre.autovetture" | "alberghi.edifici" | "alberghi.costruzioni_leggere" | "alberghi.mobili_arredamento" | "alberghi.biancheria" | "alberghi.attrezzatura" | "alberghi.impianti_generici" | "alberghi.impianti_specifici" | "alberghi.macchine_ufficio_elettroniche" | "alberghi.autoveicoli_trasporto" | "alberghi.autovetture" | "persona.edifici" | "persona.costruzioni_leggere" | "persona.mobili_arredamento" | "persona.biancheria" | "persona.impianti_specifici" | "persona.attrezzatura" | "persona.mobili_ufficio" | "persona.macchine_ufficio_elettroniche" | "persona.autoveicoli_trasporto" | "persona.autovetture" | "immateriali.software_brevetti" | "immateriali.marchi" | "immateriali.avviamento"
category_label: string
coefficient: number
kind: "tangible" | "intangible"
cost: string
purchase_date: string (date)
in_service_date: string (date)
first_year_half: boolean
expense_in_full: boolean
depreciation_overrides: object
received_invoice_id: string
supplier_name: string
document_number: string
notes: string
disposal_date: string (date)
disposal_amount: string | "0.00"
Send only what changes. To record a sale or elimination give disposal_date and disposal_amount ("0.00" when thrown away): the result has disposal.gain (positive plusvalenza, negative minusvalenza). depreciation_overrides records years where less than the maximum was deducted. Get the user’s OK first. Needs a live key. Free.
delete_fixed_assettaxes:writeeliminaid*: stringDeletes a fixed asset registered by mistake (id from list_fixed_assets), as DELETE /v1/fixed-assets/{id}: it leaves the libro cespiti of every year. To record a sale or an elimination use update_fixed_asset with disposal_date instead. Confirm with the user first. Needs a live key. Free.
get_fixed_assets_registertaxes:readyear*: integerEvery asset owned during the year with fondo at 1 January and 31 December, the year’s quota and disposals; totals per category and closing_entries (a summary of the year-end depreciation entries for the accountant; getbeel keeps no general ledger). reliable is false: to check.
get_tax_estimatetaxes:readyear: integerAn ESTIMATE ("stima, da verificare con il commercialista"), never the amount to pay: for a company IRES 24% and IRAP; for the regime forfettario the imposta sostitutiva (15% or 5%) and INPS; for a persona fisica in regime ordinario (entity irpef) IRPEF by bracket, the self-employment detrazione, ritenute subite, the addizionali regionale and comunale (only when net IRPEF is due) and INPS; for the regime di vantaggio (entity minimi) the 5% imposta sostitutiva on income collected minus costs, contributions and earlier losses (quadro LM, codes 1793/1794/1795) and INPS. installments lists acconti and saldo with F24 codes and dates (confirmed false = date not yet confirmed by a source in force). figures shows what came from getbeel (invoices, payments, depreciation); warnings lists what is missing (unreviewed invoices, ATECO group, contributions assumed…). inputs_saved false means defaults: ask the user for the inputs and save them with save_tax_estimate_inputs.
save_tax_estimate_inputstaxes:writemodificayear*: integer
entity: "company" | "forfettario" | "irpef" | "minimi" | "other"
other_revenue: string | number
other_costs: string | number
personnel_costs: string | number
permanent_staff_costs: string | number
ires_adjustments: string | number
irap_rate: number
isa_subject: boolean
prior_year_ires: string | number
prior_year_irap: string | number
ateco_code: string
forfettario_group: integer
startup_rate: boolean
revenue_basis: "collected" | "invoiced"
inps_scheme: "gestione_separata" | "artigiani" | "commercianti" | "cassa_professionale" | "none"
inps_reduction_35: boolean
insured_before_1996: boolean
inps_amount_override: string | number
contributions_paid: string | number
prior_year_substitute_tax: string | number
irpef_activity: "professional" | "business"
regional_surcharge_rate: number
municipal_surcharge_rate: number
prior_year_irpef: string | number
withholdings_suffered: string | number
minimi_prior_losses: string | number
Saves for a year what getbeel cannot know: entity (company, forfettario, irpef, minimi), for irpef the kind of activity, the addizionali rates, the ritenute suffered and last year’s IRPEF due (RN34), for minimi the earlier losses still usable (LM9), ATECO code or group, start-up 5% rate, INPS scheme and 35% reduction, personnel and permanent staff costs, other revenue and costs, IRAP regional rate, last year’s taxes for the acconti. Only send what the user told you. Returns the recomputed estimate. Needs a live key; saving the inputs is free (nothing is charged to the balance).
list_pos_rt_linkstaxes:readlimit: integer
cursor: string
status: "to_file" | "filed" | "end_to_file" | "ended"
Payment terminals (POS) linked to registratori telematici (RT), with status (to_file, filed, end_to_file, ended) and pending: the operation still to communicate to the AdE and its window (from, due). Since 2026 every POS must be linked to the RT in the AdE portal (L. 207/2024; provv. 424470/2025).
add_pos_rt_linktaxes:writecrealabel: string
rt_serial*: string
acquirer_country: "IT" | "ES"
acquirer_id*: string
acquirer_name*: string
pos_type*: "00" | "01"
terminal_id: string
contract_number*: string
itinerant: boolean
province: string
municipality: string
street: string
street_number: string
postal_code: string
active_from*: string (date)
ended_on: string (date)
idempotency_key: string
Records a POS used with an RT: rt_serial (matricola RT), acquirer_id (its codice fiscale, 11 digits) and acquirer_name, pos_type 00 physical (with terminal_id) or 01 virtual, contract_number (convenzione), the address of the shop or itinerant, active_from. Ask the user for these values; never guess them. Needs a live key. Free.
end_pos_rt_linktaxes:writemodificaid*: string
ended_on: string (date)
Sets ended_on (last day the POS was used with that RT): the end becomes the next thing to communicate. Get the user’s OK first. Needs a live key. Free.
get_pos_rt_csvtaxes:readpart: integerThe CSV for "Collegamento massivo" in Fatture e Corrispettivi with every link still to communicate (I to associate, C to end), at most 1,000 rows per part, and next_steps (the portal path). The columns follow the AdE Manuale operativo; separator and header names are not in an official document (layout.not_confirmed): if the portal refuses it, the user pastes tsv into the AdE template. The user uploads it themselves; afterwards call mark_pos_rt_links_filed with its links.
mark_pos_rt_links_filedtaxes:writemodificalinks*: object[]Only after the user confirms the AdE processed the upload (Storico richieste massive): their pending operation becomes filed. Needs a live key. Free.
get_tax_settingstaxes:readnessunoThe company’s VAT periodicity (monthly or quarterly liquidazione), whether it is a withholding agent (sostituto d’imposta) and its OSS registration (oss_from/oss_until: EU B2C sales VAT, union scheme) and the automatic F24 preparation (auto_prepare, auto_prepare_days), as Tasse → Impostazioni. null means not set: get_tax_calendar leaves those deadlines out until it is.
update_tax_settingstaxes:writemodificavat_periodicity: "monthly" | "quarterly"
withholding_agent: boolean
oss_from: string (date)
oss_until: string (date)
auto_prepare: boolean
auto_prepare_days: integer
Sets the VAT periodicity, whether the company is a withholding agent and/or its OSS registration dates (oss_from, oss_until; null clears) and/or the automatic F24 preparation (auto_prepare on by default, auto_prepare_days 1-30); only what you send changes. The periodicity decides the VAT periods of the registers, liquidazioni and F24, and oss_from adds the quarterly OSS return deadlines: set them as the company actually is registered, never guess; ask the user (or their accountant) and confirm first. Needs a live key.
get_reminder_settingsinvoices:readnessunoAutomatic payment reminders (solleciti): whether they are on, the days after the due date when they go out, and since when (enabled_at). Off by default.
update_reminder_settingsinvoices:writemodificaenabled: boolean
days: integer[]
Switches automatic payment reminders on or off and/or sets the days after the due date (up to 5 steps, e.g. [3, 10, 30]); only what you send changes. When on, getbeel emails customers of live overdue invoices due from today on: confirm with the user first. Needs a live key.
get_tax_profiletaxes:readnessunoWhich taxes apply to the company and why: legal form, regime fiscale, 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 (forfettario, impatriati…), each with its effect for the current year computed by getbeel (substitute-tax rate or taxed share, until when, F24 codes, the official source of each number) and regime\_warnings when the RegimeFiscale does not match. Each field says whether the user set it or getbeel detected it (with the evidence). questions lists what is still unknown: ask the user those questions in plain language, one at a time, and never guess the answers.
update_tax_profiletaxes:writemodificalegal_form: "srl" | "srls" | "spa" | "sapa" | "snc" | "sas" | "ditta_individuale" | "professionista" | "ente_non_commerciale" | "other"
vat_periodicity: "monthly" | "quarterly"
withholding_agent: boolean | null
has_employees: boolean | null
reverse_charge_suppliers: boolean | null
oss_registered: "false"
intrastat: boolean | null
in_liquidation: boolean | null
liquidation_from: string (date)
first_fiscal_year: integer
social_security: "gestione_separata" | "artigiani" | "commercianti" | "cassa_professionale" | "none"
social_security_fund: string
regimes: object[]
confirm: "legal_form" | "regime_fiscale" | "vat_periodicity" | "withholding_agent" | "has_employees" | "reverse_charge_suppliers" | "intrastat" | "oss_suggested" | "oss_registered" | "in_liquidation" | "first_fiscal_year" | "social_security" | "special_regimes"[]
Sets profile fields (only what you send changes; null clears a value back to the detection), confirms detected values (confirm) or replaces the special regimes (regimes, with typed params per kind, e.g. forfettario { startup: true }, impatriati_2024 { minor_child: true }). getbeel computes the rates from them; never send rates. It changes which deadlines the tax calendar lists, so only send what the user told you or confirmed: never guess, especially employees, the OSS registration, social security and special regimes. Recorded in the audit log. Needs a live key.
detect_tax_profiletaxes:writemodificanessunoRe-runs the detection from the company data (name, regime, issued and received invoices, withholdings) and returns the profile with the evidence and the questions. It never changes a value the user set; new obligations also add a notice in the app. getbeel already runs it monthly. Needs a live key.
get_filingtaxes:readid*: stringOne filing (id fil_…) with its status, amounts, F24 lines, approval (approved_at, approved_by), skip_reason, filed_reference and next steps. Use list_filing_events for its comments and history.
set_filing_statustaxes:writemodificaid*: string
status*: "needs_review" | "changes_requested" | "approved" | "skipped" | "filed"
reason: string
reference: string
expected_updated_at: string
Moves a filing in the review: approved (visto bueno), skipped (not to be done: reason required), needs_review (back to review, or reopen a skipped filing), filed (a LIPE, annual VAT return or Redditi PF return sent: reference = its protocol number), changes_requested (only the commercialista, in the app). When the team requires the commercialista’s approval, only the commercialista approves. A paid F24 is recorded with record_filing_receipt instead. Pay as you go: filed completes the filing and charges it once from the prepaid balance, like its receipt (never twice for the same filing; insufficient_balance when the balance does not cover it, and nothing changes). Approving, asking for changes, skipping and reopening are free. Only do what the user asked, and confirm first. Recorded in the history and the audit log. Needs a live key.
skip_filingtaxes:writemodificatype*: "bollo" | "withholdings" | "vat_payment" | "lipe" | "vat_return" | "redditi_pf"
period*: string
reason*: string
For a filing type and period never prepared (or already prepared), records "not to be done" with the reason (e.g. the accountant pays it, nothing is due). getbeel then never prepares it automatically and never charges it. Reopen it with set_filing_status needs_review. Only when the user says so. Needs a live key.
comment_filingtaxes:writecreaid*: string
body*: string
Adds a comment to a filing’s history, read by the team and the commercialista (e.g. a question about a figure). Needs a live key.
list_filing_eventstaxes:readid*: stringComments and status changes of a filing, oldest first, with who did them (the commercialista or the team) and the reason.
get_tax_rulestaxes:readnessunoThe rules behind the tax calendar and estimates: every rule value by date with its official source (origin code or db), the values missing in the next 13 months, and the proroghe in force. For getbeel administrators also the pending proposals of the weekly rules watch (with their source link and quote) and the last runs.
add_tax_rule_valuetax_rules:admincreakey*: string
value*: number
valid_from*: string
valid_to: string
source_url*: string
source_title*: string
source_article: string
quote: string
status: "active" | "pending"
Adds a value of a known rule key (e.g. inps.maternity_yearly) for its dates, with its official source. status active puts it in force at once (official source only: agenziaentrate.gov.it, mef.gov.it, finanze.gov.it, gazzettaufficiale.it, inps.it, normattiva.it, fatturapa.gov.it); pending (default) waits for approval. Only for getbeel administrators (a live key with the tax_rules:admin scope, created in the admin page by a super-admin); it changes every company’s calendar or estimate. Only do what the user asked, and confirm first.
add_tax_calendar_overridetax_rules:admincreadeadline_kind*: "all" | "bollo" | "withholdings" | "vat_payment" | "vat_annual_balance" | "vat_advance" | "lipe" | "vat_return" | "oss_return" | "income_tax_balance" | "income_tax_advance" | "chamber_fee" | "income_tax_return" | "financial_statements" | "inps_fixed" | "inps_balance" | "inps_advance" | "inps_reduction_request" | "pf_tax_balance" | "pf_tax_advance" | "pf_tax_return"
nominal_from*: string
nominal_to*: string
new_due_date*: string
valid_from*: string
source_url*: string
source_title*: string
quote: string
note: string
status: "active" | "pending"
Moves the deadlines of deadline_kind (all: every tax deadline) whose legal date is in nominal_from–nominal_to to new_due_date, from valid_from, citing the decree. status active applies it at once (official source only), updates prepared unpaid F24s and tells the affected teams; pending (default) waits for approval. Only for getbeel administrators (a live key with the tax_rules:admin scope, created in the admin page by a super-admin); it changes every company’s calendar or estimate. Only do what the user asked, and confirm first.
decide_tax_ruletax_rules:adminmodificakind*: "rule_value" | "override"
id*: string
decision*: "approve" | "reject" | "withdraw"
note: string
Approves (in force at once) or rejects a pending rule value or proroga (kind rule_value or override, id from get_tax_rules). Here only proposals with an official source can be approved, and rules-watch proposals only when their quote was found in the source; read the source first. Only for getbeel administrators (a live key with the tax_rules:admin scope, created in the admin page by a super-admin); it changes every company’s calendar or estimate. Only do what the user asked, and confirm first.
get_autofatturainvoices:readid*: stringOne reverse-charge autofattura (TD17, TD18, TD19) by its id (the bank transaction id on the Autofatture page): supplier, amount, TD type, number, whether the XML is ready and its SDI status (null until sent; queued, sent_to_sdi, consegnata, scartata…).
send_autofattura_to_sdiinvoices:writemodificaid*: stringSends a generated autofattura to SDI, exactly like the Send to SDI button. It is a real fiscal act paid from the prepaid balance (insufficient_balance when it does not cover it): only when the user asked, and confirm first. Returns the autofattura with sdi.status = queued; call get_autofattura later for the SDI answer. Repeating it never sends or charges again (autofattura_already_queued / autofattura_already_sent). Needs a live key.
list_advisorsadvisors:readnessunoThe commercialisti (accountants) who can see this company in getbeel with read-only access: active members (id mem_…) and pending invitations (id inv_…, with expires_at).
invite_advisoradvisors:writeinviaemail*: stringEmails an invitation to join the company as commercialista: once accepted they can read and export invoices, received invoices, bank movements and taxes, and change nothing. BEFORE calling this tool, tell the user the exact email address and that this person will see all the company’s invoices, bank data and taxes, and get their explicit OK. Needs a live key.
invite_accountantadvisors:writeinviaemail*: string
company_ids: string[]
Invites one commercialista (read-only access) to this account and/or several of its client companies at once (company_ids from list_companies, at most 25; without them, the company of company_id, else this account). Each company is invited like invite_advisor; one result per company (invited, already_invited, or failed with the reason), one failing never stops the others. BEFORE calling this tool, tell the user the exact email address and the companies, and that this person will see all their invoices, bank data and taxes, and get their explicit OK. Needs a live key.
remove_advisoradvisors:writeeliminaid*: stringRevokes a pending invitation (inv_…) or removes the commercialista from the company (mem_…), ids from list_advisors. They lose access at once. Confirm with the user first. Needs a live key.
list_ai_rulesreceived_invoices:readtype: "invoice_scan" | "fattura_emessa"The team's AI rules: plain-language instructions the AI follows, in order, when it reads received invoices (type invoice_scan) or drafts issued invoices from Stripe payments (fattura_emessa). Only active rules are followed. invoice_scan rules need the received_invoices scopes, fattura_emessa rules the invoices scopes.
create_ai_rulereceived_invoices:writecreatext*: string
type: "invoice_scan" | "fattura_emessa"
active: boolean
Adds an AI rule at the end of its type; it applies to the next invoices the AI reads, not to ones already read. Write it as the user would say it and confirm it with them first. invoice_scan rules need the received_invoices scopes, fattura_emessa rules the invoices scopes. Needs a live key.
update_ai_rulereceived_invoices:writemodificaid*: string
text: string
active: boolean
Changes an AI rule's text, or pauses (active false) or resumes it (id from list_ai_rules). invoice_scan rules need the received_invoices scopes, fattura_emessa rules the invoices scopes. Needs a live key.
delete_ai_rulereceived_invoices:writeeliminaid*: stringDeletes an AI rule (id from list_ai_rules). To stop it for a while, pause it with update_ai_rule instead. Confirm with the user first. invoice_scan rules need the received_invoices scopes, fattura_emessa rules the invoices scopes. Needs a live key.
ask_accountant_questiontaxes:readquestion*: stringFor a tax or bookkeeping question from the user ("how much VAT do I pay in November?", "can I offset my VAT credit?", "what is due this month?"): returns the company’s own figures that bear on it (open deadlines, recent filings, the last liquidazione IVA, withholdings to pay, the tax estimate, P&L and receivables, depending on the topics found in the question), official sources to cite, other tools to call, and professional_needed with the reasons a commercialista is required (visto di conformità above €5,000 of VAT credit, audits and notices, penalties, income tax return and bilancio, payroll, extraordinary operations, special regimes, specific deductibility). getbeel does not write the answer: you do, only from data and sources, following guidance. Every figure is to check ("da verificare"). If professional_needed.required is true, say so first. Never present it as formal advice.
list_bank_transactionsbank:readlimit: integer
cursor: string
statement_id: string
from: string (date)
to: string (date)
status: "to_confirm" | "reconciled" | "missing_invoice" | "no_invoice_needed" | "rejected"
Lists bank transactions (from uploaded statements and connected banks), newest first, as GET /v1/bank-transactions: date, description, counterparty, amount, currency and reconciliation state. Filter as the parameters describe; pass next_cursor as cursor for the next page.
start_reconciliationbank:writemodificastatement_id*: stringMatches a bank statement’s transactions to invoices again (statement id from list_bank_statements; status review, completed or failed), as POST /v1/reconciliations. Runs in the background: check it with get_reconciliation. Confirmed matches stay; confirm with the user first.
list_invoice_paymentsinvoices:readid*: stringThe payments recorded on an issued invoice (by hand, from the bank or from Stripe), with dates and amounts, as GET /v1/invoices/{id}/payments. To record one, use mark_invoice_paid.
list_invoice_deliveriesinvoices:readid*: stringThe emails getbeel sent for an issued invoice (the invoice itself and payment reminders), with recipient, date and delivery status, as GET /v1/invoices/{id}/deliveries. SDI delivery is the invoice status (get_invoice), not this list.
list_filingstaxes:readlimit: integer
cursor: string
type: "bollo" | "withholdings" | "vat_payment" | "lipe" | "vat_return" | "redditi_pf"
status: "ready" | "needs_review" | "changes_requested" | "approved" | "skipped" | "filed" | "paid"
Lists prepared tax filings (LIPE, VAT return data, F24…), newest first, as GET /v1/filings, with type, period, status (ready: prepared, no review asked; needs_review: waiting for the commercialista; changes_requested; approved; skipped: not to be done; filed; paid) and amounts. See the history with list_filing_events. Open one with get_filing_next_steps, download its file with get_filing_file.
get_filing_filetaxes:readid*: string
format: "csv" | "xlsx" | "json"
The file of a prepared filing (the LIPE XML to send to the Agenzia delle Entrate, or the VAT return data sheet: format csv, xlsx or json), as GET /v1/filings/{id}/file. Returns download_url, a private link valid 15 minutes: give it to the user, never fetch it yourself; and file_spec, the id of the official specification the file follows (get_filing shows its name, version and source).
list_fixed_asset_categoriestaxes:readnessunoThe fixed asset categories with their depreciation rates (coefficienti, DM 31/12/1988), as GET /v1/fixed-asset-categories. Use a category key with register_fixed_asset.
create_companycompanies:writecreaname*: string
country: string
vat_number: string
codice_fiscale: string
regime_fiscale: string
address: string
street_number: string
postal_code: string
city: string
province: string
Adds a client company to this account (for software houses, marketplaces and commercialisti that manage several companies), with its fiscal data, as POST /v1/companies. Pass its id as company_id to the other tools. It is real data: needs a live key, and confirm the P.IVA and name with the user first.
update_companycompanies:writemodificaid*: string
name: string
country: string
vat_number: string
codice_fiscale: string
regime_fiscale: string
address: string
street_number: string
postal_code: string
city: string
province: string
Changes the fiscal data of the key's own company or one of its client companies (id from list_companies; only the fields sent), as PATCH /v1/companies/{id}. These are the data every invoice carries (cedente/prestatore): confirm each change with the user first. Needs a live key.
list_drivedrive:readmonth: string
folder: string
The company's Drive as in the app, for one month (month 2026-10: received invoices' files by invoice date, uploaded bank statements and documents by upload date) or one uploads folder (folder from folders[].path, e.g. contratti). Send month or folder. Invoice files also need received_invoices:read and bank statements bank:read; without them they are left out.
get_drive_filedrive:readid*: stringA private download link (download_url, valid 15 minutes) for a file from list_drive: give it to the user, never fetch it yourself. Invoice files also need received_invoices:read and bank statements bank:read; without them they are left out.
upload_drive_filedrive:writecreafolder*: string
file_url: string
file_base64: string
file_name: string
Stores a document (PDF, PNG, JPEG, DOC or DOCX, up to 25 MB) in a Drive folder that takes uploads (writable in list_drive: a month like 2026-10, documents, or a custom folder), from a public https file_url or file_base64 with file_name. It is only stored, not read by the AI: a supplier invoice to record goes to upload_received_invoice instead. Needs a live key.
create_drive_folderdrive:writecreaname*: string
month: string
Creates an uploads folder at the root of the Drive or inside a month (month 2026-10). Confirm the name with the user first. Needs a live key.
delete_drive_filedrive:writeeliminaid*: stringDeletes a file from list_drive for good. A received invoice’s file (the invoice stays, without its file) also needs received_invoices:write; a bank statement also needs bank:write, and one holding autofatture at SDI cannot be deleted. Name the file and confirm with the user first. Needs a live key.
delete_drive_folderdrive:writeeliminapath*: stringDeletes a custom Drive folder (path from list_drive, kind custom) and every file in it, for good. Month and system folders cannot be deleted. Say how many files it holds and confirm with the user first. Needs a live key.
upload_received_invoicereceived_invoices:writecreafile_url: string
file_base64: string
file_name: string
Uploads a supplier invoice or receipt (PDF, JPEG, PNG or WEBP, up to 50 MB) and the AI reads it, like an upload in the app; the invoice then appears in list_received_invoices with status pending_review for the user to approve. Pass file_url (a public https link) or file_base64 with file_name (base64 only for files up to about 3 MB; larger ones need file_url). Check progress with get_received_invoice_upload. It uses one invoice credit and adds the document to the real books: confirm with the user first. Needs a live key.
get_received_invoice_uploadreceived_invoices:readid*: stringWhere an upload from upload_received_invoice is: pending or processing while the AI reads it, completed (the invoice is in list_received_invoices), or failed with the error. error_code ai_out_of_credits or ai_unavailable: the AI could not read the file, nothing was saved and no credit was used; upload it again later.
list_categoriesreceived_invoices:readnessunoThe team's categories for received invoices (expense categories), with the slug each received invoice carries in category.
create_categoryreceived_invoices:writecrealabel*: string
color: string
Adds an invoice category (its slug comes from the label). Confirm the name with the user first. Needs a live key.
update_categoryreceived_invoices:writemodificaid*: string
label: string
color: string
Changes a category’s label or colour (id from list_categories). Needs a live key.
delete_categoryreceived_invoices:writeeliminaid*: stringDeletes a category; its invoices move to "other". Default categories cannot be deleted. Confirm with the user first. Needs a live key.
set_received_invoice_categoryreceived_invoices:writemodificaid*: string
category*: string
Sets a received invoice's category (id from list_received_invoices, category = a slug from list_categories). Needs a live key.
set_vat_adjustmenttaxes:writemodificakey*: string
action*: "exclude" | "adjust"
vat_amount: string
reason*: string
Changes what one VAT register row (key from get_vat_registers) puts in the liquidazione, as Rettifica in the app: action exclude keeps it out; action adjust sets the VAT that counts (vat_amount, e.g. the deductible 40% of a company car cost). reason is required and kept for the accountant. It replaces an earlier adjustment of the row. A liquidazione already saved stays as it was until prepare_filing (type vat_payment) runs again: say so. This changes the VAT the company pays: confirm the row, the amount and the reason with the user first. Needs a live key.
remove_vat_adjustmenttaxes:writeeliminakey*: stringThe row (key from get_vat_registers) counts as getbeel computed it again. Confirm with the user first. Needs a live key.

ask_accountant_question riceve la domanda così come l'ha scritta l'utente e restituisce cosa dicono i dati dell'azienda (scadenze aperte, adempimenti recenti, l'ultima liquidazione IVA, ritenute da versare, la stima delle imposte, conto economico e crediti, secondo gli argomenti della domanda), le fonti ufficiali da citare, gli altri strumenti da usare e professional_needed con i motivi per cui serve il commercialista (per esempio il visto di conformità per compensare più di 5.000 € di credito IVA, controlli e avvisi, sanzioni, dichiarazione dei redditi e bilancio, buste paga). Getbeel qui non chiama un modello linguistico: la risposta la scrive il tuo assistente da quei dati, seguendo la sua guidance, così ogni cifra si ritrova nei dati e Getbeel non inventa nulla.

Gli strumenti su banca, connessioni e documenti raccolti lavorano su dati reali: una chiave di test può leggerli, solo una chiave live può modificarli. Ogni strumento che modifica dati chiede all'assistente di confermare prima con te.

Gli strumenti restituiscono JSON con gli stessi campi dell'API. Gli errori hanno la stessa forma, in un risultato con isError: true.

Esempi

Ogni risultato è un blocco di testo con lo stesso JSON dell'API. Gli esempi mostrano la chiamata tools/call e il testo del risultato.

Una fattura non consegnata con get_invoice

La fattura è emessa: lo SDI non ha potuto recapitarla e l'ha messa nel cassetto fiscale del cliente dal giorno in sdi.available_since. Non va inviata di nuovo. Il significato di ogni stato è nel ciclo di vita SDI.

Chiamata
{
  "method": "tools/call",
  "params": {
    "name": "get_invoice",
    "arguments": { "id": "fe_8c1d2e4f-5a6b-4c7d-9e8f-0a1b2c3d4e5f" }
  }
}
Risultato
{
  "object": "invoice",
  "id": "fe_8c1d2e4f-5a6b-4c7d-9e8f-0a1b2c3d4e5f",
  "livemode": true,
  "number": "118",
  "tipo_documento": "TD01",
  "invoice_date": "2026-10-28",
  "due_date": "2026-11-27",
  "status": "not_delivered",
  "is_proforma": false,
  "currency": "EUR",
  "amount_subtotal": "1000.00",
  "amount_tax": "220.00",
  "amount_total": "1220.00",
  "customer": {
    "name": "Verdi S.r.l.",
    "vat_number": "01234567890",
    "codice_fiscale": null,
    "codice_destinatario": "0000000",
    "pec": null,
    "email": "amministrazione@verdi.example",
    "country": "IT",
    "address": "Via Roma 1",
    "postal_code": "20121",
    "city": "Milano",
    "province": "MI"
  },
  "sdi": {
    "identificativo_sdi": "7731024559",
    "file_name": "IT13815270965_0004K.xml",
    "error_message": null,
    "error_codes": [],
    "errors": [],
    "available_since": "2026-10-30",
    "updated_at": "2026-10-30T10:25:05.000Z"
  },
  "payment_status": "unpaid",
  "amount_due": "1220.00",
  "amount_credited": "0.00",
  "withholdings": [],
  "related_invoice_id": null,
  "series_id": null,
  "amount_paid": "0.00",
  "paid_at": null,
  "overdue": false,
  "payment_link_url": null,
  "lines": [
    {
      "description": "Consulenza di ottobre",
      "quantity": "1",
      "unit_price": "1000.00",
      "amount": "1000.00",
      "vat_rate": "22.00",
      "natura": null
    }
  ],
  "created_at": "2026-10-28T09:12:44.512Z",
  "updated_at": "2026-10-30T10:25:06.104Z"
}

Le fatture scartate con list_invoices

status accetta draft, sending, sent, delivered, not_delivered e rejected. Il risultato è una pagina: se has_more è true, ripeti la chiamata con cursor uguale a next_cursor.

Chiamata
{
  "method": "tools/call",
  "params": {
    "name": "list_invoices",
    "arguments": {
      "status": "rejected",
      "date_from": "2026-10-01",
      "limit": 10
    }
  }
}
Risultato (abbreviato)
{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "fe_2b7e9a10-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
      "number": "121",
      "invoice_date": "2026-10-30",
      "status": "rejected",
      "customer": {
        "name": "Bianchi S.p.A.",
        "vat_number": "01234567891",
        "…": "…"
      },
      "sdi": {
        "identificativo_sdi": "7731099120",
        "file_name": "IT13815270965_0004N.xml",
        "error_message": "00305 1.4.1.1.2 <IdCodice> non valido",
        "error_codes": ["00305"],
        "errors": [
          { "code": "00305", "description": "1.4.1.1.2 <IdCodice> non valido" }
        ],
        "available_since": null,
        "updated_at": "2026-10-30T15:02:11.000Z"
      },
      "…": "…"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

La fattura 121 non è emessa: va corretta la partita IVA del cliente (vedi 00305) e va inviata di nuovo con lo stesso numero e la stessa data.

Argomenti rigorosi

Ogni strumento dichiara additionalProperties: false e il server rifiuta gli argomenti che non conosce, invece di ignorarli: un assistente non crede mai di aver filtrato o impostato qualcosa che non ha avuto effetto. L'errore arriva come risultato con isError: true e il messaggio dice cosa correggere.

Un argomento sconosciuto (per esempio starting_after al posto di cursor):

MCP error -32602: Input validation error: Invalid arguments for tool list_invoices: Unrecognized key: "starting_after"

Un valore fuori dall'elenco ammesso elenca le opzioni:

MCP error -32602: Input validation error: Invalid arguments for tool list_invoices: Invalid option: expected one of "draft"|"sending"|"sent"|"delivered"|"not_delivered"|"rejected" at status

Un numero fuori dai limiti:

MCP error -32602: Input validation error: Invalid arguments for tool list_invoices: Too big: expected number to be <=100 at limit

Gli altri errori (scope mancante, risorsa inesistente, fattura non in bozza…) hanno la stessa forma dell'API, { "error": { "type", "code", "message", "param" } }, sempre in un risultato con isError: true. In modalità ricerca, call_tool risponde anche con tool_not_found (nessuno strumento con quel nome) e tool_not_read_only (lo strumento modifica dati: chiamalo direttamente).

Sicurezza

  • Parti dalla sandbox. Con una chiave di test send_invoice non raggiunge mai lo SDI.
  • Dai solo gli scope necessari. Una chiave senza scope di scrittura può leggere e validare, ma non creare né inviare.
  • Chiedi conferma prima di inviare. Configura il client perché chieda la tua approvazione prima di ogni chiamata a send_invoice. Un invio live emette una fattura con valore fiscale.
  • Tutto è registrato. Ogni chiamata MCP finisce nel registro delle richieste della chiave, come le chiamate API, e conta nel limite di richieste.
  • Revoca in un attimo. Revoca una chiave, o un'app collegata, in Impostazioni → Chiavi API e MCP: perde l'accesso subito.

Risorse e prompt

Oltre agli strumenti, il server offre altre due cose ai client che le supportano (Claude, Claude Code, Cursor, VS Code). Tutto funziona anche con i soli strumenti, come fa ChatGPT con Getbeel.

Le risorse sono contesto in sola lettura che alleghi alla conversazione (per esempio con @ in Claude). Ogni URI contiene l'azienda, l'id di list_companies (anche il tuo account), e richiede lo scope dello strumento di lettura che rispecchia. Un'azienda su cui la chiave non può agire risponde come un URI sconosciuto, mai "vietato".

URICosa èScope
getbeel://companies/{company_id}/profileAzienda, dati fiscali, stato della ricezione SDI, banche e caselle collegateaccount:read
getbeel://companies/{company_id}/invoices/{invoice_id}Una fattura emessa (fe_…) o ricevuta, come get_invoice, con link al PDFinvoices:read, received_invoices:read
getbeel://companies/{company_id}/invoices/{invoice_id}/xmlL'XML FatturaPA (text/xml), se conservatocome la fattura
getbeel://companies/{company_id}/tax-calendarProssime scadenze, come get_tax_calendartaxes:read
getbeel://companies/{company_id}/reports/{period}Conto economico, flusso di cassa e scadenzario per 2026, 2026-Q3 o 2026-10taxes:read
getbeel://companies/{company_id}/vat/{period}Liquidazione IVA di 2026-10 o 2026-Q3, da verificaretaxes:read

resources/list mostra un profilo per ogni azienda su cui la chiave può agire; gli altri URI arrivano da resources/templates/list, e i client completano company_id e period mentre scrivi. Gli strumenti di lettura di questi oggetti (whoami, get_invoice, list_invoices, list_received_invoices, get_tax_calendar, get_report, get_vat_settlement) restituiscono anche un resource_link all'URI corrispondente, dopo il loro risultato di sempre.

I prompt sono flussi di lavoro che avvii tu (un comando con / nella maggior parte dei client). Ognuno accetta un company_id facoltativo (di default l'azienda della chiave) e restituisce i passi e gli strumenti da usare. Tutto ciò che scrive o invia aspetta il tuo OK esplicito, e l'assistente non presenta né paga nulla al posto tuo.

PromptArgomentiCosa fa
close_monthmonthMovimenti bancari senza fattura, fatture non allo SDI o scartate, acquisti da rivedere, IVA, poi un riepilogo
vat_settlementperiodRegistri, liquidazione, poi (dopo il tuo OK) l'F24 e come pagarlo
reconcile_bankRivedi, conferma e applica gli abbinamenti bancari suggeriti
chase_unpaidScadenzario crediti, fatture scadute, solleciti inviati solo dopo il tuo OK
new_invoiceclient (facoltativo)Cliente, righe, bozza, e invio allo SDI solo quando lo dici tu
setup_checkCosa manca (codice destinatario, banca, casella, profilo fiscale, conservazione) e come sistemarlo

Risorse e prompt sono gli stessi nella modalità ricerca.

Modalità ricerca

Di default il server elenca tutti gli strumenti. Gli assistenti che non devono caricare tutti gli schemi all'inizio possono collegarsi a https://www.getbeel.com/api/mcp?tools=search (oppure inviare l'header Getbeel-MCP-Tools: search, per i client il cui accesso richiede l'URL semplice). Gli strumenti di sola lettura sono sostituiti da due:

  • search_tools: riceve qualche parola ("send invoice", "bank statement", "F24 bollo") e restituisce gli strumenti corrispondenti con descrizione, scope e schema di input. Senza parole elenca tutti gli strumenti per nome.
  • call_tool: esegue uno strumento di sola lettura per name con i suoi arguments (company_id compreso), con gli stessi controlli di scope e la stessa validazione di una chiamata diretta.

Gli strumenti che modificano dati o inviano qualcosa restano elencati con il loro nome, così il client ti chiede conferma per ciascuno: approvare call_tool non approva mai un invio.

claude mcp add --transport http getbeel "https://www.getbeel.com/api/mcp?tools=search"

Server card e registro

La scheda del server (MCP Server Card) è in https://www.getbeel.com/api/mcp/server-card, elencata in https://www.getbeel.com/.well-known/ai-catalog.json. Il nome del server nel registro MCP è com.getbeel/mcp.

Server MCP della documentazione

Questa documentazione ha un suo server MCP pubblico, in sola lettura, con gli strumenti list_pages, get_page e search:

claude mcp add --transport http getbeel-docs https://docs.getbeel.com/api/mcp

In questa pagina