# MCP server (https://docs.getbeel.com/en/api/mcp)

Connect Claude, ChatGPT, Cursor and other MCP clients to Getbeel.

The Getbeel MCP server gives AI agents the same powers as the API, with the same checks.

![The API keys and MCP page: test and live keys, permissions and the MCP server address.](/screenshots/api-keys-mcp.en.webp)

|                |                                                                       |
| -------------- | --------------------------------------------------------------------- |
| URL            | `https://www.getbeel.com/api/mcp`                                     |
| Transport      | Streamable HTTP, stateless (`POST` only, JSON responses)              |
| Authentication | OAuth 2.1 sign-in, or `Authorization: Bearer gb_test_…` / `gb_live_…` |

## Sign in with OAuth (no key) [#sign-in-with-oauth-no-key]

Claude (web, desktop and Claude Code), ChatGPT, Cursor and the other clients that follow the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) connect by signing in: add the URL above, sign in to Getbeel, then choose:

- **Team**: the workspace the app works on (one per connection).
- **Mode**: **Test** (the default: sandbox, nothing reaches SDI) or **Live**.
- **Permissions**: the same [scopes](/en/api/authentication) as API keys. By default every read scope, validation and write.

The screen shows exactly where **Allow** sends you: the full host (`claude.ai`), or the app on your device (`localhost:6274`, `cursor://…`). Any app can register with any name, so only Claude and ChatGPT, whose destinations Getbeel checked, show as verified. Every other app shows **Getbeel has not verified this app**: allow it only if you started the connection yourself.

The app then acts on that team as you, like a key you created. You see it in **Settings → API keys & MCP → Connected apps**, with when it was last used, and you can revoke it there: it loses access immediately.

<Tabs items={['Claude', 'ChatGPT', 'Cursor', 'Claude Code']}>
<Tab value="Claude">

In claude.ai or Claude Desktop: **Settings → Connectors → Add custom connector**, name `Getbeel`, URL `https://www.getbeel.com/api/mcp`. Choose **Connect** and sign in.

</Tab>
<Tab value="ChatGPT">

In **Settings → Apps & Connectors** (developer mode) create a connector with URL `https://www.getbeel.com/api/mcp` and authentication **OAuth**, then sign in.

</Tab>
<Tab value="Cursor">

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "getbeel": {
      "url": "https://www.getbeel.com/api/mcp"
    }
  }
}
```

Cursor shows **Needs login** next to the server: click it and sign in.

</Tab>
<Tab value="Claude Code">

```bash
claude mcp add --transport http getbeel https://www.getbeel.com/api/mcp
```

Then run `/mcp` in Claude Code and choose **Authenticate**.

</Tab>
</Tabs>

For client developers: an unauthenticated request gets `401` with `WWW-Authenticate: Bearer resource_metadata="https://www.getbeel.com/.well-known/oauth-protected-resource/api/mcp"`. That document names the authorization server `https://www.getbeel.com/api/auth` (metadata at `/.well-known/oauth-authorization-server/api/auth`): dynamic client registration, authorization code with PKCE (`S256` only), refresh tokens (`offline_access`), resource `https://www.getbeel.com/api/mcp`. Access tokens start with `gb_oat_` and last one hour.

## With an API key [#with-an-api-key]

Clients that only take a header use a key from **Settings → API keys & MCP**. Start with a test key: with it no invoice reaches SDI.

<Tabs items={['Claude Code', 'Cursor', 'Claude Desktop']}>
<Tab value="Claude Code">

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

</Tab>
<Tab value="Cursor">

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "getbeel": {
      "url": "https://www.getbeel.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GETBEEL_API_KEY}"
      }
    }
  }
}
```

</Tab>
<Tab value="Claude Desktop">

Through the `mcp-remote` bridge (requires Node.js). In **Settings → Developer → Edit Config**:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "getbeel": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.getbeel.com/api/mcp",
        "--header",
        "Authorization:${GETBEEL_AUTH}"
      ],
      "env": {
        "GETBEEL_AUTH": "Bearer gb_test_..."
      }
    }
  }
}
```

</Tab>
</Tabs>

Any other client that supports remote MCP servers over HTTP with custom headers works the same way.

## Tools [#tools]

The list below is generated from the tool definitions in the server code (`pnpm --filter docs mcp-tools`), so it matches what your client receives from `tools/list`. The descriptions are the ones the server sends to the assistant; the server appends the required scope to each.

- **Writes**: empty for read-only tools. `send` and `delete` are marked destructive (`destructiveHint`): a live send is a transmission to SDI with legal effect.
- Every tool also takes `company_id`, not listed in the table: the id of a client company (from `list_companies`) to act on instead of the key's own account. `list_companies` accepts it and ignores it.

{/* mcp-tools:start (generated by scripts/mcp-tools.ts, do not edit) */}

| Tool | Scope | Writes | Arguments (\* = required) | Description |
| --- | --- | --- | --- | --- |
| `list_companies` | `account:read` |  | none | The 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. |
| `whoami` | `account:read` |  | none | The 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_invoices` | `invoices:read` |  | `limit`: integer<br/>`cursor`: string<br/>`status`: "draft" \| "sending" \| "sent" \| "delivered" \| "not\_delivered" \| "rejected"<br/>`date_from`: string (date)<br/>`date_to`: string (date)<br/>`payment_status`: "unpaid" \| "partially\_paid" \| "paid"<br/>`overdue`: "true" \| "false"<br/>`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_invoice` | `invoices:read` |  | `id`\*: string | One 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_invoices` | `received_invoices:read` |  | `limit`: integer<br/>`cursor`: string<br/>`search`: string<br/>`source`: "email" \| "forwarded" \| "manual" \| "bank\_transaction" \| "sdi"<br/>`status`: "processing" \| "pending\_review" \| "verified" \| "rejected" \| "exported" \| "missing\_document"<br/>`date_from`: string (date)<br/>`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_invoice` | `invoices:validate` |  | `xml`\*: string | Checks 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_draft` | `invoices:write` | create | `customer`\*: object<br/>`tipo_documento`: "TD01" \| "TD02" \| "TD04" \| "TD05" \| "TD06" \| "TD24" \| "TD25"<br/>`number`: string<br/>`date`: string (date)<br/>`series_id`: string<br/>`related_invoice_id`: string<br/>`currency`: string<br/>`lines`\*: object[]<br/>`withholding`: object<br/>`cassa_previdenziale`: object<br/>`payment`: object<br/>`notes`: string<br/>`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_draft` | `invoices:write` | update | `id`\*: string<br/>`customer`: object<br/>`tipo_documento`: "TD01" \| "TD02" \| "TD04" \| "TD05" \| "TD06" \| "TD24" \| "TD25"<br/>`number`: string<br/>`date`: string (date)<br/>`currency`: string<br/>`lines`: object[]<br/>`withholding`: object<br/>`cassa_previdenziale`: object<br/>`payment`: object<br/>`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_invoice` | `invoices:write` | update | `id`\*: string | Puts 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_invoice` | `invoices:write` | send | `id`\*: string | Sends 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_customer` | `invoices:write` | send | `id`\*: string<br/>`to`: string[]<br/>`cc`: string[]<br/>`language`: "it" \| "en"<br/>`message`: string<br/>`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_paid` | `invoices:write` | update | `id`\*: string<br/>`amount`: string \| number<br/>`date`: string (date)<br/>`method`: "bank\_transfer" \| "card" \| "cash" \| "stripe" \| "other"<br/>`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_invoices` | `invoices:read` |  | `limit`: integer<br/>`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_link` | `invoices:write` | create | `id`\*: string | Creates 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_reminder` | `invoices:write` | send | `id`\*: string<br/>`to`: string[]<br/>`cc`: string[]<br/>`language`: "it" \| "en"<br/>`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_invoice` | `invoices:write` | create | `invoice_id`\*: string<br/>`interval`\*: "monthly" \| "quarterly" \| "yearly"<br/>`start_date`: string (date)<br/>`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_statements` | `bank:read` |  | `limit`: integer<br/>`cursor`: string<br/>`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_statement` | `bank:read` |  | `id`\*: string | One 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_statement` | `bank:write` | create | `file_url`: string<br/>`file_base64`: string<br/>`file_name`: string<br/>`currency`: string<br/>`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_reconciliation` | `bank:read` |  | `id`\*: string<br/>`limit`: integer<br/>`cursor`: string<br/>`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_unmatched` | `bank:read` |  | `type`\*: "payments" \| "invoices"<br/>`limit`: integer<br/>`cursor`: string<br/>`from`: string (date)<br/>`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_match` | `bank:write` | update | `reconciliation_id`\*: string<br/>`match_id`\*: string<br/>`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_manually` | `bank:write` | update | `reconciliation_id`\*: string<br/>`transaction_id`\*: string<br/>`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_connections` | `connections:read` |  | none | The mailboxes (gmail, outlook, imap), the forwarding address and the Stripe account connected to getbeel, with health (healthy, reconnect\_required, error). |
| `connect_mailbox` | `connections:write` | create | `provider`\*: "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_mailbox` | `connections:write` | create | `connection_id`\*: string<br/>`from`\*: string (date)<br/>`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_documents` | `received_invoices:read` |  | `limit`: integer<br/>`cursor`: string<br/>`search`: string<br/>`source`: "email" \| "forwarded" \| "manual" \| "bank\_transaction" \| "sdi"<br/>`status`: "processing" \| "pending\_review" \| "verified" \| "rejected" \| "exported" \| "missing\_document"<br/>`date_from`: string (date)<br/>`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_document` | `received_invoices:write` | update | `id`\*: string<br/>`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_calendar` | `taxes:read` |  | `from`: string (date)<br/>`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_filing` | `taxes:write` | create | `type`\*: "bollo" \| "withholdings" \| "vat\_payment" \| "lipe" \| "vat\_return" \| "redditi\_pf"<br/>`period`\*: string<br/>`amount`: string<br/>`previous_credit`: string<br/>`previous_debt`: string<br/>`annual_credit_used`: string<br/>`advance`: string<br/>`advance_method`: "1" \| "2" \| "3" \| "4"<br/>`declarant_fiscal_code`: string<br/>`declarant_role`: integer<br/>`previous_year_credit`: string<br/>`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_steps` | `taxes:read` |  | `id`\*: string | One 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_receipt` | `taxes:write` | update | `id`\*: string<br/>`file_url`: string<br/>`file_base64`: string<br/>`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_position` | `taxes:read` |  | `period`\*: string | VAT 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_return` | `taxes:read` |  | `period`\*: string | Draft 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_registers` | `taxes:read` |  | `period`\*: string | Registro 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_settlement` | `taxes:read` |  | `period`\*: string | The 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_report` | `taxes:read` |  | `type`\*: "profit-and-loss" \| "cash-flow" \| "aging"<br/>`period`: string<br/>`from`: string (date)<br/>`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_withholdings` | `taxes:read` |  | `limit`: integer<br/>`cursor`: string<br/>`paid_in`: string<br/>`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_withholding` | `taxes:write` | create | `recipient`\*: object<br/>`document`: object<br/>`invoice_id`: string<br/>`type`: "RT01" \| "RT02"<br/>`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"<br/>`rate`\*: string \| number<br/>`gross_amount`\*: string \| number<br/>`not_subject_amount`: string \| number<br/>`withheld_amount`: string \| number<br/>`paid_on`: string (date)<br/>`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_withholding` | `taxes:write` | update | `id`\*: string<br/>`recipient`: object<br/>`document`: object<br/>`invoice_id`: string<br/>`type`: "RT01" \| "RT02"<br/>`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"<br/>`rate`: string \| number<br/>`gross_amount`: string \| number<br/>`not_subject_amount`: string \| number<br/>`withheld_amount`: string \| number<br/>`paid_on`: string (date)<br/>`notes`: string<br/>`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_withholding` | `taxes:write` | delete | `id`\*: string | Deletes 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_withholdings` | `taxes:write` | update | none | Reads 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_cu` | `taxes:read` |  | `year`\*: integer | For 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_connections` | `bank:read` |  | none | The 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_connection` | `bank:write` | update | `connection_id`\*: string | Fetches 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_connection` | `bank:write` | update | `connection_id`\*: string<br/>`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_connection` | `bank:write` | delete | `connection_id`\*: string | Disconnects 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_status` | `received_invoices:read` |  | none | Whether 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_receiving` | `received_invoices:write` | update | none | Turns 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_receiving` | `received_invoices:write` | update | none | Turns 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_invoice` | `received_invoices:write` | create | `xml`: string<br/>`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_quotes` | `invoices:read` |  | `status`: "draft" \| "sent" \| "accepted" \| "declined" \| "expired"<br/>`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_quote` | `invoices:write` | create | `customer`\*: object<br/>`date`: string (date)<br/>`currency`: string<br/>`lines`\*: object[]<br/>`withholding`: object<br/>`cassa_previdenziale`: object<br/>`payment`: object<br/>`notes`: string<br/>`valid_until`: string (date)<br/>`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_quote` | `invoices:write` | send | `id`\*: string<br/>`to`: string[]<br/>`cc`: string[]<br/>`language`: "it" \| "en"<br/>`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_invoice` | `invoices:write` | create | `id`\*: string<br/>`series_id`: string<br/>`date`: string (date)<br/>`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_note` | `invoices:write` | create | `invoice_id`\*: string<br/>`lines`: object[]<br/>`series_id`: string<br/>`date`: string (date)<br/>`reason`: string<br/>`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_notes` | `invoices:read` |  | `invoice_id`\*: string | The 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_items` | `invoices:read` |  | `search`: string<br/>`include_archived`: "true" \| "false"<br/>`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_quote` | `invoices:read` |  | `id`\*: string | One quote (preventivo) with its customer, lines, totals, status and validity, and the invoice id once converted. |
| `update_quote` | `invoices:write` | update | `id`\*: string<br/>`customer`: object<br/>`currency`: string<br/>`lines`: object[]<br/>`withholding`: object<br/>`cassa_previdenziale`: object<br/>`payment`: object<br/>`notes`: string<br/>`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_quote` | `invoices:write` | delete | `id`\*: string | Deletes a quote that was not converted to an invoice. It cannot be undone: confirm with the user first. |
| `accept_quote` | `invoices:write` | update | `id`\*: string | Records that the customer accepted the quote (status accepted). It does not create the invoice: use convert\_quote\_to\_invoice for that. |
| `decline_quote` | `invoices:write` | update | `id`\*: string | Records that the customer declined the quote. |
| `get_quote_pdf` | `invoices:read` |  | `id`\*: string | Renders 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_item` | `invoices:write` | create | `name`\*: string<br/>`description`: string<br/>`code`: string<br/>`unit_price`\*: string \| number<br/>`unit`: string<br/>`vat_rate`: string \| number<br/>`natura`: string | Saves a product or service (description, unit price, VAT rate or natura) for reuse in invoices and quotes. |
| `update_item` | `invoices:write` | update | `id`\*: string<br/>`name`: string<br/>`description`: string<br/>`code`: string<br/>`unit_price`: string \| number<br/>`unit`: string<br/>`vat_rate`: string \| number<br/>`natura`: string<br/>`archived`: boolean | Changes a saved item (id from list\_items). |
| `delete_item` | `invoices:write` | delete | `id`\*: string | Deletes a saved item (id from list\_items). Invoices that used it keep their lines. Confirm with the user first. |
| `list_numbering_series` | `invoices:read` |  | none | The numbering series of invoices and quotes (sezionali): prefix or suffix, the next number and which document types use them. |
| `create_numbering_series` | `invoices:write` | create | `name`\*: string<br/>`prefix`: string<br/>`suffix`: string<br/>`yearly_reset`: boolean<br/>`default_for_invoices`: boolean<br/>`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_series` | `invoices:write` | update | `id`\*: string<br/>`name`: string<br/>`prefix`: string<br/>`suffix`: string<br/>`yearly_reset`: boolean<br/>`default_for_invoices`: boolean<br/>`default_for_credit_notes`: boolean<br/>`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_invoices` | `invoices:read` |  | `limit`: integer | The 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_invoice` | `invoices:read` |  | `id`\*: string | One recurring invoice with its schedule and status. |
| `update_recurring_invoice` | `invoices:write` | update | `id`\*: string<br/>`interval`: "monthly" \| "quarterly" \| "yearly"<br/>`next_date`: string (date)<br/>`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_invoice` | `invoices:write` | update | `id`\*: string | No new invoices are created until it is resumed. |
| `resume_recurring_invoice` | `invoices:write` | update | `id`\*: string | Starts creating invoices again from the next date. Confirm the next date with the user first. |
| `delete_recurring_invoice` | `invoices:write` | delete | `id`\*: string | Stops and removes the schedule. Invoices already created stay. Confirm with the user first. |
| `get_usage` | `account:read` |  | `period`: string | This 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_export` | `taxes:read` |  | `period`\*: string | Builds 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_address` | `connections:read` |  | none | The 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_link` | `connections:write` | create | none | Returns 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_invoices` | `connections:write` | create | `from`: string (date)<br/>`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_balance` | `account:read` |  | none | The 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_usage` | `account:read` |  | `month`: string | A 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_prices` | `account:read` |  | none | The 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_topup` | `billing:write` | create | `amount_cents`\*: integer | Creates 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_link` | `billing:write` | create | none | Creates 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_assets` | `taxes:read` |  | `limit`: integer<br/>`cursor`: string<br/>`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_asset` | `taxes:write` | create | `name`\*: string<br/>`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"<br/>`category_label`: string<br/>`coefficient`: number<br/>`kind`: "tangible" \| "intangible"<br/>`cost`\*: string<br/>`purchase_date`: string (date)<br/>`in_service_date`: string (date)<br/>`first_year_half`: boolean<br/>`expense_in_full`: boolean<br/>`depreciation_overrides`: object<br/>`received_invoice_id`: string<br/>`supplier_name`: string<br/>`document_number`: string<br/>`notes`: string<br/>`disposal_date`: string (date)<br/>`disposal_amount`: string \| "0.00"<br/>`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_asset` | `taxes:write` | update | `id`\*: string<br/>`name`: string<br/>`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"<br/>`category_label`: string<br/>`coefficient`: number<br/>`kind`: "tangible" \| "intangible"<br/>`cost`: string<br/>`purchase_date`: string (date)<br/>`in_service_date`: string (date)<br/>`first_year_half`: boolean<br/>`expense_in_full`: boolean<br/>`depreciation_overrides`: object<br/>`received_invoice_id`: string<br/>`supplier_name`: string<br/>`document_number`: string<br/>`notes`: string<br/>`disposal_date`: string (date)<br/>`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_asset` | `taxes:write` | delete | `id`\*: string | Deletes 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_register` | `taxes:read` |  | `year`\*: integer | Every 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_estimate` | `taxes:read` |  | `year`: integer | An 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_inputs` | `taxes:write` | update | `year`\*: integer<br/>`entity`: "company" \| "forfettario" \| "irpef" \| "minimi" \| "other"<br/>`other_revenue`: string \| number<br/>`other_costs`: string \| number<br/>`personnel_costs`: string \| number<br/>`permanent_staff_costs`: string \| number<br/>`ires_adjustments`: string \| number<br/>`irap_rate`: number<br/>`isa_subject`: boolean<br/>`prior_year_ires`: string \| number<br/>`prior_year_irap`: string \| number<br/>`ateco_code`: string<br/>`forfettario_group`: integer<br/>`startup_rate`: boolean<br/>`revenue_basis`: "collected" \| "invoiced"<br/>`inps_scheme`: "gestione\_separata" \| "artigiani" \| "commercianti" \| "cassa\_professionale" \| "none"<br/>`inps_reduction_35`: boolean<br/>`insured_before_1996`: boolean<br/>`inps_amount_override`: string \| number<br/>`contributions_paid`: string \| number<br/>`prior_year_substitute_tax`: string \| number<br/>`irpef_activity`: "professional" \| "business"<br/>`regional_surcharge_rate`: number<br/>`municipal_surcharge_rate`: number<br/>`prior_year_irpef`: string \| number<br/>`withholdings_suffered`: string \| number<br/>`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_links` | `taxes:read` |  | `limit`: integer<br/>`cursor`: string<br/>`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_link` | `taxes:write` | create | `label`: string<br/>`rt_serial`\*: string<br/>`acquirer_country`: "IT" \| "ES"<br/>`acquirer_id`\*: string<br/>`acquirer_name`\*: string<br/>`pos_type`\*: "00" \| "01"<br/>`terminal_id`: string<br/>`contract_number`\*: string<br/>`itinerant`: boolean<br/>`province`: string<br/>`municipality`: string<br/>`street`: string<br/>`street_number`: string<br/>`postal_code`: string<br/>`active_from`\*: string (date)<br/>`ended_on`: string (date)<br/>`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_link` | `taxes:write` | update | `id`\*: string<br/>`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_csv` | `taxes:read` |  | `part`: integer | The 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_filed` | `taxes:write` | update | `links`\*: 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_settings` | `taxes:read` |  | none | The 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_settings` | `taxes:write` | update | `vat_periodicity`: "monthly" \| "quarterly"<br/>`withholding_agent`: boolean<br/>`oss_from`: string (date)<br/>`oss_until`: string (date)<br/>`auto_prepare`: boolean<br/>`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_settings` | `invoices:read` |  | none | Automatic 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_settings` | `invoices:write` | update | `enabled`: boolean<br/>`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_profile` | `taxes:read` |  | none | Which 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_profile` | `taxes:write` | update | `legal_form`: "srl" \| "srls" \| "spa" \| "sapa" \| "snc" \| "sas" \| "ditta\_individuale" \| "professionista" \| "ente\_non\_commerciale" \| "other"<br/>`vat_periodicity`: "monthly" \| "quarterly"<br/>`withholding_agent`: boolean \| null<br/>`has_employees`: boolean \| null<br/>`reverse_charge_suppliers`: boolean \| null<br/>`oss_registered`: "false"<br/>`intrastat`: boolean \| null<br/>`in_liquidation`: boolean \| null<br/>`liquidation_from`: string (date)<br/>`first_fiscal_year`: integer<br/>`social_security`: "gestione\_separata" \| "artigiani" \| "commercianti" \| "cassa\_professionale" \| "none"<br/>`social_security_fund`: string<br/>`regimes`: object[]<br/>`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_profile` | `taxes:write` | update | none | Re-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_filing` | `taxes:read` |  | `id`\*: string | One 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_status` | `taxes:write` | update | `id`\*: string<br/>`status`\*: "needs\_review" \| "changes\_requested" \| "approved" \| "skipped" \| "filed"<br/>`reason`: string<br/>`reference`: string<br/>`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_filing` | `taxes:write` | update | `type`\*: "bollo" \| "withholdings" \| "vat\_payment" \| "lipe" \| "vat\_return" \| "redditi\_pf"<br/>`period`\*: string<br/>`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_filing` | `taxes:write` | create | `id`\*: string<br/>`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_events` | `taxes:read` |  | `id`\*: string | Comments and status changes of a filing, oldest first, with who did them (the commercialista or the team) and the reason. |
| `get_tax_rules` | `taxes:read` |  | none | The 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_value` | `tax_rules:admin` | create | `key`\*: string<br/>`value`\*: number<br/>`valid_from`\*: string<br/>`valid_to`: string<br/>`source_url`\*: string<br/>`source_title`\*: string<br/>`source_article`: string<br/>`quote`: string<br/>`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_override` | `tax_rules:admin` | create | `deadline_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"<br/>`nominal_from`\*: string<br/>`nominal_to`\*: string<br/>`new_due_date`\*: string<br/>`valid_from`\*: string<br/>`source_url`\*: string<br/>`source_title`\*: string<br/>`quote`: string<br/>`note`: string<br/>`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_rule` | `tax_rules:admin` | update | `kind`\*: "rule\_value" \| "override"<br/>`id`\*: string<br/>`decision`\*: "approve" \| "reject" \| "withdraw"<br/>`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_autofattura` | `invoices:read` |  | `id`\*: string | One 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_sdi` | `invoices:write` | update | `id`\*: string | Sends 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_advisors` | `advisors:read` |  | none | The 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_advisor` | `advisors:write` | send | `email`\*: string | Emails 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_accountant` | `advisors:write` | send | `email`\*: string<br/>`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_advisor` | `advisors:write` | delete | `id`\*: string | Revokes 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_rules` | `received_invoices:read` |  | `type`: "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_rule` | `received_invoices:write` | create | `text`\*: string<br/>`type`: "invoice\_scan" \| "fattura\_emessa"<br/>`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_rule` | `received_invoices:write` | update | `id`\*: string<br/>`text`: string<br/>`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_rule` | `received_invoices:write` | delete | `id`\*: string | Deletes 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_question` | `taxes:read` |  | `question`\*: string | For 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_transactions` | `bank:read` |  | `limit`: integer<br/>`cursor`: string<br/>`statement_id`: string<br/>`from`: string (date)<br/>`to`: string (date)<br/>`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_reconciliation` | `bank:write` | update | `statement_id`\*: string | Matches 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_payments` | `invoices:read` |  | `id`\*: string | The 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_deliveries` | `invoices:read` |  | `id`\*: string | The 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_filings` | `taxes:read` |  | `limit`: integer<br/>`cursor`: string<br/>`type`: "bollo" \| "withholdings" \| "vat\_payment" \| "lipe" \| "vat\_return" \| "redditi\_pf"<br/>`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_file` | `taxes:read` |  | `id`\*: string<br/>`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_categories` | `taxes:read` |  | none | The 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_company` | `companies:write` | create | `name`\*: string<br/>`country`: string<br/>`vat_number`: string<br/>`codice_fiscale`: string<br/>`regime_fiscale`: string<br/>`address`: string<br/>`street_number`: string<br/>`postal_code`: string<br/>`city`: string<br/>`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_company` | `companies:write` | update | `id`\*: string<br/>`name`: string<br/>`country`: string<br/>`vat_number`: string<br/>`codice_fiscale`: string<br/>`regime_fiscale`: string<br/>`address`: string<br/>`street_number`: string<br/>`postal_code`: string<br/>`city`: string<br/>`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_drive` | `drive:read` |  | `month`: string<br/>`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_file` | `drive:read` |  | `id`\*: string | A 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_file` | `drive:write` | create | `folder`\*: string<br/>`file_url`: string<br/>`file_base64`: string<br/>`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_folder` | `drive:write` | create | `name`\*: string<br/>`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_file` | `drive:write` | delete | `id`\*: string | Deletes 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_folder` | `drive:write` | delete | `path`\*: string | Deletes 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_invoice` | `received_invoices:write` | create | `file_url`: string<br/>`file_base64`: string<br/>`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_upload` | `received_invoices:read` |  | `id`\*: string | Where 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_categories` | `received_invoices:read` |  | none | The team's categories for received invoices (expense categories), with the slug each received invoice carries in category. |
| `create_category` | `received_invoices:write` | create | `label`\*: string<br/>`color`: string | Adds an invoice category (its slug comes from the label). Confirm the name with the user first. Needs a live key. |
| `update_category` | `received_invoices:write` | update | `id`\*: string<br/>`label`: string<br/>`color`: string | Changes a category’s label or colour (id from list\_categories). Needs a live key. |
| `delete_category` | `received_invoices:write` | delete | `id`\*: string | Deletes a category; its invoices move to "other". Default categories cannot be deleted. Confirm with the user first. Needs a live key. |
| `set_received_invoice_category` | `received_invoices:write` | update | `id`\*: string<br/>`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_adjustment` | `taxes:write` | update | `key`\*: string<br/>`action`\*: "exclude" \| "adjust"<br/>`vat_amount`: string<br/>`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_adjustment` | `taxes:write` | delete | `key`\*: string | The row (key from get\_vat\_registers) counts as getbeel computed it again. Confirm with the user first. Needs a live key. |

{/* mcp-tools:end */}

`ask_accountant_question` takes the user's question as written and returns what the company's own data says about it (open deadlines, recent filings, the last VAT settlement, withholdings to pay, the tax estimate, P&L and receivables, depending on the topics in the question), the official sources to cite, the other tools to call and `professional_needed` with the reasons a commercialista is required (for example the visto di conformità to offset more than €5,000 of VAT credit, audits and notices, penalties, the income tax return and the bilancio, payroll). Getbeel does not call a language model here: your assistant writes the answer from that bundle, following its `guidance`, so every figure can be traced to the data and nothing is invented on Getbeel's side.

Bank, connection and collected-document tools work on real data: a test key can read it, only a live key can change it. Every tool that changes data tells the assistant to confirm with you first.

Tools return JSON with the same fields as the API. Errors have the [same shape](/en/api/errors), in a result with `isError: true`.

## Examples [#examples]

Every result is a text block with the same JSON as the API. The examples show the `tools/call` request and the result text.

### A not delivered invoice with `get_invoice` [#a-not-delivered-invoice-with-get_invoice]

The invoice is issued: SDI could not deliver it and put it in the customer's cassetto fiscale on the day in `sdi.available_since`. Do not send it again. What each status means: [SDI lifecycle](/en/api/sdi-lifecycle).

```json title="Request"
{
  "method": "tools/call",
  "params": {
    "name": "get_invoice",
    "arguments": { "id": "fe_8c1d2e4f-5a6b-4c7d-9e8f-0a1b2c3d4e5f" }
  }
}
```

```json title="Result"
{
  "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": "October consulting",
      "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"
}
```

### Rejected invoices with `list_invoices` [#rejected-invoices-with-list_invoices]

`status` takes `draft`, `sending`, `sent`, `delivered`, `not_delivered` and `rejected`. The result is one page: when `has_more` is `true`, call again with `cursor` set to `next_cursor`.

```json title="Request"
{
  "method": "tools/call",
  "params": {
    "name": "list_invoices",
    "arguments": {
      "status": "rejected",
      "date_from": "2026-10-01",
      "limit": 10
    }
  }
}
```

```json title="Result (shortened)"
{
  "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
}
```

Invoice `121` is not issued: correct the customer's partita IVA (see [`00305`](/en/api/reference-data/sdi-errors)) and send it again with the same number and date.

## Strict arguments [#strict-arguments]

Every tool declares `additionalProperties: false`, and the server refuses arguments it does not know instead of dropping them: an assistant never believes it filtered or set something that had no effect. The error comes back as a result with `isError: true`, and the message says what to fix.

An unknown argument (for example `starting_after` instead of `cursor`):

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

A value outside the allowed list names the options:

```text
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
```

A number out of range:

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

Other errors (missing scope, unknown resource, invoice not a draft…) have the [same shape as the API](/en/api/errors), `{ "error": { "type", "code", "message", "param" } }`, always in a result with `isError: true`. In search mode, `call_tool` also answers `tool_not_found` (no tool with that name) and `tool_not_read_only` (the tool changes data: call it directly).

## Safety [#safety]

- **Start in the sandbox.** With a test key `send_invoice` never reaches SDI.
- **Grant only the scopes needed.** A key without write scopes can read and validate, but not create or send.
- **Confirm before sending.** Set your client to ask for your approval before every `send_invoice` call. A live send issues a legally valid invoice.
- **Everything is logged.** Every MCP call goes into the key's request log, like API calls, and counts towards the [rate limit](/en/api/rate-limits).
- **Revoke in seconds.** Revoke a key, or a connected app, in Settings → API keys & MCP: it loses access immediately.

## Resources and prompts [#resources-and-prompts]

Besides tools, the server offers two more things for clients that support them (Claude, Claude Code, Cursor, VS Code). Everything also works with tools alone, which is how ChatGPT uses Getbeel.

**Resources** are read-only context you attach to a conversation (for example with `@` in Claude). Every URI has the company in it, the `id` from `list_companies` (your own account too), and needs the scope of the read tool it mirrors. A company your key cannot act on answers like an unknown URI, never "forbidden".

| URI                                                          | What it is                                                                | Scope                                     |
| ------------------------------------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------- |
| `getbeel://companies/{company_id}/profile`                   | Company, tax data, SDI receiving status, connected banks and mailboxes    | `account:read`                            |
| `getbeel://companies/{company_id}/invoices/{invoice_id}`     | An issued (`fe_…`) or received invoice, as `get_invoice`, with a PDF link | `invoices:read`, `received_invoices:read` |
| `getbeel://companies/{company_id}/invoices/{invoice_id}/xml` | The FatturaPA XML (`text/xml`), when stored                               | same as the invoice                       |
| `getbeel://companies/{company_id}/tax-calendar`              | Upcoming deadlines, as `get_tax_calendar`                                 | `taxes:read`                              |
| `getbeel://companies/{company_id}/reports/{period}`          | Profit and loss, cash flow and aging for `2026`, `2026-Q3` or `2026-10`   | `taxes:read`                              |
| `getbeel://companies/{company_id}/vat/{period}`              | VAT settlement of `2026-10` or `2026-Q3`, to check (_da verificare_)      | `taxes:read`                              |

`resources/list` shows one profile per company the key can act on; the other URIs come from `resources/templates/list`, and clients complete `company_id` and `period` as you type. The read tools for these objects (`whoami`, `get_invoice`, `list_invoices`, `list_received_invoices`, `get_tax_calendar`, `get_report`, `get_vat_settlement`) also return a `resource_link` to the matching URI after their usual result.

**Prompts** are workflows you start on purpose (a slash command in most clients). Each takes an optional `company_id` (default: the key's company) and returns the steps and tools to use. Anything that writes or sends waits for your explicit OK, and the assistant never files or pays for you.

| Prompt           | Arguments           | What it does                                                                                              |
| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------- |
| `close_month`    | `month`             | Bank movements without invoice, invoices not at SDI or rejected, purchases to review, VAT, then a summary |
| `vat_settlement` | `period`            | Registers, liquidazione, then (after your OK) the F24 and how to pay it                                   |
| `reconcile_bank` |                     | Review, confirm and apply the suggested bank matches                                                      |
| `chase_unpaid`   |                     | Receivables aging, overdue invoices, reminders sent only after your OK                                    |
| `new_invoice`    | `client` (optional) | Customer, lines, draft, and the send to SDI only when you say so                                          |
| `setup_check`    |                     | What is missing (codice destinatario, bank, mailbox, tax profile, conservazione) and how to fix it        |

Resources and prompts are the same in [search mode](#search-mode).

## Search mode [#search-mode]

The server lists every tool by default. Assistants that should not load every schema up front can connect to `https://www.getbeel.com/api/mcp?tools=search` (or send the header `Getbeel-MCP-Tools: search`, for clients whose sign-in needs the plain URL). The read-only tools are then replaced by two:

- `search_tools`: takes a few words (`"send invoice"`, `"bank statement"`, `"F24 bollo"`) and returns the matching tools with their descriptions, scopes and input schemas. Without words it lists every tool by name.
- `call_tool`: runs a read-only tool by `name` with its `arguments` (`company_id` included), with the same scope checks and validation as a direct call.

Tools that change data or send something stay listed under their own names, so your client asks you before each one: approving `call_tool` never approves a send.

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

## Server card and registry [#server-card-and-registry]

The server's card ([MCP Server Card](https://github.com/modelcontextprotocol/ext-server-card)) is at `https://www.getbeel.com/api/mcp/server-card`, listed in `https://www.getbeel.com/.well-known/ai-catalog.json`. The server's name in the MCP registry is `com.getbeel/mcp`.

## Docs MCP server [#docs-mcp-server]

These docs have their own public, read-only MCP server with the tools `list_pages`, `get_page` and `search`:

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