# Advisors (your accountant) (https://docs.getbeel.com/en/api/advisors) Invite a commercialista with read-only access, list who has access, revoke an invitation or remove them. An **advisor** is the company's commercialista: a team member with the read-only role `auditor` (shown as **Accountant** in the app). Once they accept the invitation they can read and export issued and received invoices, bank movements and the Taxes section, and change nothing. It is the same invitation as [Invite your accountant](/en/guide/report-e-commercialista#invite-your-accountant) in the app. Scopes: `advisors:read` to list, `advisors:write` to invite and remove. Inviting or removing someone gives a real person access to real data, so it needs a **live key** (`403 livemode_required` with a test key). `advisors:write` is never selected by default when you create a key: tick it on purpose. The key's member must be allowed to do the same in the app: `invites.manage` to invite or revoke an invitation, `members.manage` to remove a member (never the primary owner or themselves). Otherwise `403 invite_not_allowed` or `remove_not_allowed`. ## Invite [#invite] ```bash curl https://www.getbeel.com/api/v1/advisors \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "email": "studio@commercialista.it" }' ``` `201` with the advisor, `status: "invited"`. The invitation email is sent right away and expires after 7 days (`expires_at`). An address that already has a pending advisor invitation gets that invitation back with `200` and no second email, so retries are safe; revoke it to send a new one. An address already in the team answers `409 already_member`; one invited to another role `409 already_invited`. A refused invitation policy answers `403 invite_not_allowed` with the reason. ```json { "id": "inv_42", "object": "advisor", "email": "studio@commercialista.it", "name": null, "role": "auditor", "status": "invited", "invited_at": "2026-11-09T10:00:00.000Z", "expires_at": "2026-11-16T10:00:00.000Z", "joined_at": null } ``` ## List [#list] `GET /v1/advisors` returns the active advisors (`id` `mem_…`, `status: "active"`, `joined_at`) and the pending invitations (`inv_…`). Other team members are not listed. The list is not paginated (`has_more` is always `false`). ## Remove [#remove] `DELETE /v1/advisors/{id}`: `inv_…` revokes the invitation, `mem_…` removes the commercialista from the team, who loses access at once. Returns `{ "id", "object": "advisor", "deleted": true }`. ## Client companies [#client-companies] With the `Getbeel-Company` header a parent account invites the commercialista of one of its client companies, with the same rules. To invite the same commercialista to several companies at once (this account and its client companies), send them in `company_ids` (at most 25): ```bash curl https://www.getbeel.com/api/v1/advisors/invitations \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "email": "studio@commercialista.it", "company_ids": ["", ""] }' ``` `POST /v1/advisors/invitations` answers `200` with one result per company, in the order sent: `invited`, `already_invited` (the pending invitation, no second email) or `failed` with the reason (`company_not_found` for an id that is not this account or a client company you manage, `already_member`, `invite_not_allowed`, `subscription_required`, `credits_exhausted`, `rate_limited`). Each company is invited exactly like `POST /v1/advisors`; one failing never stops the others. Without `company_ids` it invites to the company of the `Getbeel-Company` header, else this account. A test key gets `403 livemode_required`. In the app: **Client companies → Invite your accountant**. ## MCP and SDKs [#mcp-and-sdks] - MCP: `list_advisors`, `invite_advisor`, `invite_accountant` (several companies) and `remove_advisor`. The assistant must confirm the email address with you before inviting. - TypeScript: `getbeel.advisors.list()`, `getbeel.advisors.invite('studio@commercialista.it')`, `getbeel.advisors.remove('inv_42')`. - Python: `client.advisors.list()`, `client.advisors.invite("studio@commercialista.it")`, `client.advisors.remove("inv_42")`. # Authentication (https://docs.getbeel.com/en/api/authentication) Test and live API keys, scopes and good practice. Every request carries an API key in the `Authorization` header: ![The API keys and MCP page: test and live keys, permissions and the MCP server address.](/screenshots/api-keys-mcp.en.webp) ```bash curl https://www.getbeel.com/api/v1/me \ -H "Authorization: Bearer gb_test_..." ``` ## Test and live keys [#test-and-live-keys] | Prefix | Mode | What happens when you send | | ---------- | ---- | ----------------------------------------------------------------------- | | `gb_test_` | Test | The send goes to the [sandbox](/en/api/sandbox): no invoice reaches SDI | | `gb_live_` | Live | The invoice is transmitted to SDI and is legally issued | The endpoints are the same. Build and test with a test key and switch to a live key in production only. Reads (`GET`) return your account's data in both modes. ## Creating and managing keys [#creating-and-managing-keys] Create keys in **Settings → API keys & MCP** in the app. - The key is shown **once**. Getbeel keeps only a hash and the prefix (e.g. `gb_live_a1B2`), which you see in the list. - You can set an expiry date and revoke a key at any time. - A key belongs to one team and acts as the member who created it: it only sees that team's data. - If the member leaves the team, their keys are revoked. If they lose the permission to manage settings (for example they become an auditor), their keys are suspended. ## Scopes [#scopes] When you create a key you choose what it can do. A request to an endpoint outside the key's scopes gets `403 insufficient_scope`. | Scope | Allows | | ------------------------- | -------------------------------------------------------------------------------------------------------------- | | `account:read` | `GET /me`, MCP tool `whoami` | | `invoices:read` | `GET /invoices`, `GET /invoices/{id}`, tools `list_invoices`, `get_invoice` | | `received_invoices:read` | `GET /received-invoices`, tool `list_received_invoices` | | `invoices:validate` | `POST /invoices/validate`, tool `validate_invoice` | | `invoices:write` | `POST /invoices`, `POST /invoices/{id}/send`, `create_invoice_draft` and `send_invoice` tools | | `received_invoices:write` | `POST /received-invoices/{id}/approve` and `/reject`, tool `approve_collected_document` (live keys) | | `bank:read` | Bank statements, transactions, reconciliations, matches, unmatched lists | | `bank:write` | Upload statements, run reconciliations, approve, reject and link matches (live keys) | | `connections:read` | `GET /connections`, `GET /forwarding-address`, tool `list_connections` | | `connections:write` | Connect mailboxes and Stripe, scan mailboxes, sync Stripe (live keys) | | `taxes:read` | Tax calendar, prepared filings, VAT position estimate | | `taxes:write` | Prepare a filing (F24) and upload its receipt (live keys) | | `advisors:read` | `GET /advisors`, tool `list_advisors` | | `advisors:write` | Invite or remove a commercialista with read-only access: `POST /advisors`, `DELETE /advisors/{id}` (live keys) | | `drive:read` | Folders, files and download links: `GET /drive`, `GET /drive/files/{id}/download`, tools `list_drive`, `get_drive_file`. Invoice files also need `received_invoices:read`, bank statements `bank:read` | | `drive:write` | Create a folder: `POST /drive/folders`, tool `create_drive_folder` (live keys) | | `billing:write` | Create an "Add credits" link for a person to pay (`POST /billing/topups`, tool `create_billing_topup`) and a "Change card" link (`POST /billing/payment-method`, tool `create_billing_card_link`) (live keys; never ticked by default) | Endpoints that create and send invoices need the `invoices:write` scope. New keys have every scope selected by default except `advisors:write`, which gives a person lasting access to the company's data; untick what an integration doesn't need. Scopes can't be edited later: create a new key instead. Give each integration only the scopes it needs: a read-only key cannot send invoices. ## Authentication errors [#authentication-errors] All with status `401` and `type: "authentication_error"`: | `code` | Meaning | | ------------------- | ----------------------------------------------- | | `missing_api_key` | The `Authorization: Bearer …` header is missing | | `invalid_api_key` | The key does not exist or is mistyped | | `api_key_revoked` | The key was revoked | | `api_key_expired` | The key has expired | | `api_key_suspended` | Whoever created it can no longer manage keys | ## Good practice [#good-practice] - Keep the key on your server, in an environment variable such as `GETBEEL_API_KEY`. Never in code, in a browser or in a mobile app. - Use one key per integration, so you can revoke one without stopping the others. - If a key ends up in a repository or a log, revoke it and create a new one. Claude, ChatGPT and Cursor connect to the [MCP server](/en/api/mcp) by signing in (OAuth 2.1). The connection gets a team, a mode and scopes like a key, and is listed under Settings → API keys & MCP → Connected apps. # Autofatture (https://docs.getbeel.com/en/api/autofatture) Read a reverse-charge autofattura (TD17, TD18, TD19) and send it to SDI, exactly like the Send to SDI button. An autofattura is the document you send to SDI for a purchase from a foreign supplier (reverse charge): **TD17** for services from abroad, **TD18** for goods from another EU country, **TD19** for goods already in Italy. getbeel proposes and generates them from your bank debits, the Autofatture import and the foreign invoices you receive. The id is the one on the Autofatture page (the bank transaction it belongs to). Reads take `invoices:read` (both key modes). Sending takes `invoices:write` and a **live key**: it is a real fiscal act. ## Read an autofattura [#read-an-autofattura] ```bash curl "https://www.getbeel.com/api/v1/autofatture/$AUTOFATTURA_ID" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` ```json title="Response" { "id": "9ea93ca3-fb8b-4ac3-b991-bdec63081696", "object": "autofattura", "date": "2026-11-02", "supplier": "Vercel Inc.", "supplier_country": "US", "supplier_invoice_number": "INV-1102", "amount": "-20.00", "currency": "USD", "tipo_documento": "TD17", "numero": "AF-2026-7", "status": "generated", "xml_ready": true, "sdi": { "status": null, "id": null, "error": null, "updated_at": null } } ``` `status` is the XML: `generated` means it is ready to send. `sdi.status` is `null` until you send it, then `queued`, `sending`, `sent_to_sdi`, and SDI's answer: `consegnata` (delivered), `non_consegnata`, `scartata` (rejected, with `sdi.error`). ## Send it to SDI [#send-it-to-sdi] ```bash curl -X POST "https://www.getbeel.com/api/v1/autofatture/$AUTOFATTURA_ID/send" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` It runs the same steps as the **Send to SDI** button on the Autofatture page: - the XML must be generated (`409 autofattura_xml_missing` or `autofattura_not_generated` otherwise); - the send is paid from your prepaid balance at the SDI send price (see [Pricing](/en/api/pricing)). When the balance does not cover it the answer is `402 insufficient_balance` ([Errors](/en/api/errors#insufficient_balance)) and nothing is sent; - it is queued: the response is the autofattura with `sdi.status: "queued"`. Read it again later for SDI's answer. **Safe to repeat.** A second call never sends or charges again: `409 autofattura_already_queued` while it is on its way, `409 autofattura_already_sent` once SDI has it. A corrected resend after a rejection is not charged again. Other refusals: `409 sdi_monthly_cap_reached` (the monthly limit of live sends), `409 sdi_not_available` (an account still on a legacy plan without the SDI service), `404 resource_missing`, `403 livemode_required` with a test key. The MCP tools `get_autofattura` and `send_autofattura_to_sdi` do the same (see [MCP](/en/api/mcp)). # Bank connections (https://docs.getbeel.com/en/api/bank-connections) Automatic bank transactions through Enable Banking, using your company's own Enable Banking application. Getbeel downloads your bank account movements every 6 hours and matches them to invoices, as if a statement arrived every month. The connection goes through [Enable Banking](https://enablebanking.com) with **your own Enable Banking application**: you register it in your company's name, and Getbeel signs the calls with its private key. Scopes: `bank:read` to read, `bank:write` to connect, reconnect, sync and disconnect. Reads work with any key; changes need a live key (`403 livemode_required`). Each connected account costs €2 a month and each imported movement €0.02, from the prepaid balance (`402 insufficient_balance` when it does not cover them). ## Before you start [#before-you-start] 1. Create an account at [Enable Banking](https://enablebanking.com/sign-in/). 2. In the [control panel](https://enablebanking.com/cp/applications) register an application in the **Production** environment (or **Sandbox** to try it with the "Mock ASPSP" test bank). Choose "Generate in the browser" and export the `.pem` private key. 3. Under "Allowed redirect URLs" add exactly: ```text https://getbeel.com/api/open-banking/callback ``` 4. Activate the application with "Activate by linking accounts": in restricted mode the application only reads the accounts linked there. Enable Banking describes restricted mode as meant for evaluation and "individual non-commercial use". Check with Enable Banking that your use fits their terms, or sign a contract with them. ## Connect a bank [#connect-a-bank] ```bash curl -X POST https://www.getbeel.com/api/v1/bank-connections \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d @- < Bank data is real: there is no sandbox for it. Test keys (`gb_test_…`) can read statements, transactions and matches; uploading and reviewing need a live key (`gb_live_…`), otherwise `403 livemode_required`. Each new movement of an uploaded statement costs €0.02 from the prepaid balance (`402 insufficient_balance` when it does not cover it). Scopes: `bank:read` to read, `bank:write` to upload and review. ## 1. Upload a statement [#1-upload-a-statement] PDF, CSV or TXT, or a bank file: CBI (Italian RH flat file), CAMT.053 (ISO 20022 XML) or MT940; up to 50 MB (export a spreadsheet as CSV first). CBI, CAMT.053 and MT940 files are recognised by their content and read exactly, without AI; PDF and CSV are read with AI. Send the file as multipart: ```bash curl -X POST https://www.getbeel.com/api/v1/bank-statements \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "file=@estratto-ottobre.csv" \ -F "currency=EUR" ``` Requests are limited to about 4 MB. For larger files (up to 50 MB) put the file online and send JSON with `file_url` (public `https`, no redirects): ```bash curl -X POST https://www.getbeel.com/api/v1/bank-statements \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "file_url": "https://example.com/estratto-ottobre.pdf" }' ``` The answer is `202` with the statement in status `pending`. Processing runs in the background: | Status | Meaning | | ------------ | ---------------------------------------------------------------------- | | `pending` | Queued | | `processing` | Reading the file | | `parsed` | Transactions saved (webhook `bank_statement.parsed`) | | `matching` | AI matching to received invoices | | `review` | Done: the matches wait for review (webhook `reconciliation.completed`) | | `completed` | Marked as done in the app | | `failed` | Could not be read: retry with `POST /reconciliations` | `GET /bank-statements/{id}` also returns the bank, the period and the opening and closing balance (when the statement shows running balances). ## 2. Review the matches [#2-review-the-matches] A reconciliation has the same id as its statement: ```bash curl https://www.getbeel.com/api/v1/reconciliations/$STATEMENT_ID \ -H "Authorization: Bearer $GETBEEL_API_KEY" curl "https://www.getbeel.com/api/v1/reconciliations/$STATEMENT_ID/matches?state=to_confirm" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Every transaction has one match. `match_type` is `exact`, `fuzzy` (check it), `manual` or `unmatched`, with a `confidence` from `0.00` to `1.00`. `state` says what to do: | State | Meaning | | ------------------- | ------------------------------------------------------ | | `to_confirm` | An invoice was found: approve or reject it | | `reconciled` | Confirmed | | `missing_invoice` | No invoice found for this payment | | `no_invoice_needed` | Confirmed that it needs none (fees, taxes, transfers…) | | `rejected` | The suggestion was wrong | Then: - `POST /reconciliations/{id}/matches/{matchId}/approve`: the invoice is right (for a payment without invoice: none is needed). - `POST /reconciliations/{id}/matches/{matchId}/reject`: the suggestion is wrong. - `POST /reconciliations/{id}/matches` with `{ "transaction_id", "invoice_id" }`: link a received invoice by hand. - `POST /reconciliations` with `{ "statement_id" }`: run reading and matching again (it replaces the transactions and matches). ## 3. What is missing [#3-what-is-missing] - `GET /unmatched/payments`: money out with no invoice found, the documents to ask your suppliers for. - `GET /unmatched/invoices`: received invoices no bank payment is matched to. Both take `from` and `to` (`YYYY-MM-DD`) and the usual [pagination](/en/api/pagination). `GET /bank-transactions` lists every movement, with `statement_id`, `from`, `to` and `status` filters. ## With an AI assistant [#with-an-ai-assistant] The [MCP server](/en/api/mcp) has `upload_bank_statement`, `get_bank_statement`, `get_reconciliation`, `list_unmatched`, `approve_match` and `match_manually`. The assistant asks you before every change. # Changelog (https://docs.getbeel.com/en/api/changelog) Changes to the Getbeel API that can affect an integration, newest first. Changes that can affect an existing integration, newest first. New endpoints and tools are listed in the [reference](/en/api/reference) and on their pages. ## 2026-11-12 [#2026-11-12] ### `authorization_url` opens a Getbeel page first [#authorization_url-opens-a-getbeel-page-first] `POST /bank-connections` and `POST /bank-connections/{id}/reconnect` still return `authorization_url`, valid for 30 minutes. It now opens `https://getbeel.com/bank-login?t=…`, a page that names your team, instead of the bank's page directly. **Continue** takes the person to the bank, and the rest of the login is unchanged. - **Why.** The person who logs in to the bank sees which team gets their accounts before they share anything. A bank link someone else started can no longer pass for yours. - **What to change.** Nothing, if you open the URL in a browser as before. If your code checked that the URL is on `enablebanking.com` or `tilisy.com`, accept `getbeel.com` too. - The MCP tool `reconnect_bank_connection` returns the same new URL. ## Related [#related] - [Bank connections](/en/api/bank-connections): the bank login step by step. - [Errors](/en/api/errors): the error format. # CLI (https://docs.getbeel.com/en/api/cli) Send invoices, upload bank statements and check deadlines from the terminal. The `getbeel` command uses the [TypeScript SDK](/en/api/sdk-typescript). Node.js 20.19+. ```bash npm install -g @getbeel/cli # or: npx @getbeel/cli whoami getbeel login # paste a key from Settings → API keys & MCP getbeel whoami ``` `login` checks the key and saves it in `~/.config/getbeel/config.json` (readable only by you). `GETBEEL_API_KEY` or `--api-key` take precedence (and then go to the default host, not a base URL saved with another key); `getbeel logout` forgets it. Start with a test key (`gb_test_…`): sends go to the [sandbox](/en/api/sandbox). ## Commands [#commands] | Command | What it does | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `invoices list [--status s] [--limit n] [--cursor c] [--all]` | Issued invoices | | `invoices get ` | One invoice | | `invoices create --file invoice.json` | Create a draft from a [CreateInvoiceRequest](/en/api/reference) JSON file | | `invoices validate --file fattura.xml` | Check a FatturaPA XML | | `invoices send ` | Send a draft to SDI (to the sandbox with a test key) | | `received list [--status s] [--source s] [--all]` | Received invoices | | `bank statements upload [--currency EUR]` | Upload a statement (PDF, CSV, TXT, CBI, CAMT.053, MT940) | | `bank statements list [--all]` | Statements and their status | | `bank connections list` | Connected banks | | `bank connections sync ` | Sync a bank now | | `taxes calendar [--from date] [--to date]` | Tax deadlines | | `taxes registers --period 2026-Q3` | Sales and purchase VAT registers of a month or quarter | | `taxes settlement --period 2026-10` | VAT settlement of the period (to check) | | `taxes report --type profit-and-loss --period 2026` | Management report: P&L, cash flow, receivables aging | | `filings prepare --type bollo\|withholdings --period 2026-Q3 [--amount 200.00]` | Prepare an F24 | | `filings prepare --type vat_payment\|lipe --period 2026-10` | Save the VAT settlement and prepare its F24, or a quarter's LIPE file | | `filings list [--all]` | Prepared filings | ## Options [#options] - `--json`: print the API's JSON (for scripts and `jq`); errors go to stderr as JSON. - `--company `: act on a [client company](/en/api/companies). - `--idempotency-key `: for `create`, `send`, `upload` and `prepare` (otherwise a random one). - `--base-url `: another API host (https; http only for localhost). Exit codes: `0` ok, `1` API error (printed with code and request id), `2` wrong command or options. ```bash getbeel invoices create --file invoice.json --json | jq -r .id | xargs getbeel invoices send ``` # Multiple companies (multi-company) (https://docs.getbeel.com/en/api/companies) Software houses, marketplaces and accountants manage their clients' companies from one account, with one API key. Each company on Getbeel is a separate account, with its own fiscal data, invoices, bank and SDI sending. A **parent** account (your accounting firm, software house or marketplace) can have **client companies**: you create them, work on them in the app by switching between them, and the parent account's API key (or MCP connection) can act on each of them. ## The rules [#the-rules] - Whoever adds a client company becomes its **owner**. Only a company's members see it: invite colleagues from the company's **Members** page, like the client. - A parent account's key acts on a client company only if the member who created the key can manage that company (owner or member, not auditor). Otherwise the answer is `404 company_not_found`, the same as for a company that does not exist. - One level only: a client company cannot have client companies. A client company does not see the parent account or the other client companies. - If the parent account is deleted, the client companies stay, with their data and members. - For now each company has its own plan: sending real invoices to SDI from a client company needs the SDI add-on on that company. With a test key the sandbox works on all of them, but only a live key can add companies or change their data (`403 livemode_required`). ## In the app [#in-the-app] **Client companies** lists each company with its SDI status (fiscal data complete or what is missing, SDI sending on) and **Add company**. A name and VAT number are enough; complete the rest later in **Company data**. To work on a company, use **Open** or the selector at the top of the sidebar. The **Client companies** entry is in the sidebar of teams that chose **Accountant** when getting started or that already have a client company. Everyone else finds the page in **Settings → Company → Manage client companies**. Inside a client company the entry is not shown: a client company cannot have client companies of its own. ## With the API [#with-the-api] Create the company (scope `companies:write`, live key). The key's member becomes its owner, so the same key can use it right away: ```bash curl -X POST https://www.getbeel.com/api/v1/companies \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "Rossi Srl", "vat_number": "01234567890", "regime_fiscale": "RF01", "address": "Via Roma", "street_number": "1", "postal_code": "20121", "city": "Milano", "province": "MI" }' ``` The response is the company, with its `id` and `sdi_readiness` (`ready` and the `missing` fields). Then send its `id` in the **`Getbeel-Company`** header on any other endpoint: ```bash curl https://www.getbeel.com/api/v1/invoices \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Getbeel-Company: $COMPANY_ID" ``` Without the header, requests act on the key's own account. `GET /v1/me` with the header shows the company you are acting on. | Endpoint | Scope | | | -------------------------- | ----------------- | -------------------------------------------------------- | | `GET /v1/companies` | `account:read` | The key's account and the client companies it can act on | | `POST /v1/companies` | `companies:write` | Adds a client company | | `GET /v1/companies/{id}` | `account:read` | One company (or the account itself) | | `PATCH /v1/companies/{id}` | `companies:write` | Changes only the fields sent | `/v1/companies` is always relative to the key's account: the `Getbeel-Company` header does not apply there. A client company's key cannot create companies (`409 company_nesting_not_allowed`). Keys created before this feature do not have the `companies:write` scope: create a new key to add companies over the API. Reading and acting on companies works with existing keys. ## With an AI assistant (MCP) [#with-an-ai-assistant-mcp] The `list_companies` tool lists the companies, `create_company` adds one and `update_company` changes its data (live key); every other tool takes `company_id` to act on a client company. Ask for example: _"List my client companies and tell me which ones are not ready for SDI"_, or _"Draft an invoice for Rossi Srl…"_. Clients that allow custom headers can also use `Getbeel-Company`. ## Webhooks [#webhooks] A client company's events go to the endpoints set up **on that company** (the company's Settings → API keys & MCP) and to the parent account's matching endpoints, as long as the member who added the parent's endpoint can still manage the company. The parent's copy carries `company_id` (the company's id, the `Getbeel-Company` value); the company's own copy does not. # Connections (https://docs.getbeel.com/en/api/connections) Connect mailboxes and Stripe, scan for supplier invoices and review the documents collected. Getbeel collects supplier invoices from email (Gmail, Outlook, IMAP or a forwarding address) and turns Stripe invoices into fatture. The API exposes the same connections as **Settings → Email** and the fatture emesse page. Scopes: `connections:read` to read, `connections:write` to connect, scan and sync; `received_invoices:write` to approve collected documents. Reading works with any key; changes need a live key (`403 livemode_required` otherwise). Each document read with AI is paid from the prepaid balance (`402 insufficient_balance` when it does not cover it). ## List connections [#list-connections] ```bash curl https://www.getbeel.com/api/v1/connections \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Each connection has `provider` (`gmail`, `outlook`, `imap`, `forwarding`, `stripe`), `active` and `health.status`: `healthy`, `reconnect_required` (connect it again), `error` or `unknown`. ## Connect a mailbox [#connect-a-mailbox] Gmail and Outlook use OAuth, which a person has to approve. The API returns a link: ```bash curl -X POST https://www.getbeel.com/api/v1/connections/email \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "gmail" }' ``` Open `url` in a browser signed in to Getbeel as a member of the team (it asks you to sign in otherwise), approve access, and you land back in the app. The mailbox then appears in `GET /connections`. IMAP connects directly: Getbeel tests the login (port 993, TLS) and saves the password encrypted. Use an app password. ```bash curl -X POST https://www.getbeel.com/api/v1/connections/email \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "imap", "email": "fatture@example.it", "password": "app-password", "host": "imap.example.it" }' ``` New mailboxes count toward the plan's mailbox limit (`402` when it is reached). ## Scan a mailbox [#scan-a-mailbox] ```bash curl -X POST https://www.getbeel.com/api/v1/connections/$CONNECTION_ID/scan \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "2026-10-01", "to": "2026-10-31" }' ``` At most a year per request. The scan runs in the background (`202`); every invoice found fires `received_invoice.created` and appears in `GET /received-invoices?source=email`. ## Forwarding address [#forwarding-address] `GET /forwarding-address` returns the address to forward supplier invoices to, or `null` until it is set up in the app (it needs the email routing add-on). Forwarded invoices have `source: forwarded`. ## Review collected documents [#review-collected-documents] Collected documents are the [received invoices](/en/api/reference) with a `source` (`email`, `forwarded`, `manual`, `bank_transaction`). The ones waiting for a person have `status: pending_review`: ```bash curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \ -H "Authorization: Bearer $GETBEEL_API_KEY" curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `approve` sets `verified`, `reject` sets `rejected`. Documents still being read, missing-document placeholders and exported ones cannot be reviewed (`409`). ## Stripe [#stripe] - `POST /connections/stripe` returns a link to Stripe Connect; after approving you land on the fatture emesse page. - `POST /connections/stripe/sync` (optional `{ "from", "to" }`, default the last 30 days) imports Stripe invoices as fatture emesse. It needs the SDI add-on and quota; if the connection has automatic sending on, the invoices also go to SDI. ## With an AI assistant [#with-an-ai-assistant] The [MCP server](/en/api/mcp) has `list_connections`, `connect_mailbox` (returns the link), `scan_mailbox`, `list_collected_documents` and `approve_collected_document`. IMAP passwords never go through the assistant: connect IMAP in the app or with the API. # Drive (https://docs.getbeel.com/en/api/drive) Read the company's Drive by month or folder, download a file, upload documents and manage folders. The Drive holds the company's documents as the app shows them: received invoices' files, uploaded bank statements and uploaded documents, by month and folder. Reads take `drive:read`, writes `drive:write` and a live key. Drive never shows a key more than it can read elsewhere: received invoices' files also need `received_invoices:read`, bank statements `bank:read`. Without them those files are left out of the listing and refused on download. ## List a month or a folder [#list-a-month-or-a-folder] ```bash curl "https://www.getbeel.com/api/v1/drive?month=2026-10" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Send `month` (`2026-10`) or `folder` (a path from `folders[].path`, such as `contratti` or `2026-10/contratti`), one of them: a whole Drive can be very large. ```json title="Response" { "object": "drive", "month": "2026-10", "folder": null, "folders": [ { "object": "drive_folder", "path": "2026-10", "name": "2026-10", "kind": "month", "month": "2026-10", "file_count": 2, "total_size": 418204, "updated_at": "2026-10-28T09:12:00.000Z", "writable": true } ], "files": [ { "object": "drive_file", "id": "ZG9jdW1lbnQ6…", "name": "1761642720000_contratto.pdf", "kind": "document", "folder": "2026-10", "mime_type": "application/pdf", "size": 208102, "created_at": "2026-10-28T09:12:00.000Z", "document_date": "2026-10-28T09:12:00.000Z", "month": "2026-10", "vendor_name": null } ] } ``` `kind` is `invoice` (a received invoice's file), `reconciliation` (an uploaded bank statement) or `document`. Folders are `system` (invoices, reconciliation), `month` or `custom`; uploads go only to folders with `writable: true`. ## Download a file [#download-a-file] ```bash curl https://www.getbeel.com/api/v1/drive/files/$FILE_ID/download \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` The answer has `download_url`, a private link valid 15 minutes, and `expires_at`. Give the link to the person who needs the file; don't store it. A file that is not this company's, or that storage refuses, is a `404`. ## Upload a document [#upload-a-document] ```bash curl -X POST https://www.getbeel.com/api/v1/drive/files \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "folder": "2026-10", "file_url": "https://example.com/contratto.pdf" }' ``` - `folder` is a month (its folder is created if missing), `documents` or a custom folder that exists. - Send `file_url` (public `https`) or `file_base64` with `file_name`. PDF, PNG, JPEG, DOC or DOCX up to 25 MB; the type is read from the content. - The file is only stored, not read by the AI. To record a supplier invoice, [upload it as a received invoice](/en/api/received-invoices#upload-an-invoice). | Status | `code` | When | | ------ | ----------------------- | ---------------------------------- | | 404 | `resource_missing` | No such folder, or a system folder | | 413 | `payload_too_large` | Over 25 MB | | 415 | `unsupported_file_type` | Not a PDF, PNG, JPEG, DOC or DOCX | ## Folders [#folders] ```bash curl -X POST https://www.getbeel.com/api/v1/drive/folders \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "name": "Contratti", "month": "2026-10" }' ``` - A folder goes at the root, or inside a month with `month`. Its path comes from the name (`2026-10/contratti`). A name shaped like a month is refused, and a name already used there is `409 folder_exists`. - `DELETE /drive/folders?path=2026-10/contratti` deletes a custom folder and every file in it, for good. Month and system folders cannot be deleted. ## Delete a file [#delete-a-file] ```bash curl -X DELETE https://www.getbeel.com/api/v1/drive/files/$FILE_ID \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Deletes the file for good, as Delete in the app. A received invoice's file also needs `received_invoices:write` (the invoice stays, without its file); a bank statement needs `bank:write`. A bank statement holding autofatture that are, or may be, at SDI is a fiscal record: it cannot be deleted (`409 statement_has_sent_autofatture`). ## MCP [#mcp] `list_drive`, `get_drive_file`, `upload_drive_file`, `create_drive_folder`, `delete_drive_file`, `delete_drive_folder`. ## Related [#related] - [Received invoices](/en/api/received-invoices): the files the AI reads. - [Bank reconciliation](/en/api/bank-reconciliation): the statements in the reconciliation folder. - [Authentication](/en/api/authentication): the `drive:read` and `drive:write` scopes. # Errors (https://docs.getbeel.com/en/api/errors) The error shape, HTTP statuses and every code the API can return, with what to do. Every error has the same shape: ```json { "error": { "type": "invalid_request_error", "code": "parameter_unknown", "message": "Unknown parameter 'starting_after'. Allowed: limit, cursor, status, date_from, date_to, payment_status, overdue, search.", "param": "starting_after" } } ``` - `type` is the category. - `code` is stable: use it in your code to decide what to do. - `message` is for people and may change. - `param`, when present, names the field, parameter or header to fix. Every response, successful or not, has an `X-Request-Id` header (`req_…`). Quote it when you contact support. ## Types and HTTP statuses [#types-and-http-statuses] | `type` | Status | When | | ----------------------- | ---------------------------- | ----------------------------------------------------------- | | `authentication_error` | 401 | Key or token missing, wrong, revoked, expired or suspended | | `permission_error` | 402, 403 | A scope, a plan or the right mode (test or live) is missing | | `invalid_request_error` | 400, 404, 409, 413, 415, 422 | The request is invalid, or invalid in the current state | | `not_found_error` | 404 | The resource does not exist or is not in your team | | `rate_limit_error` | 429 | Too many requests, see [Rate limits](/en/api/rate-limits) | | `api_error` | 500, 502, 503, 504 | Our error or an external service's: try again later | General rule: fix a `4xx` before repeating the request (except the concurrency `409`s and `429`, listed below); retry `5xx` and network errors with backoff and the same [idempotency key](/en/api/idempotency). ## Codes [#codes] The list comes from the API code (every `ApiError` an endpoint or an MCP tool can return). ### Authentication and permissions [#authentication-and-permissions] | `code` | Status | Meaning | What to do | | ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `missing_api_key` | 401 | The `Authorization` header is missing | Send `Authorization: Bearer gb_…` | | `invalid_api_key` | 401 | Unknown or malformed key | Check the key in Settings → API keys & MCP | | `api_key_revoked` | 401 | Key revoked, or its creator left the team | Create a new key | | `api_key_expired` | 401 | Key expired | Create a new key | | `api_key_suspended` | 401 | The key's creator can no longer manage API keys | Have a member with that permission create the key | | `invalid_token` | 401 | OAuth token (`gb_oat_…`) expired, revoked or invalid | Refresh it; if that fails, connect the app again | | `insufficient_scope` | 403 | The required scope (named in the message) is missing | Create a key with that scope (keys cannot be edited) or reconnect the app | | `insufficient_permissions` | 403 | The key's creator cannot add client companies | Use a key of a member with that permission | | `livemode_required` | 403 | The operation changes real data and needs a live key | Use a `gb_live_…` key | | `test_mode_required` | 403 | The receiving sandbox only takes test keys | Use a `gb_test_…` key | | `company_not_eligible` | 403 | Issuing invoices needs an Italian company profile | Complete Settings → Company | | `invite_not_allowed` | 403 | The key's creator cannot invite a commercialista | Use a key of a member with that permission | | `remove_not_allowed` | 403 | The key's creator cannot remove that commercialista | As above | | `sdi_addon_required` | 402 | Live invoices (or Stripe sync) need the SDI plan | Turn it on in Settings → Usage & billing (for a client company, on the parent account); in test, use the sandbox | | `sdi_quota_exhausted` | 402 | This month's SDI quota is used up | Upgrade the SDI plan, or wait for next month | | `insufficient_balance` | 402 | The prepaid balance does not cover the action (pay as you go); the answer is `application/problem+json` with `balance_cents`, `required_cents` and `topup_url` (only `required_cents` for a client company) | Add credits from `topup_url` (Settings → Billing & usage) or turn on auto top-up | | `no_card` | 409 | No card is saved yet, so there is no card to change (`POST /billing/payment-method`); `application/problem+json` like `insufficient_balance` | Add a card with a top-up or in Settings → Billing & usage | | `not_pay_as_you_go` | 409 | Usage, top-ups and card links are for pay-as-you-go accounts | The account (signed up before 13 November 2026) keeps its plan: see `GET /usage` | | `billing_permission_required` | 403 | The key's creator cannot manage billing | Use a key of a member with the billing permission | | `billed_to_parent` | 403 | A client company pays from its gestore's balance (its own key reads neither the balance nor the usage) | Add credits on the parent account | | `subscription_required` | 402 | The paid product is needed (invoice processing, reconciliation) | Pick a plan in Settings → Usage & billing | | `limit_reached` | 402 | The plan's number of mailboxes is reached | Disconnect a mailbox or change plan | ### Request [#request] | `code` | Status | Meaning | What to do | | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `parameter_unknown` | 400 | Unknown query parameter (the message lists the allowed ones) or, on `PATCH /invoices/{id}`, unknown body field | Remove it or fix its name (for example `cursor`, not `starting_after`) | | `rate_limit_exceeded` | 429 | Too many requests for the key | Wait `Retry-After` seconds, then retry ([Rate limits](/en/api/rate-limits)) | | `parameter_invalid` | 400 | A parameter, field or header is invalid (see `param`) | Fix the value | | `parameter_missing` | 400 | A required parameter is missing | Add it | | `invalid_json` | 400 | The body is not valid JSON | Send valid JSON with `Content-Type: application/json` | | `invalid_multipart` | 400 | The multipart body cannot be read | Send `multipart/form-data` with a `file` field | | `file_url_unusable` | 400, 413 | `file_url` is not a public https link answering 200 without redirects, or the file is over 50 MB | Use a direct public link, or upload the file | | `payload_too_large` | 413 | JSON body over 1 MB; XML over 5 MB (the SDI limit for one file); bank statement over 50 MB; receipt over 10 MB | Make the file smaller | | `file_invalid` | 413 | A filing receipt is over 10 MB | Upload a smaller file | | `unsupported_media_type` | 415 | Unsupported `Content-Type` | Use the one named in the message | | `unsupported_file_type` | 415 | Unsupported bank statement type (for example a spreadsheet) | Upload PDF, CSV, TXT, CBI, CAMT.053 or MT940 | | `resource_missing` | 404 | No resource with that id in your team | Check the id (and `Getbeel-Company` or `company_id`) | | `company_not_found` | 404 | The client company does not exist or is no longer available | Use an id from `GET /companies` | | `numbering_series_not_found` | 404 | The numbering series does not exist | Use an id from `GET /numbering-series` | | `received_invoice_not_found` | 400 | The received invoice given for the fixed asset is not in this company | Use an id from `GET /received-invoices` | ### Idempotency and concurrency [#idempotency-and-concurrency] | `code` | Status | Meaning | What to do | | -------------------------- | ------ | ---------------------------------------------------------- | ----------------------------------------------------------- | | `idempotency_key_in_use` | 409 | A request with the same `Idempotency-Key` is still running | Retry in a few seconds with the same key | | `idempotency_key_reused` | 422 | The key was already used for a different request | Use a new key for a new request | | `invoice_send_in_progress` | 409 | A send of this invoice is already running | Do not repeat it: read the status with `GET /invoices/{id}` | | `sync_in_progress` | 409 | A sync of this bank connection is running or just ran | Retry in a minute | | `filing_conflict` | 409 | The filing is being prepared right now | Retry in a few seconds | | `reconciliation_conflict` | 409 | The match changed meanwhile | Read the reconciliation again and retry | ### Issued invoices and sending to SDI [#issued-invoices-and-sending-to-sdi] | `code` | Status | Meaning | What to do | | -------------------------------- | ------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invoice_not_draft` | 409 | Only a draft can be sent or edited: this one was already sent | Do not resend it: read the status and the outcome in `sdi` ([SDI lifecycle](/en/api/sdi-lifecycle)). On `PATCH`: a rejected invoice is reopened first (`POST /invoices/{id}/reopen`), a sent one is corrected with a credit note | | `invoice_not_sendable` | 409 | A proforma is not sent to SDI | Create a real invoice | | `invoice_not_rejected` | 409 | Only an invoice rejected by SDI can be reopened, and not while an automatic fix is running | Check the status: a `delivered`, `not_delivered` or `00404` invoice is issued and is never reopened. A `draft` is edited as it is (`PATCH`); a delivered one is corrected with a credit note | | `invoice_invalid` | 422 | The invoice fails the local checks (FatturaPA XML or credit note rules) | Fix what the message says | | `invoice_number_taken` | 409 | An invoice with this number already exists | Leave the number out (getbeel assigns the next one) or pick a free one | | `invoice_number_out_of_sequence` | 422 | The number would jump ahead in the numbering | Use the next number or one that fills a gap | | `company_profile_incomplete` | 422 | The company profile lacks what is needed to issue (name, partita IVA or codice fiscale…) | Complete Settings → Company | | `credit_exceeds_invoice` | 422 | The credit note exceeds what is left to credit on the invoice | Reduce the lines | | `invoice_not_issued` | 409 | An invoice SDI accepted is needed (for a credit note, a payment, a link) | Wait for the outcome, or pick another invoice | | `invoice_not_creditable` | 409 | This invoice cannot be credited (proforma or credit note) | Pick the original invoice | | `sdi_send_failed` | 502 | The send did not start: the invoice stays a draft | Try again later | | `internal_error` | 500 | Internal error (for example the invoice could not be created) | Retry; if it persists, contact support with `X-Request-Id` | An **SDI rejection** is not an API error: the send succeeds, then SDI answers. See below. ### Quotes, numbering series and collection [#quotes-numbering-series-and-collection] | `code` | Status | Meaning | What to do | | -------------------------- | ------ | -------------------------------------------------------------- | ------------------------------------------- | | `quote_not_editable` | 409 | The quote can no longer be edited | Create a new one | | `quote_converted` | 409 | The quote already became an invoice | Use the invoice created | | `quote_invalid` | 422 | The quote is not valid | Fix what the message says | | `numbering_series_exists` | 409 | A series with this prefix or suffix already exists | Pick another one | | `numbering_series_in_use` | 409 | The series has invoices and cannot be changed or deleted | Create a new one | | `numbering_series_invalid` | 422 | The series is not valid | Fix what the message says | | `natura_required` | 422 | An item at 0% VAT has no `natura` (SdI would refuse it: 00400) | Give the `natura` (N1–N7) or a rate | | `customer_email_missing` | 422 | The customer has no email address | Pass `to` or add the email to the customer | | `email_failed` | 502 | The email was not sent | Try again later | | `invoice_already_paid` | 409 | The invoice is already paid | Nothing to do | | `amount_exceeds_balance` | 422 | The payment exceeds the amount due | Reduce the amount | | `invoice_pdf_missing` | 409 | The invoice PDF is not ready yet | Try again shortly | | `invoice_not_copyable` | 422 | The invoice cannot be repeated (for example a credit note) | Use an ordinary invoice | | `recurring_invoice_exists` | 409 | This invoice already repeats | Change the existing schedule | | `stripe_not_connected` | 409 | No active Stripe connection | Connect Stripe (`POST /connections/stripe`) | | `stripe_mode_mismatch` | 409 | The Stripe connection is in the other mode (test or live) | Use a key of the same mode | | `stripe_error` | 502 | Stripe error | Try again later | ### Banks, connections and documents [#banks-connections-and-documents] | `code` | Status | Meaning | What to do | | ------------------------------------ | -------- | ------------------------------------------------------------------------------- | --------------------------------------------------- | | `bank_connection_inactive` | 409 | The connection is not active | Finish the bank login or reconnect | | `bank_connection_requires_reconnect` | 409 | The consent expired or was revoked | Reconnect the bank | | `bank_connection_conflict` | 409 | The connection changed meanwhile | Read it again and retry | | `bank_connection_limit` | 409 | The maximum number of connected banks is reached | Disconnect one | | `bank_credentials_invalid` | 422 | The Enable Banking app credentials are invalid | Check the credentials | | `redirect_url_not_allowed` | 422 | The return URL is not allowed | Use an allowed https URL | | `bank_daily_limit` | 429 | The bank allows about four unattended updates a day, used up | getbeel retries by itself later | | `bank_error`, `bank_sync_failed` | 502 | Bank or Enable Banking error | getbeel retries; try again later | | `bank_unavailable` | 503 | Banking service unavailable | Try again later | | `connection_not_scannable` | 409 | The mailbox cannot be scanned now | Read the message (connection expired, scan running) | | `reconnect_required` | 409 | The mailbox authorization expired or was revoked; no scan was created | Reconnect the mailbox in the app, then scan again | | `imap_connect_failed` | 422 | IMAP connection failed | Check email, password, server and port (993) | | `rate_limited` | 429 | Too many IMAP connection attempts | Try again later | | `unavailable` | 503 | Feature not available on this deployment, or an external service is unreachable | Try again later | | `internal` | 500 | Internal error while connecting IMAP | Retry; contact support with `X-Request-Id` | | `invoice_not_reviewable` | 409 | The collected document is not waiting for review | Nothing to do | | `workflow_unavailable` | 503 | Background processing is not available | Try again later | | `storage_error` | 500, 503 | The file was not stored | Retry | | `file_url_unreachable` | 502, 504 | `file_url` could not be downloaded | Retry or upload the file | | `file_empty` | 400 | The file sent is empty | Send the file again | | `credits_exhausted` | 402 | No invoice credits left for the upload | Buy a pack or change plan in Usage & billing | | `processing_unavailable` | 503 | The upload could not start reading the file | Retry | | `default_category` | 409 | A default category cannot be deleted | Delete another category, or rename this one | | `unknown_category` | 422 | Not a category of this team | Use a slug from `GET /categories` | | `folder_exists` | 409 | A Drive folder with that name exists there | Pick another name | | `folder_too_large` | 503 | The Drive folder has too many files to delete at once | Try again: each call deletes more | | `statement_has_sent_autofatture` | 409 | The statement holds autofatture at SDI: a fiscal record | Keep it; it cannot be deleted | ### SDI receiving and client companies [#sdi-receiving-and-client-companies] | `code` | Status | Meaning | What to do | | ----------------------------- | ------ | --------------------------------------------------------------- | ------------------------------------------- | | `company_not_ready` | 422 | The company does not have what it needs to receive from SDI yet | Complete the steps in `GET /sdi-receiving` | | `fiscal_id_taken` | 409 | The partita IVA is already set up for receiving elsewhere | Contact support | | `invoice_unreadable` | 422 | The test XML cannot be read | Fix the XML (for example the document date) | | `sdi_provider_unavailable` | 502 | The receiving channel does not answer | Try again later | | `company_nesting_not_allowed` | 409 | A client company cannot have client companies | Use the parent account's key | | `already_member` | 409 | The person is already in the team | Nothing to do | | `already_invited` | 409 | There is already an invitation for another role | Revoke it in the app | ### Filings, VAT, withholdings, fixed assets, POS–RT [#filings-vat-withholdings-fixed-assets-posrt] | `code` | Status | Meaning | What to do | | ---------------------------- | -------- | --------------------------------------------------------------- | ------------------------------------------ | | `taxes_not_available` | 400 | Taxes are available for Italian companies only | Set the country to Italy in the profile | | `vat_not_applicable` | 400 | A regime without VAT (forfettario or minimi) | No VAT registers or settlements to prepare | | `settings_missing` | 400 | The VAT period (monthly or quarterly) is not set | Set it in Taxes → Settings | | `settlements_missing` | 400 | The quarter's saved settlements for the LIPE are missing | Save the settlements named first | | `period_not_closed` | 400 | The period is not over | Prepare the filing after the period ends | | `period_not_started` | 400 | The month has not started | Pick a period that has started | | `nothing_due` | 422 | Nothing is due in the period | No F24 to prepare | | `filing_completed` | 409 | The filing is already paid or filed and no longer changes | Nothing to do | | `file_missing` | 400 | The receipt was not uploaded | Upload it again | | `file_invalid` | 500 | The generated LIPE file fails the official XSD check | Contact support with `X-Request-Id` | | `too_many_documents` | 400, 422 | Too many documents in the period to compute it here | Pick a shorter period or contact support | | `withholding_exists` | 409 | The received invoice already has a withholding | Update that one | | `withholding_remitted` | 409 | The withholding was already paid with an F24 | It can no longer change or be deleted | | `withholding_unpaid` | 400 | The day the fee was paid (`paid_on`) is missing | Record it first | | `no_paid_filing` | 409 | No paid withholdings F24 for the period | Prepare it and upload the receipt | | `coefficient_above_maximum` | 400 | Rate above the ministerial maximum (art. 102(2) TUIR) | Use at most the rate given | | `not_a_small_asset` | 400 | Full deduction only for assets up to €516.46 (art. 102(5) TUIR) | Depreciate the asset | | `disposal_incomplete` | 400 | Both `disposal_date` and `disposal_amount` are needed | Pass both or neither | | `in_service_before_purchase` | 400 | In service before it was bought | Fix the dates | | `too_many_assets` | 400 | The maximum number of fixed assets is reached | Contact support | | `pos_rt_link_exists` | 409 | This POS is already linked to this RT | Use the existing link | | `terminal_id_required` | 400 | A physical POS (`pos_type` `00`) needs its `terminal_id` | Add it, or use `01` for a virtual POS | | `link_already_filed` | 409 | The link was already communicated to the Agenzia | End it (`ended_on`) and add a new one | | `too_many_links` | 400 | The maximum number of POS–RT links is reached | End the ones no longer in use | [Idempotency](/en/api/idempotency) errors are also described on that page. ## SDI rejections [#sdi-rejections] An SDI rejection is not an API error: the send request succeeds, then SDI answers with a rejection receipt. The invoice moves to `rejected`, you receive the `invoice.rejected` webhook, and the codes are in `sdi.errors` (code and description) and `sdi.error_codes`. What they mean and how to fix them: [SDI rejection codes](/en/api/reference-data/sdi-errors). Exception: `00404` on an invoice already sent means SDI already holds an accepted copy. The invoice **is issued**, does not become `rejected` and must not be resent. See [SDI lifecycle](/en/api/sdi-lifecycle). ## Errors in MCP tools [#errors-in-mcp-tools] MCP tools return the same errors as a result with `isError: true`, with the `{ "error": { … } }` body in the text. Unknown or invalid arguments are refused earlier, with an `Input validation error: …` message that says what to fix: see [MCP server](/en/api/mcp#strict-arguments). In search mode, `call_tool` can answer `tool_not_found` and `tool_not_read_only`. # Filings (F24, LIPE, VAT return) (https://docs.getbeel.com/en/api/filings) Prepare the F24 for stamp duty, withholdings or VAT, the LIPE file or the annual VAT return data, with the values to copy, the link to the Agenzia delle Entrate page and email drafts, then record the receipt. A `filing` is a payment Getbeel prepares for a [tax deadline](/en/api/taxes): the amount, the F24 lines, a reminder PDF and the next steps. You pay it yourself, in F24 web or from your bank; then you upload the receipt (quietanza) and the filing is paid. Scope: `taxes:read` to read, `taxes:write` to prepare and upload the receipt. Tax deadlines are real data: there is no sandbox. Test keys can read; preparing and uploading need a live key (`403 livemode_required`). Preparing is free; a filing is charged once, when it is paid or filed (`402 insufficient_balance` when the balance does not cover it). ## What Getbeel prepares (v1) [#what-getbeel-prepares-v1] | `type` | Period | Amount | | -------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bollo` | Quarter (`2026-Q3`) | Computed by Getbeel: €2 per issued invoice with bollo virtuale, or without it but with bollo due (below) | | `withholdings` | Month (`2026-10`) | The sum of the [withholdings](/en/api/withholdings) on fees paid that month (codice tributo 1040), or `amount` if you do not record them in Getbeel | | `vat_payment` | Month or quarter, as the company settles VAT | The VAT settlement computed from the [VAT registers](/en/api/vat-registers) and saved (codici tributo 6001–6012, 6031–6033) | | `lipe` | Quarter (`2026-Q3`) | No payment: the XML file of the Comunicazione liquidazioni periodiche IVA, from the quarter's saved settlements, checked against the official XSD | | `vat_return` | Year (`2026`), once it is over | The data sheet of the annual VAT return (Dichiarazione IVA): `amount` is the balance to pay (VX1, codice tributo 6099). Not the file to send | | `redditi_pf` | Year (`2026`), once it is over | Individuals only: the data sheet of the Redditi PF return from the year's [tax estimate](/en/api/tax-tools): `amount` is the saldo of the year. Not the file to send | For stamp duty Getbeel follows the Agenzia delle Entrate's rules for the quarter's lists: - **List A**: invoices sent with bollo virtuale. - **List B**: invoices without bollo virtuale whose exempt or non-taxable lines (Natura N2.1, N2.2, N3.5, N3.6, N4) add up to more than €77.47: stamp duty is due on the part not subject to VAT. The Agenzia charges them anyway: Getbeel counts them and flags them (`invoices_without_bollo_flag`, `needs_review`). If one does not need it, remove it from the list in the "Fatture e corrispettivi" portal. - The quarter is the one of the SDI delivery. Invoices still waiting for SDI are in `pending_invoices` and not counted. - Small amounts: Q1 stamp duty below €5,000 may be paid by 30 September, and Q1 + Q2 below €5,000 by 30 November (`deferral`). Getbeel keeps the normal deadline and only tells you. Invoices issued outside Getbeel, paper invoices and self-invoices are not counted. ## Prepare an F24 [#prepare-an-f24] ```bash curl -X POST https://www.getbeel.com/api/v1/filings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "type": "bollo", "period": "2026-Q3" }' ``` ```bash curl -X POST https://www.getbeel.com/api/v1/filings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "withholdings", "period": "2026-10" }' ``` For withholdings Getbeel adds up the fees recorded in [`/withholdings`](/en/api/withholdings) with `paid_on` in the month (the ritenuta is made when the fee is paid, art. 25 DPR 600/1973) and lists them in `details.withholdings`; once you upload the receipt those fees are remitted and can no longer change. If you do not record them in Getbeel, send `amount` with the total withheld. With no fees and no `amount` the answer is `422 nothing_due`. `201` with the filing in status `ready` (webhook `filing.ready`). Calling again for the same period recomputes it until it is paid; then it answers `409 filing_completed`. Stamp duty is prepared only once the quarter is over (`period_not_closed`) and when something is due (`nothing_due`). `vat_payment` and `lipe` are prepared once the period is over too. `vat_payment` saves the settlement even when there is nothing to pay (a credit, up to €100 carried, Q4 of quarterly payers) and then answers `422 nothing_due`; `lipe` answers `400 settlements_missing` until every settlement of the quarter is saved, and companies send `declarant_fiscal_code` and `declarant_role`. The VAT inputs and the rules are in [VAT registers and settlements](/en/api/vat-registers). ## LIPE: the schema check [#lipe-the-schema-check] When a `lipe` is prepared, Getbeel validates the XML against the official IVP18 schema of the Agenzia delle Entrate ("Specifiche IVP2018_SchemaIV18.zip", schema version 1.0, from the [technical specifications page](https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/liquidazioni-periodiche-iva/st-comunicazione-delle-liquidazioni-periodiche-iva); the provvedimento of 14 March 2024 left it unchanged). The result is in `checks.xsd`. A file that fails is never saved: the answer is `500 file_invalid` (a Getbeel bug, tell us). `checks.ade_control_software` is always `not_run`. The Agenzia's control software ("Software di controllo Liquidazioni periodiche Iva" for the LIPE, the "procedura di controllo" for the VAT return) is a Java desktop program, started with Java Web Start, that updates itself at every launch. It has no documented command line or batch mode, and the Agenzia publishes no web service that checks a file without the taxpayer's login, nor terms that allow running it as a service for others. So Getbeel cannot honestly run it for you: it checks what it can (the schema for the LIPE; the arithmetic rules of the specifications for the VAT return, below), and the steps tell you to run the control software before sending. ## VAT return (Dichiarazione IVA) [#vat-return-dichiarazione-iva] ```bash curl -X POST https://www.getbeel.com/api/v1/filings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "vat_return", "period": "2026", "previous_year_credit": "1200.00" }' ``` Getbeel adds up the [VAT registers](/en/api/vat-registers) of every settlement period of the year (12 months or 4 quarters), the settlements you saved and the VAT F24s marked paid, and returns the rows of the return in `details.vat_return`, in whole euros as filed, with the field code of the technical specifications (`VE023001` = quadro VE, row 23, field 1). `previous_year_credit` is the credit of last year's return still available (VX5 minus what you already offset): it goes in VL25. Download the sheet with `GET /filings/{id}/file?format=csv|xlsx|json` (CSV by default). **It is not the file to send.** The telematic return is a fixed-length record file (records A, B, D, Z of 1,900 characters) with many parts Getbeel does not know (front page, VA, VC, VO, VT, signatures). Fill it with the Agenzia's free "Software di compilazione Iva" or your accountant's software, check it with the control procedure and send it from your Agenzia area or through an intermediary, between 1 February and 30 April (art. 8 DPR 322/1998). Pay the balance by 16 March with codice tributo 6099. | Quadro | Rows Getbeel fills | From | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | VE | VE20–VE23 by rate (4, 5, 10, 22%), VE24–VE26, VE30–VE35 by Natura, VE37 (VAT due later), VE38 (split payment), VE39, VE50 (volume d'affari) | Sales register | | VF | VF2, VF3, VF11, VF13 by rate, VF18, VF25–VF27, VF71 (VAT deducted) | Purchase register and self-invoices | | VJ | VJ1 (TD28), VJ3 (TD17, TD19), VJ9 (TD18), VJ19 | Self-invoices (reverse charge) | | VL | VL1–VL4, VL23, VL25, VL30 (fields 1–3), VL32, VL33, VL36, VL38, VL39 | The above, saved settlements, paid F24s | | VX | VX1 (to pay, not below €10.33), VX2 (credit) | VL38, VL39 | The column 2 of VE20–VE23 and VF2–VF13 is the rate times column 1, as the specifications require; the difference with the VAT in the registers goes in VE25 and VF26. `details.vat_return.checks` lists the specifications' controls Getbeel runs on the sheet (they hold by construction; a failure is a Getbeel bug). Once the return's receipt is uploaded it is `filed`, and that year's `vat_payment` and `lipe` answer `409 filing_completed`: a change after filing is a corrective return, for your accountant. Sales whose VAT you adjusted in the registers count with the adjusted VAT, as in the settlements (the difference shows in VE25). Domestic reverse charge (TD16) VAT is in the VJ19 total and the balance; you put it in its row. `details.vat_return.issues` lists what to check before copying: documents missing from the registers, sales or purchases without a single row (Natura N2.2, N5, N7, purchases without VAT), domestic reverse charge (TD16) whose VJ row depends on the case, foreign suppliers without a self-invoice, non-deductible VAT (it goes in VF21/VF22, Getbeel keeps it in VF1–VF13), settlements not saved, the VAT advance paid outside Getbeel. **Which model.** As of November 2026 the model for tax year 2026 ("IVA 2027") is not published, not even as a draft. The rows follow the latest one, "IVA 2026, periodo d'imposta 2025", approved by provvedimento prot. 51732 of 15 January 2026 ([model and instructions](https://www.agenziaentrate.gov.it/portale/iva-2026/modello-e-istruzioni)), with the technical specifications of provvedimento prot. 50925 of 11 February 2026. `details.vat_return.model` says which one; the sheet will move to the 2027 model when it is published. **Not from an official source** (Getbeel's reading, to check with your accountant): which row each Natura code goes to (N2.1 → VE34, N3.1–N3.4 → VE30 fields 2–5, N3.5 → VE31, N3.6 → VE32, N4 → VE33, N6.1–N6.8 → VE35 fields 2–9, N6.9 → VE35 field 1), which VJ row each self-invoice type goes to, and split-payment sales only in VE38 (read from the VE50 formula, which would otherwise count them twice). The instructions never name the FatturaPA codes. ## Redditi PF (individuals) [#redditi-pf-individuals] For a persona fisica whose [tax estimate](/en/api/tax-tools) of the year is `forfettario`, `irpef` or `minimi`: ```bash curl -X POST https://getbeel.com/api/v1/filings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "redditi_pf", "period": "2025" }' ``` `details.redditi_pf.lines` places the estimate on the Modello Redditi PF 2026 lines (tax year 2025), as printed in the AdE instructions (Fascicoli 1–3): | Regime | Lines | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `forfettario` | LM22 col. 3 revenue, LM34 col. 3 income, LM35 col. 2 contributions, LM38 taxable, LM39 substitute tax | | `minimi` | LM2, LM5 col. 5, LM6, LM7 col. 2, LM49, LM9 col. 3, LM10, LM11 (5%) | | `irpef` | RE21 col. 5 income (a business uses quadro RG: no rigo), RN1 col. 5, RN3, RN4, RN5, RN7 col. 4, RN26, RN33 col. 4, RN34, RV2 col. 2, RV10 col. 2 | | INPS | RR5 col. 15 (gestione separata); artigiani and commercianti split it over RR2/RR3, so `rigo` is `null` | - `rigo: null` means the line was not given as one rigo: the amount is shown with its meaning. - `payments` lists the saldo and acconti with their F24 codes; `amount` is the saldo of the year. - It is an estimate: other income, family and deductible expenses are not in Getbeel. `GET /filings/{id}/file?format=csv|json` downloads the sheet. - A company gets `400 redditi_pf_not_applicable`. - It is completed as **filed** with the AdE receipt or the protocol number (charged once, see Pricing). ## Which specification each file follows [#which-specification-each-file-follows] Every prepared filing keeps the official specification its file follows, in `file_spec` (also in the `Getbeel-File-Spec` header of `GET /v1/filings/{id}/file`, and in MCP `get_filing_file`): | `file_spec.id` | File | Official document | Official format | | -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------- | | `lipe:IVP18` | LIPE XML | Specifiche tecniche and XSD IVP18 (Versione 1.0), provv. AdE prot. 125654 of 14 March 2024 | yes | | `vat_return:IVA2026` | VAT return data sheet | Model IVA 2026 (tax year 2025), provv. AdE prot. 51732 of 15 January 2026 | no: the rows to copy | | `redditi_pf:PF2026` | Redditi PF data sheet | Model Redditi PF 2026 (tax year 2025), provv. AdE prot. 72078 of 27 February 2026 | no: the lines to copy | | `f24:F24-2013` | F24 reminder (bollo, withholdings, VAT) | Model "MOD. F24 – 2013 EURO", provv. AdE of 19 June 2013 | no: a reminder | `file_spec` also has the name, version, the act that approved it, its official page (`source_url`) `other_tax_year` (a return on the model of another tax year: check the rows against that year's model) and `provisional` (that model is the earlier one because the new one is not published yet: check it when it is). The id is stored when the filing is prepared; a file is only generated on that specification, never on another version: when Getbeel moves to a new one it keeps generating the old one for the filings that use it, and a specification it no longer generates answers `409 file_spec_outdated`. A filing skipped before it was prepared has no file: `file_spec` is `null` and the file answers `409 filing_file_missing`. ## Next steps [#next-steps] `GET /filings/{id}` returns `f24_lines` (Erario section: codice tributo, reference month and year, amount) and `next_steps`: | Field | What | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `file_url` | The F24 reminder PDF (`GET /filings/{id}/file`): the values to enter, not the ministerial form; for a `lipe`, the XML file; for a `vat_return`, the data sheet | | `deep_link` | The Agenzia page to open: "Fatture e corrispettivi" for stamp duty, the reserved area (F24 web) for withholdings. You sign in with SPID, CIE or CNS | | `copy_values` | The values to copy one by one: codice fiscale, codice tributo, year, amount, total | | `drafts` | Email drafts (in Italian) to the bank or the commercialista. Getbeel never sends them: you review and send | | `steps` | The steps, in order | ## Record the receipt [#record-the-receipt] After paying, upload the receipt (PDF, PNG or JPEG, up to 10 MB): ```bash curl -X POST https://www.getbeel.com/api/v1/filings/$FILING_ID/receipt \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -F "file=@quietanza-f24.pdf" ``` The filing becomes `paid`; a LIPE or a VAT return, with the Agenzia's receipt, becomes `filed` (webhook `filing.filed`). The receipt is stored, not read: make sure you upload the right one. ## No CBI F24 file yet [#no-cbi-f24-file-yet] Companies with corporate banking can import F24 payments as a CBI file. Getbeel does not produce it: the CBI standard "Pagamenti F24" (CBI-F24-001) is distributed only to users registered on [cbi-org.eu](https://www.cbi-org.eu/Servizi/Standard), under the CBI IPR policy, and the only public copy found is an outdated third-party mirror (version 6.15 of 2015). The file also needs your company's own SIA code and an F24 service agreed with your bank. Until Getbeel builds it from the version CBI distributes, use the values to copy, the reminder PDF or the email draft to your bank. ## Review with the commercialista [#review-with-the-commercialista] Invite your commercialista (POST /v1/advisors or **Taxes → Your commercialista**): from then on every prepared filing starts in `needs_review`. The commercialista opens it in the app and approves it (`approved`, with who and when), sends it back (`changes_requested`, with a comment) or marks it not to be done (`skipped`, with the reason). Without a commercialista a prepared filing is `ready`. | Status | Meaning | | ------------------- | --------------------------------------------------------------------------- | | `ready` | Prepared, no review asked | | `needs_review` | Waiting for the commercialista | | `changes_requested` | Sent back: see the history | | `approved` | Visto bueno: `approved_at`, `approved_by` | | `skipped` | Not to be done: `skip_reason`; never prepared automatically, never charged | | `filed` | A LIPE or VAT return sent: a receipt or `filed_reference` (protocol number) | | `paid` | An F24 paid: the receipt | - `POST /v1/filings/{id}/status` with `status` `approved`, `skipped`, `needs_review` (back to review, or reopen a skip) or `filed` (with `reference`). An API key acts as the team: `changes_requested` is the commercialista's, in the app. - `POST /v1/filings/skip` with `type`, `period` and `reason` for a deadline never prepared. - `GET /v1/filings/{id}/events` is the history (comments and status changes, who and why); `POST` adds a comment. - With **require the commercialista's approval** on (tax settings `require_accountant_approval`, set by an owner), only the commercialista approves, and a receipt or protocol number waits for the approval (`409 approval_required`). Every step also shows up in the app's notifications, and by email: - a filing waiting for review (when it is prepared, or when you switch on the commercialista's approval) → the commercialista; - changes requested, with the whole comment → the owners and whoever prepared the filing; - approved by the commercialista → the owners; - with the commercialista's approval required, a filing due within 5 working days and still not approved (to review, or sent back for changes) → the commercialista and the owners, once per filing and due date (again only if a proroga moves the date). Each email is in the recipient's language, links to the filing, and never goes to the person who made the change. An approval by a team member and a skip are in the app only. Webhooks: `filing.needs_review`, `filing.changes_requested`, `filing.approved`, `filing.skipped`, `filing.approval_due`, `filing.filed`. MCP: `get_filing`, `set_filing_status`, `skip_filing`, `comment_filing`, `list_filing_events`. ## With an AI assistant (MCP) [#with-an-ai-assistant-mcp] `get_tax_calendar`, `prepare_filing`, `get_filing_next_steps`, `record_filing_receipt`, `get_vat_position`, `get_vat_registers`, `get_vat_settlement` and `ask_accountant_question` (the company's own figures for a tax question, the official sources, and whether a commercialista is needed: Getbeel does not write the answer, the assistant does, from that data). The assistant asks before preparing an F24 or recording a receipt, and never pays or sends anything. See [MCP server](/en/api/mcp). # Idempotency (https://docs.getbeel.com/en/api/idempotency) Safely retry requests that create or send invoices with the Idempotency-Key header. A flaky network can lose the response to a request that succeeded. Retrying it blindly could create two drafts or, worse, send the same invoice twice. The `Idempotency-Key` header prevents that. ## How it works [#how-it-works] Send a unique value (we recommend a UUID v4) in the `Idempotency-Key` header of every `POST` that creates or sends: ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/INVOICE_ID/send \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: 9f1c2a4e-7b3d-4e8a-a1f2-3c5d7e9b0a12" ``` - The first request with a key runs, and its response is stored for **24 hours**. - If you repeat the same request with the same key, you get the stored response and the operation does not run again. - If you reuse the key for a different request (another endpoint or body), you get an error instead of a wrong response. It applies to `POST /invoices` and `POST /invoices/{id}/send`. ## Good practice [#good-practice] - Generate the key when you decide to perform the operation and store it with the operation, so a retry after a crash reuses it. - Use a new key for every distinct operation: two invoices, two keys. - Retry only network errors, `429` and `5xx`. A `4xx` needs fixing, not retrying. The errors: `409 idempotency_key_in_use` (a request with the same key is still running: retry shortly with the same key), `422 idempotency_key_reused` (key already used for a different request: use a new one), `400 parameter_invalid` with `param: "Idempotency-Key"` (the key must be 1–255 visible ASCII characters). See [Errors](/en/api/errors). Even without a key, a draft is sent only once: a second send gets `409 invoice_send_in_progress` or `409 invoice_not_draft` before any call to SDI. See [SDI lifecycle](/en/api/sdi-lifecycle#sending-twice-never-creates-a-duplicate). # Introduction (https://docs.getbeel.com/en/api) The Getbeel REST API and MCP server for Italian e-invoicing. Getbeel lets you create, validate and send Italian e-invoices (FatturaPA) to SDI, read issued and received invoices, and follow every SDI receipt with webhooks. The same operations are available as MCP tools for AI agents. ## How it works [#how-it-works] - **REST and JSON.** Fields in `snake_case`, ISO 8601 dates, amounts as decimal strings (`"122.00"`) to avoid rounding errors. - **Italian tax terms stay in Italian**: `codice_destinatario`, `tipo_documento`, `natura`, `regime_fiscale`. Everything else is English. - **Test and live keys.** `gb_test_…` keys use the [sandbox](/en/api/sandbox), which simulates SDI; `gb_live_…` keys transmit for real. The endpoints are the same. - **One API, one MCP server.** The [MCP server](/en/api/mcp) uses the same keys and services as the API. ## Base URL [#base-url] ```text https://www.getbeel.com/api/v1 ``` The API will also be served at `https://api.getbeel.com/v1`. The current URL will keep working. ## What you can do today [#what-you-can-do-today] | Endpoint | What it does | | -------------------------- | --------------------------------------------------------- | | `GET /me` | The account, company and key making the request | | `GET /invoices` | List issued invoices | | `GET /invoices/{id}` | One issued invoice, with its lines | | `POST /invoices` | Create a draft invoice | | `POST /invoices/{id}/send` | Send the draft to SDI (or to the sandbox with a test key) | | `POST /invoices/validate` | Check a FatturaPA XML without sending it | | `GET /received-invoices` | List supplier invoices | Every detail, with the playground, is in the [API reference](/en/api/reference). Webhooks are described in [Webhooks](/en/api/webhooks). Multiple companies (`companies`), invoices received through SDI on Getbeel's codice destinatario, invoice PDF and XML downloads, contacts, bank reconciliation, SDKs and a CLI. These docs are updated as they ship. ## Next steps [#next-steps] # Email, payments and reminders (https://docs.getbeel.com/en/api/invoice-collection) Email the invoice to your customer, record payments, create a Stripe payment link and send reminders. Once SDI has the invoice, it needs collecting. The API does what the **Payment** block of an issued invoice does in the app: customer emails, payments, payment links and reminders. Every endpoint uses the `invoices:write` scope (reads use `invoices:read`). You can email, mark as paid and remind invoices SDI accepted (`sent`, `delivered`, `not_delivered`) and proformas. Drafts and rejected invoices answer `409 invoice_not_issued`. Credit notes (TD04) can be emailed but are not collected: no payments, links or reminders. With a `gb_test_` key you work on sandbox invoices and **emails never reach the customer**: they go only to the team owner's address, with a banner and `[TEST]` in the subject. In the response `sandbox` is `true` and `sent_to` shows where it actually went. ## Email the invoice to the customer [#email-the-invoice-to-the-customer] ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/email \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "to": ["accounts@customer.com"], "language": "en", "message": "Thank you for your business!", "attach_xml": false }' ``` Every field is optional: without `to` it uses the customer's email on the invoice (`422 customer_email_missing` when there is none). The customer receives the PDF as a **courtesy copy** (copia di cortesia): the legally valid invoice is the one SDI delivered, and the email says so. `attach_xml: true` also attaches the FatturaPA file. When the invoice has a payment link, the email has a **Pay now** button. The response (`201`) is the email record with `status: sent` and `provider_message_id`. When the provider refuses the email we answer `502 email_failed`: the attempt stays on record and you can retry with the same `Idempotency-Key`. ```bash curl https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/deliveries \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `GET /deliveries` lists the invoice's emails (copies and reminders), newest first. ## Record a payment [#record-a-payment] ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payments \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Without a body it records everything still due, dated today, method `bank_transfer`: the invoice becomes `paid`. For a part payment pass the amount: ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payments \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": "50.00", "date": "2026-10-30", "method": "card" }' ``` Methods: `bank_transfer`, `card`, `cash`, `stripe`, `other`. More than what is still due answers `422 amount_exceeds_balance`, an invoice already paid `409 invoice_already_paid`. The response holds `payment` and the updated invoice. Every invoice now has these fields: | Field | Meaning | | ------------------ | ------------------------------------------------------------------------------- | | `payment_status` | `unpaid`, `partially_paid` or `paid` | | `amount_due` | What the customer pays: the total less the ritenuta d'acconto (withholding tax) | | `amount_paid` | Sum of the payments recorded | | `paid_at` | Date of the payment that settled it | | `overdue` | `true` when issued, unpaid and past `due_date` | | `payment_link_url` | The Stripe payment link, until paid | For invoices to collect or overdue: `GET /invoices?payment_status=unpaid` or `GET /invoices?overdue=true`. Invoices imported from Stripe are already paid. ## Stripe payment link [#stripe-payment-link] ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payment-link \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Creates a [Payment Link](https://docs.stripe.com/payment-links) for the outstanding amount on the Stripe account connected to the team (`201`), or returns the existing one (`200`). Without Stripe connected it answers `409 stripe_not_connected`: connect it from the fatture emesse page of the app or with [`POST /connections/stripe`](/en/api/connections). The Stripe mode must match the invoice: sandbox invoices need a test-mode connection, real invoices a live one (`409 stripe_mode_mismatch` otherwise). When a payment is recorded the link is switched off, since it charges the old balance: create a new one for what is left. When the customer pays, Getbeel records the payment (method `stripe`) within the hour and the invoice becomes paid. ## Reminders [#reminders] A manual reminder: ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/reminders \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "language": "en" }' ``` It takes the same fields as the email (`to`, `cc`, `language`, `message`) and attaches the PDF with the payment link. An invoice already paid answers `409`. **Automatic reminders** are switched on per company in the app (**Fatture emesse → Reminders**): off by default, they go out the number of days after the due date you choose (for example 3, 10, 30), once per step, only for live invoices with the customer's email and due from the day you switched them on. The same setting through the API (`invoices:write`, live keys; reading takes `invoices:read` and works with both): ```bash curl -X PATCH https://www.getbeel.com/api/v1/companies/me/reminder-settings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "days": [3, 10, 30] }' ``` A `PATCH` changes only what it sends. The answer, like `GET /companies/me/reminder-settings`, has `enabled`, `days` (up to 5 steps) and `enabled_at`, the day reminders started. MCP tools: `get_reminder_settings`, `update_reminder_settings`. ## Webhooks [#webhooks] | Event | When | `data.object` | | ---------------------- | --------------------------------------------- | --------------- | | `invoice.emailed` | Email or reminder sent | `invoice_email` | | `invoice.email_failed` | Sending failed | `invoice_email` | | `invoice.paid` | The payments cover what is due | `invoice` | | `invoice.overdue` | The day after the due date, once, when unpaid | `invoice` | ## With an AI assistant [#with-an-ai-assistant] The [MCP server](/en/api/mcp) has `email_invoice_to_customer`, `mark_invoice_paid`, `list_overdue_invoices`, `create_payment_link` and `send_payment_reminder`. Before sending an email the assistant asks you to confirm the recipients. # Credit notes, quotes, items and numbering (https://docs.getbeel.com/en/api/invoicing) Credit an invoice with a TD04 credit note, turn a quote into an invoice, save items and number with series. Four everyday invoicing tools, on the same services as the app. Writes need the `invoices:write` scope, reads `invoices:read`. Test keys work on sandbox data (their own credit notes, quotes and items), live keys on real data. ## Edit a draft [#edit-a-draft] `PATCH /invoices/{id}` changes a draft with the same rules as create and the app's edit form; the answer is the invoice with its totals recomputed. - Send only what changes. Each field replaces that part: `lines` replaces every line (send them all), `customer` and `payment` are sent whole, `notes: null` removes the causale. - If the draft has a withholding or a cassa previdenziale and you change `lines`, `withholding` or `cassa_previdenziale`, send those again too (`null` removes them): their amounts depend on the lines. Otherwise `400 parameter_missing`. - A number from a numbering series and the type of a credit note do not change: sending a different value answers `422 invoice_invalid` (the same value is accepted), and a series number cannot move to another year (`422 invoice_invalid`); a typed number must fit the year's sequence (`422 invoice_number_out_of_sequence`). - Only drafts: `409 invoice_not_draft` once it is sent, `409 invoice_send_in_progress` while it is being sent. A rejected invoice is reopened first ([SDI lifecycle](/en/api/sdi-lifecycle#rejected-ns--rejected)); a sent one is corrected with a credit note. ```bash curl -X PATCH https://www.getbeel.com/api/v1/invoices/$INVOICE \ -H "Authorization: Bearer $GETBEEL_API_KEY" -H "Content-Type: application/json" \ -d '{"lines": [{"description": "Consulenza novembre", "quantity": "3", "unit_price": "120.00", "vat_rate": "22"}], "notes": "Novembre 2026"}' ``` In MCP: `update_invoice_draft` and `reopen_rejected_invoice`. ## Credit notes (TD04) [#credit-notes-td04] A credit note credits an invoice SDI accepted: all of it, or some lines (also with a smaller quantity). ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE/credit-notes \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "lines": [{ "index": 0, "quantity": 2 }], "reason": "Returned goods" }' ``` - Without `lines` it credits the whole invoice (ritenuta, cassa and discounts included). A partial credit leaves those out: split them by hand. - The note copies the customer and payment data, refers to the invoice in `DatiFattureCollegate` (number and date) and starts as a **draft**: send it with `POST /invoices/{id}/send`, like any invoice. Webhook events are the invoice ones (`invoice.sent`, `invoice.delivered`…). - Number: the default series for credit notes, else the invoice's series. `series_id` picks one. - Credit notes that were not rejected can add up to the invoice total at most (`422 credit_exceeds_invoice`). Drafts, proformas and other notes cannot be credited (`409`). Once SDI accepts the note, the invoice shows `amount_credited` and its `amount_due` goes down: fully credited, it becomes `paid`, and reminders and overdue events take it into account. A rejected note stops counting. Alternatively, `POST /invoices` with `tipo_documento: "TD04"` and `related_invoice_id` creates a note with free lines. In the app: open a sent invoice and choose **Create credit note**. ## Quotes [#quotes] A quote has the same fields as an invoice (customer, lines, payment, notes) plus `valid_until`. Numbered per year (`12/2026`), statuses `draft` → `sent` → `accepted` or `declined`; a draft or sent quote past `valid_until` reads as `expired`. ```bash # create curl -X POST https://www.getbeel.com/api/v1/quotes \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "customer": { "denominazione": "Rossi S.r.l.", "partita_iva": "01234567890", "email": "accounts@rossi.it" }, "lines": [{ "description": "Website", "unit_price": "2500", "vat_rate": "22" }], "valid_until": "2026-12-31" }' # email the PDF to the customer curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/send \ -H "Authorization: Bearer $GETBEEL_API_KEY" # accepted: it becomes an invoice draft curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/convert \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` - `GET /quotes/{id}/pdf` downloads the PDF. With a test key the email goes to the account owner only. - `convert` creates the invoice dated today (or `date`) with the next number, under the same rules as `POST /invoices` (live keys need the SDI plan and quota), and marks the quote accepted. A quote converts once (`409 quote_converted`). - `POST /quotes/{id}/accept` and `POST /quotes/{id}/decline` record the customer's answer. - `GET /quotes/{id}` reads a quote; `PATCH /quotes/{id}` changes it until it is converted (`409 quote_converted`) or accepted (`409 quote_not_editable`); `DELETE /quotes/{id}` removes it (its invoice, if any, stays). In the app: **Issued invoices → Quotes**. ## Items [#items] Saved products and services with price, VAT (or natura) and unit, to pick in invoices and quotes. ```bash curl -X POST https://www.getbeel.com/api/v1/items \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Consulting", "unit_price": "80", "unit": "ore", "vat_rate": "22" }' ``` `GET /items?search=consult`, `PATCH /items/{id}` and `DELETE /items/{id}`. Invoices already made do not change when you edit an item. ## Numbering (series) [#numbering-series] Without series Getbeel uses Standard numbering: plain numbers without a suffix (`1`, `2`, `3`…) restarting at 1 every calendar year, as the Agenzia delle Entrate allows (Risoluzione 1/E of 2013); if the company chose one sequence across years, `default_numbering.yearly_reset` is `false`. Invoices numbered before keep the number sent to SdI (`45/`) and the next one continues without the slash (`46`). An invoice's `number` is always exactly the XML `Numero`. Without `number`, `POST /invoices` assigns it for the year of the date; a numeric `number` may be the next one or fill a gap, never skip ahead of its year's sequence (`422 invoice_number_out_of_sequence`). See the [numbering guide](/en/guide/numerazione-fatture). A series adds a prefix or suffix (`FT-12`, `12/A`), restarts from 1 every year (unless `yearly_reset: false`) and has its own sequence, separate for test and live keys. A number is never assigned twice. ```bash # list with the next number curl https://www.getbeel.com/api/v1/numbering-series \ -H "Authorization: Bearer $GETBEEL_API_KEY" # new series, default for invoices (live keys only) curl -X POST https://www.getbeel.com/api/v1/numbering-series \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Foreign", "suffix": "/E", "default_for_invoices": true }' ``` `POST /invoices`, `POST /quotes/{id}/convert` and credit notes take `series_id` (`null` = the standard numbering). Prefix, suffix and yearly restart cannot change after the first invoice (`409 numbering_series_in_use`); `GET /numbering-series/{id}` reads one series, and `PATCH /numbering-series/{id}` renames it, makes it the default or archives it (`{ "archived": true }`), with a live key. In the app: **Issued invoices → Quotes → Numbering**, and the **Numbering** menu in the new-invoice form. ## With an AI assistant [#with-an-ai-assistant] MCP tools: `list_quotes`, `create_quote`, `send_quote`, `convert_quote_to_invoice`, `create_credit_note`, `list_credit_notes` and `list_items`. The assistant asks before sending an email or creating a credit note; nothing goes to SDI without `send_invoice`. # 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. 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. In **Settings → Apps & Connectors** (developer mode) create a connector with URL `https://www.getbeel.com/api/mcp` and authentication **OAuth**, then sign in. ```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. ```bash claude mcp add --transport http getbeel https://www.getbeel.com/api/mcp ``` Then run `/mcp` in Claude Code and choose **Authenticate**. 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. ```bash claude mcp add --transport http getbeel https://www.getbeel.com/api/mcp \ --header "Authorization: Bearer $GETBEEL_API_KEY" ``` ```json title=".cursor/mcp.json" { "mcpServers": { "getbeel": { "url": "https://www.getbeel.com/api/mcp", "headers": { "Authorization": "Bearer ${env:GETBEEL_API_KEY}" } } } } ``` 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_..." } } } } ``` 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
`cursor`: string
`status`: "draft" \| "sending" \| "sent" \| "delivered" \| "not\_delivered" \| "rejected"
`date_from`: string (date)
`date_to`: string (date)
`payment_status`: "unpaid" \| "partially\_paid" \| "paid"
`overdue`: "true" \| "false"
`search`: string | Lists issued invoices (fatture emesse), newest invoice\_date first. Filter by status (draft, sending, sent, delivered, not\_delivered, rejected) and invoice\_date range, or search by customer, subject or number. Amounts are decimal strings. Pass next\_cursor as cursor to get the next page. Statuses: delivered = issued and delivered. not\_delivered = SDI could not deliver it (ricevuta di impossibilità di recapito): the invoice IS issued and is in the customer's reserved area (cassetto fiscale) since sdi.available\_since; tell the customer, never resend it (SDI would reject the copy as a duplicate). rejected = never issued: tell the user what sdi.errors says to fix, then reopen\_rejected\_invoice (back to draft, same number and date), update\_invoice\_draft with the correction and, once the user confirms, send\_invoice again (or "Correggi e reinvia" in the app). sent with sdi.error\_codes 00404 = SDI already holds an accepted copy: it is issued, do not resend. | | `get_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
`cursor`: string
`search`: string
`source`: "email" \| "forwarded" \| "manual" \| "bank\_transaction" \| "sdi"
`status`: "processing" \| "pending\_review" \| "verified" \| "rejected" \| "exported" \| "missing\_document"
`date_from`: string (date)
`date_to`: string (date) | Lists received (supplier) invoices, newest invoice\_date first, with their source (sdi, email, forwarded, …). Filter by source and invoice\_date range. Pass next\_cursor as cursor to get the next page. With a test key: only invoices received in the sandbox. | | `validate_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
`tipo_documento`: "TD01" \| "TD02" \| "TD04" \| "TD05" \| "TD06" \| "TD24" \| "TD25"
`number`: string
`date`: string (date)
`series_id`: string
`related_invoice_id`: string
`currency`: string
`lines`\*: object[]
`withholding`: object
`cassa_previdenziale`: object
`payment`: object
`notes`: string
`idempotency_key`: string | Creates a draft issued invoice (fattura emessa) for the customer and lines given. Nothing is sent: use send\_invoice afterwards. Customer: denominazione (company) or nome + cognome (person); an Italian customer needs partita\_iva or codice\_fiscale; codice\_destinatario (7 characters) or pec for delivery. Lines: description, quantity (default 1), unit\_price, and vat\_rate (e.g. "22") or natura for a 0% line (e.g. N2.2). Amounts are decimal strings; totals are computed by getbeel. The number defaults to the next free one and the date to today. With a test key (gb\_test\_) the draft is a sandbox invoice. Returns the invoice with its id, number, totals and status draft. | | `update_invoice_draft` | `invoices:write` | update | `id`\*: string
`customer`: object
`tipo_documento`: "TD01" \| "TD02" \| "TD04" \| "TD05" \| "TD06" \| "TD24" \| "TD25"
`number`: string
`date`: string (date)
`currency`: string
`lines`: object[]
`withholding`: object
`cassa_previdenziale`: object
`payment`: object
`notes`: string | Changes a draft invoice (status draft) with the same rules as create\_invoice\_draft. Send only the fields to change; each one replaces that part: lines replaces every line (send them all), customer and payment are sent whole. If the draft has a withholding or cassa\_previdenziale and you change lines, withholding or cassa\_previdenziale, send them again too (null removes them): their amounts depend on the lines. A number from a numbering series and the type of a credit note cannot change. Nothing is sent to SDI. Returns the updated invoice with its recomputed totals; show it to the user. A rejected invoice is reopened first with reopen\_rejected\_invoice; a sent or delivered one cannot be edited (it is corrected with a credit note). | | `reopen_rejected_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
`to`: string[]
`cc`: string[]
`language`: "it" \| "en"
`message`: string
`attach_xml`: boolean | Emails the PDF courtesy copy (copia di cortesia) of an issued invoice to the customer, with the Stripe payment link when the invoice has one. The legal invoice is still the one SDI delivered; this is a convenience copy. Recipients default to the customer's email on the invoice. BEFORE calling, tell the user who will receive it and get their OK. With a test key (gb\_test\_) the invoice is a sandbox one and the email goes only to the team owner, never to the customer. Returns the email record (status sent or failed). | | `mark_invoice_paid` | `invoices:write` | update | `id`\*: string
`amount`: string \| number
`date`: string (date)
`method`: "bank\_transfer" \| "card" \| "cash" \| "stripe" \| "other"
`note`: string | Records a payment on an issued invoice. Without amount it records everything still due and the invoice becomes paid; with a smaller amount it becomes partially\_paid. date defaults to today, method to bank\_transfer. Confirm the amount and date with the user first. | | `list_overdue_invoices` | `invoices:read` | | `limit`: integer
`cursor`: string | Issued invoices past their due date and not fully paid, newest invoice\_date first, with amount\_due, amount\_paid and the customer. Pass next\_cursor as cursor for the next page. | | `create_payment_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
`to`: string[]
`cc`: string[]
`language`: "it" \| "en"
`message`: string | Emails a payment reminder (sollecito) for an unpaid invoice to the customer, with the PDF and the payment link. Recipients default to the customer's email. BEFORE calling, tell the user who will receive it and get their OK. With a test key the email goes only to the team owner. | | `create_recurring_invoice` | `invoices:write` | create | `invoice_id`\*: string
`interval`\*: "monthly" \| "quarterly" \| "yearly"
`start_date`: string (date)
`auto_send`: boolean | Copies an existing invoice (invoice\_id) into a new draft every month, quarter or year, dated the day it is created, with the next number. With auto\_send the new invoice is also sent to SDI (a real transmission with a live key): only set it after the user explicitly asks for it. Confirm the interval and start date with the user first. | | `list_bank_statements` | `bank:read` | | `limit`: integer
`cursor`: string
`status`: "pending" \| "processing" \| "parsed" \| "matching" \| "review" \| "completed" \| "failed" | Lists uploaded bank statements, newest first, with status (pending, processing, parsed, matching, review = matched and ready for review, completed, failed), bank, period and transaction counts. The id is also the reconciliation id. | | `get_bank_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
`file_base64`: string
`file_name`: string
`currency`: string
`idempotency_key`: string | Uploads a bank statement (PDF, CSV or TXT, or a CBI, CAMT.053 XML or MT940 bank file, up to 50 MB; export spreadsheets as CSV) and starts reading it and matching its payments to the received invoices, like an upload in the app. Bank files are read exactly; PDF and CSV with AI. Pass file\_url (a public https link) or file\_base64 with file\_name (base64 only for files up to about 3 MB; larger files need file\_url). The statement comes back with status pending; reading and matching take a minute or two, then call get\_reconciliation with its id. A movement already imported for the same bank account (the same file again, an overlapping period) is not saved again, and a movement already imported is not charged again: transactions.total counts only the new ones (0 when nothing is new). Statements whose bank account is not recognised (no bank name or last 4 digits) save every movement. Confirm with the user first: it adds the statement to their real books and uses AI credits. Needs a live key (gb\_live\_). | | `get_reconciliation` | `bank:read` | | `id`\*: string
`limit`: integer
`cursor`: string
`state`: "to\_confirm" \| "reconciled" \| "missing\_invoice" \| "no\_invoice\_needed" \| "rejected" | The reconciliation of a bank statement (id = statement id): status, counts per state and a page of matches. Each match pairs a bank transaction with a received invoice: state to\_confirm (found by AI, needs approval), reconciled, missing\_invoice (payment without invoice), no\_invoice\_needed or rejected; match\_type exact, fuzzy, manual or unmatched; confidence 0–1. Filter by state; pass next\_cursor as cursor for more. | | `list_unmatched` | `bank:read` | | `type`\*: "payments" \| "invoices"
`limit`: integer
`cursor`: string
`from`: string (date)
`to`: string (date) | type payments: money out with no invoice found (missing documents to collect). type invoices: received invoices with no matching bank payment. Newest first; optional from/to dates (YYYY-MM-DD). | | `approve_match` | `bank:write` | update | `reconciliation_id`\*: string
`match_id`\*: string
`decision`: "approve" \| "reject" | Approves a reconciliation match (the invoice found is right; for a payment without invoice: no invoice is needed) or rejects it (decision reject). Show the user the transaction and the invoice, and confirm with the user first. Needs a live key. | | `match_manually` | `bank:write` | update | `reconciliation_id`\*: string
`transaction_id`\*: string
`invoice_id`\*: string | Links a received invoice (id from list\_unmatched type invoices or list\_collected\_documents) to a bank transaction of a reconciliation. Show the pair and confirm with the user first. Needs a live key. | | `list_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
`from`\*: string (date)
`to`\*: string (date) | Scans a connected Gmail, Outlook or IMAP mailbox (connection id from list\_connections) for supplier invoices between two dates (at most a year). Runs in the background and uses AI credits: confirm with the user first. Found invoices appear in list\_collected\_documents. Needs a live key. | | `list_collected_documents` | `received_invoices:read` | | `limit`: integer
`cursor`: string
`search`: string
`source`: "email" \| "forwarded" \| "manual" \| "bank\_transaction" \| "sdi"
`status`: "processing" \| "pending\_review" \| "verified" \| "rejected" \| "exported" \| "missing\_document"
`date_from`: string (date)
`date_to`: string (date) | Supplier invoices and receipts getbeel collected (source email, forwarded, manual, bank\_transaction), newest first, with their review status (pending\_review needs a person). Same list as list\_received\_invoices. Empty with a test key. | | `approve_collected_document` | `received_invoices:write` | update | `id`\*: string
`decision`: "approve" \| "reject" | Marks a collected document as verified (approve) or rejected (decision reject), like reviewing it in the app. Show the user the vendor, date and amount, and confirm with the user first. Needs a live key. | | `get_tax_calendar` | `taxes:read` | | `from`: string (date)
`to`: string (date) | The company's Italian tax deadlines (scadenzario) between from and to (default: 90 days ago to a year ahead): stamp duty on e-invoices (bollo), withholding taxes (ritenute, 1040), VAT payments, LIPE and the VAT return; for a company the IRES/IRAP saldo and acconti; for a person with partita IVA the INPS contributions of the scheme in the tax profile (inps\_fixed AF/CF instalments, inps\_balance and inps\_advance with causale AP/CP or PXX/P10, one of the two, and the forfettario 35% request inps\_reduction\_request). Each deadline has due\_date (already moved off weekends and holidays), amount when known (bollo from the issued invoices; a VAT payment without a saved liquidazione shows the VAT computed from the registers, amount\_status provisional), status (to\_prepare, ready, paid, filed, not\_due), can\_prepare and filing\_id. missing\_settings lists what the user must set in the app (Tasse) first. needs\_review means the rule may not fit the company: tell the user to check it. | | `prepare_filing` | `taxes:write` | create | `type`\*: "bollo" \| "withholdings" \| "vat\_payment" \| "lipe" \| "vat\_return" \| "redditi\_pf"
`period`\*: string
`amount`: string
`previous_credit`: string
`previous_debt`: string
`annual_credit_used`: string
`advance`: string
`advance_method`: "1" \| "2" \| "3" \| "4"
`declarant_fiscal_code`: string
`declarant_role`: integer
`previous_year_credit`: string
`idempotency_key`: string | Prepares a filing for a deadline: type bollo (stamp duty on e-invoices, period a closed quarter like 2026-Q3, amount computed by getbeel from the issued invoices), withholdings (ritenute on professionals’ fees paid in a month, period like 2026-10, codice 1040: getbeel adds up the fees recorded with list\_withholdings and paid in that month; pass amount only for fees not recorded in getbeel), vat\_payment (the liquidazione IVA of a closed month or quarter, as the company settles VAT: saves it and returns its F24; call get\_vat\_settlement first and show it; optional previous\_credit / previous\_debt only to replace what getbeel computed for the previous period, or when it has no earlier data that year (note previous\_missing), annual\_credit\_used, advance and advance\_method for the December/Q4 acconto), lipe (the LIPE XML of a closed quarter from the saved liquidazioni, checked against the official XSD; companies pass declarant\_fiscal\_code of the signer and declarant\_role, 1 = legal representative) or vat\_return (period a closed year like 2026: the data sheet of the annual Dichiarazione IVA, quadri VE, VF, VJ, VL, VX in whole euros from the VAT registers and saved liquidazioni, with issues to check; optional previous\_year\_credit for VL25; not the telematic file, which the user or accountant fills with the AdE software) or redditi\_pf (period a closed year: the data sheet of the Redditi PF return of a persona fisica, from the tax estimate of the year in Stima imposte, entity forfettario, irpef or minimi: lines of quadri LM, RE, RN, RV, RR and the saldo/acconti F24 codes; returns redditi\_pf\_not\_applicable for a company; not the telematic file). vat\_payment answers nothing\_due (the liquidazione is still saved) for a credit, for up to €100 carried forward and for Q4 of quarterly payers; lipe answers settlements\_missing until every month or the quarter is saved. Returns the filing with f24\_lines (none for lipe and redditi\_pf; 6099 for a vat\_return balance), checks (xsd for the LIPE; the AdE control software is never run by getbeel) and next\_steps (file link, AdE page, values to copy, email drafts). Nothing is paid, signed or sent: the user pays in F24 web or home banking, and checks, signs and uploads the LIPE in their AdE area. VAT figures are computed from the registers in getbeel and must be checked ("da verificare"). Tell the user the amount and period and get their OK first. Calling again before it is paid or filed recomputes it. Needs a live key. Pay as you go: each filing is charged once per type, period and company from the prepaid balance, when it is paid or filed (record\_filing\_receipt, or set\_filing\_status filed with the protocol number of a return); preparing it (by hand or automatically), preparing it again, the review (approving included) and skipping it are free: any F24 (bollo, withholdings, vat\_payment) €1.00, LIPE €3.00, VAT return data €12.00, Redditi PF return €9.00. Tell the user the price before they mark it paid or filed. | | `get_filing_next_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
`file_url`: string
`file_base64`: string
`file_name`: string | Attaches the receipt (F24 quietanza or the AdE receipt of a LIPE, PDF/PNG/JPEG up to 10 MB) to a ready filing and marks it paid (a LIPE: filed). Pass file\_url (public https link) or file\_base64 with file\_name. ONLY after the user confirms they paid and that this is the receipt: ask first. Needs a live key. Pay as you go: each filing is charged once per type, period and company from the prepaid balance, when it is paid or filed (record\_filing\_receipt, or set\_filing\_status filed with the protocol number of a return); preparing it (by hand or automatically), preparing it again, the review (approving included) and skipping it are free: any F24 (bollo, withholdings, vat\_payment) €1.00, LIPE €3.00, VAT return data €12.00, Redditi PF return €9.00. Tell the user the price before they mark it paid or filed. | | `get_vat_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"
`period`: string
`from`: string (date)
`to`: string (date) | Management figures from the invoices and bank movements in getbeel, net of VAT. type profit-and-loss: revenue (issued e-invoices accepted by SDI) minus costs (reviewed supplier invoices, by category), by document date, with a monthly breakdown. cash-flow: money in and out of the bank accounts by month, outflows by the category of the matched supplier invoice. aging: what customers still owe today by days past due (not due, 1–30, 31–60, 61–90, over 90), per customer and invoice. period is a year (2026), quarter (2026-Q3) or month (2026-10), or send from and to; default the current year; aging ignores them. These are NOT the statutory financial statements (bilancio): say so, present the figures as to check with the accountant ("da verificare"), and mention what not\_included lists (documents still at SDI, unreviewed supplier invoices). | | `list_withholdings` | `taxes:read` | | `limit`: integer
`cursor`: string
`paid_in`: string
`status`: "unpaid" \| "withheld" \| "remitted" | Fees paid (or to pay) to professionals and agents on which the company withholds the ritenuta d’acconto as sostituto d’imposta, one per received fee: recipient, CU causale, gross / not subject / taxable / withheld amounts, paid\_on, status (unpaid: fee not paid yet; withheld: ritenuta to pay with F24 1040 by due\_date; remitted: paid with an F24 recorded in getbeel), needs\_review. Filter with paid\_in (2026-10 or 2026) and status. Fees on invoices received from SDI with DatiRitenuta are recorded automatically; sync\_withholdings reads older ones. | | `record_withholding` | `taxes:write` | create | `recipient`\*: object
`document`: object
`invoice_id`: string
`type`: "RT01" \| "RT02"
`causale`: "A" \| "B" \| "C" \| "D" \| "E" \| "F" \| "G" \| "H" \| "I" \| "J" \| "K" \| "L" \| "L1" \| "M" \| "M1" \| "M2" \| "N" \| "O" \| "O1" \| "P" \| "Q" \| "R" \| "S" \| "T" \| "U" \| "V" \| "V1" \| "V2" \| "W" \| "X" \| "Y" \| "Z" \| "ZO"
`rate`\*: string \| number
`gross_amount`\*: string \| number
`not_subject_amount`: string \| number
`withheld_amount`: string \| number
`paid_on`: string (date)
`notes`: string | 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
`recipient`: object
`document`: object
`invoice_id`: string
`type`: "RT01" \| "RT02"
`causale`: "A" \| "B" \| "C" \| "D" \| "E" \| "F" \| "G" \| "H" \| "I" \| "J" \| "K" \| "L" \| "L1" \| "M" \| "M1" \| "M2" \| "N" \| "O" \| "O1" \| "P" \| "Q" \| "R" \| "S" \| "T" \| "U" \| "V" \| "V1" \| "V2" \| "W" \| "X" \| "Y" \| "Z" \| "ZO"
`rate`: string \| number
`gross_amount`: string \| number
`not_subject_amount`: string \| number
`withheld_amount`: string \| number
`paid_on`: string (date)
`notes`: string
`remitted`: "true" | Changes a withholding (id wht\_… from list\_withholdings): most often paid\_on, the day the company paid the fee, which makes the ritenuta due with F24 1040 by the 16th of the next month; also the codice fiscale, causale or amounts. A new rate or amount recomputes withheld\_amount unless given. remitted: true links it to the month’s withholdings F24 already recorded as paid (only when the user says that F24 included it). Refused (withholding\_remitted) once an F24 recorded in getbeel paid it. Confirm with the user first. Needs a live key. Free. | | `delete_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
`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
`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"
`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
`date`: string (date)
`currency`: string
`lines`\*: object[]
`withholding`: object
`cassa_previdenziale`: object
`payment`: object
`notes`: string
`valid_until`: string (date)
`idempotency_key`: string | Creates a draft quote (preventivo) for a customer: same customer and lines as create\_invoice\_draft, plus valid\_until. Nothing is sent: the user can review it in the app, email it with send\_quote, and turn it into an invoice with convert\_quote\_to\_invoice. Lines: description, quantity (default 1), unit\_price, vat\_rate (e.g. "22") or natura for a 0% line. Use list\_items for the saved items and services and their prices. | | `send_quote` | `invoices:write` | send | `id`\*: string
`to`: string[]
`cc`: string[]
`language`: "it" \| "en"
`message`: string | Emails the quote PDF to the customer (default: the customer's email on the quote) and marks it sent. BEFORE calling, tell the user who will receive it and get their OK. With a test key the email goes only to the team owner. | | `convert_quote_to_invoice` | `invoices:write` | create | `id`\*: string
`series_id`: string
`date`: string (date)
`idempotency_key`: string | Creates an invoice draft from a quote (dated today unless date is given, next number) and marks the quote accepted. Nothing is sent to SDI: show the draft to the user and use send\_invoice only after their explicit OK. A quote converts once. | | `create_credit_note` | `invoices:write` | create | `invoice_id`\*: string
`lines`: object[]
`series_id`: string
`date`: string (date)
`reason`: string
`idempotency_key`: string | Creates a credit note (nota di credito, TD04) draft for an invoice SDI accepted: the whole invoice, or some lines (index from get\_invoice lines, optional smaller quantity). It refers to the invoice (DatiFattureCollegate) and is numbered automatically. Confirm with the user which lines and amounts to credit first. Nothing is sent: use send\_invoice with the credit note id after the user explicitly OKs it. Once SDI accepts it, the invoice amount due goes down by the credit. | | `list_credit_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
`include_archived`: "true" \| "false"
`limit`: integer | Saved items and services (articoli) with unit price, VAT rate or natura and unit, to reuse in quotes and invoices. search filters by name. | | `get_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
`customer`: object
`currency`: string
`lines`: object[]
`withholding`: object
`cassa_previdenziale`: object
`payment`: object
`notes`: string
`valid_until`: string (date) | Replaces the customer, lines or validity of a quote that is not converted yet (same fields as create\_quote). Confirm the changes with the user first. | | `delete_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
`description`: string
`code`: string
`unit_price`\*: string \| number
`unit`: string
`vat_rate`: string \| number
`natura`: string | Saves a product or service (description, unit price, VAT rate or natura) for reuse in invoices and quotes. | | `update_item` | `invoices:write` | update | `id`\*: string
`name`: string
`description`: string
`code`: string
`unit_price`: string \| number
`unit`: string
`vat_rate`: string \| number
`natura`: string
`archived`: boolean | Changes a saved item (id from list\_items). | | `delete_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
`prefix`: string
`suffix`: string
`yearly_reset`: boolean
`default_for_invoices`: boolean
`default_for_credit_notes`: boolean | Adds a numbering series (sezionale). Numbering is fiscal: confirm the series, suffix and starting number with the user first. Needs a live key. | | `update_numbering_series` | `invoices:write` | update | `id`\*: string
`name`: string
`prefix`: string
`suffix`: string
`yearly_reset`: boolean
`default_for_invoices`: boolean
`default_for_credit_notes`: boolean
`archived`: boolean | Changes a numbering series (id from list\_numbering\_series). Numbering is fiscal: confirm with the user first. Needs a live key. | | `list_recurring_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
`interval`: "monthly" \| "quarterly" \| "yearly"
`next_date`: string (date)
`auto_send`: boolean | Changes the interval, the next date or auto\_send. auto\_send makes every new invoice a real SDI transmission with a live key: only turn it on when the user explicitly asks. Confirm with the user first. | | `pause_recurring_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)
`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
`cursor`: string
`year`: integer | The company’s fixed assets, newest purchase first, each with its tax depreciation schedule (year, max\_amount, amount deducted, fondo, residual), status and residual value at the end of year (default this year). Prepared by getbeel: to check with the accountant. | | `register_fixed_asset` | `taxes:write` | create | `name`\*: string
`category_code`: "altre.edifici" \| "altre.fabbricati\_gdo" \| "altre.costruzioni\_leggere" \| "altre.sollevamento" \| "altre.macchinari" \| "altre.stigliatura" \| "altre.arredamento" \| "altre.banconi\_blindati" \| "altre.allarme" \| "altre.comunicazione" \| "altre.depurazione" \| "altre.mobili\_ufficio" \| "altre.macchine\_ufficio\_elettroniche" \| "altre.autoveicoli\_trasporto" \| "altre.autovetture" \| "alberghi.edifici" \| "alberghi.costruzioni\_leggere" \| "alberghi.mobili\_arredamento" \| "alberghi.biancheria" \| "alberghi.attrezzatura" \| "alberghi.impianti\_generici" \| "alberghi.impianti\_specifici" \| "alberghi.macchine\_ufficio\_elettroniche" \| "alberghi.autoveicoli\_trasporto" \| "alberghi.autovetture" \| "persona.edifici" \| "persona.costruzioni\_leggere" \| "persona.mobili\_arredamento" \| "persona.biancheria" \| "persona.impianti\_specifici" \| "persona.attrezzatura" \| "persona.mobili\_ufficio" \| "persona.macchine\_ufficio\_elettroniche" \| "persona.autoveicoli\_trasporto" \| "persona.autovetture" \| "immateriali.software\_brevetti" \| "immateriali.marchi" \| "immateriali.avviamento"
`category_label`: string
`coefficient`: number
`kind`: "tangible" \| "intangible"
`cost`\*: string
`purchase_date`: string (date)
`in_service_date`: string (date)
`first_year_half`: boolean
`expense_in_full`: boolean
`depreciation_overrides`: object
`received_invoice_id`: string
`supplier_name`: string
`document_number`: string
`notes`: string
`disposal_date`: string (date)
`disposal_amount`: string \| "0.00"
`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
`name`: string
`category_code`: "altre.edifici" \| "altre.fabbricati\_gdo" \| "altre.costruzioni\_leggere" \| "altre.sollevamento" \| "altre.macchinari" \| "altre.stigliatura" \| "altre.arredamento" \| "altre.banconi\_blindati" \| "altre.allarme" \| "altre.comunicazione" \| "altre.depurazione" \| "altre.mobili\_ufficio" \| "altre.macchine\_ufficio\_elettroniche" \| "altre.autoveicoli\_trasporto" \| "altre.autovetture" \| "alberghi.edifici" \| "alberghi.costruzioni\_leggere" \| "alberghi.mobili\_arredamento" \| "alberghi.biancheria" \| "alberghi.attrezzatura" \| "alberghi.impianti\_generici" \| "alberghi.impianti\_specifici" \| "alberghi.macchine\_ufficio\_elettroniche" \| "alberghi.autoveicoli\_trasporto" \| "alberghi.autovetture" \| "persona.edifici" \| "persona.costruzioni\_leggere" \| "persona.mobili\_arredamento" \| "persona.biancheria" \| "persona.impianti\_specifici" \| "persona.attrezzatura" \| "persona.mobili\_ufficio" \| "persona.macchine\_ufficio\_elettroniche" \| "persona.autoveicoli\_trasporto" \| "persona.autovetture" \| "immateriali.software\_brevetti" \| "immateriali.marchi" \| "immateriali.avviamento"
`category_label`: string
`coefficient`: number
`kind`: "tangible" \| "intangible"
`cost`: string
`purchase_date`: string (date)
`in_service_date`: string (date)
`first_year_half`: boolean
`expense_in_full`: boolean
`depreciation_overrides`: object
`received_invoice_id`: string
`supplier_name`: string
`document_number`: string
`notes`: string
`disposal_date`: string (date)
`disposal_amount`: string \| "0.00" | Send only what changes. To record a sale or elimination give disposal\_date and disposal\_amount ("0.00" when thrown away): the result has disposal.gain (positive plusvalenza, negative minusvalenza). depreciation\_overrides records years where less than the maximum was deducted. Get the user’s OK first. Needs a live key. Free. | | `delete_fixed_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
`entity`: "company" \| "forfettario" \| "irpef" \| "minimi" \| "other"
`other_revenue`: string \| number
`other_costs`: string \| number
`personnel_costs`: string \| number
`permanent_staff_costs`: string \| number
`ires_adjustments`: string \| number
`irap_rate`: number
`isa_subject`: boolean
`prior_year_ires`: string \| number
`prior_year_irap`: string \| number
`ateco_code`: string
`forfettario_group`: integer
`startup_rate`: boolean
`revenue_basis`: "collected" \| "invoiced"
`inps_scheme`: "gestione\_separata" \| "artigiani" \| "commercianti" \| "cassa\_professionale" \| "none"
`inps_reduction_35`: boolean
`insured_before_1996`: boolean
`inps_amount_override`: string \| number
`contributions_paid`: string \| number
`prior_year_substitute_tax`: string \| number
`irpef_activity`: "professional" \| "business"
`regional_surcharge_rate`: number
`municipal_surcharge_rate`: number
`prior_year_irpef`: string \| number
`withholdings_suffered`: string \| number
`minimi_prior_losses`: string \| number | Saves for a year what getbeel cannot know: entity (company, forfettario, irpef, minimi), for irpef the kind of activity, the addizionali rates, the ritenute suffered and last year’s IRPEF due (RN34), for minimi the earlier losses still usable (LM9), ATECO code or group, start-up 5% rate, INPS scheme and 35% reduction, personnel and permanent staff costs, other revenue and costs, IRAP regional rate, last year’s taxes for the acconti. Only send what the user told you. Returns the recomputed estimate. Needs a live key; saving the inputs is free (nothing is charged to the balance). | | `list_pos_rt_links` | `taxes:read` | | `limit`: integer
`cursor`: string
`status`: "to\_file" \| "filed" \| "end\_to\_file" \| "ended" | Payment terminals (POS) linked to registratori telematici (RT), with status (to\_file, filed, end\_to\_file, ended) and pending: the operation still to communicate to the AdE and its window (from, due). Since 2026 every POS must be linked to the RT in the AdE portal (L. 207/2024; provv. 424470/2025). | | `add_pos_rt_link` | `taxes:write` | create | `label`: string
`rt_serial`\*: string
`acquirer_country`: "IT" \| "ES"
`acquirer_id`\*: string
`acquirer_name`\*: string
`pos_type`\*: "00" \| "01"
`terminal_id`: string
`contract_number`\*: string
`itinerant`: boolean
`province`: string
`municipality`: string
`street`: string
`street_number`: string
`postal_code`: string
`active_from`\*: string (date)
`ended_on`: string (date)
`idempotency_key`: string | Records a POS used with an RT: rt\_serial (matricola RT), acquirer\_id (its codice fiscale, 11 digits) and acquirer\_name, pos\_type 00 physical (with terminal\_id) or 01 virtual, contract\_number (convenzione), the address of the shop or itinerant, active\_from. Ask the user for these values; never guess them. Needs a live key. Free. | | `end_pos_rt_link` | `taxes:write` | update | `id`\*: string
`ended_on`: string (date) | Sets ended\_on (last day the POS was used with that RT): the end becomes the next thing to communicate. Get the user’s OK first. Needs a live key. Free. | | `get_pos_rt_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"
`withholding_agent`: boolean
`oss_from`: string (date)
`oss_until`: string (date)
`auto_prepare`: boolean
`auto_prepare_days`: integer | Sets the VAT periodicity, whether the company is a withholding agent and/or its OSS registration dates (oss\_from, oss\_until; null clears) and/or the automatic F24 preparation (auto\_prepare on by default, auto\_prepare\_days 1-30); only what you send changes. The periodicity decides the VAT periods of the registers, liquidazioni and F24, and oss\_from adds the quarterly OSS return deadlines: set them as the company actually is registered, never guess; ask the user (or their accountant) and confirm first. Needs a live key. | | `get_reminder_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
`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"
`vat_periodicity`: "monthly" \| "quarterly"
`withholding_agent`: boolean \| null
`has_employees`: boolean \| null
`reverse_charge_suppliers`: boolean \| null
`oss_registered`: "false"
`intrastat`: boolean \| null
`in_liquidation`: boolean \| null
`liquidation_from`: string (date)
`first_fiscal_year`: integer
`social_security`: "gestione\_separata" \| "artigiani" \| "commercianti" \| "cassa\_professionale" \| "none"
`social_security_fund`: string
`regimes`: object[]
`confirm`: "legal\_form" \| "regime\_fiscale" \| "vat\_periodicity" \| "withholding\_agent" \| "has\_employees" \| "reverse\_charge\_suppliers" \| "intrastat" \| "oss\_suggested" \| "oss\_registered" \| "in\_liquidation" \| "first\_fiscal\_year" \| "social\_security" \| "special\_regimes"[] | Sets profile fields (only what you send changes; null clears a value back to the detection), confirms detected values (`confirm`) or replaces the special regimes (`regimes`, with typed `params` per kind, e.g. forfettario \{ startup: true \}, impatriati\_2024 \{ minor\_child: true \}). getbeel computes the rates from them; never send rates. It changes which deadlines the tax calendar lists, so only send what the user told you or confirmed: never guess, especially employees, the OSS registration, social security and special regimes. Recorded in the audit log. Needs a live key. | | `detect_tax_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
`status`\*: "needs\_review" \| "changes\_requested" \| "approved" \| "skipped" \| "filed"
`reason`: string
`reference`: string
`expected_updated_at`: string | Moves a filing in the review: approved (visto bueno), skipped (not to be done: reason required), needs\_review (back to review, or reopen a skipped filing), filed (a LIPE, annual VAT return or Redditi PF return sent: reference = its protocol number), changes\_requested (only the commercialista, in the app). When the team requires the commercialista’s approval, only the commercialista approves. A paid F24 is recorded with record\_filing\_receipt instead. Pay as you go: filed completes the filing and charges it once from the prepaid balance, like its receipt (never twice for the same filing; insufficient\_balance when the balance does not cover it, and nothing changes). Approving, asking for changes, skipping and reopening are free. Only do what the user asked, and confirm first. Recorded in the history and the audit log. Needs a live key. | | `skip_filing` | `taxes:write` | update | `type`\*: "bollo" \| "withholdings" \| "vat\_payment" \| "lipe" \| "vat\_return" \| "redditi\_pf"
`period`\*: string
`reason`\*: string | For a filing type and period never prepared (or already prepared), records "not to be done" with the reason (e.g. the accountant pays it, nothing is due). getbeel then never prepares it automatically and never charges it. Reopen it with set\_filing\_status needs\_review. Only when the user says so. Needs a live key. | | `comment_filing` | `taxes:write` | create | `id`\*: string
`body`\*: string | Adds a comment to a filing’s history, read by the team and the commercialista (e.g. a question about a figure). Needs a live key. | | `list_filing_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
`value`\*: number
`valid_from`\*: string
`valid_to`: string
`source_url`\*: string
`source_title`\*: string
`source_article`: string
`quote`: string
`status`: "active" \| "pending" | Adds a value of a known rule key (e.g. inps.maternity\_yearly) for its dates, with its official source. status active puts it in force at once (official source only: agenziaentrate.gov.it, mef.gov.it, finanze.gov.it, gazzettaufficiale.it, inps.it, normattiva.it, fatturapa.gov.it); pending (default) waits for approval. Only for getbeel administrators (a live key with the tax\_rules:admin scope, created in the admin page by a super-admin); it changes every company’s calendar or estimate. Only do what the user asked, and confirm first. | | `add_tax_calendar_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"
`nominal_from`\*: string
`nominal_to`\*: string
`new_due_date`\*: string
`valid_from`\*: string
`source_url`\*: string
`source_title`\*: string
`quote`: string
`note`: string
`status`: "active" \| "pending" | Moves the deadlines of deadline\_kind (all: every tax deadline) whose legal date is in nominal\_from–nominal\_to to new\_due\_date, from valid\_from, citing the decree. status active applies it at once (official source only), updates prepared unpaid F24s and tells the affected teams; pending (default) waits for approval. Only for getbeel administrators (a live key with the tax\_rules:admin scope, created in the admin page by a super-admin); it changes every company’s calendar or estimate. Only do what the user asked, and confirm first. | | `decide_tax_rule` | `tax_rules:admin` | update | `kind`\*: "rule\_value" \| "override"
`id`\*: string
`decision`\*: "approve" \| "reject" \| "withdraw"
`note`: string | Approves (in force at once) or rejects a pending rule value or proroga (kind rule\_value or override, id from get\_tax\_rules). Here only proposals with an official source can be approved, and rules-watch proposals only when their quote was found in the source; read the source first. Only for getbeel administrators (a live key with the tax\_rules:admin scope, created in the admin page by a super-admin); it changes every company’s calendar or estimate. Only do what the user asked, and confirm first. | | `get_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
`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
`type`: "invoice\_scan" \| "fattura\_emessa"
`active`: boolean | Adds an AI rule at the end of its type; it applies to the next invoices the AI reads, not to ones already read. Write it as the user would say it and confirm it with them first. invoice\_scan rules need the received\_invoices scopes, fattura\_emessa rules the invoices scopes. Needs a live key. | | `update_ai_rule` | `received_invoices:write` | update | `id`\*: string
`text`: string
`active`: boolean | Changes an AI rule's text, or pauses (active false) or resumes it (id from list\_ai\_rules). invoice\_scan rules need the received\_invoices scopes, fattura\_emessa rules the invoices scopes. Needs a live key. | | `delete_ai_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
`cursor`: string
`statement_id`: string
`from`: string (date)
`to`: string (date)
`status`: "to\_confirm" \| "reconciled" \| "missing\_invoice" \| "no\_invoice\_needed" \| "rejected" | Lists bank transactions (from uploaded statements and connected banks), newest first, as GET /v1/bank-transactions: date, description, counterparty, amount, currency and reconciliation state. Filter as the parameters describe; pass next\_cursor as cursor for the next page. | | `start_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
`cursor`: string
`type`: "bollo" \| "withholdings" \| "vat\_payment" \| "lipe" \| "vat\_return" \| "redditi\_pf"
`status`: "ready" \| "needs\_review" \| "changes\_requested" \| "approved" \| "skipped" \| "filed" \| "paid" | Lists prepared tax filings (LIPE, VAT return data, F24…), newest first, as GET /v1/filings, with type, period, status (ready: prepared, no review asked; needs\_review: waiting for the commercialista; changes\_requested; approved; skipped: not to be done; filed; paid) and amounts. See the history with list\_filing\_events. Open one with get\_filing\_next\_steps, download its file with get\_filing\_file. | | `get_filing_file` | `taxes:read` | | `id`\*: string
`format`: "csv" \| "xlsx" \| "json" | The file of a prepared filing (the LIPE XML to send to the Agenzia delle Entrate, or the VAT return data sheet: format csv, xlsx or json), as GET /v1/filings/\{id\}/file. Returns download\_url, a private link valid 15 minutes: give it to the user, never fetch it yourself; and file\_spec, the id of the official specification the file follows (get\_filing shows its name, version and source). | | `list_fixed_asset_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
`country`: string
`vat_number`: string
`codice_fiscale`: string
`regime_fiscale`: string
`address`: string
`street_number`: string
`postal_code`: string
`city`: string
`province`: string | Adds a client company to this account (for software houses, marketplaces and commercialisti that manage several companies), with its fiscal data, as POST /v1/companies. Pass its id as company\_id to the other tools. It is real data: needs a live key, and confirm the P.IVA and name with the user first. | | `update_company` | `companies:write` | update | `id`\*: string
`name`: string
`country`: string
`vat_number`: string
`codice_fiscale`: string
`regime_fiscale`: string
`address`: string
`street_number`: string
`postal_code`: string
`city`: string
`province`: string | Changes the fiscal data of the key's own company or one of its client companies (id from list\_companies; only the fields sent), as PATCH /v1/companies/\{id\}. These are the data every invoice carries (cedente/prestatore): confirm each change with the user first. Needs a live key. | | `list_drive` | `drive:read` | | `month`: string
`folder`: string | The company's Drive as in the app, for one month (month 2026-10: received invoices' files by invoice date, uploaded bank statements and documents by upload date) or one uploads folder (folder from folders[].path, e.g. contratti). Send month or folder. Invoice files also need received\_invoices:read and bank statements bank:read; without them they are left out. | | `get_drive_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
`file_url`: string
`file_base64`: string
`file_name`: string | Stores a document (PDF, PNG, JPEG, DOC or DOCX, up to 25 MB) in a Drive folder that takes uploads (writable in list\_drive: a month like 2026-10, documents, or a custom folder), from a public https file\_url or file\_base64 with file\_name. It is only stored, not read by the AI: a supplier invoice to record goes to upload\_received\_invoice instead. Needs a live key. | | `create_drive_folder` | `drive:write` | create | `name`\*: string
`month`: string | Creates an uploads folder at the root of the Drive or inside a month (month 2026-10). Confirm the name with the user first. Needs a live key. | | `delete_drive_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
`file_base64`: string
`file_name`: string | Uploads a supplier invoice or receipt (PDF, JPEG, PNG or WEBP, up to 50 MB) and the AI reads it, like an upload in the app; the invoice then appears in list\_received\_invoices with status pending\_review for the user to approve. Pass file\_url (a public https link) or file\_base64 with file\_name (base64 only for files up to about 3 MB; larger ones need file\_url). Check progress with get\_received\_invoice\_upload. It uses one invoice credit and adds the document to the real books: confirm with the user first. Needs a live key. | | `get_received_invoice_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
`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
`label`: string
`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
`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
`action`\*: "exclude" \| "adjust"
`vat_amount`: string
`reason`\*: string | Changes what one VAT register row (key from get\_vat\_registers) puts in the liquidazione, as Rettifica in the app: action exclude keeps it out; action adjust sets the VAT that counts (vat\_amount, e.g. the deductible 40% of a company car cost). reason is required and kept for the accountant. It replaces an earlier adjustment of the row. A liquidazione already saved stays as it was until prepare\_filing (type vat\_payment) runs again: say so. This changes the VAT the company pays: confirm the row, the amount and the reason with the user first. Needs a live key. | | `remove_vat_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 non valido", "error_codes": ["00305"], "errors": [ { "code": "00305", "description": "1.4.1.1.2 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. ## 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 ``` # Pagination (https://docs.getbeel.com/en/api/pagination) Lists use cursor pagination with limit, cursor, has_more and next_cursor. Endpoints that return lists (`GET /invoices`, `GET /received-invoices`) are sorted by `invoice_date`, newest first, and return one page at a time: ```json { "object": "list", "data": [{ "object": "invoice", "id": "fe_3f1c…" }], "has_more": true, "next_cursor": "WyIyMDI2LTEwLTE1IiwiZmVfM2YxYyJd" } ``` | Parameter | Description | | --------- | -------------------------------------- | | `limit` | Items per page, 1 to 100. Default 20 | | `cursor` | The `next_cursor` of the previous page | When `has_more` is `false`, `next_cursor` is `null` and you have read everything. The cursor is opaque: don't build it yourself. Repeat filters (for example `status`, `date_from`, `date_to`) on every page. ## Reading every page [#reading-every-page] ```js async function* allInvoices(params = {}) { let cursor; do { const query = new URLSearchParams({ ...params, limit: '100', ...(cursor ? { cursor } : {}), }); const res = await fetch( `https://www.getbeel.com/api/v1/invoices?${query}`, { headers: { Authorization: `Bearer ${process.env.GETBEEL_API_KEY}` }, }, ); const page = await res.json(); yield* page.data; cursor = page.has_more ? page.next_cursor : undefined; } while (cursor); } for await (const invoice of allInvoices({ status: 'rejected' })) { console.log(invoice.number, invoice.sdi.error_message); } ``` # Pricing, balance and usage (https://docs.getbeel.com/en/api/pricing) Pay as you go from a prepaid balance. The price list, the balance, top-ups, usage and the 402 insufficient_balance error. Using Getbeel is free: the app, sandbox, API, MCP server, webhooks, deadline calendar, registers and exports. You only pay for what costs money, from **one prepaid EUR balance per billing account**. A gestore with many client companies has one balance, and the tiers count all its companies. Prices exclude VAT. ## Price list [#price-list] **Sending to SDI** (invoices, credit notes, autofatture TD16–TD20: every document sent to SDI), in tiers per calendar month: | Sends per month | Price per send | | --------------- | -------------- | | 1–1,000 | €0.15 | | 1,001–10,000 | €0.12 | | above 10,000 | €0.10 | | Item | Price | | ------------------------------------------------------------ | ------ | | Invoice received from SDI | €0.15 | | Document read by AI (email scan, forwarding address, upload) | €0.03 | | Connected bank account, per month | €2.00 | | Imported bank movement | €0.02 | | F24 paid (any F24: VAT, bollo, withholdings, INPS, advances) | €1.00 | | LIPE filed | €3.00 | | OSS return filed | €3.00 | | Annual VAT return filed | €12.00 | | IRES/IRAP return filed | €9.00 | | Redditi PF return filed (self-employed, any regime) | €9.00 | A filing is charged once per type, period and company, when it is paid or filed (its receipt recorded): preparing it (by hand or automatically), preparing it again and skipping it are free. Saving the tax estimate inputs is free. A bank movement is charged once, when it is imported (bank feed or statement upload): importing it again (the same statement, a sync returning it, an overlapping statement) is free, and an uploaded statement does not save again a movement already imported for the same bank account (recognised by bank name and last 4 digits). The tax profile, regime detection, the calendar and alerts are free. Quotes, proforma, PDFs, reminders and resending after a rejection are free. Example: 200 companies that send 20 invoices and receive 30 a month through SDI make 4,000 sends (€510) and 6,000 receipts (€900): €1,410 a month. `GET /billing/prices` returns the same list (cents, net of VAT). ## Balance and top-ups [#balance-and-top-ups] - **Welcome credit**: €1 once per account (and per card and VAT number), valid 90 days, when you save your first card. A card that already got it on another team gets no second one: Billing & usage says "The welcome credit applies only once per card." The welcome credit is for new accounts only. - **Top-ups**: from €10, with an invoice for every top-up (VAT at checkout). Paid credit is valid 12 months. - **Auto top-up**: off by default; when the balance drops below a threshold it adds an amount with the saved card. If the card is declined it retries once after 24 hours, then turns off. - **Low-balance alert**: the warning on Billing & usage, the red sidebar balance and the email start once you have paid credit: a top-up (by hand or automatic) not refunded in full; the welcome credit alone does not count. The line is €10 unless you change it. - **Balance at zero**: new paid actions stop. Receiving invoices from SDI never stops: it can take the balance down to -€10, taken from the next top-up. `GET /billing/balance` returns `pricing` (`pay_as_you_go`, or `legacy_plan`: see [Accounts on a plan](#accounts-on-a-plan)), the balance in cents (`balance_cents`), credit expiring in the next 30 days (`expiring_soon_cents`), auto top-up and the low-balance alert, `welcome_credit` (`granted`, and `not_granted_reason`: `card_already_used`, `legacy_plan`, `no_card` or null), and `topup_url`. The balance may lag by up to a minute. `POST /billing/topups` with `amount_cents` creates a Stripe payment link (`checkout_url`) for a person to pay: the API never charges a card. It needs a live key with the `billing:write` scope (never ticked by default), created by someone who manages billing. With a client company's own key the `/billing` endpoints answer 403 `billed_to_parent`: the balance and usage are on the gestore's account. The Stripe page opens in the language of the person who created the key (else the team owner's, else Italian for an Italian company) and offers only the current default card (Stripe Checkout cannot preselect one saved card, so the others are hidden there; another card can still be typed in). ```bash curl https://getbeel.com/api/v1/billing/balance \ -H "Authorization: Bearer $GETBEEL_LIVE_KEY" curl -X POST https://getbeel.com/api/v1/billing/topups \ -H "Authorization: Bearer $GETBEEL_LIVE_KEY" \ -H "Content-Type: application/json" \ -d '{"amount_cents": 2500}' ``` `POST /billing/payment-method` (no body) creates a Stripe link (`checkout_url`, setup mode: nothing is charged) where a person enters a new card: it becomes the default card and the one auto top-ups charge. The same card saved twice is kept once. Same key and scope as top-ups; 409 `no_card` when no card is saved yet, as `application/problem+json` in the same shape as the 402 below. MCP: `create_billing_card_link`. ## Usage [#usage] `GET /billing/usage?month=2026-12` returns per item (`by_meter`) the quantity, amount and the next send's price at this month's tier, and per company (`by_company`) for a gestore. ## Insufficient balance (402) [#insufficient-balance-402] A paid action the balance does not cover answers **402** `application/problem+json` with `code` `insufficient_balance`, `balance_cents`, `required_cents` and `topup_url`, plus the usual `error` object. Here `balance_cents` is the available balance (the balance minus amounts reserved for actions in progress), never below 0. For a client company billed to its gestore the answer has no `balance_cents` and no `topup_url` (the balance is the gestore's): the message asks the account that bills the company to add credits. MCP tools return the same text. See [Errors](/en/api/errors). ## Accounts on a plan [#accounts-on-a-plan] Customers who signed up before 13 November 2026 keep their plan (or the SDI add-on), its prices and everything it includes, with no end date: with an active paid plan, tax filings and connected bank accounts are included, and without a plan they stay closed as before (402 `subscription_required`). Pay as you go is only for accounts created from that day. For these accounts `GET /billing/balance` answers with `pricing: "legacy_plan"`, amounts at 0, `topup_url` null and `welcome_credit.not_granted_reason: "legacy_plan"`. `GET /billing/usage`, `POST /billing/topups` and `POST /billing/payment-method` answer 409 `not_pay_as_you_go`. `GET /usage` returns the month's SDI transactions (`sdi_transactions`, `free_allowance`, `email_extractions`, `estimated_amount`, `rate_card`, `received_unit_amount`, `email_extraction_unit_amount`). # Quickstart (https://docs.getbeel.com/en/api/quickstart) Create a test key, make your first call, validate an XML and send an invoice in the sandbox. Send your first e-invoice in about five minutes, in the sandbox: nothing reaches the real SDI and nothing is billed. ## Before you start [#before-you-start] - **A Getbeel account** with a team. Settings → Company does not need to be complete for test keys. - **Permission to manage settings** in that team (owners and members, not auditors), to create a key. - **Not needed:** a card, a plan, a live key or SDI set-up. The sandbox and test keys are free ([Pricing](/en/api/pricing)). Copy this prompt into Claude Code, Cursor or Codex. ```text title="Prompt" Add the Getbeel API to this project. 1. Read https://docs.getbeel.com/en/api/quickstart.md and https://docs.getbeel.com/llms.txt before writing code. 2. Read the API key from the GETBEEL_API_KEY environment variable. Never hard-code it. Use a test key (gb_test_...) until I say otherwise. 3. Base URL: https://www.getbeel.com/api/v1. Call GET /me first to check the key. 4. Validate invoices with POST /invoices/validate and create drafts with POST /invoices. 5. Show me the draft and wait for my OK before calling POST /invoices/{id}/send. 6. Send an Idempotency-Key header (a new UUID per operation) on every POST that creates or sends. 7. Handle errors by error.type and error.code; on 429 wait for the Retry-After seconds. ``` ### Create a test key [#create-a-test-key] In the Getbeel app open **Settings → API keys & MCP** and create a key in **Test** mode. The key (`gb_test_…`) is shown once: copy it right away. Members who can manage settings can create keys (owners and members, not auditors). ```bash export GETBEEL_API_KEY="gb_test_..." ``` ### Make your first call [#make-your-first-call] ```bash curl https://www.getbeel.com/api/v1/me \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` ```json title="Response" { "object": "account", "id": "5b0c2f8e-6a3d-4c1e-9f0a-2d7b1e4c9a10", "name": "Rossi S.r.l.", "slug": "rossi", "company": { "name": "Rossi S.r.l.", "vat_number": "01234567890", "regime_fiscale": "RF01", "sdi_configured": true }, "api_key": { "prefix": "gb_test_a1B2", "mode": "test", "scopes": [ "account:read", "invoices:read", "received_invoices:read", "invoices:validate" ] } } ``` The response is shortened. `api_key.mode` confirms you are using a test key. ### Validate a FatturaPA XML [#validate-a-fatturapa-xml] Send an XML file as is, or as JSON `{ "xml": "…" }`. Nothing is sent or stored. ```bash curl https://www.getbeel.com/api/v1/invoices/validate \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/xml" \ --data-binary @fattura.xml ``` ```json title="Response" { "object": "validation_result", "valid": false, "tipo_documento": "TD01", "errors": [ { "code": "00421", "message": "DatiRiepilogo (rate 22): Imposta 30 does not match calculated 22.00" } ], "checks": ["structure", "xsd", "business_rules"] } ``` Validation uses the official FatturaPA XSD schema (v1.2.3) and the SDI content controls that depend on the file alone (Specifiche tecniche v1.9.1, Appendice 1: VAT and natura, totals with SDI's tolerances, summaries, document type rules), the same checks Getbeel runs before every send. Each error carries the Agenzia delle Entrate code and wording: `00200` for the schema (with the line in the file), `00201` past 50 format errors, `00313`–`00476` for content. Not checked locally: signatures, the AdE registries (VAT numbers, recipient codes) and duplicates. ### Create a draft [#create-a-draft] ```bash curl https://www.getbeel.com/api/v1/invoices \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "tipo_documento": "TD01", "customer": { "denominazione": "Bianchi S.p.A.", "partita_iva": "01234567890", "country": "IT", "codice_destinatario": "ABCDE12", "address": "Via Roma 1", "postal_code": "20121", "city": "Milano", "province": "MI" }, "lines": [ { "description": "Consulting, October", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00" } ] }' ``` The response is the invoice with `status: "draft"` and its `id`. The full list of fields is in the [API reference](/en/api/reference). ### Send the draft to the sandbox [#send-the-draft-to-the-sandbox] ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/INVOICE_ID/send \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` With a test key the send goes to the sandbox, which answers like SDI: the invoice moves to `sent` and then to `delivered`. Check the status with `GET /invoices/{id}` or receive [webhooks](/en/api/webhooks). ### Try a rejection [#try-a-rejection] Create another draft with `"partita_iva": "00000000000"` for the customer and send it: the sandbox rejects it with code `00305` (customer IdCodice not valid) and the invoice becomes `rejected`: correct it and send it again with the same number and date (see [SDI lifecycle](/en/api/sdi-lifecycle)). Every outcome is on the [Sandbox](/en/api/sandbox) page. ## What just happened [#what-just-happened] - **You created a test key.** It acts on your team with your access, only on sandbox data. It is stored as a hash: Getbeel cannot show it again. - **`GET /me` checked it.** `api_key.mode` is `test` and `api_key.scopes` lists what the key may do. - **The XML was validated** with the same checks Getbeel runs before every send. Nothing was stored. - **A draft was created** with `status: "draft"`, the next number of the test sequence and today's date. Until you send it, change it with `PATCH /invoices/{id}`. - **The sandbox answered like SDI**: `sent`, then `delivered` (or `rejected` with the SDI code). With a live key the same calls reach the real SDI. ## If it fails [#if-it-fails] | Error | Cause | Fix | | ---------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- | | `401` `missing_api_key` | No `Authorization` header | Send `-H "Authorization: Bearer $GETBEEL_API_KEY"` | | `401` `invalid_api_key` | The key is mistyped, or the variable is empty | `echo $GETBEEL_API_KEY`, then copy the key again or create a new one | | `403` `insufficient_scope` | The key lacks the scope named in the message | Create a key with that scope (keys cannot be edited) | | `403` `company_not_eligible` | Issuing needs an Italian company profile | Complete **Settings → Company** | | `422` on `POST /invoices` | A field is missing or invalid; `param` names it | Fix the field and send again with a new `Idempotency-Key` | ```json title="401 response" { "error": { "type": "authentication_error", "code": "missing_api_key", "message": "No API key provided. Send it as 'Authorization: Bearer gb_…'." } } ``` Every code and what to do with it: [Errors](/en/api/errors). ## Next steps [#next-steps] Get a signed event for every SDI outcome instead of polling. Let Claude, ChatGPT or Cursor prepare invoices for you to approve. Create a live key when the sandbox flow works end to end. The same calls in TypeScript, Python or the terminal. # Rate limits (https://docs.getbeel.com/en/api/rate-limits) 120 requests per minute per key, with RateLimit and Retry-After headers. Each API key can make **120 requests every 60 seconds**, in test and live mode. The count is per key, not per IP address, and includes calls to the [MCP server](/en/api/mcp). ## Headers [#headers] Every response tells you where you stand: | Header | Value | | --------------------- | -------------------------------------- | | `RateLimit-Limit` | Requests allowed in the window (`120`) | | `RateLimit-Remaining` | Requests left | | `RateLimit-Reset` | Seconds until the window resets | ## When you exceed the limit [#when-you-exceed-the-limit] You get `429` with `type: "rate_limit_error"` and `code: "rate_limit_exceeded"`, plus a `Retry-After` header with the seconds to wait. ```js async function getbeel(path, init = {}) { for (let attempt = 0; attempt < 3; attempt++) { const res = await fetch(`https://www.getbeel.com/api/v1${path}`, { ...init, headers: { Authorization: `Bearer ${process.env.GETBEEL_API_KEY}`, ...init.headers, }, }); if (res.status !== 429) return res; const wait = Number(res.headers.get('Retry-After') ?? '1'); await new Promise((resolve) => setTimeout(resolve, wait * 1000)); } throw new Error('Getbeel rate limit: too many retries'); } ``` Requests refused for a missing scope also count towards the limit. If you need a higher limit, write to us. # Received invoices (https://docs.getbeel.com/en/api/received-invoices) List and review supplier invoices, upload one for the AI to read, and manage the categories and AI rules that file them. Received invoices are the supplier invoices and receipts of your company: from SDI (`source: "sdi"`), collected from email (`email`) or the forwarding address (`forwarded`), uploaded (`manual`), or read from a bank movement (`bank_transaction`). The same list as **Received invoices** in the app. Reads take `received_invoices:read` and work with both key modes. Writes take `received_invoices:write` and a live key: the books are real, there is no sandbox copy (`403 livemode_required` with a test key). ## List [#list] ```bash curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Newest invoice date first, [paginated](/en/api/pagination). Filter by `status` (`processing`, `pending_review`, `verified`, `rejected`, `exported`, `missing_document`), `source`, `search` and `date_from` / `date_to`. With a test key the list holds only the invoices received in the [sandbox](/en/api/sdi-receiving). MCP: `list_received_invoices`, and `list_collected_documents` for those still to review. ## Approve or reject [#approve-or-reject] ```bash curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` - `POST /received-invoices/{id}/approve` moves an invoice from `pending_review` (or `rejected`) to `verified`, like reviewing it in the app. Already verified: nothing changes. - `POST /received-invoices/{id}/reject` moves it from `pending_review` (or `verified`) to `rejected`: use it for documents that are not invoices. MCP: `approve_collected_document`, with `decision: "reject"` to reject. ## Reverse charge on foreign invoices [#reverse-charge-on-foreign-invoices] An invoice from a foreign supplier collected by email, the forwarding address or an upload carries `reverse_charge`: the autofattura getbeel proposed for it (`null` when none applies, for example an Italian supplier or an invoice received through SDI). ```json title="reverse_charge" { "tipo_documento": "TD17", "status": "proposed", "reason": "non_eu_services", "deadline_basis": "effettuazione", "deadline": "2026-12-15" } ``` - `tipo_documento`: `TD17` services from abroad, `TD18` goods from another EU state, `TD19` goods already in Italy; `null` when no TD applies or the supplier country is missing. The rule decides it, not the AI. - `status`, the live state of the proposal: `proposed` (the XML draft is generated automatically), `needs_review` (check it on the Autofatture page first), `needs_country` (enter the supplier country), `not_required` (goods imported from outside the EU: the customs document replaces the TD), `generated` (the XML draft exists, not sent), `sent` (handed to SDI), `dismissed` (deleted by the team). - `reason` and `deadline` are the ones the rule set when the proposal was made (or when the team set its country and type). - `deadline`: the 15th of the month after the receipt of the invoice (EU suppliers, `receipt`) or after the purchase (non-EU suppliers, `effettuazione`), art. 1, c. 3-bis, lett. b, d.lgs. 127/2015. Sending the autofattura to SDI is always done by a person in the app. Rules and sources: [Autofatture](/en/guide/autofatture). ## Upload an invoice [#upload-an-invoice] Send a PDF, JPEG, PNG or WEBP (up to 50 MB) for the AI to read, as an upload in the app. ```bash curl -X POST https://www.getbeel.com/api/v1/received-invoices/uploads \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "file_url": "https://example.com/fattura-rossi.pdf" }' ``` ```json title="Response" { "object": "received_invoice_upload", "id": "scan_1794408453000_k3j9x2a", "status": "pending", "files": 1, "processed": 0, "skipped": 0, "error": null } ``` - Send `file_url` (a public `https` URL, no redirects) or `file_base64` with `file_name`. The type is read from the file, not its name. - Each file uses one invoice credit ([Pricing](/en/api/pricing)). - `GET /received-invoices/uploads/{id}` follows it: `pending` and `processing` while the AI reads it, `completed` when the invoice is in the list with `status: "pending_review"`, `failed` with the reason in `error`. `skipped` counts files that were not an invoice or were a duplicate. | Status | `code` | When | | ------ | ----------------------- | --------------------------------------------------------------------------------------------------- | | 413 | `payload_too_large` | The file is over 50 MB | | 415 | `unsupported_file_type` | Not a PDF, JPEG, PNG or WEBP (FatturaPA XML arrives through [SDI receiving](/en/api/sdi-receiving)) | | 402 | `credits_exhausted` | No invoice credits left | MCP: `upload_received_invoice`, `get_received_invoice_upload`. ## Categories [#categories] Categories file received invoices by type of cost. A received invoice carries the category's `slug` in `category`. ```bash curl -X POST https://www.getbeel.com/api/v1/categories \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "label": "Software" }' ``` - `GET /categories` lists them in the app's order. `POST /categories` adds one: its slug comes from the label, its colour from the next preset unless you send `color` (`#rrggbb` or `hsl()`). - `PATCH /categories/{id}` renames or recolours one; the slug stays. `DELETE /categories/{id}` deletes one and moves its invoices to `other`. Default categories cannot be deleted (`409 default_category`). - `POST /received-invoices/{id}/category` with `{ "category": "software" }` sets an invoice's category (`422 unknown_category` for a slug the team doesn't have). MCP: `list_categories`, `create_category`, `update_category`, `delete_category`, `set_received_invoice_category`. ## AI rules [#ai-rules] Plain-language instructions the AI follows, in order, when it reads your invoices. The same rules as **Settings → AI rules**. ```bash curl -X POST https://www.getbeel.com/api/v1/ai-rules \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "text": "Le fatture di Amazon Web Services vanno nella categoria software" }' ``` - `type` is `invoice_scan` (the default: reading received invoices) or `fattura_emessa` (drafting issued invoices from Stripe payments). The scope follows the type: `invoice_scan` rules take the `received_invoices` scopes, `fattura_emessa` rules the `invoices` scopes. - A new rule goes last of its type and applies to the next invoices the AI reads; invoices already read stay as they are. - `GET /ai-rules` lists them (filter with `type`). `PATCH /ai-rules/{id}` changes the text or pauses the rule (`"active": false`). `DELETE /ai-rules/{id}` deletes it. MCP: `list_ai_rules`, `create_ai_rule`, `update_ai_rule`, `delete_ai_rule`. ## Related [#related] - [Connections](/en/api/connections): connect a mailbox and scan it for invoices. - [SDI receiving](/en/api/sdi-receiving): receive supplier invoices straight from SDI. - [Webhooks](/en/api/webhooks): `received_invoice.created` for every new invoice. # Recurring invoices (https://docs.getbeel.com/en/api/recurring-invoices) Repeat an invoice every month, quarter or year, optionally sending it to SDI. A recurring invoice starts from an invoice you already have (the **template**): every month, quarter or year Getbeel creates a draft copy dated that day, with the next number and the same payment term (the due date moves by the same number of days). With `auto_send` the new invoice also goes to SDI. Scope `invoices:write` (reads `invoices:read`). In the app: open an issued invoice and choose **Make recurring**; the list is under **Fatture emesse → Recurring invoices**, with pause and resume. ## Create [#create] ```bash curl -X POST https://www.getbeel.com/api/v1/recurring-invoices \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "invoice_id": "fe_…", "interval": "monthly", "auto_send": false }' ``` - `interval`: `monthly`, `quarterly` or `yearly`. - `start_date` (optional, today or later): the date of the first new invoice. By default it is the first date after today in the series `invoice_date` + n × interval. A schedule on the 31st moves to the 28th after February (the day of the stored next date is kept). - `auto_send`: send every new invoice to SDI. With a live key that is a real transmission; with a test key it goes to the sandbox. Proformas are never sent. One schedule per invoice (`409 recurring_invoice_exists`). An invoice that cannot be copied (invalid data) answers `422 invoice_not_copyable`. ## How it runs [#how-it-runs] Every morning Getbeel creates the invoices of the schedules that reached `next_date` and moves `next_date` to the next period. Live invoices follow the same rules as in the app: they need the SDI add-on and quota. When creation fails (for example the quota is used up) `last_error` says why and Getbeel tries again the next day; `last_invoice_id` is the latest invoice created. Test keys see and create only sandbox schedules, live keys only real ones. ## Manage [#manage] ```bash # list curl https://www.getbeel.com/api/v1/recurring-invoices \ -H "Authorization: Bearer $GETBEEL_API_KEY" # pause and resume curl -X POST https://www.getbeel.com/api/v1/recurring-invoices/$ID/pause \ -H "Authorization: Bearer $GETBEEL_API_KEY" curl -X POST https://www.getbeel.com/api/v1/recurring-invoices/$ID/resume \ -H "Authorization: Bearer $GETBEEL_API_KEY" # change curl -X PATCH https://www.getbeel.com/api/v1/recurring-invoices/$ID \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "interval": "quarterly", "next_date": "2027-01-01", "auto_send": true }' # delete (invoices already created stay) curl -X DELETE https://www.getbeel.com/api/v1/recurring-invoices/$ID \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` On resume, a `next_date` already past jumps to the next period: no catch-up invoices. ## With an AI assistant [#with-an-ai-assistant] The MCP tool `create_recurring_invoice` creates the schedule after confirming the interval and date with you; it sets `auto_send` only when you ask for it. # Modalità di pagamento (MP) (https://docs.getbeel.com/en/api/reference-data/modalita-pagamento) The FatturaPA ModalitaPagamento values, MP01 to MP23. Maps to the field `2.4.2.2 ModalitaPagamento` of the payment data. Descriptions are the official Italian ones, with an English gloss. | Code | Official description | In English | | ------ | ------------------------------------------ | --------------------------------------- | | `MP01` | Contanti | Cash | | `MP02` | Assegno | Cheque | | `MP03` | Assegno circolare | Banker's draft | | `MP04` | Contanti presso Tesoreria | Cash at the Treasury | | `MP05` | Bonifico | Bank transfer | | `MP06` | Vaglia cambiario | Bill of exchange | | `MP07` | Bollettino bancario | Bank payment slip | | `MP08` | Carta di pagamento | Payment card | | `MP09` | RID | Direct debit (RID) | | `MP10` | RID utenze | Utility direct debit | | `MP11` | RID veloce | Fast direct debit | | `MP12` | RIBA | Bank receipt (RIBA) | | `MP13` | MAV | Payment notice (MAV) | | `MP14` | Quietanza erario stato | State treasury receipt | | `MP15` | Giroconto su conti di contabilità speciale | Transfer between special accounts | | `MP16` | Domiciliazione bancaria | Bank standing order | | `MP17` | Domiciliazione postale | Post office standing order | | `MP18` | Bollettino di c/c postale | Postal account slip | | `MP19` | SEPA Direct Debit | SEPA Direct Debit | | `MP20` | SEPA Direct Debit CORE | SEPA Direct Debit CORE | | `MP21` | SEPA Direct Debit B2B | SEPA Direct Debit B2B | | `MP22` | Trattenuta su somme già riscosse | Withholding from sums already collected | | `MP23` | PagoPA | PagoPA | Between businesses the most common is `MP05` (bank transfer), with the IBAN in the payment data. Source: Agenzia delle Entrate, FatturaPA format technical specifications version 1.4. # Natura IVA (N) (https://docs.getbeel.com/en/api/reference-data/natura) The natura codes for lines without VAT, N1 to N7 with sub-codes. `natura` maps to the FatturaPA field `Natura` (`2.2.1.14` on lines, `2.2.2.2` in the summary). Set it **only** when the VAT rate is zero: it says why VAT does not apply. Descriptions are the official Italian ones, with an English gloss. | Code | Official description | In English | | ------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `N1` | Escluse ex art. 15 | Excluded under art. 15 | | `N2.1` | Non soggette ad IVA ai sensi degli artt. da 7 a 7-septies del DPR 633/72 | Out of scope: place of supply outside Italy (arts. 7 to 7-septies) | | `N2.2` | Non soggette – altri casi | Out of scope, other cases | | `N3.1` | Non imponibili – esportazioni | Zero-rated: exports | | `N3.2` | Non imponibili – cessioni intracomunitarie | Zero-rated: intra-EU supplies | | `N3.3` | Non imponibili – cessioni verso San Marino | Zero-rated: supplies to San Marino | | `N3.4` | Non imponibili – operazioni assimilate alle cessioni all'esportazione | Zero-rated: transactions treated as exports | | `N3.5` | Non imponibili – a seguito di dichiarazioni d'intento | Zero-rated: under a declaration of intent | | `N3.6` | Non imponibili – altre operazioni che non concorrono alla formazione del plafond | Zero-rated: other, not counted towards the ceiling | | `N4` | Esenti | Exempt | | `N5` | Regime del margine / IVA non esposta in fattura | Margin scheme / VAT not shown | | `N6.1` | Inversione contabile – cessione di rottami e altri materiali di recupero | Reverse charge: scrap and recovered materials | | `N6.2` | Inversione contabile – cessione di oro e argento puro | Reverse charge: pure gold and silver | | `N6.3` | Inversione contabile – subappalto nel settore edile | Reverse charge: construction subcontracting | | `N6.4` | Inversione contabile – cessione di fabbricati | Reverse charge: sale of buildings | | `N6.5` | Inversione contabile – cessione di telefoni cellulari | Reverse charge: mobile phones | | `N6.6` | Inversione contabile – cessione di prodotti elettronici | Reverse charge: electronic products | | `N6.7` | Inversione contabile – prestazioni comparto edile e settori connessi | Reverse charge: construction and related services | | `N6.8` | Inversione contabile – operazioni settore energetico | Reverse charge: energy sector | | `N6.9` | Inversione contabile – altri casi | Reverse charge: other cases | | `N7` | IVA assolta in altro stato UE (vendite a distanza …; servizi di telecomunicazioni, tele-radiodiffusione ed elettronici …) | VAT paid in another EU state (distance sales; telecom, broadcasting and electronic services) | ## Codes no longer valid [#codes-no-longer-valid] Since 1 January 2021 the generic codes `N2`, `N3` and `N6` are no longer accepted: use the sub-code. An invoice that uses them is rejected with code `00445`. ## Common errors [#common-errors] | SDI code | Cause | | ----------------- | ------------------------------------------------------------------------- | | `00400` | Zero rate on a line without `natura` | | `00401` | `natura` on a line with a non-zero rate (only allowed with `TD16`) | | `00429` / `00430` | The same problem in the summary data | | `00444` | A line's `natura` is missing from the summary | | `00420` | Natura `N6.x` (reverse charge) with VAT chargeability `S` (split payment) | Which natura applies depends on the transaction: ask your accountant when in doubt. Source: Agenzia delle Entrate, FatturaPA format technical specifications version 1.4. # Regime fiscale (RF) (https://docs.getbeel.com/en/api/reference-data/regime-fiscale) The regime_fiscale values of the seller, RF01 to RF20. `regime_fiscale` maps to the FatturaPA field `1.2.1.8 RegimeFiscale` of the seller (cedente/prestatore): the tax regime of whoever issues the invoice. Descriptions are the official Italian ones, with an English gloss. | Code | Official description | In English | | ------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `RF01` | Ordinario | Ordinary regime | | `RF02` | Contribuenti minimi (art. 1, c. 96-117, L. 244/2007) | "Minimi" small-taxpayer regime | | `RF04` | Agricoltura e attività connesse e pesca (artt. 34 e 34-bis, D.P.R. 633/1972) | Agriculture, related activities and fishing | | `RF05` | Vendita sali e tabacchi (art. 74, c. 1, D.P.R. 633/1972) | Salt and tobacco sales | | `RF06` | Commercio dei fiammiferi (art. 74, c. 1, D.P.R. 633/1972) | Matches trade | | `RF07` | Editoria (art. 74, c. 1, D.P.R. 633/1972) | Publishing | | `RF08` | Gestione di servizi di telefonia pubblica (art. 74, c. 1, D.P.R. 633/1972) | Public telephone services | | `RF09` | Rivendita di documenti di trasporto pubblico e di sosta (art. 74, c. 1, D.P.R. 633/1972) | Resale of public transport and parking tickets | | `RF10` | Intrattenimenti, giochi e altre attività di cui alla tariffa allegata al D.P.R. n. 640/72 (art. 74, c. 6, D.P.R. 633/1972) | Entertainment and gaming | | `RF11` | Agenzie di viaggi e turismo (art. 74-ter, D.P.R. 633/1972) | Travel agencies | | `RF12` | Agriturismo (art. 5, c. 2, L. 413/1991) | Farm holidays | | `RF13` | Vendite a domicilio (art. 25-bis, c. 6, D.P.R. 600/1973) | Door-to-door sales | | `RF14` | Rivendita di beni usati, di oggetti d'arte, d'antiquariato o da collezione (art. 36, D.L. 41/1995) | Second-hand goods, art, antiques and collectibles | | `RF15` | Agenzie di vendite all'asta di oggetti d'arte, antiquariato o da collezione (art. 40-bis, D.L. 41/1995) | Auction houses for art, antiques and collectibles | | `RF16` | IVA per cassa P.A. (art. 6, c. 5, D.P.R. 633/1972) | Cash-basis VAT, public administration | | `RF17` | IVA per cassa (art. 32-bis, D.L. 83/2012) | Cash-basis VAT | | `RF18` | Altro | Other | | `RF19` | Regime forfettario (art. 1, c. 54-89, L. 190/2014) | Flat-rate regime | | `RF20` | Regime transfrontaliero di Franchigia IVA (Direttiva UE 2020/285) | Cross-border VAT exemption scheme for small businesses (EU Directive 2020/285) | - `RF03` (new productive initiatives) was removed in 2017 and is no longer accepted. - `RF20` was added with version 1.9 of the technical specifications (January 2025). - Businesses in the flat-rate regime (`RF19`) normally issue invoices without VAT with natura `N2.2`. Source: Agenzia delle Entrate, FatturaPA format technical specifications version 1.4. # SDI rejection codes (https://docs.getbeel.com/en/api/reference-data/sdi-errors) Every code in SDI rejection receipts, with its cause and how to fix it. When a check fails, SDI sends a **rejection receipt (NS, ricevuta di scarto)** with one or more 5-digit codes and a short description. In Getbeel the codes are in `sdi.error_codes` and, with SDI's description, in `sdi.errors` of the [invoice](/en/api/reference); the `invoice.rejected` webhook carries the full invoice in `data.object`. A rejected invoice **counts as never issued**: fix what the code says and send it again with the same number and date, preferably within 5 days of the rejection receipt. The one exception is `00404` on an invoice you had already sent: see below. The full picture of outcomes is in the [SDI lifecycle](/en/api/sdi-lifecycle). ## SDI receipts [#sdi-receipts] | Receipt | Meaning | Status in Getbeel | | ----------------------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------- | | RC, ricevuta di consegna | Delivered to the recipient: issued | `delivered` | | MC, ricevuta di impossibilità di recapito | Not delivered but **issued**: it is in the customer's cassetto fiscale from `sdi.available_since` | `not_delivered` | | NS, ricevuta di scarto | File refused: the invoice counts as never issued | `rejected` | | NE, notifica di esito (PA) | Acceptance or refusal by a public administration | Acceptance: `delivered`; refusal: `rejected` | | DT, decorrenza termini (PA) | The administration did not answer within 15 days | `delivered` | ## 00404: duplicate of an issued invoice [#00404-duplicate-of-an-issued-invoice] `00404` ("Fattura duplicata") means SDI **already accepted** a document with the same supplier, the same year of the date and the same number (for autofatture TD16–TD20, TD22, TD23, TD28 and TD29 the cessionario counts). The check does not apply when the earlier document was rejected, and a credit note (`TD04`) may share an invoice's number. - **On an invoice you had already sent** (for example a second submission of the same document): the invoice **is issued**, because SDI holds an accepted copy. Do not regenerate it or send it again: it would be rejected with `00404` again. Getbeel keeps its previous status, with `00404` in `sdi.error_codes`, and the app shows it as **Already issued · duplicate**. - **On a new invoice** that by mistake has the number of another one already issued in the same year: this invoice is not issued. Give it a free number (Getbeel assigns the next one) and send it. ## All codes [#all-codes] Codes and descriptions from Allegato A to the technical specifications, version 1.9.1, Appendix 1 (pp. 112–123), and from the SDI technical specifications, version 1.8.4 (file checks: 00302, 00304, 00398, 00399). Code 00448 concerns the dati fattura communications (Appendix 2), not e-invoices, and is not listed. SDI's messages are shortened; the number before a field name (for example 1.4.1.1.2) is its position in the FatturaPA layout. ### File name, size and signature [#file-name-size-and-signature] Getbeel generates the file name and the XML and does not sign invoices (SDI accepts unsigned files), so these codes only come from files prepared elsewhere. | Code | SDI message | Cause | How to fix | | ------- | ---------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `00001` | Nome file non valido | The file name does not follow `IT_.xml` | Rename the file to the scheme (Getbeel does it for you) | | `00002` | Nome file duplicato | A file with the same name was already sent to SDI, even if rejected | Resend under a new file name (a new progressive) | | `00003` | File larger than allowed | The file exceeds the limit of the transmission channel | Make the file smaller, for example the attachments, or split the batch | | `00100` | Certificato di firma scaduto | The file is signed with an expired certificate | Sign with a valid certificate, or send the file unsigned | | `00101` | Certificato di firma revocato | The signing certificate was revoked | As above | | `00102` | Electronic signature not valid | The file was changed after it was signed | Sign the final file again, or send it unsigned | | `00103` | Signature without time reference | Qualified signature without a time reference | Sign with a time reference, or send unsigned | | `00104` | The CA is not in the list of trusted CAs | Certificate issued by an unrecognised authority | Use a certificate from an accredited CA, or send unsigned | | `00105` | Signature time reference after receipt | The signing date is in the future relative to the send | Fix the signer's clock and sign again | | `00106` | Compressed file empty or unreadable | Empty or damaged ZIP archive | Rebuild the archive and resend | | `00107` | Certificato di firma non valido | Certificate invalid for other reasons | Sign with a valid certificate, or send unsigned | ### Format [#format] | Code | SDI message | Cause | How to fix | | ------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `00200` | File non conforme al formato | The XML does not match the FatturaPA XSD; the message names the exact point | Fix the field named; validate first with `POST /invoices/validate` | | `00201` | More than the maximum number of format errors (50) | Too many format errors: the receipt does not list them all | Validate the XML with `POST /invoices/validate` and fix every error | | `00428` | `FormatoTrasmissione` not consistent with the `versione` attribute | For example `FPR12` in `FormatoTrasmissione` with `versione="FPA12"` | Use the same value in both: `FPR12` for businesses and consumers, `FPA12` for public administrations | ### Tax identifiers and recipient [#tax-identifiers-and-recipient] | Code | SDI message | Cause | How to fix | | ------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `00300` | 1.1.1.2 `IdCodice` (transmitter) not valid | The transmitter's tax code is not in the Anagrafe Tributaria | Fix the transmitter identifier (with Getbeel it is the transmission channel: contact support) | | `00301` | 1.2.1.1.2 `IdCodice` (supplier) not valid | The issuer's partita IVA is not in the Anagrafe Tributaria | Check the partita IVA in Settings → Company | | `00302` | 1.2.1.2 `CodiceFiscale` (supplier) non valido | The issuer's codice fiscale is not in the Anagrafe Tributaria | Correct the codice fiscale in Settings → Company and resend | | `00303` | 1.3.1.1.2 or 1.4.4.1.2 `IdCodice` (fiscal representative) not valid | The fiscal representative's partita IVA does not exist | Fix the fiscal representative's partita IVA | | `00304` | 1.3.1.2 `CodiceFiscale` (rappresentante fiscale) non valido | The fiscal representative's codice fiscale is not in the Anagrafe Tributaria | Correct the fiscal representative's codice fiscale and resend | | `00305` | 1.4.1.1.2 `IdCodice` (customer) not valid | The customer's partita IVA is not in the Anagrafe Tributaria | Check the customer's partita IVA (for example with the Agenzia's service or VIES) and fix it | | `00306` | 1.4.1.2 `CodiceFiscale` (customer) not valid | The customer's codice fiscale does not exist (checked only when there is no partita IVA) | Fix the customer's codice fiscale | | `00311` | 1.1.4 `CodiceDestinatario` not valid | The codice destinatario does not exist | Ask the customer for the right code, or use `0000000` with or without their PEC (the invoice will go to their cassetto fiscale) | | `00312` | 1.1.4 `CodiceDestinatario` not active | The channel of the codice destinatario is switched off | As above | | `00313` | `CodiceDestinatario` `XXXXXXX` only for non-residents | `XXXXXXX` used for an Italian customer or without a foreign `IdFiscaleIVA` | For an Italian customer use their code or `0000000`; `XXXXXXX` only with `IdPaese` other than `IT` | | `00320` | Supplier `IdFiscaleIVA` and `CodiceFiscale` not consistent | The issuer's partita IVA and codice fiscale belong to different subjects | Fix one of them in the company profile | | `00321` | Supplier `CodiceFiscale` of a subject outside the VAT group | With a VAT group partita IVA, the codice fiscale is not a group member's | Use the codice fiscale of the member company that issues | | `00322` | Supplier `CodiceFiscale` missing with a VAT group `IdFiscaleIVA` | Group partita IVA without the member's codice fiscale | Add the member company's codice fiscale | | `00323` | Supplier `IdCodice` of a partita IVA closed more than 5 years ago | The supplier's partita IVA closed more than 5 years ago (in autofatture the supplier is the foreign seller) | Check the supplier's partita IVA and use the active one | | `00324` | Customer `IdFiscaleIVA` and `CodiceFiscale` not consistent | The customer's partita IVA and codice fiscale belong to different subjects | Fix one of them in the customer data | | `00325` | Customer `CodiceFiscale` of a subject outside the VAT group | Customer with a group partita IVA and the codice fiscale of a non-member | Use the codice fiscale of the group company that buys | | `00326` | Customer `CodiceFiscale` missing with a VAT group `IdFiscaleIVA` | Customer's group partita IVA without the member's codice fiscale | Add the member company's codice fiscale | | `00327` | Customer `CodiceFiscale` of a VAT group, not of a member | Without a partita IVA, the VAT group's codice fiscale is given instead of a member's | Use the codice fiscale of the member company | | `00330` | `PECDestinatario` with a value not allowed | The PEC given is one of SDI's own mailboxes | Give the customer's PEC | | `00398` | Codice Ufficio not identifiable in IPA with the "Centrale" office `CodiceDestinatario` | Invoice to a public administration sent to its "Centrale" office code when SDI cannot tell which of its offices receives it | Use the recipient office's unique code given by the administration (IPA, indicepa.gov.it) and resend | | `00399` | `CessionarioCommittente` in IPA with `FormatoTrasmissione` `FPR12` | The customer is a public administration but the invoice uses the business-to-business format | Issue it in the PA format (`FPA12`) with the office's unique code and resend | | `00417` | Customer `IdFiscaleIVA` and `CodiceFiscale` both missing | The customer has neither a partita IVA nor a codice fiscale | Give at least one of them | | `00427` | `CodiceDestinatario` length not consistent with `FormatoTrasmissione` | 7 characters with `FPA12`, or 6 with `FPR12` | Businesses and consumers: 7-character code with `FPR12`. Public administrations: 6-character office code with `FPA12` | ### Content and calculations [#content-and-calculations] | Code | SDI message | Cause | How to fix | | ------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `00400` | `Natura` missing with zero `AliquotaIVA` (lines) | A zero-VAT line without a natura | Give the line's [natura](/en/api/reference-data/natura) | | `00401` | `Natura` present with non-zero `AliquotaIVA` (lines) | A natura on a line with VAT | Remove the natura (allowed only with `TD16`) | | `00403` | 2.1.1.3 `Data` after the date of receipt | The invoice date is in the future | Use today's date or an earlier one | | `00411` | `DatiRitenuta` missing with lines subject to withholding | A line has `Ritenuta` = `SI` but the withholding block is missing | Add the withholding (type, rate, amount, reason) | | `00413` | `Natura` missing with zero rate on the pension fund contribution | Zero-VAT contribution without a natura | Give the contribution's natura | | `00414` | `Natura` present with non-zero rate on the pension fund contribution | Contribution with VAT and a natura | Remove the natura from the contribution | | `00415` | `DatiRitenuta` missing with a contribution subject to withholding | Contribution with `Ritenuta` = `SI` and no withholding block | Add the withholding | | `00418` | 2.1.1.3 `Data` before the linked document's date | For example a credit note dated before the invoice it corrects | Use a date on or after the linked document's | | `00419` | `DatiRiepilogo` missing for a VAT rate in the invoice | A rate of the lines or the contribution has no summary | Add a summary for every rate | | `00420` | Natura `N6.x` with VAT chargeability `S` (split payment) | Reverse charge and split payment together | Pick one: with natura N6 the chargeability cannot be `S` | | `00421` | 2.2.2.6 `Imposta` not calculated by the rules | `Imposta` ≠ `ImponibileImporto` × `AliquotaIVA` / 100, rounded to 2 decimals (1 cent tolerance) | Recalculate the tax of each summary | | `00422` | 2.2.2.5 `ImponibileImporto` not calculated by the rules | The summary's taxable amount is not the sum of the lines, contributions and roundings at that rate (1 euro tolerance) | Sum the lines per rate | | `00423` | 2.2.1.11 `PrezzoTotale` not calculated by the rules | Line total ≠ (unit price ± discounts) × quantity (1 cent tolerance) | Recalculate the line total | | `00424` | `AliquotaIVA` not expressed as a percentage | Rate written as `0.22` | Write `22.00` | | `00425` | 2.1.1.4 `Numero` without digits | The invoice number has no digits | The number must contain at least one digit | | `00429` | `Natura` missing with zero `AliquotaIVA` (summary) | Zero-VAT summary without a natura | Give the natura in the summary | | `00430` | `Natura` present with non-zero `AliquotaIVA` (summary) | A natura in a summary with VAT | Remove the natura (allowed only with `TD16`) | | `00437` | Document discount or surcharge without percentage or amount | The discount type is given but not how much | Give the percentage or the amount | | `00438` | Line discount or surcharge without percentage or amount | As above, on a line | Give the percentage or the amount | | `00443` | Line VAT rates missing from the summary | A rate of the lines or the contribution is missing from the summaries | Add the summary for that rate | | `00444` | Line natura values missing from the summary | A natura of the lines or the contribution is missing from the summaries | Add the summary for that natura | | `00445` | Generic natura `N2`, `N3` or `N6` no longer allowed | A "parent" natura code (invalid since 2021) | Use the sub-code, for example `N2.2` | | `00460` | Amount above the simplified invoice limit | Simplified invoice over 400 euro (except `RF19`, `RF20` or corrections) | Issue an ordinary invoice (`TD01`) | | `00471` | For this document type supplier and customer must differ | The same subject as supplier and customer with `TD01`, `TD02`, `TD03`, `TD06`, `TD16`–`TD20`, `TD24`, `TD25`, `TD28`, `TD29` (or `TD07`) | Fix the customer, or use the right document type (for example `TD27` for self-consumption) | | `00472` | For this document type supplier and customer must be the same | `TD21` or `TD27` with a customer other than the supplier | Put yourself as the customer, or change the document type | | `00473` | Supplier country not allowed for this document type | `TD17`, `TD18`, `TD19` or `TD28` with an Italian supplier, or `TD29` with a foreign one | Put the foreign seller as supplier (or `IT` for `TD29`); an Italian supplier needs no autofattura | | `00474` | No zero-rate lines allowed for this document type | Splafonamento autofattura (`TD21`) with zero-VAT lines | Every line needs a non-zero rate | | `00475` | This document type needs the customer's partita IVA | `TD16`–`TD20`, `TD22`, `TD23`, `TD28` or `TD29` without the customer's `IdFiscaleIVA` | Give the customer's partita IVA | | `00476` | Supplier and customer both with a country other than `IT` | An invoice between two foreign parties | At least one must have `IdPaese` `IT`; an invoice between foreign parties does not go through SDI | | `00477` | Art. 8(1)(c) non-taxable with an invalidated declaration of intent | The dichiarazione d'intento cited was invalidated by the Agenzia | Charge VAT, or ask the customer for a valid declaration of intent | ### Uniqueness [#uniqueness] | Code | SDI message | Cause | How to fix | | ------- | --------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `00404` | Fattura duplicata | SDI already accepted a document with the same supplier (or customer for autofatture), year and number | On an invoice already sent: **it is issued, do not regenerate or resend it** (see above). On a new invoice: use a free number | | `00409` | Fattura duplicata nel lotto | Two invoices with the same number and year in the same file | Give every invoice in the batch its own number | Sources: Agenzia delle Entrate, [Allegato A, Specifiche tecniche version 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) (31 March 2026), Appendix 1 "Elenco dei codici errore relativi alla fattura ordinaria e a quella semplificata", pp. 112–123 (uniqueness: pp. 122–123); [SDI technical specifications version 1.8.4](https://www.fatturapa.gov.it/export/documenti/Specifiche-tecniche-relative-al-Sistema-di-Interscambio-versione-1.8.4.pdf) (31 March 2026), file checks; [SDI documentation on fatturapa.gov.it](https://www.fatturapa.gov.it/it/norme-e-regole/DocumentazioneSDI/); [La fattura elettronica e i servizi gratuiti](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guida_fattura_elettronica_dicembre_2025), December 2025, pp. 16–18; circolare 13/E of 2 July 2018, § 1.6 (resend within 5 days with the same date and number). Causes and fixes explain the official descriptions; messages are shortened. # Tipo documento (TD) (https://docs.getbeel.com/en/api/reference-data/tipo-documento) The tipo_documento values FatturaPA allows, from TD01 to TD29. `tipo_documento` maps to the FatturaPA field `2.1.1.1 TipoDocumento`. Descriptions are the official Italian ones, with an English gloss. ## Ordinary invoice [#ordinary-invoice] | Code | Official description | In English | | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `TD01` | Fattura | Invoice. The normal case | | `TD02` | Acconto/anticipo su fattura | Advance payment on an invoice | | `TD03` | Acconto/anticipo su parcella | Advance payment on a professional fee note | | `TD04` | Nota di credito | Credit note | | `TD05` | Nota di debito | Debit note | | `TD06` | Parcella | Professional fee note | | `TD16` | Integrazione fattura reverse charge interno | Self-billing, domestic reverse charge | | `TD17` | Integrazione/autofattura per acquisto servizi dall'estero | Self-billing, services bought from abroad | | `TD18` | Integrazione per acquisto di beni intracomunitari | Self-billing, goods bought in the EU | | `TD19` | Integrazione/autofattura per acquisto di beni ex art. 17 c. 2 DPR 633/72 | Self-billing, goods from non-resident suppliers | | `TD20` | Autofattura per regolarizzazione e integrazione delle fatture (ex art. 6 c. 9-bis D.Lgs. 471/97 o art. 46 c. 5 D.L. 331/93) | Self-billing to correct or complete invoices | | `TD21` | Autofattura per splafonamento | Self-billing for exceeding the VAT-free ceiling (seller and buyer are the same) | | `TD22` | Estrazione beni da Deposito IVA | Goods taken out of a VAT warehouse | | `TD23` | Estrazione beni da Deposito IVA con versamento dell'IVA | Same, with VAT paid | | `TD24` | Fattura differita di cui all'art. 21, comma 4, lett. a) | Deferred invoice for goods with delivery notes or documented services | | `TD25` | Fattura differita di cui all'art. 21, comma 4, terzo periodo lett. b) | Deferred invoice for triangular sales | | `TD26` | Cessione di beni ammortizzabili e per passaggi interni (ex art. 36 DPR 633/72) | Sale of depreciable assets and internal transfers | | `TD27` | Fattura per autoconsumo o per cessioni gratuite senza rivalsa | Own use or free supplies (seller and buyer are the same) | | `TD28` | Acquisti da San Marino con IVA (fattura cartacea) | Purchases from San Marino with VAT (paper invoice) | | `TD29` | Comunicazione per omessa o irregolare fatturazione (art. 6, comma 8, D.Lgs. 471/97) | Report of a missing or irregular invoice. Since spec version 1.9 | Codes `TD07` to `TD15` are not used in the ordinary invoice. ## Simplified invoice [#simplified-invoice] | Code | Official description | In English | | ------ | ---------------------------- | ---------------------- | | `TD07` | Fattura semplificata | Simplified invoice | | `TD08` | Nota di credito semplificata | Simplified credit note | | `TD09` | Nota di debito semplificata | Simplified debit note | ## SDI checks tied to the document type [#sdi-checks-tied-to-the-document-type] - `00471`: for `TD01`, `TD02`, `TD03`, `TD06`, `TD16`–`TD20`, `TD24`, `TD25`, `TD28`, `TD29` (and `TD07`) seller and buyer must be different parties. - `00472`: for `TD21` and `TD27` seller and buyer must be the same. - `00473`: `TD17`, `TD18`, `TD19` and `TD28` do not allow an Italian seller; `TD29` requires an Italian seller. - `00475`: `TD16`–`TD20`, `TD22`, `TD23`, `TD28` and `TD29` require the buyer's VAT number. Details in [SDI rejection codes](/en/api/reference-data/sdi-errors). Source: Agenzia delle Entrate, FatturaPA format technical specifications version 1.4 and Allegato A technical specifications version 1.9 (31 January 2025). # API reference (https://docs.getbeel.com/en/api/reference) Every endpoint, generated from the OpenAPI document, with the playground. These pages are generated from the API's OpenAPI 3.1 document, so they always match the code. Download the document from [`/openapi.json`](https://docs.getbeel.com/openapi.json) to generate clients and SDKs. ## Playground [#playground] Every page has a playground to try the request from your browser. Requests go through a proxy on this site, which only forwards to the Getbeel API and does not log bodies. In the `Authorization` field enter `Bearer gb_test_…`. The playground runs in your browser: don't paste a live key into it. ## Conventions [#conventions] - Base URL: `https://www.getbeel.com/api/v1`. - Authentication: [API key](/en/api/authentication) in the `Authorization` header. - Errors: [common shape](/en/api/errors) `{ "error": { type, code, message, param } }`. - Lists: [cursor pagination](/en/api/pagination). - `POST` requests that create or send: [`Idempotency-Key`](/en/api/idempotency) header. # Reports and export for the accountant (https://docs.getbeel.com/en/api/reports) Profit and loss, cash flow and receivables aging from the data in Getbeel, and the ZIP with XML, VAT journal and registers for the accountant. Getbeel computes three **management reports** from the invoices and bank movements it already has, and builds a **ZIP for the accountant** with the XML e-invoices, the VAT journal (prima nota IVA) and the VAT registers. They are the same sections as the app's **Taxes → VAT and reports**. Scope: `taxes:read`. The export carries every invoice and bank movement of the period, so it also needs `invoices:read`, `received_invoices:read` and `bank:read`. The reports are not the statutory financial statements (bilancio, artt. 2423 ff. c.c.): amounts net of VAT, without accruals and deferrals, depreciation, payroll, inventory or taxes. `management_figures` is always `true` and `reliable` always `false`: show them as figures to check with the accountant. ## Reports [#reports] ```bash curl "https://www.getbeel.com/api/v1/companies/me/reports/profit-and-loss?period=2026" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `GET /companies/me/reports/{type}`: `type` is `profit-and-loss`, `cash-flow` or `aging`. `period` is a year (`2026`), a quarter (`2026-Q3`) or a month (`2026-10`); or send `from` and `to` (at most two years). Without either, the current year. The response has `object: "report"`, `type`, `period`, `start`, `end`, `currency: "EUR"`, a `note` and one of `profit_and_loss`, `cash_flow` and `aging`. Amounts are decimal strings (`"1234.50"`). ### Profit and loss (`profit-and-loss`) [#profit-and-loss-profit-and-loss] - **Revenue**: issued invoices accepted by SDI (delivered or not delivered), by document date. The amount is the taxable amount of `DatiRiepilogo` (cassa previdenziale included, VAT and stamp duty excluded), as in the [VAT registers](/en/api/vat-registers). Credit notes (TD04, TD08) subtract. - **Costs**: reviewed supplier invoices, by document date, net of VAT (in euros, or converted for other currencies), split by `category`. Credit notes subtract. - **Competence**: art. 2423-bis, c. 1, n. 3 c.c. (income and charges count in the year they belong to, "indipendentemente dalla data dell'incasso o del pagamento"). The document date stands in for the competence date: it is the date of the operation for an immediate invoice (art. 21, c. 4 DPR 633/1972) and the end of the month for a deferred one (TD24, TD25). A service spanning two periods is not split. - **Not revenue**: TD16–TD19 and TD28 (reverse-charge integrations: VAT only, the cost is the supplier's invoice), TD20 (regularisation self-invoice: a cost), TD21–TD23 (splafonamento, VAT warehouse: VAT only), TD26 (sale of a fixed asset: the gain is income, which needs the book value), TD27 (self-supply and free supplies), TD29. - `not_included` lists what is left out: invoices still at SDI, supplier invoices to review, TD26 sales, foreign-currency documents without a rate. - `by_month` gives revenue, costs and result for each month. Non-deductible VAT, which is a cost in the accounts, is not known to Getbeel and is not added. ### Cash flow (`cash-flow`) [#cash-flow-cash-flow] Money in and out of the accounts in Getbeel (uploaded statements and connected banks) by booking date, month by month. Outflows matched to a supplier invoice (approved match) are grouped by its category, the rest under `unmatched`. `invoice_payments_recorded` reports payments recorded on issued invoices (app, Stripe, API): shown apart, never added to the bank movements. ### Receivables aging (`aging`) [#receivables-aging-aging] What customers still owe **today** on issued invoices, by days past the due date: `not_due`, `overdue_1_30`, `overdue_31_60`, `overdue_61_90`, `overdue_over_90`. `period`, `from` and `to` are not used. - Outstanding = document total less the ritenuta withheld by the customer and the credit notes issued (the `ImportoPagamento`), less the VAT of split-payment invoices, which the public body pays to the State (art. 17-ter DPR 633/1972), less the payments recorded. - No due date on the invoice: 30 days after the invoice date (art. 4, c. 2, lett. a, D.Lgs. 231/2002, "trenta giorni dalla data di ricevimento da parte del debitore della fattura"; the invoice date stands in for the date of receipt). Those rows have `due_date_assumed: true`. - `customers` sums per customer; `invoices` lists the invoices, most overdue first (at most 1,000, then `has_more`). ## Export for the accountant [#export-for-the-accountant] ```bash curl -o export.zip "https://www.getbeel.com/api/v1/companies/me/accountant-export?period=2026-Q3" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `period` is a year, a quarter or a month. Italian companies only. The ZIP contains: | Folder or file | Content | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fatture-emesse/` | FatturaPA XML of the issued invoices accepted by or pending at SDI, as transmitted (SDI file name) | | `fatture-ricevute/` | XML of the supplier invoices of the period (by document or receipt date), as received from SDI or attached; PDFs and images in `altri-documenti/` | | `autofatture/` | XML of the TD16–TD19 self-invoices Getbeel sent | | `prima-nota-iva.csv` | One line per document and VAT rate or natura: register, dates, number, document type, counterparty, `AliquotaIVA`, `Natura`, `ImponibileImporto`, `Imposta`, total, status, XML file name | | `registri-iva/` | Sales and purchase VAT registers of each settlement period (CSV), when the company charges VAT | | `banca/movimenti-bancari.csv` | The bank movements of the period with the matched invoice | | `LEGGIMI.txt` | What is inside, and any file that could not be read | CSVs use semicolons, decimal commas and UTF-8 with BOM, so Excel opens them as is. **Accounting software formats.** Italian accounting packages (TeamSystem, Zucchetti, Profis by Sistemi and others) import e-invoices from the FatturaPA XML files (technical specifications, Allegato A v1.9.1): the one format they all share. None of the three publishes the layout of its journal import, so Getbeel does not produce a proprietary format and does not guess one. A period with more than 3,000 files or 250 MB answers `422 too_many_documents`: ask for a quarter or a month. ## MCP and SDKs [#mcp-and-sdks] - MCP: `get_report` with `type` and `period` (or `from`/`to`). The ZIP export is not an MCP tool: it is a binary file. - TypeScript SDK: `getbeel.taxes.report('profit-and-loss', { period: '2026' })`, `getbeel.taxes.accountantExport('2026-Q3')` (a `Blob`). - Python SDK: `client.taxes.report("aging")`, `client.taxes.accountant_export("2026-Q3")` (bytes). - CLI: `getbeel taxes report --type cash-flow --period 2026-Q3`. # Sandbox (https://docs.getbeel.com/en/api/sandbox) Test keys send to an SDI simulated by getbeel. Here is how to trigger every outcome. With a test key (`gb_test_…`), `POST /invoices/{id}/send` contacts neither SDI nor the transmission channel: getbeel generates and validates the XML as for a real send, gives it a simulated 12-digit SDI identifier and a file name, and a few seconds later applies an outcome with the matching [webhooks](/en/api/webhooks). The sandbox is free and uses no SDI quota; only the [rate limit](/en/api/rate-limits) applies. ## How to trigger each outcome [#how-to-trigger-each-outcome] The outcome depends on the customer data, checked in this order: | Outcome | How to trigger it | Status | `sdi` | Webhook | | ------------- | ----------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------ | ----------------------- | | Rejected | Customer partita IVA `00000000000` (with or without a leading `IT`, spaces ignored) | `rejected` | `error_codes: ["00305"]`, `errors: [{ "code": "00305", "description": null }]` | `invoice.rejected` | | Not delivered | Codice destinatario `MC00000` (any case) and any other partita IVA | `not_delivered` | `available_since: null` | `invoice.not_delivered` | | Delivered | Any other valid invoice | `delivered` | — | `invoice.delivered` | - The send answers `200` with `status: "sent"` and the `invoice.sent` webhook. The outcome follows about 3 seconds later; if it ever does not, a periodic job applies it within a few minutes. Read the invoice again with `GET /invoices/{id}`. - **The simulated rejection uses code `00305`** (IdCodice of the cessionario not valid), with the message `00305 1.4.1.1.2 non valido (sandbox: partita IVA 00000000000 is always rejected)`, and the invoice goes to `rejected` like a real rejection. `00404` is not simulated: on an invoice already sent it means it is **already issued**, see [SDI lifecycle](/en/api/sdi-lifecycle#duplicate-of-an-issued-invoice-00404-on-a-sent-invoice). - **The simulated non-delivery has no date**: `sdi.available_since` is `null`. In real life an MC carries the date the invoice was made available in the cassetto fiscale; your code must handle both. - An invoice that fails local validation is not sent: the request answers `422 invoice_invalid` and the invoice stays a draft. - A rejected test invoice is reopened like a live one: `POST /invoices/{id}/reopen`, correct it with `PATCH /invoices/{id}` (for example a real partita IVA instead of `00000000000`) and send it again. ## Test and live compared [#test-and-live-compared] | | Test (`gb_test_`) | Live (`gb_live_`) | | ------------ | ---------------------------- | ------------------------------------------------------- | | Endpoints | The same | The same | | Sending | SDI simulated by getbeel | Real SDI, through an accredited transmission provider | | Response | `200`, `sent` | `202`, `sending` | | Outcome | Decided by the customer data | Decided by SDI, minutes up to 5 days | | Legal effect | None | The invoice is issued (when delivered or not delivered) | | Cost | Free, no quota | Per the [rate card](/en/api/pricing) | ## The transmission channel's sandbox [#the-transmission-channels-sandbox] This is something else: the test environment of the transmission provider (openapi.com) that getbeel uses internally to test the channel. **A getbeel test key never reaches it.** We describe it because it explains which outcomes getbeel could test against a real channel (tested on 9 November 2026): - outgoing invoices and autofatture go to SENT, then DONE/DELIVERED a few minutes apart, even with codice destinatario `0000000`; - it never produces an MC: openapi.com documents a simulation only for incoming invoices (`POST /IT-invoices_supplier_simulate`, Invoice API 1.8.7); - it has no duplicate check: the same file sent twice is delivered twice, so `00404` never comes from there. That is why MC and `00404` are tested by replaying recorded receipts into getbeel's webhook. ## Test received invoices [#test-received-invoices] `POST /sandbox/inbound-invoices` receives an invoice as if it came from SDI (your XML or a sample addressed to your company): it shows in `GET /received-invoices` with the test key (`source: "sdi"`) and sends `received_invoice.created` to test endpoints. See [Receiving from SDI](/en/api/sdi-receiving#sandbox). # SDI lifecycle (https://docs.getbeel.com/en/api/sdi-lifecycle) The statuses of an issued invoice, what each SDI outcome means and what to do. An issued invoice moves through a few statuses, always forward. The status tells you whether the invoice **is issued**: something to know before you send it again, because an issued invoice is never resent. ## Statuses [#statuses] | `status` | Meaning | Issued? | | --------------- | ------------------------------------------------------------------------------------ | ------------- | | `draft` | Draft, editable | No | | `sending` | The XML is being prepared and the send is queued (live keys only) | No, not yet | | `sent` | Transmitted to SDI, waiting for the outcome (minutes, up to 5 days) | Pending | | `delivered` | Ricevuta di consegna (RC) | **Yes** | | `not_delivered` | Ricevuta di impossibilità di recapito (MC): it is in the customer's cassetto fiscale | **Yes** | | `rejected` | Ricevuta di scarto (NS) | **No**, never | ```text draft → sending → sent → not_delivered → delivered → rejected ``` Transitions only move forward, in this order. A receipt that arrives late or twice never moves an invoice back: a `sent` that arrives after a `delivered` is ignored. `not_delivered` can still become `delivered`, and a delivered invoice can still become `rejected` when a public administration refuses it. SDI dates without a time zone are read as Italian time (Europe/Rome). With a test key, `POST /invoices/{id}/send` answers at once with `sent` and the outcome follows a few seconds later from the [sandbox](/en/api/sandbox). With a live key it answers `202` with `sending`. ## Each outcome [#each-outcome] ### Delivered (RC) → `delivered` [#delivered-rc--delivered] SDI delivered the invoice to the customer's indirizzo telematico. The invoice is issued and the VAT becomes chargeable on the invoice date. ### Not delivered (MC) → `not_delivered` [#not-delivered-mc--not_delivered] SDI ran its checks but could not deliver the file: the customer's channel was not active, or the codice destinatario was `0000000` with no registered address. It put the invoice in the customer's reserved area in "Fatture e Corrispettivi" (the cassetto fiscale), from the date in `sdi.available_since`. ![A not delivered invoice (MC): it counts as issued, is in the cassetto fiscale from the date shown and must not be sent again.](/screenshots/invoice-not-delivered.en.webp) - **The invoice is issued.** Do not send it again: SDI would reject the copy as a duplicate (`00404`). - Tell the customer another way (email, phone) that it is in their reserved area; for them the VAT is deductible from when they view it. An email courtesy copy ([`POST /invoices/{id}/email`](/en/api/invoice-collection)) helps. - For the next invoices, ask for their codice destinatario or PEC. - For an autofattura (TD16–TD19) the recipient is your own company: you find it in your cassetto fiscale. To receive them directly, register an indirizzo telematico in "Fatture e Corrispettivi" (see [codice destinatario](/en/guide/codice-destinatario)). ### Rejected (NS) → `rejected` [#rejected-ns--rejected] One or more SDI checks failed. **The invoice counts as never issued.** ![An invoice rejected by SDI: the error code, its description, the resend rule and the Correct and resend button.](/screenshots/invoice-rejected.en.webp) - `sdi.errors` lists the codes with SDI's description; `sdi.error_codes` only the codes. What each code means and how to fix it: [SDI rejection codes](/en/api/reference-data/sdi-errors). - Correct it and send it again **with the same number and date**, preferably within 5 days of the rejection. The new submission has a new file name, and SDI does not treat it as a duplicate because the first one was rejected. - Reopen, correct, resend: 1. `POST /invoices/{id}/reopen` puts it back to `draft` with the same number and date (in the app: **Correct and resend**; in MCP: `reopen_rejected_invoice`). `sdi.errors` stays on it until it is sent again. 2. `PATCH /invoices/{id}` fixes what `sdi.errors` says ([Invoicing](/en/api/invoicing#edit-a-draft); MCP `update_invoice_draft`). 3. `POST /invoices/{id}/send` sends it again, with an `Idempotency-Key` so a retry does not count twice. Any other status answers `409 invoice_not_rejected`. Test keys reopen sandbox rejections the same way. ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE/reopen \ -H "Authorization: Bearer $GETBEEL_API_KEY" curl -X PATCH https://www.getbeel.com/api/v1/invoices/$INVOICE \ -H "Authorization: Bearer $GETBEEL_API_KEY" -H "Content-Type: application/json" \ -d '{"customer": {"denominazione": "Rossi S.r.l.", "partita_iva": "01234567890", "codice_destinatario": "M5UXCR1", "address": "Via Roma 1", "postal_code": "20121", "city": "Milano", "province": "MI"}}' curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE/send \ -H "Authorization: Bearer $GETBEEL_API_KEY" -H "Idempotency-Key: $(uuidgen)" ``` - A public administration's refusal after delivery (notifica di esito) also shows as `rejected` today, but it is not an SDI rejection: the invoice had been delivered. Do not apply the resend rule then; ask your accountant how to correct it. - For live invoices, getbeel may try to fix the XML itself and resend it (at most 3 times): the invoice goes back to `sent` with a new submission, or back to draft for a manual fix. ### Duplicate of an issued invoice (`00404` on a sent invoice) [#duplicate-of-an-issued-invoice-00404-on-a-sent-invoice] SDI rejects with `00404` ("Fattura duplicata") a file with the same supplier, year and number as a document it already accepted. When this happens to an invoice that was sent, SDI **already accepted an earlier copy: the invoice is issued**. ![An invoice rejected as a duplicate (00404) of an accepted copy: it counts as already issued and stays locked.](/screenshots/invoice-duplicate.en.webp) - getbeel does not move it to `rejected`: it stays `sent` (or whatever status it had), with `00404` in `sdi.error_codes` and `sdi.errors`. No webhook event. - **Do not regenerate or resend it**: every new submission would be rejected with `00404` again. - Support links the accepted submission. In the VAT registers the document counts as issued, flagged for review (`needs_review`). For autofatture TD16–TD20, TD22, TD23, TD28 and TD29 the uniqueness check is made on the cessionario (your company). ### Pending → `sent` [#pending--sent] SDI has the file and has not answered yet. Checks and delivery take from a few minutes up to 5 days when SDI is very busy. Do not resend a `sent` invoice: wait for the outcome. ## What the web app, API and MCP show [#what-the-web-app-api-and-mcp-show] | Outcome | Web (badge) | API `status` and `sdi` | MCP (`get_invoice`, `list_invoices`) | Webhook | | ------------------------- | ------------------------------------- | ---------------------------------------- | ------------------------------------------- | ----------------------- | | Being prepared | Sending to SDI... | `sending` | The same JSON as the API | — | | Pending | Sent to SDI | `sent` | As the API | `invoice.sent` | | RC | Delivered | `delivered` | As the API | `invoice.delivered` | | MC | Issued · in cassetto fiscale | `not_delivered`, `sdi.available_since` | As the API: "issued, never resend" | `invoice.not_delivered` | | NS | Rejected, with **Correct and resend** | `rejected`, `sdi.errors` | As the API: "fix sdi.errors and resend" | `invoice.rejected` | | `00404` on a sent invoice | Already issued · duplicate (locked) | `sent` with `00404` in `sdi.error_codes` | As the API: "already issued, do not resend" | — | ![The issued invoices list with each invoice's SDI status: draft, sent, delivered, issued in cassetto fiscale, rejected, already issued (duplicate).](/screenshots/issued-invoices.en.webp) - **Web.** The invoice detail explains the outcome with the official sources: for MC the date it was made available and "Do not send it again"; for NS the codes with their description and the resend rule; for `00404` "Already issued: SDI holds an accepted copy". - **API.** `GET /invoices/{id}` and `GET /invoices?status=…` (see the [reference](/en/api/reference)). - **MCP.** The `list_invoices` and `get_invoice` tools return the same JSON, and their descriptions explain every status to the assistant, so it never offers to resend an issued invoice. Example: [MCP server](/en/api/mcp#examples). ## Webhooks [#webhooks] Every status change sends an [event](/en/api/webhooks) with the full invoice in `data.object`: | Event | New status | | ----------------------- | --------------- | | `invoice.sent` | `sent` | | `invoice.delivered` | `delivered` | | `invoice.not_delivered` | `not_delivered` | | `invoice.rejected` | `rejected` | One event per transition: a duplicate or late receipt does not produce another. A `00404` on an issued invoice changes no status and sends no event. Read the invoice again with `GET /invoices/{id}` when you need its current state. ## Sending twice never creates a duplicate [#sending-twice-never-creates-a-duplicate] - **`Idempotency-Key`.** Repeating `POST /invoices/{id}/send` with the same key returns the first response without a second send ([Idempotency](/en/api/idempotency)). - **One send per draft.** A send claims the draft atomically: a second request, even without a key, gets `409 invoice_send_in_progress` or `409 invoice_not_draft` before any call to SDI. - **Ambiguous outcomes.** When a send ends without a clear answer (timeout, 5xx, network error), getbeel looks the document up at the transmission channel before trying again: if SDI already received it, getbeel records its identifier instead of sending it again. - Autofatture follow the same rule: a send claims the document atomically, and the channel is looked up only after an ambiguous outcome. ## Sources [#sources] - Agenzia delle Entrate, [La fattura elettronica e i servizi gratuiti](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guida_fattura_elettronica_dicembre_2025), December 2025: p. 16 (SDI checks, duplicates, up to 5 days), p. 17 (ricevuta di scarto, resend with the same date and number and a new file name; ricevuta di consegna), p. 18 (impossibilità di recapito, date made available, issued for the supplier, a rejection means never issued), pp. 19–20 (registering the indirizzo telematico). - Agenzia delle Entrate, [circolare 13/E of 2 July 2018](https://www.agenziaentrate.gov.it/portale/documents/20143/297470/Circolare+n+13+del+02+luglio+2018_Circolare_13_02072018.pdf/da0b0db7-64eb-ac7b-c925-4fdbc776279d), § 1.6, pp. 11–12: a rejected invoice should preferably be sent again within five days of the rejection, with the original date and number. - Agenzia delle Entrate, [Allegato A, Specifiche tecniche version 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) (31 March 2026), Appendix 1, "Verifiche di unicità della fattura", pp. 122–123: codes `00404` and `00409`, check on the cessionario for TD16–TD20, TD22, TD23, TD28, TD29. - [fatturapa.gov.it, SDI documentation](https://www.fatturapa.gov.it/it/norme-e-regole/DocumentazioneSDI/): technical specifications and list of checks. # Receiving from SDI (https://docs.getbeel.com/en/api/sdi-receiving) Receive supplier invoices from the Sistema di Interscambio, with codice destinatario, checklist and sandbox. Getbeel receives from the Sistema di Interscambio (SDI) the invoices suppliers send to your company and adds them to the received invoices, read from the XML (signed `.p7m` files too). You find them with `GET /received-invoices` and `source: "sdi"`, next to the ones collected from email, forwarding or uploads. Scopes: `received_invoices:read` to read the status, `received_invoices:write` to turn receiving on and for the sandbox. ## How it works [#how-it-works] 1. **Turn receiving on** with `POST /sdi-receiving` (or in the app, Settings → SDI receiving). It needs complete company data (`422 company_not_ready`) and the SDI add-on (`402 sdi_addon_required`). Live keys only (`403 livemode_required`). 2. The response has the **codice destinatario** to give to suppliers. 3. **Register the code as indirizzo telematico** in the Agenzia delle Entrate area (Fatture e Corrispettivi). The company does it, once: see the [guide](/en/guide/codice-destinatario). From then on every invoice reaches Getbeel, whatever code the supplier wrote. 4. Each received invoice creates a received invoice (`status: "pending_review"`, `source: "sdi"`) and sends the `received_invoice.created` webhook. If the same document was already collected from email (same supplier, number and date), Getbeel links it to the existing one instead of creating a second, and sends no new webhook. ```bash curl -X POST https://getbeel.com/api/v1/sdi-receiving \ -H "Authorization: Bearer $GETBEEL_LIVE_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` ## Status and checklist [#status-and-checklist] `GET /sdi-receiving` returns: | Field | Meaning | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `status` | `not_enabled`, `pending`, `active` or `error` (`last_error` says why) | | `codice_destinatario` | The code to give suppliers and register as indirizzo telematico | | `fiscal_id` | The P.IVA (or codice fiscale) you receive for | | `indirizzo_telematico.confirmed` | A member confirmed in the app that it is registered (Getbeel cannot check it) | | `conservazione` | The status of the [free AdE conservazione](/en/guide/conservazione): `not_activated`, `active`, `expired`, with dates | | `readiness.steps` | `company_data`, `sdi_addon`, `receiving_enabled`, `indirizzo_telematico`, `conservazione` (recommended), each with `done` | | `links` | The Fatture e Corrispettivi portal and the Agenzia's information page | A P.IVA can receive in one Getbeel workspace only: a second attempt answers `409 fiscal_id_taken`. ## Cost [#cost] Each invoice received from SDI costs €0.18 on the rate card ([pricing](/en/api/pricing)). An invoice collected from email is billed as email extraction, not SDI receiving; if the same invoice also arrives from SDI, the SDI receipt counts. ## Sandbox [#sandbox] With a test key, `POST /sandbox/inbound-invoices` receives an invoice as if it came from SDI: pass your XML (or a base64 `.p7m`) in `xml`, or send an empty body to receive a sample invoice addressed to your company. MCP: `create_sandbox_inbound_invoice`. ```bash curl -X POST https://getbeel.com/api/v1/sandbox/inbound-invoices \ -H "Authorization: Bearer $GETBEEL_TEST_KEY" ``` The invoice shows in `GET /received-invoices` with the same test key (`source: "sdi"`) and the `received_invoice.created` webhook goes to test endpoints. Nothing shows in the app. An unreadable XML answers `422 invoice_unreadable`. ## MCP [#mcp] The `get_sdi_receiving_status` tool reads the status and the checklist; `list_received_invoices` takes `source: "sdi"`. Turning receiving on stays in the app or the API: the company does the Agenzia delle Entrate registration itself. Today receiving goes through an accredited transmission provider (openapi.com): the codice destinatario is theirs. Invoices that cannot be matched to a company stay in quarantine and we check them by hand. # Python SDK (https://docs.getbeel.com/en/api/sdk-python) The official Python client, typed, with one dependency (httpx). `getbeel` covers the whole [API](/en/api/reference). It adds an `Idempotency-Key` to every `POST` that supports one, retries rate limits and server errors, raises typed errors, pages through lists and verifies webhook signatures. Python 3.9+. ```bash pip install getbeel ``` ## Create and send an invoice [#create-and-send-an-invoice] ```python from getbeel import Getbeel client = Getbeel() # reads GETBEEL_API_KEY; or Getbeel(api_key="gb_test_...") draft = client.invoices.create( tipo_documento="TD01", currency="EUR", customer={ "denominazione": "Bianchi S.p.A.", "partita_iva": "01234567890", "country": "IT", "codice_destinatario": "ABCDE12", }, lines=[{"description": "Consulting, October", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00"}], ) sent = client.invoices.send(draft["id"]) # show the draft and get an OK first ``` Responses are dicts with the fields of the [API reference](/en/api/reference). Bodies can be a dict, keyword arguments or both. The query parameter `from` is `from_`. Options: `Getbeel(api_key=None, base_url=None, company=None, timeout=60.0, max_retries=2, http_client=None)`; `base_url` defaults to `GETBEEL_BASE_URL`, then `https://www.getbeel.com/api/v1`. ## Resources [#resources] `me()`, `invoices`, `recurring_invoices`, `received_invoices`, `bank_statements` (`upload` takes a path, bytes or a file), `bank_transactions`, `reconciliations`, `unmatched`, `bank_connections`, `connections`, `companies`, `taxes` (`calendar`, `calendar_ics`, `vat_position`, `vat_registers`, `vat_settlement`, `report`, `accountant_export`), `filings` (`prepare`, `list`, `get`, `file`, `upload_receipt`). Method names follow the [TypeScript SDK](/en/api/sdk-typescript) in snake_case. ## Idempotency and errors [#idempotency-and-errors] ```python from getbeel import GetbeelError, NotFoundError client.invoices.send(draft["id"], idempotency_key=f"send-{draft['id']}") try: client.invoices.get("missing") except NotFoundError as e: print(e.code, e.message) except GetbeelError as e: print(e.status, e.type, e.code, e.param, e.request_id) ``` Every `POST` that supports idempotency gets a random `Idempotency-Key`, kept across automatic retries and returned in `e.idempotency_key` when it fails. Those `POST`s and reads are retried `max_retries` times on `408`, `429` (after `Retry-After`), `5xx`, network errors and `409 idempotency_key_in_use`; other `POST`s only on `429`. Subclasses: `InvalidRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `APIError`, `APIConnectionError`. ## Pagination and client companies [#pagination-and-client-companies] ```python for invoice in client.invoices.iter_all(status="delivered"): print(invoice["number"]) bianchi = client.with_company("COMPANY_ID") # Getbeel-Company header bianchi.invoices.list() ``` ## Webhooks [#webhooks] ```python from getbeel import webhooks, WebhookSignatureError try: event = webhooks.construct_event(raw_body, headers["Getbeel-Signature"], os.environ["GETBEEL_WEBHOOK_SECRET"]) except WebhookSignatureError: ... # answer 400 ``` `webhooks.verify(payload, header, secret)` returns `True` or `False`; signatures older than 5 minutes are refused. See [Webhooks](/en/api/webhooks). # TypeScript SDK (https://docs.getbeel.com/en/api/sdk-typescript) The official Node.js and TypeScript client, generated from the OpenAPI spec. `@getbeel/sdk` wraps the whole [API](/en/api/reference) with types generated from the OpenAPI spec. It adds an `Idempotency-Key` to every `POST` that supports one, retries rate limits and server errors, throws typed errors, pages through lists and verifies webhook signatures. ESM, no runtime dependencies: Node.js 20.19+, Deno, Bun, Cloudflare Workers and Vercel Edge. ```bash npm install @getbeel/sdk ``` ## Create and send an invoice [#create-and-send-an-invoice] ```ts import { Getbeel } from '@getbeel/sdk'; const getbeel = new Getbeel({ apiKey: process.env.GETBEEL_API_KEY }); // gb_test_… in the sandbox const draft = await getbeel.invoices.create({ tipo_documento: 'TD01', currency: 'EUR', customer: { denominazione: 'Bianchi S.p.A.', partita_iva: '01234567890', country: 'IT', codice_destinatario: 'ABCDE12', }, lines: [ { description: 'Consulting, October', quantity: '1', unit_price: '1000.00', vat_rate: '22.00', }, ], }); const sent = await getbeel.invoices.send(draft.id); // show the draft and get an OK first ``` Options: `apiKey` (default `GETBEEL_API_KEY`), `baseUrl` (default `https://www.getbeel.com/api/v1`), `company`, `maxRetries` (2), `timeoutMs` (60 000), `fetch`. ## Resources [#resources] | Property | Methods | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `me()` | Account, company, key mode and scopes | | `invoices` | `list`, `listAll`, `get`, `create`, `validate`, `send`, `email`, `listDeliveries`, `recordPayment`, `listPayments`, `createPaymentLink`, `sendReminder` | | `recurringInvoices` | `list`, `get`, `create`, `update`, `delete`, `pause`, `resume` | | `receivedInvoices` | `list`, `listAll`, `approve`, `reject` | | `bankStatements` | `upload`, `uploadFromUrl`, `list`, `listAll`, `get` | | `bankTransactions` | `list`, `listAll` | | `reconciliations` | `create`, `get`, `listMatches`, `createMatch`, `approveMatch`, `rejectMatch` | | `unmatched` | `payments`, `invoices` | | `bankConnections` | `list`, `get`, `create`, `delete`, `sync`, `reconnect` | | `connections` | `list`, `createEmail`, `scan`, `forwardingAddress`, `createStripe`, `syncStripe` | | `companies` | `list`, `get`, `create`, `update` | | `taxes` | `calendar`, `vatPosition`, `vatRegisters`, `vatSettlement`, `report`, `accountantExport` | | `filings` | `prepare`, `list`, `listAll`, `get`, `file`, `uploadReceipt` | Request and response types are exported (`Invoice`, `CreateInvoiceRequest`, `Filing`…), and all of them under `types`. ## Idempotency and retries [#idempotency-and-retries] Every `POST` that supports [idempotency](/en/api/idempotency) (creates, sends, payments, uploads, syncs) gets a random `Idempotency-Key`, the same on every automatic retry, so a retried create never creates two invoices. A failed call carries it in `error.idempotencyKey`: retry with that key, never a new one. To choose it yourself: ```ts await getbeel.invoices.send(draft.id, { idempotencyKey: `send-${draft.id}` }); ``` Reads and those `POST`s are retried twice with backoff on `408`, `429` (after `Retry-After`), `5xx`, network errors and `409 idempotency_key_in_use`. Other `POST`s (approve, reject, pause, receipt upload) are retried only on `429`, so they never act twice. ## Errors [#errors] ```ts import { GetbeelError } from '@getbeel/sdk'; try { await getbeel.invoices.get('missing'); } catch (error) { if (error instanceof GetbeelError) { console.log( error.status, error.type, error.code, error.param, error.requestId, ); } } ``` `code` is the API [error code](/en/api/errors). Network failures have `status: 0` and code `connection_error` or `timeout`. ## Pagination [#pagination] ```ts const page = await getbeel.invoices.list({ status: 'delivered', limit: 50 }); // page.data, page.has_more, page.next_cursor for await (const invoice of getbeel.invoices.listAll({ status: 'delivered' })) { console.log(invoice.number); } ``` ## Client companies [#client-companies] ```ts const client = getbeel.withCompany('COMPANY_ID'); // or new Getbeel({ company: 'COMPANY_ID' }) await client.invoices.list(); ``` Every call carries the `Getbeel-Company` header. See [Companies](/en/api/companies). ## Files [#files] ```ts import { readFile } from 'node:fs/promises'; await getbeel.bankStatements.upload({ file: await readFile('october.csv'), filename: 'october.csv', }); await getbeel.bankStatements.uploadFromUrl({ file_url: 'https://…/statement.pdf', }); // over 4.5 MB const pdf = await getbeel.filings.file('FILING_ID'); // Blob (XML for a LIPE) const registers = await getbeel.taxes.vatRegisters('2026-Q3'); const settlement = await getbeel.taxes.vatSettlement('2026-10'); const pnl = await getbeel.taxes.report('profit-and-loss', { period: '2026' }); const zip = await getbeel.taxes.accountantExport('2026-Q3'); // Blob ``` ## Webhooks [#webhooks] Verify the signature on the raw body, before parsing it: ```ts import { webhooks } from '@getbeel/sdk'; export async function POST(request: Request) { const body = await request.text(); const event = await webhooks .constructEvent( body, request.headers.get('Getbeel-Signature'), process.env.GETBEEL_WEBHOOK_SECRET!, ) .catch(() => null); if (!event) return new Response('invalid signature', { status: 400 }); if (event.type === 'invoice.delivered') { // … } return new Response('ok'); } ``` `webhooks.verify(body, header, secret)` returns `true` or `false`. Signatures older than 5 minutes are refused (`toleranceSeconds`). See [Webhooks](/en/api/webhooks). # Tax rules (https://docs.getbeel.com/en/api/tax-rules) The rule values and proroghe behind the tax calendar and estimates, with their official sources; for getbeel administrators, the proposals of the weekly rules watch. The tax calendar and the estimates follow rules that change by year or by law. getbeel keeps them **versioned by date**, each with its official source: - **rule values**: numbers such as the INPS minimale and rates of a year, the forfettario thresholds or the impatriati shares (key, value, `valid_from`, `valid_to`); - **proroghe**: a decree or an Agenzia delle Entrate communication that moves a deadline (`deadline_kind`, the legal dates it moves, `new_due_date`). A missing value is never replaced by last year's: the estimate says it is missing. Every week a **rules watch** reads the official sources (Agenzia delle Entrate news and prassi, MEF Dipartimento Finanze, Gazzetta Ufficiale, INPS circolari and messaggi) and proposes changes, each with its link and the sentence that states it. Nothing changes until a getbeel administrator approves it. When a proroga is approved, the teams whose deadlines it moves get a notice in the app, and prepared F24s not paid yet take the new date. Scopes: `taxes:read` to read. **Only getbeel administrators** change the rules, with a **live key** that has the admin-only scope `tax_rules:admin`. That key is created in the getbeel admin page and is never offered in Settings → API keys or on an MCP sign-in (`403 insufficient_scope` without it, `403 live_key_required` with a test key, `403 super_admin_required` once its creator is no longer an administrator). Every change is in the audit log. ## Read the rules in force [#read-the-rules-in-force] ```bash curl https://www.getbeel.com/api/v1/tax-rules \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `GET /v1/tax-rules` returns every rule value by date (`origin: "code"` shipped with getbeel, `"db"` added since), `coverage` (values missing in the next 13 months, and whether they are overdue) and `overrides` (the proroghe in force). `pending` and `watch_runs` are `null` unless the key belongs to a getbeel administrator. ## Add a rule value [#add-a-rule-value] ```bash curl https://www.getbeel.com/api/v1/tax-rules/values \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "key": "inps.maternity_yearly", "value": 7.5, "valid_from": "2027-01-01", "valid_to": "2027-12-31", "source_url": "https://www.inps.it/…/circolare-2027", "source_title": "INPS, circolare n. 9 del 2 febbraio 2027", "source_article": "§ 1", "status": "pending" }' ``` `POST /v1/tax-rules/values` answers `201`. `status: "active"` puts the value in force at once, only with an official source (`agenziaentrate.gov.it`, `mef.gov.it`, `finanze.gov.it`, `gazzettaufficiale.it`, `inps.it`, `normattiva.it`, `fatturapa.gov.it`; `400 official_source_required` otherwise). Two active values of a key never overlap (`409 rule_value_overlap`). An unknown key needs a release of getbeel. ## Add a proroga [#add-a-proroga] ```bash curl https://www.getbeel.com/api/v1/tax-rules/overrides \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "deadline_kind": "vat_payment", "nominal_from": "2027-06-16", "nominal_to": "2027-06-16", "new_due_date": "2027-07-21", "valid_from": "2027-06-01", "source_url": "https://www.gazzettaufficiale.it/eli/id/…", "source_title": "DPCM 1 giugno 2027, art. 1", "status": "pending" }' ``` `POST /v1/tax-rules/overrides` answers `201`. `deadline_kind: "all"` moves every tax deadline of those legal dates (never the EU OSS return or the bilancio deposit, which a proroga must name). A proroga never brings a deadline earlier. ## Approve, reject or withdraw [#approve-reject-or-withdraw] ```bash curl https://www.getbeel.com/api/v1/tax-rules/decisions \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "override", "id": "3f6c…", "decision": "approve" }' ``` `POST /v1/tax-rules/decisions` puts a pending proposal in force (`approve`) or sets it aside (`reject`); `withdraw` takes a rule in force out (a value entered wrong: withdraw it, then add the corrected one; the `id` of a value added without a deploy is in `GET /v1/tax-rules`). Withdrawing a proroga moves prepared F24s back to the legal date. Through the API only proposals with an official source can be approved, and a rules-watch proposal only when its quote was found word for word in the source (`400 quote_not_verified` for a PDF: read it and approve it in the admin page). `404 proposal_not_found` when it was already decided. The same tools exist in [MCP](/en/api/mcp): `get_tax_rules`, `add_tax_rule_value`, `add_tax_calendar_override`, `decide_tax_rule`. # Fixed assets, estimates and POS–RT (https://docs.getbeel.com/en/api/tax-tools) Fixed assets and depreciation with the libro cespiti, the tax estimate (IRES, IRAP, IRPEF, forfettario, minimi, INPS) and POS–RT links with the Agenzia delle Entrate CSV. The same features as **Tasse → Cespiti**, **Tasse → Stima imposte** and **Tasse → POS e RT**. Scope `taxes:read` to read, `taxes:write` to write; writes need a live key (`403 livemode_required`) and are free. Italian companies only (`400 taxes_not_available`). Rules and sources are in the guides: [Fixed assets](/en/guide/cespiti), [Tax estimate](/en/guide/stima-imposte), [POS and tills](/en/guide/collegamento-pos-rt). ## Fixed assets [#fixed-assets] ```bash curl -X POST "https://www.getbeel.com/api/v1/fixed-assets" \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "Notebook", "category_code": "altre.macchine_ufficio_elettroniche", "cost": "1200.00", "received_invoice_id": "", "in_service_date": "2026-03-15" }' ``` - `category_code` picks the DM 31/12/1988 coefficient (`GET /v1/fixed-asset-categories`); without it send `category_label` and `coefficient`. A coefficient above the category's answers `400 coefficient_above_maximum`. - `received_invoice_id` fills date, supplier and number from the received invoice; in the tax estimate the asset's cost leaves the year's costs. - `expense_in_full: true` deducts a tangible asset up to €516.46 in full (`400 not_a_small_asset` otherwise). - The response has `schedule` (year, `max_amount`, `amount`, accumulated, residual), `status`, `accumulated_depreciation` and `residual_value` at the end of `as_of_year`. - `PATCH /v1/fixed-assets/{id}` with `disposal_date` and `disposal_amount` records a disposal: a positive `disposal.gain` is a gain, negative a loss. `depreciation_overrides` (`{"2027": "100.00"}`) records quotas below the maximum. - `GET /v1/companies/me/fixed-assets-register?year=2026` is the year's libro cespiti with `totals`, `by_category` and `closing_entries` (summary of the year-end entries); `&format=csv` or `xlsx` returns the file. ## Tax estimate [#tax-estimate] ```bash curl "https://www.getbeel.com/api/v1/companies/me/tax-estimate?year=2026" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `reliable` is always `false` and `label` is "Stima, da verificare con il commercialista". `figures` shows what came from Getbeel (issued and received invoices, payments, depreciation); `ires`/`irap` (companies), `forfettario`, `irpef` (individuals in the ordinary regime) or `minimi` (regime di vantaggio, quadro LM lines), and `inps`; `installments` the advances and balance with F24 tax code, `due_date` and `confirmed` (`false` for dates not yet confirmed by a source in force); `warnings` what is missing. `PUT /v1/companies/me/tax-estimate` saves for the year what Getbeel cannot know (`entity`, `ateco_code` or `forfettario_group`, `inps_scheme`, `personnel_costs`, `permanent_staff_costs`, `irap_rate`, `prior_year_ires`…) and returns the recomputed estimate. Fields not sent keep their value; the next year starts from the same answers. Amounts are decimal strings (`"12000.00"`) like everywhere in the API; plain numbers are accepted too. ## POS–RT links [#posrt-links] ```bash curl -X POST "https://www.getbeel.com/api/v1/pos-rt-links" \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "rt_serial": "99IEY928374", "acquirer_id": "04107060966", "acquirer_name": "NEXI PAYMENTS S.P.A.", "pos_type": "00", "terminal_id": "54281242", "contract_number": "0840003060", "province": "MI", "municipality": "Milano", "street": "Via Roma", "street_number": "1", "postal_code": "20121", "active_from": "2026-11-02" }' ``` - `pos_type` `00` is a physical POS and needs its `terminal_id` (`400 terminal_id_required` without it); for `01`, a virtual POS, `terminal_id` is ignored and stored empty. - Each link has `status` (`to_file`, `filed`, `end_to_file`, `ended`) and `pending`: the operation to communicate (`I` or `C`) with the `from`–`due` window of AdE provvedimento 424470/2025. - After it is communicated a link cannot change (`409 link_already_filed`): `PATCH` with `ended_on` ends it, and the end becomes the next thing to communicate. - `GET /v1/pos-rt-links/export?part=1` returns the CSV (`csv`, up to 1,000 rows per part), the same rows tab-separated (`tsv`) to paste into the AdE template, `links` (id and operation of each row), which parts of the format are official and which are not (`layout`), and the portal steps (`next_steps`). `&format=csv` returns the file. - After the upload in Fatture e Corrispettivi, `POST /v1/pos-rt-links/mark-filed` with those `links` marks them communicated; a link whose pending operation changed meanwhile is left alone. - `GET /v1/pos-rt-links/{id}` reads one link. `PATCH /v1/pos-rt-links/{id}` changes it; once communicated, only `label` and `ended_on` (the last day of use, which makes the end the next thing to communicate). `DELETE /v1/pos-rt-links/{id}` deletes a link not communicated yet; a communicated one answers `409 link_already_filed`: end it instead. Getbeel never uploads the file or signs in to the portal for you. ## MCP [#mcp] `list_fixed_assets`, `register_fixed_asset`, `update_fixed_asset`, `delete_fixed_asset`, `get_fixed_assets_register`, `get_tax_estimate`, `save_tax_estimate_inputs`, `list_pos_rt_links`, `add_pos_rt_link`, `end_pos_rt_link`, `get_pos_rt_csv`, `mark_pos_rt_links_filed`. # Taxes and deadlines (https://docs.getbeel.com/en/api/taxes) Your Italian company's tax calendar, as JSON or as an .ics calendar, and the VAT position estimate. Getbeel works out the company's tax deadlines from its profile (country, regime fiscale) and two settings you choose once, in the app (**Taxes**) or with `PATCH /companies/me/tax-settings`: monthly or quarterly VAT (`vat_periodicity`), whether the company pays professionals' fees with a withholding (`withholding_agent`) and, for companies registered in the OSS (VAT on B2C sales to consumers in other EU countries), the dates of the registration (`oss_from`, `oss_until`; `null` clears them). It is the same list as the **Taxes → Deadlines** page. Scope: `taxes:read`. Italian companies only. ```bash curl -X PATCH https://www.getbeel.com/api/v1/companies/me/tax-settings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "vat_periodicity": "quarterly" }' ``` Changing them needs `taxes:write` and a live key; a `PATCH` changes only what it sends, and `GET /companies/me/tax-settings` reads them (`null` = not set yet). Set the periodicity as the company actually settles VAT: it decides the VAT periods of the registers, the liquidazioni and the F24. MCP tools: `get_tax_settings`, `update_tax_settings`. Getbeel never signs in to your Agenzia delle Entrate area and never pays for you. It prepares the amounts and the F24 (see [Filings](/en/api/filings)); you pay it in F24 web or from your bank. ## Tax profile [#tax-profile] Each company pays different taxes. The tax profile says which apply and why: legal form, regime fiscale, VAT periodicity, withholding agent, employees, foreign suppliers (reverse charge), Intrastat, OSS, liquidation, first tax year and, for persons, social security and special income tax regimes (forfettario, impatriati, rientro docenti, neo-residenti). It is the same card as **Taxes → Your tax profile** in the app. Free on every plan. ```bash curl https://www.getbeel.com/api/v1/companies/me/tax-profile \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Getbeel detects what it can from data it already has, and shows the evidence in `detection.fields.` (`value`, `confidence`, `evidence.key` and `evidence.params`): | Field | Detected from | | -------------------------- | ---------------------------------------------------------------------------------------- | | `legal_form` | The company name (S.r.l., S.p.A., …); a personal codice fiscale is only a hint | | `regime_fiscale` | The company profile (the RF code on every issued invoice) | | `vat_periodicity` | Last year's turnover: above €800,000 it must be monthly (art. 7 DPR 542/1999) | | `withholding_agent` | Withholdings recorded in the last 12 months | | `reverse_charge_suppliers` | Received invoices from suppliers outside Italy | | `intrastat` | Sales to businesses in other EU countries | | `oss_suggested` | Sales to consumers in other EU countries above €10,000 a year (art. 7-octies DPR 633/72) | | `in_liquidation` | "in liquidazione" in the company name | Never a silent guess: a value you set always wins (`sources.` = `user`); a high-confidence detection is used (`detected`); anything else stays `null` and is listed in `questions`, each with a plain-language question to ask the user once. Employees, the OSS registration, social security and special regimes are never taken from a detection: they are always asked. ```bash curl -X PATCH https://www.getbeel.com/api/v1/companies/me/tax-profile \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "has_employees": true, "oss_registered": true, "confirm": ["legal_form"] }' ``` A `PATCH` changes only what it sends and marks it confirmed; `null` clears a value back to the detection; `confirm` confirms detected values as they are; `regimes` replaces the special income tax regimes (`[]`: none). `POST /companies/me/tax-profile/detect` runs the detection again now. Every month (the 2nd) getbeel runs the detection again for every company that has run it before. A new obligation (withholdings, foreign suppliers, Intrastat) is applied and announced in the app ("New obligation: …"). A change that would take a deadline away or change it (for example no withholdings in the last 12 months, monthly instead of quarterly VAT, or a different legal form) is **never applied by a detection**, monthly or `POST …/detect`: the earlier value stays and the field carries `held` (`value`, `confidence`, `evidence`, `since`: what the new data say). The owner gets one notice in their language, and the app shows the field as "To check". Only your answer changes it: a `PATCH` with the value, or `confirm` to keep the earlier one. Changing the profile and running the detection need `taxes:write` and a live key; every change goes to the audit log with the key and the channel (API or MCP). MCP tools: `get_tax_profile`, `update_tax_profile`, `detect_tax_profile`. When a special regime ends within a year (its last day is the `effect.ends_year` of each regime, or its own `valid_until` when earlier), the owners and the commercialisti get an email and the app shows a notice ("Impatriati (before 2024): ends on 31 December 2027, from 2028 it no longer applies"): once about a year before and once a month before. The end of the forfettario start-up rate is announced the same way, with both rates from the rule values (5% and then 15% today). The profile changes the calendar: deadlines that do not apply are left out, and each one says why it applies in `applies_because`. ## The calendar [#the-calendar] ```bash curl "https://www.getbeel.com/api/v1/companies/me/tax-calendar?from=2026-10-01&to=2027-03-31" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Without `from` and `to`: from 90 days ago to a year from today (three years at most). | `kind` | What | Codici tributo | Source | | -------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | `bollo` | Stamp duty on e-invoices, per quarter | 2521–2524 | Art. 6 DM 17/06/2014; Ris. AdE 42/E/2019 | | `withholdings` | Withholding tax on professionals' fees and, with employees, on salaries, per month | 1040; 1001 | Arts. 23, 25 DPR 600/1973; art. 18 D.Lgs. 241/97 | | `vat_payment` | Monthly or quarterly VAT payment | 6001–6012, 6031–6033 | DPR 100/1998; art. 7 DPR 542/1999 | | `vat_advance` | VAT advance (27 December) | 6013, 6035 | Art. 6 L. 405/1990 | | `vat_annual_balance` | Annual VAT balance (16 March) | 6099 | Art. 6 DPR 542/1999 | | `lipe` | Quarterly VAT report (LIPE) | – | Art. 21-bis DL 78/2010 | | `vat_return` | Annual VAT return (30 April) | – | Art. 8 DPR 322/1998 | | `pf_tax_return` | Redditi PF return of an individual (31 October; 2 November 2026) | – | Art. 2 c. 1 DPR 322/1998 | | `pf_tax_balance` | Individual: saldo + first acconto (30 June; 20 July 2026 for ISA, forfettari, minimi) | 4001, 3801, 3844, 4033, 3843 / 1792, 1790 / 1795, 1793 | Art. 17 DPR 435/2001; DL 89/2026 art. 6 | | `pf_tax_advance` | Individual: second acconto (30 November) | 4034 / 1791 / 1794 | Art. 17 c. 3 DPR 435/2001 | | `oss_return` | OSS return and payment, per quarter (OSS only) | – (Portale OSS) | Arts. 369f, 369i Dir. 2006/112/EC; art. 74-sexies DPR 633/72 | Each deadline has: - `due_date`: the real date. Saturdays, Sundays and public holidays move to the next working day; 1–20 August moves to 20 August. `nominal_due_date` is the date the law names. When a published extension (proroga) moves the deadline, `due_date` is the new date and `extension` gives the official source (`source_title`, `source_url`); otherwise `extension` is `null`. - `amount` and `amount_status`: stamp duty is computed from your issued invoices (`provisional` until the quarter ends). VAT amounts are `null` until you save the settlement; a saved settlement with nothing to pay makes the deadline `not_due`. - `status`: `to_prepare`, `ready` (F24 prepared), `paid`, `filed` or `not_due` (no stamp duty due that quarter, or no VAT to pay). - `can_prepare` and `filing_type`: whether Getbeel can prepare the filing: the F24 for bollo, withholdings and VAT (`vat_payment`, once the period is over) and the LIPE file (`lipe`). - `needs_review`: for special VAT regimes the general rule may not fit. Check it ("da verificare"). - `source`: the law the deadline comes from. - `applies_because`: why it applies to this company, from the tax profile, as keys with parameters: `issues_e_invoices`, `vat_monthly`, `vat_quarterly`, `vat_payer` (`regime`), `withholding_agent`, `has_employees`, `oss_registered`, `oss_sales` (`countries`). - `review_key`: `in_liquidation` when the company is in liquidation and the deadline falls from that date: check it with the liquidator ("da verificare"). - OSS returns keep their date even on a weekend (EU rule) and are flagged `needs_review` then; they are paid from the Portale OSS, not with an F24. `missing_settings` lists the settings still to choose in the app; until then the deadlines that depend on them are left out. Forfettari (RF19) and minimi (RF02) have no VAT deadlines. ### OSS (EU B2C sales) [#oss-eu-b2c-sales] With `oss_from` set, the calendar adds `oss_return` for every quarter of the registration: the quarterly OSS return and its payment, due by the **last day of the month after the quarter** (30 April, 31 July, 31 October, 31 January), even with no sales (a nil return). Sources: Directive 2006/112/EC arts. 369f and 369i, Regulation (EU) 282/2011 art. 59a, DPR 633/72 arts. 74-quinquies and 74-sexies. - The date is **not moved** on weekends or holidays: the European Commission's OSS page says so. The Agenzia does not say otherwise, so when it falls on a non-working day the deadline has `needs_review: true` ("da verificare"). - It is paid from the Agenzia's Portale OSS by direct debit or bank transfer with the reference `IT//Qn.YYYY`, **not with an F24**, and credits cannot offset it. - From 2027 the rules move to the Testo unico IVA (D.Lgs. 10/2026, arts. 149–153); the dates are expected to stay the same (da verificare). ### Income taxes (companies) [#income-taxes-companies] For a company that pays IRES (SRL, SpA), the calendar also lists, for a tax year that matches the calendar year and a bilancio approved within 120 days: | `kind` | Due | F24 codes | Source | | ---------------------- | -------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------- | | `income_tax_balance` | IRES and IRAP saldo + first acconto: 30 June (ISA subjects, 2026 only: 20 July, DL 89/2026 art. 6) | 2003, 2001, 3800, 3812 | art. 17 c. 1-2 DPR 435/2001 | | `chamber_fee` | Diritto annuale camerale, with the first acconto | 3850 | art. 6 DM 21/04/2011 | | `income_tax_advance` | Second acconto: 30 November (60%, or 50% for ISA subjects) | 2002, 3813 | art. 17 c. 3 DPR 435/2001; art. 58 DL 124/2019 | | `income_tax_return` | Redditi SC and IRAP returns: 31 October (2 November in 2026) | — | art. 2 c. 2 DPR 322/1998 | | `financial_statements` | Deposito del bilancio: 30 May (not moved: a civil-law deadline) | — | artt. 2435 and 2478-bis c.c. | Whether the company pays IRES and applies ISA comes from **Taxes → Tax estimate**, per tax year (`settings.income_tax`). Until it is saved there, nothing is guessed: the deadlines are left out and `missing_settings` contains `income_tax`. ISA subjects pay by 21 July in 2025 (DL 84/2025 art. 13) and 20 July in 2026. The deadlines are `needs_review` from 2027, because the payment rules move to the Testo unico versamenti (D.Lgs. 33/2025) and the same dates are assumed. Code 3813 (IRAP second acconto) is in the AdE codici tributo table (11 November 2026), and the IRAP return is due the same day as Redditi SC (DM 11 September 2008, art. 2 DPR 322/1998). Amounts are not computed here yet: see the tax estimate. ### INPS contributions (persons with partita IVA) [#inps-contributions-persons-with-partita-iva] For a person, the calendar adds the INPS deadlines of the scheme in the tax profile (`social_security`): | `kind` | Due | F24 causale | Source | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------- | | `inps_fixed` | Artigiani / commercianti, fixed contributions on the minimale: 16 May, 16 August (paid by 20 August), 16 November, 16 February of the next year. `period` is `YYYY-Qn` | AF / CF | art. 18 c. 1-2 D.Lgs. 241/1997; INPS circ. 14/2026 §9 | | `inps_balance` | Saldo of last year + first acconto: 30 June (30 July with 0.40%) | AP / CP; PXX or P10 (gestione separata) | art. 18 c. 4 D.Lgs. 241/1997; INPS circ. 62/2026 §3 | | `inps_advance` | Second acconto: 30 November | AP / CP; PXX or P10 | art. 18 c. 4 D.Lgs. 241/1997; INPS circ. 62/2026 §3 | | `inps_reduction_request` | Forfettari artigiani / commercianti: request for the 35% reduction by 28 February (not moved; `needs_review` when it is not a working day) | — | art. 1 c. 83 L. 190/2014; INPS circ. 14/2026 §8 | - A **cassa professionale** has its own calendar: nothing is listed for it. With no scheme in the profile, nothing is guessed. - In the first fiscal year there is no saldo of the year before, no second acconto and no 28 February request (a new business asks for the 35% when it enrols). The four fixed instalments are listed: when you start during the year, only the months from the enrolment are due (INPS circ. 14/2026 §2), and the calendar, which knows only the year, cannot tell which ones. - Amounts come from the INPS Cassetto previdenziale (fixed instalments, codeline). Above the minimale they follow the income: see the tax estimate. - PXX is the 26.07% rate, P10 the 24% rate for pensioners and people insured elsewhere. ISA subjects and forfettari: whether the 2026 extension to 20 July (DL 89/2026 art. 6) also covers contributions is not confirmed by INPS, so 30 June is shown. - From 2027 the same dates are assumed and flagged (`needs_review`): the payment rules move to D.Lgs. 33/2025, and the 35% regime's commi of L. 190/2014 are repealed by D.Lgs. 117/2026. ### Automatic preparation [#automatic-preparation] On by default (`auto_prepare: true` in the tax settings): every morning getbeel prepares the F24 of stamp duty (bollo), withholdings (ritenute) and periodic VAT whose due date is within `auto_prepare_days` days (default 5), once the period is over and the amount is known. It is the same as pressing **Prepare** (the same checks and the same `filing.ready` webhook), plus an in-app notice. You check the F24 and pay it, and you can still recompute it, prepare it by hand or upload the receipt. LIPE and the annual VAT return need a signer and your answers, so they are never prepared automatically; neither are deadlines marked `needs_review`, nor the December VAT of monthly payers until the acconto IVA is saved in its liquidazione. VAT is prepared with the liquidazione's saved inputs (credits carried, acconto). Switch it off with `PATCH /companies/me/tax-settings` and `{"auto_prepare": false}` (or in **Taxes → Settings**, or with the MCP tool `update_tax_settings`): you then only get reminders. ## In your calendar (.ics) [#in-your-calendar-ics] In the app, **Taxes → Add to calendar** shows a private address to add to Google Calendar, Outlook or Apple Calendar: ``` https://www.getbeel.com/api/v1/companies/me/tax-calendar.ics?token=… ``` The token replaces the API key (calendar apps cannot send headers). Anyone with the address sees the deadlines: if you shared it by mistake, regenerate it in the app and the old one stops working. ## VAT position (estimate) [#vat-position-estimate] ```bash curl "https://www.getbeel.com/api/v1/companies/me/vat-position?period=2026-Q3" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `period` is a month (`2026-10`) or a quarter (`2026-Q3`). - `sales_vat`: VAT on the issued invoices SDI accepted in the period. Credit notes subtract; split payment is left out (`split_payment_invoices`); deferred VAT is apart (`deferred_sales_vat`). - `purchase_vat_estimate`: VAT on the reviewed supplier invoices, in euros. - `balance_estimate`: positive to pay, negative in credit. `reliable` is always `false`: Getbeel does not know deductibility, the month supplier invoices were received or reverse-charge self-invoices. Use it to get an idea and check it with your accountant. Getbeel prepares no VAT F24 from it. For the actual settlement, with its F24 and the LIPE, use the [VAT registers and settlements](/en/api/vat-registers). Profit and loss, cash flow, receivables aging and the ZIP for the accountant: [Reports and export](/en/api/reports). ## OSS return (draft) [#oss-return-draft] For a company registered in the OSS union scheme (tax settings `oss_from` / `oss_until`), the draft of the quarterly return, to enter in the Agenzia delle Entrate's Portale OSS: ```bash curl "https://www.getbeel.com/api/v1/companies/me/oss-return?period=2026-Q3" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` - **What counts:** issued invoices of the quarter to a consumer (no VAT number) in another EU country, lines with Natura N7 ("IVA assolta in altro stato UE"). - **`countries`:** per Member State and rate, the taxable amount and the VAT at that country's standard rate on the invoice date (European Commission TEDB). VAT is computed per line, rounded to the cent, then added up; `vat_country_level` is the same VAT computed once on the country total, as the portal may do, and `rounding_gap` is true when they differ by more than €0.01. - **`corrections`:** credit notes (TD04, TD08) on sales of an earlier quarter, as corrections of that quarter (within three years). `balances` per country; a negative balance is refunded by that country (`refunds`), never set against another; `total_due` is never negative. - **`deadline`:** the last day of the month after the quarter, as the EU rules set it. Getbeel does not move it for weekends or holidays: check for any extension. - **`reference`:** the payment reference `IT/IT{partita IVA}/Q{n}.{YYYY}`. Payment: from the portal (SEPA direct debit) or by bank transfer to the Banca d'Italia, never with F24 or by offsetting. - **`nil_return`:** no OSS sales and no corrections: a nil return is still due. - **`doubtful`:** invoices that need a decision, with the `reason`: `n7_not_eu_consumer`, `italian_vat_to_eu_consumer`, `outside_registration`, `foreign_currency` (it needs the ECB rate of the quarter's last day), `rate_unknown`, `credit_note_unlinked`, `credit_note_before_sale`, `correction_too_old`. They are left out of the totals. `reliable` is always `false`: reduced rates and goods are not modelled yet (every sale is counted as a service at the standard rate). Getbeel never files or pays the return: you do it in the Portale OSS with your own credentials (no intermediary is allowed). Free. MCP: `get_oss_return`. ## Webhook [#webhook] `tax_deadline.upcoming` arrives 7 days and 1 day before each deadline not yet paid, once each, to live endpoints only. `data.object` is the deadline with `reminder_days_before`. See [Webhooks](/en/api/webhooks). `tax_deadline.insufficient_funds` arrives once per due date, from 5 working days before it, when the F24 payments due that day (including amounts still estimated from the registers) are higher than the balance of every connected EUR bank account, using balances at most 3 days old. Due dates are taken in order and each one's F24s come out of the balance, so two close dates that together exceed it are flagged; bollo of small quarters counts on the day it is really paid (with Q2 or Q3). A new alert goes out when the amount due on that day changes. `data.object` is an `f24_funds_alert` with `due_date`, `amount_due`, `available_balance`, `shortfall`, `deadline_ids` and `bank_account_id`. The team's owners also get an email and an in-app notice. An F24 the bank cannot debit is rejected and paid late (sanctions, art. 13 D.Lgs. 471/1997). # VAT registers and settlements (https://docs.getbeel.com/en/api/vat-registers) The sales and purchase VAT registers, the monthly or quarterly VAT settlement (liquidazione) with its F24, and the LIPE file, prepared from the documents in Getbeel. Getbeel builds the **VAT registers** (sales and purchases) of a month or quarter from the issued invoices, supplier invoices and autofatture it already has, computes the period's **VAT settlement** (liquidazione IVA) in the rows of the LIPE (VP2–VP14) and, from it, prepares the **F24** and the **LIPE** file. These are the same pages as **Taxes → VAT registers** and **Taxes → VAT settlements** in the app. Scope: `taxes:read` to read, `taxes:write` to save a settlement or prepare the LIPE (through [Filings](/en/api/filings)). Italian companies with VAT only: forfettari and minimi get `400 vat_not_applicable`. Registers and settlements only count the documents in Getbeel. `reliable` is always `false`: Getbeel does not know deductibility (art. 19-bis.1), the pro-rata, documents kept elsewhere, VP10 payments or VP11 tax credits. Check with your accountant before paying or filing. Getbeel never signs, pays or sends anything. First choose in the app (**Taxes → Settings**) whether the company settles VAT **monthly** or **quarterly**: until then the settlement answers `400 settings_missing`, and a period in the wrong format (a month for a quarterly payer) answers `400 parameter_invalid`. ## VAT registers [#vat-registers] ```bash curl "https://www.getbeel.com/api/v1/companies/me/vat-registers?period=2026-Q3" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `period` is a month (`2026-10`) or a quarter (`2026-Q3`). **Sales register** (art. 23 DPR 633/1972): - Invoices issued in Getbeel and accepted by SDI (delivered or not delivered), by document date. Taxable amount and VAT per rate and natura are the XML's `DatiRiepilogo`. A document whose submission SDI rejected with `00404` because it already accepted a copy also counts as issued: its row is flagged `needs_review` until support links the accepted submission ([SDI lifecycle](/en/api/sdi-lifecycle)). - Credit notes (TD04, TD08) are negative. - Split payment (art. 17-ter): recorded but not due (`vat_counted` 0, flag `split_payment`). - Deferred VAT (`EsigibilitaIVA` D): due when the invoice is collected (art. 6, c. 5 DPR 633/1972) and, under IVA per cassa, one year after the operation at the latest (art. 32-bis DL 83/2012); the row counts in that period (`deferred_vat_collected`). A row that reaches the one-year limit unpaid is flagged `needs_review`: the limit does not apply to art. 6, c. 5 sales, and the e-invoice does not say which case it is. - Reverse-charge autofatture TD16–TD19 and TD28 (art. 17 DPR 633/1972; arts. 46–47 DL 331/1993): the VAT is due here and, as a rule, deducted on the purchase side, so they appear in **both** registers (flag `reverse_charge`). **Purchase register** (art. 25 DPR 633/1972): - Supplier invoices as soon as the AI has read them, including those received through SDI. Those you have not reviewed yet count too, with the `unreviewed` flag on their row; `totals.to_review` counts the rows to check. Rejected documents never count. - Period: the period of receipt. An invoice received by the 15th of the month after the operation counts in the operation's period, never across years (art. 1, c. 1, DPR 100/1998). The receipt date is known for invoices received through SDI; for the others the document date is used (`late_receipt` marks invoices received later). - VAT charged by foreign suppliers is not Italian VAT: it counts 0 (`foreign_vat`); the autofattura carries it. A supplier whose country cannot be told (no country, a tax ID that is neither Italian nor prefixed by a known country) is not taken for Italian: its VAT counts 0, flag `country_unknown`. - Reverse-charge autofatture, as above. Each row has `breakdown` (per rate and natura), `taxable`, `vat`, `vat_counted` (the VAT entering the settlement), `counted`, `flags` and `adjustment`. Each register's totals are in `totals` (also per rate, `by_rate`). ```json { "object": "vat_registers", "period": "2026-Q3", "start": "2026-07-01", "end": "2026-09-30", "currency": "EUR", "sales": { "rows": [ { "key": "sales:issued_invoice:fe_3f2a…", "source": "issued_invoice", "document_id": "fe_3f2a…", "number": "42", "date": "2026-07-15", "received_date": null, "counterparty_name": "Rossi S.r.l.", "counterparty_vat": "IT01234567897", "tipo_documento": "TD01", "breakdown": [ { "rate": "22.00", "natura": null, "taxable": "1000.00", "vat": "220.00" } ], "taxable": "1000.00", "vat": "220.00", "vat_counted": "220.00", "counted": true, "flags": [], "adjustment": null } ], "totals": { "documents": 1, "taxable": "1000.00", "vat": "220.00", "vat_counted": "220.00", "excluded": 0, "adjusted": 0, "by_rate": [] } }, "purchases": { "rows": [], "totals": { "documents": 0, "taxable": "0.00", "vat": "0.00", "vat_counted": "0.00", "excluded": 0, "adjusted": 0, "by_rate": [] } }, "missing": [ { "source": "received_invoice", "id": "inv_…", "number": "A/17", "date": "2026-09-28", "name": "Fornitore S.p.A.", "reason": "processing" } ], "reliable": false, "note": "To check (da verificare): …" } ``` `missing` lists the period's documents not in the registers yet: `processing` (the AI is still reading it; it joins on its own), `no_vat_data` (foreign-currency amounts without a euro value), `pending_sdi` (issued invoice still waiting for SDI), `autofattura_pending`, `autofattura_unreadable`, `autofattura_missing` (a foreign purchase whose TD17/TD18/TD19 was not sent to SDI yet: due by the 15th of the next month; only purchases received since the automatic proposals exist, and not when any TD17/TD18/TD19 sent for the same supplier has the same invoice number or a close amount in the same or an adjacent month). ### Excluding or correcting a row [#excluding-or-correcting-a-row] Getbeel cannot know whether a purchase is only partly deductible (company cars, phones, pro-rata) or whether you deduct it later. In the app (**Taxes → VAT registers → Edit**) you can exclude a row from the settlement or set the VAT that counts, always with a reason. The row shows `adjustment` and `vat_counted` changes accordingly. For a purchase with non-deductible VAT set the VAT to 0 rather than excluding it: the LIPE instructions count non-deductible purchases among the operazioni passive (VP3). Exclude only documents that do not belong to the period or the company. A deferred-VAT row not due yet cannot be changed: change it in the period it is due. The same correction through the API, on the row's `key` (`register:source:document_id`). It needs `taxes:write` and a live key: ```bash curl -X PUT "https://www.getbeel.com/api/v1/companies/me/vat-adjustments/purchases:received_invoice:$INVOICE_ID" \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "adjust", "vat_amount": "8.80", "reason": "Auto aziendale, IVA detraibile al 40%" }' ``` `action` is `exclude` or `adjust` (with `vat_amount`, the VAT that counts); `reason` is required. `DELETE /companies/me/vat-adjustments/{key}` removes the correction. A row that is not this company's answers `404`, a source in the wrong register `400`. A liquidazione already saved keeps its numbers until you prepare it again. MCP tools: `set_vat_adjustment`, `remove_vat_adjustment`. ### Export [#export] In the app each register downloads as CSV, Excel (XLSX) or PDF, for you or your accountant. ## VAT settlement (liquidazione) [#vat-settlement-liquidazione] ```bash curl "https://www.getbeel.com/api/v1/companies/me/vat-settlements?period=2026-10" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `period` is a month for monthly payers, a quarter for quarterly payers. The settlement is computed now from the registers, in the LIPE rows (`lipe`): | Field | LIPE row | What | | ------------------------------------------ | --------- | -------------------------------------------------------------- | | `operations_active` / `operations_passive` | VP2 / VP3 | Taxable sales and purchases (without art. 15 exclusions, N1) | | `vat_due` / `vat_deducted` | VP4 / VP5 | VAT due and VAT deducted (the registers' `vat_counted`) | | `vat_balance_debit` / `vat_balance_credit` | VP6 | Balance owed or in credit | | `previous_debt` | VP7 | Previous period's debt up to €100, not paid | | `previous_credit` | VP8 | Previous period's credit (not in the first period of the year) | | `annual_credit` | VP9 | Previous year's credit used in this settlement | | `car_payments` / `tax_credits` | VP10/VP11 | Not known to Getbeel: always `0.00` | | `interest` | VP12 | 1% interest for quarterly payers (Q1–Q3) | | `advance`, `advance_method` | VP13 | VAT advance (acconto), December or Q4 only | | `amount_due` / `amount_credit` | VP14 | Amount to pay or in credit (`null` for Q4 of quarterly payers) | The rules Getbeel applies: - **Minimum payment**: up to €100 is not paid and moves to the next period (`carried_debt`, note `below_minimum_carried`), but it must be paid by 16 December (monthly) or 16 November (quarterly) anyway: November, December, Q3 and Q4 VAT is never carried (art. 1, c. 4, DPR 100/1998; art. 7 DPR 542/1999, as amended by D.Lgs. 1/2024). - **Credit**: a negative result moves to the next period (`carried_credit`, the next settlement's VP8) within the same year. - **Previous period**: VP7 and VP8 come from the previous period of the same year: its saved settlement or, if it is not saved, the one Getbeel computes from its registers, back through the year. `previous` says which (`source`: `saved`, `computed` or `input`). Only when Getbeel has no earlier data that year do you pass them (`previous_debt`, `previous_credit`); the note `previous_missing` says so. Amounts you pass replace the computed ones. - **Quarterly interest**: 1% on the amount due for Q1, Q2 and Q3 (art. 7 DPR 542/1999), note `interest_added`. - **Q4 of quarterly payers**: paid with the annual balance (code 6099, by 16 March, plus 1%): `amount_to_pay` is `0.00` and the note is `paid_with_annual_balance`. - **Advance** (art. 6 L. 405/1990): in December or Q4 give the advance paid (`advance`, at least €103.29) and its method (`advance_method`: 1 historical, 2 forecast, 3 analytical, 4 special sectors). `amount_to_pay` is what the F24 pays now; `tax_code` and `due_date` are the tax code (6001–6012 for months, 6031–6033 for quarters) and the deadline. `saved` is the saved version, with `outdated: true` when the registers changed since. ```json { "object": "vat_settlement", "period": "2026-10", "periodicity": "monthly", "start": "2026-10-01", "end": "2026-10-31", "currency": "EUR", "lipe": { "operations_active": "12000.00", "operations_passive": "4000.00", "vat_due": "2640.00", "vat_deducted": "880.00", "vat_balance_debit": "1760.00", "vat_balance_credit": "0.00", "previous_debt": "0.00", "previous_credit": "300.00", "annual_credit": "0.00", "car_payments": "0.00", "tax_credits": "0.00", "interest": "0.00", "advance": "0.00", "advance_method": null, "amount_due": "1460.00", "amount_credit": "0.00" }, "result": "1460.00", "amount_to_pay": "1460.00", "carried_debt": "0.00", "carried_credit": "0.00", "tax_code": "6010", "due_date": "2026-11-16", "notes": [], "inputs": { "previous_credit": null, "previous_debt": null, "annual_credit_used": null, "advance": null, "advance_method": null }, "registers": { "sales": { "documents": 14, "…": "…" }, "purchases": { "documents": 6, "…": "…" }, "missing": 0 }, "saved": null, "reliable": false, "note": "To check (da verificare): …" } ``` ## Saving the settlement and preparing the F24 [#saving-the-settlement-and-preparing-the-f24] Once the period is over, save the settlement with [`POST /v1/filings`](/en/api/filings) and `type: vat_payment`: ```bash curl -X POST https://www.getbeel.com/api/v1/filings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "type": "vat_payment", "period": "2026-10" }' ``` Optional: `previous_credit`, `previous_debt` (to replace the computed carry-over, or when Getbeel has no earlier data that year), `annual_credit_used`, `advance` and `advance_method` (December or Q4). The response is the filing with its F24 line and `details.settlement` (the LIPE rows). When there is nothing to pay (a credit, up to €100 carried, Q4 of quarterly payers) the settlement is **still saved**, an F24 prepared earlier for the period and not paid is deleted, and the answer is `422 nothing_due`. Until the F24 is paid you can recompute it; afterwards it answers `409 filing_completed`, and so it does once the LIPE of the quarter is filed (a change then goes into a corrective LIPE). `previous_debt` (VP7) is at most 100.00. ## The LIPE [#the-lipe] The Comunicazione liquidazioni periodiche IVA (art. 21-bis DL 78/2010) is sent every quarter: by 31 May, 30 September, 30 November and the end of February of the next year. Getbeel prepares the XML file from the quarter's **saved** settlements (its three months, or the quarter): ```bash curl -X POST https://www.getbeel.com/api/v1/filings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "lipe", "period": "2026-Q3", "declarant_fiscal_code": "RSSMRA80A01F205X", "declarant_role": 1 }' ``` - Companies name who signs: `declarant_fiscal_code` (16-character codice fiscale) and `declarant_role` (codice carica, 1 = legal representative). - A settlement of the quarter not saved yet: `400 settlements_missing`; an invalid company codice fiscale or partita IVA: `fiscal_code_invalid`, `vat_number_invalid`. - The file follows the Agenzia's technical specifications (supply `IVP18`): one module per month or one for the quarter; Q4 of quarterly payers is quarter `5`, without interest or VP14. File name: `IT{codice fiscale}_LI_{5 characters}.xml`, unique for each file. The specifications want the codice fiscale of whoever transmits it: Getbeel uses the company's, since you upload it from the company's own area; an accountant who sends it renames it with their own. `GET /filings/{id}/file` returns the XML (`application/xml`). You then check it with the Agenzia's control software, sign it and upload it in "Fatture e corrispettivi" (or hand it to your accountant). When you upload the receipt with `POST /filings/{id}/receipt` the LIPE becomes `filed` (webhook `filing.filed`). ## SDKs, CLI and MCP [#sdks-cli-and-mcp] ```ts const registers = await getbeel.taxes.vatRegisters('2026-Q3'); const settlement = await getbeel.taxes.vatSettlement('2026-10'); ``` ```python registers = client.taxes.vat_registers("2026-Q3") settlement = client.taxes.vat_settlement("2026-10") ``` ```bash getbeel taxes registers --period 2026-Q3 getbeel taxes settlement --period 2026-10 getbeel filings prepare --type vat_payment --period 2026-10 ``` With an AI assistant: `get_vat_registers`, `get_vat_settlement` and `prepare_filing` (types `vat_payment` and `lipe`). The assistant shows the settlement and asks before saving it. See [MCP server](/en/api/mcp). ## Sources [#sources] The rules above follow the official texts, read on 2 November 2026. Check them with your accountant: Getbeel prepares, you file. - LIPE: technical specifications `SpecificheIVP18_2024.pdf`, XSD `Specifiche IVP2018_SchemaIV18.zip` (version 1.0) and the instructions `IVA period_2024.pdf`, approved by provvedimento of the Agenzia delle Entrate prot. 125654 of 14 March 2024, on [agenziaentrate.gov.it](https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/liquidazioni-periodiche-iva). The XSD and the AdE control software still call VP10 `VersamentiAutoUE`; Getbeel never fills it. - Monthly settlement and the €100 threshold: [art. 1 DPR 100/1998](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.del.presidente.della.repubblica:1998-03-23;100~art1) (as amended by D.Lgs. 1/2024). - Quarterly settlement and the 1% interest: [art. 7 DPR 542/1999](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.del.presidente.della.repubblica:1999-12-14;542~art7). The 1% is "calcolati sugli importi da versare … relativamente alla liquidazione del trimestre" (LIPE instructions, VP12): Getbeel applies it to the quarter's own amount (VP6 − VP8 − VP9). A debt carried in VP7 is left out because it already includes its interest: the €100 threshold is checked "comprensivo degli interessi dovuti dai contribuenti trimestrali" ([Istruzioni IVA 2026](https://www.agenziaentrate.gov.it/portale/iva-2026/modello-e-istruzioni), quadro VH). - Advance: art. 6 L. 405/1990 (due by 27 December); the €103.29 minimum is in the LIPE instructions and specifications. - LIPE deadlines: art. 21-bis DL 78/2010. - Registers and deduction: artt. 19, 23 and 25 DPR 633/1972 (artt. 19 and 25 as amended by D.Lgs. 148/2026 from 12 August 2026: deduction at the latest with the return of the second following year); split payment art. 17-ter; deferred VAT art. 6, c. 5 and [art. 32-bis DL 83/2012](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legge:2012-06-22;83~art32bis). - From 1 January 2027 most of these articles move to the Testo unico IVA (D.Lgs. 10/2026) and the Testo unico adempimenti (D.Lgs. 141/2026); DPR 100/1998 and DPR 542/1999 stay. Not from an official text (to confirm with your accountant): leaving amounts excluded under art. 15 (natura N1) out of VP2, and counting a deferred-VAT sale in VP2 of the period it was issued only. # Webhooks (https://docs.getbeel.com/en/api/webhooks) Get an event for every SDI receipt and verify the Getbeel-Signature header. Instead of polling, register an HTTPS endpoint: Getbeel sends it a signed JSON `POST` for every event you choose, about your invoices, reconciliations and taxes. | Part | Rule | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Request | `POST`, JSON body, headers `Content-Type: application/json`, `User-Agent: getbeel-webhooks/1.0` and [`Getbeel-Signature`](#verifying-the-signature) | | Your answer | Any `2xx` within 10 seconds. Redirects are not followed: a `3xx` counts as a failure | | Retries | After a non-`2xx`, a timeout or a network error: again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h and 24 h. Up to 9 attempts over about 3 days, then the delivery is `failed` | | Duplicates | Delivery is at least once: deduplicate on the event `id` | | Order | Not guaranteed: re-read the invoice when order matters | | Modes | A **test** endpoint gets the events of test keys (the sandbox); a **live** endpoint gets real ones | ## Add an endpoint [#add-an-endpoint] In the app, open **Settings → API keys & MCP → Webhooks**, choose **Add endpoint**, then the URL, the mode and the events. The signing secret is shown once: store it on your server. - The URL must be `https` on a public host. Private and internal hosts are refused, also when a public name resolves to one. - **Send test event** posts a test event to the endpoint at once. Every delivery is listed under **Recent deliveries**, with the status, and **Redeliver** sends one again. - An endpoint works while the member who added it can manage the team's settings. When they lose that permission, its deliveries stop. ## Events [#events] | Event | When | Invoice status | | ----------------------- | ------------------------------------------- | --------------- | | `invoice.sent` | Transmitted to SDI, waiting for the outcome | `sent` | | `invoice.delivered` | Delivery receipt (RC) | `delivered` | | `invoice.not_delivered` | Delivery failure (MC) | `not_delivered` | | `invoice.rejected` | Rejection notice (NS), with the SDI codes | `rejected` | With a test key the events come from the [sandbox](/en/api/sandbox), so you can test every case. Bank and collection events carry real data, so only **live** endpoints receive them: | Event | When | `data.object` | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------ | | `bank_statement.parsed` | A [bank statement](/en/api/bank-reconciliation) was read | `bank_statement` | | `reconciliation.completed` | AI matching finished: the matches can be reviewed | `reconciliation` | | `received_invoice.created` | A supplier invoice arrived from SDI (`source: "sdi"`) or was collected (mailbox scan, forwarding or upload) | `received_invoice` | | `invoice.emailed` | An invoice or reminder email was sent to the customer | `invoice_email` | | `invoice.email_failed` | The customer email could not be sent (`error` says why) | `invoice_email` | | `invoice.paid` | The payments recorded cover the amount due | `invoice` | | `invoice.overdue` | The day after the due date, once, when the invoice is unpaid | `invoice` | | `filing.ready` | A [filing](/en/api/filings) was prepared (or recomputed) | `filing` | | `filing.filed` | Its receipt was uploaded (paid), or a return was marked filed with its protocol number | `filing` | | `filing.needs_review` | A prepared filing waits for the commercialista's review | `filing` | | `filing.changes_requested` | The commercialista sent it back with a comment | `filing` | | `filing.approved` | Approved (visto bueno): it can be paid or filed | `filing` | | `filing.skipped` | Marked not to be done, with the reason | `filing` | | `filing.approval_due` | With the commercialista's approval required, due within 5 working days and still not approved (once per due date) | `filing` | | `tax_deadline.upcoming` | A [tax deadline](/en/api/taxes) is 7 days or 1 day away, not paid | `tax_deadline` | | `tax_deadline.insufficient_funds` | An F24 due within 5 working days is higher than the balance of every connected bank account | `f24_funds_alert` | | `bank_connection.expiring` | A [connected bank](/en/api/bank-connections)'s consent ends within 7 days | `bank_connection` | | `bank_connection.expired` | The consent ended or was revoked: updates stop until you reconnect | `bank_connection` | `invoice.accepted` and `invoice.refused` (public administration outcome), `invoice.terms_expired` (decorrenza termini). ## The payload [#the-payload] Every event is an `event` object; for invoice events `data.object` is the full invoice, the same as `GET /invoices/{id}` (without the lines). ```json title="POST to your endpoint" { "id": "evt_8a1f…", "object": "event", "type": "invoice.rejected", "created": 1761742800, "livemode": true, "data": { "object": { "object": "invoice", "id": "fe_3f1c…", "number": "121", "status": "rejected", "sdi": { "identificativo_sdi": "7731024559", "file_name": "IT13815270965_0004N.xml", "error_message": "00305 1.4.1.1.2 non valido", "error_codes": ["00305"], "errors": [ { "code": "00305", "description": "1.4.1.1.2 non valido" } ], "available_since": null, "updated_at": "2026-10-30T15:02:11.000Z" }, "…": "…" } } } ``` Branch on `type`. An event can arrive more than once or late: deduplicate on `id` and, when you need the current state, read the invoice with `GET /invoices/{id}`. What each status means: [SDI lifecycle](/en/api/sdi-lifecycle). ## Verifying the signature [#verifying-the-signature] Every request has a `Getbeel-Signature` header: ```text Getbeel-Signature: t=1761742800,v1=5f2b9c… ``` - `t` is the Unix timestamp (seconds) of the delivery. - `v1` is the hex HMAC-SHA256 of the string `t` + `.` + the raw request body, computed with your endpoint's secret. To verify it: recompute the HMAC over the **raw** body (before parsing the JSON), compare it with `v1` in constant time, and reject old timestamps (we suggest 5 minutes) to prevent replays. ```js import { createHmac, timingSafeEqual } from 'node:crypto'; import express from 'express'; export function verifyGetbeelSignature( rawBody, header, secret, toleranceSeconds = 300, ) { let timestamp; const signatures = []; for (const part of (header ?? '').split(',')) { const [key, value] = part.trim().split('='); if (key === 't') timestamp = value; if (key === 'v1' && value) signatures.push(value); } if (!timestamp || signatures.length === 0) return false; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false; const expected = createHmac('sha256', secret) .update(`${timestamp}.${rawBody}`) .digest('hex'); return signatures.some( (signature) => signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected)), ); } const app = express(); // Express: read the raw body, not the parsed JSON app.post( '/webhooks/getbeel', express.raw({ type: 'application/json' }), (req, res) => { const ok = verifyGetbeelSignature( req.body.toString('utf8'), req.get('Getbeel-Signature'), process.env.GETBEEL_WEBHOOK_SECRET, ); if (!ok) return res.sendStatus(400); const event = JSON.parse(req.body); // handle event.type … res.sendStatus(200); }, ); ``` ```python import hashlib import hmac import os import time from flask import Flask, request app = Flask(__name__) def verify_getbeel_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool: timestamp, signatures = None, [] for part in (header or "").split(","): key, _, value = part.strip().partition("=") if key == "t": timestamp = value elif key == "v1" and value: signatures.append(value) if not timestamp or not timestamp.isdigit() or not signatures: return False if abs(time.time() - int(timestamp)) > tolerance: return False expected = hmac.new( secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256 ).hexdigest() return any(hmac.compare_digest(expected, signature) for signature in signatures) # Flask: request.get_data() returns the raw body @app.post("/webhooks/getbeel") def getbeel_webhook(): if not verify_getbeel_signature( request.get_data(), request.headers.get("Getbeel-Signature"), os.environ["GETBEEL_WEBHOOK_SECRET"] ): return "", 400 event = request.get_json() # handle event["type"] … return "", 200 ``` ## If it fails [#if-it-fails] What **Recent deliveries** shows, and what to do: | Delivery error | Cause | Fix | | ------------------------------------------------------------------ | --------------------------------------- | -------------------------------------------------------- | | `HTTP 4xx` or `5xx` | Your endpoint answered an error | Fix the handler; Getbeel retries on the schedule above | | `Timed out after 10 seconds` | No answer in 10 seconds | Answer `2xx` first, then do the work in a queue | | `Could not connect to the endpoint` | DNS, TLS or network error | Check that the URL is reachable from the internet | | `Endpoint URL not allowed` | Not `https`, or a private host | Use a public `https` URL (for tests, webhook.site works) | | `The member who added this endpoint can no longer manage webhooks` | That member left or lost the permission | Add the endpoint again as a member who manages settings | Failures that cannot succeed (URL not allowed, endpoint disabled, the member's permission) are not retried. ## Good practice [#good-practice] - Answer with a `2xx` right away and do heavy work later, in a queue. - The same event can arrive more than once: make handling idempotent (for example, don't email the customer twice). - Events can arrive out of order: if order matters, re-read the status with `GET /invoices/{id}`. - Keep the webhook secret on your server, like the API key. Webhooks have just shipped. Events, header and signature algorithm are as described here; the fields of `data` are described in the API reference and may gain new fields. # Withholding tax (ritenute) (https://docs.getbeel.com/en/api/withholdings) Invoices with ritenuta and cassa previdenziale, withholdings owed as sostituto d'imposta, F24 code 1040 and data for the Certificazione Unica and the 770. Two sides of the same withholding: - **You issue** a professional's invoice: `POST /v1/invoices` with `withholding` (the `DatiRitenuta` block) and, if needed, `cassa_previdenziale`. The customer pays `amount_due`, the total less the withholdings. - **You pay** a professional or an agent: you are the sostituto d'imposta, you withhold the ritenuta and pay it yourself with an F24 (tax code 1040) by the 16th of the month after the payment. `/v1/withholdings` keeps one fee per row; at year end `/v1/withholdings/cu` gives the data for the CU and the 770. Scopes: `taxes:read` to read, `taxes:write` to write (live key, like [filings](/en/api/filings)). Recording withholdings is free. ## Issuing an invoice with a withholding [#issuing-an-invoice-with-a-withholding] ```bash curl -X POST https://www.getbeel.com/api/v1/invoices \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "customer": { "denominazione": "Cliente S.r.l.", "partita_iva": "01234567890" }, "lines": [ { "description": "Consulting, October", "unit_price": "1000.00", "vat_rate": "22" }, { "description": "Expenses advanced", "unit_price": "50.00", "natura": "N1" } ], "cassa_previdenziale": { "type": "TC22", "rate": "4", "vat_rate": "22", "subject_to_withholding": true }, "withholding": { "type": "RT01", "rate": "20", "reason": "A" } }' ``` - `withholding.amount` can be left out: Getbeel computes `rate` × (subject lines + the cassa contribution when subject). Natura N1 lines (expenses advanced in the customer's name, art. 15 DPR 633/72) are not subject unless you send `subject_to_withholding: true`. Subject lines get `SI`. - For commissions (`reason` Q to V) the rate applies to part of the amount only (art. 25-bis DPR 600/1973): `amount` is required. - `withholding.contributions`: further `DatiRitenuta` blocks for contributions the customer withholds (RT03 INPS, RT04 ENASARCO, RT05 ENPAM, RT06 other). They also reduce `amount_due` and `ImportoPagamento`. - `cassa_previdenziale.amount` can be left out: `rate` × fees (lines except N1); Getbeel also writes `ImponibileCassa`. `subject_to_withholding` is for a rivalsa that is part of the fee; the integrative contribution of the professional funds is not part of it (CU 2026 instructions, punto 4). - `reason` is the CU causale: accepted codes are those of the FatturaPA schema that are also CU 2026 causali (A, B, C, D, E, G, H, I, L, L1, M, M1, M2, N, O, O1, P, Q, R, S, T, U, V, V1, W, ZO). The invoice returned has `withholdings` (type, rate, amount and causale of each block) and `amount_due` net of all of them. ## Withholdings you owe [#withholdings-you-owe] ```bash curl https://www.getbeel.com/api/v1/withholdings?paid_in=2026-10 \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Invoices received from SDI with `DatiRitenuta` RT01 or RT02 become a withholding on arrival (`source: sdi`). `POST /v1/withholdings/sync` reads the ones received earlier (100 per call, `has_more`). Getbeel derives the amounts the way the CU wants them: | Field | CU | How | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `gross_amount` | punto 4 | Lines without VAT + cassa contribution subject to withholding. The integrative contribution (cassa without `Ritenuta` SI) is left out | | `not_subject_amount` | punto 7 | The rest: expenses advanced, the non-subject share of commissions (50% or 80%) | | `taxable_amount` | punto 8 | The base the issuer applied the rate to: the lines with `Ritenuta` SI, or the share that matches `ImportoRitenuta` | | `withheld_amount` | punto 9 | Sum of `ImportoRitenuta` of the RT01/RT02 blocks | When the figures do not add up, the professional's codice fiscale is missing (the CU needs it) or the invoice has a discount on the total, the withholding has `needs_review: true` and `notes` says why. `status`: - `unpaid`: you have not paid the fee yet, so nothing is withheld yet. When you pay: `PATCH /v1/withholdings/{id}` with `paid_on`. - `withheld`: fee paid, withholding to pay by `due_date` (the 16th of the next month, moved to the next working day). `overdue` after that. - `remitted`: paid with an F24 recorded in Getbeel. It no longer changes (`409 withholding_remitted`). - If a fee changes after the F24 was prepared, compute the F24 again: paid as it is, it remits only the fees that stayed the same; the others stay due. - A fee recorded after the month's F24 was paid, or an F24 prepared with `amount`: if that withholding was in the paid F24, `PATCH` with `{ "remitted": true }` links and locks it (`409 no_paid_filing` when the month has no paid F24). - Test keys do not see withholdings (real data about professionals, like received invoices). A fee that did not come through SDI (paper invoice, receipt for occasional work): ```bash curl -X POST https://www.getbeel.com/api/v1/withholdings \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "recipient": { "name": "Luca Bianchi", "fiscal_code": "BNCLCU85M01H501Z" }, "causale": "M", "rate": "20", "gross_amount": "500.00", "paid_on": "2026-10-20" }' ``` `withheld_amount` is computed when left out: (`gross_amount` − `not_subject_amount`) × `rate`. ## The month's F24 [#the-months-f24] `POST /v1/filings` with `{ "type": "withholdings", "period": "2026-10" }` adds up the withholdings with `paid_on` in the month and prepares the F24 (Erario section, code 1040, month `10`, year `2026`). See [Filings](/en/api/filings). Once the receipt is uploaded, those withholdings become `remitted`. ## Certificazione Unica and 770 [#certificazione-unica-and-770] ```bash curl "https://www.getbeel.com/api/v1/withholdings/cu?year=2026" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Per percipiente and causale, the fees **paid** in the year (the payment date counts): gross (punto 4), sums not subject (7), taxable (8), withheld (9), and how much was paid with F24s recorded in Getbeel. `form_770` lists per month the withholdings made, the amount paid and the date (quadro ST, section I: punti 1, 2, 7, 11, 14). `format=csv` returns a spreadsheet (semicolons, comma decimals). Deadlines (CU 2026 instructions, tax year 2025; for 2026 fees the CU 2027 instructions of January 2027 apply): CU to the percipiente by 16 March; to the Agenzia by 16 March, or by 30 April for habitual self-employment (causale A) and non-occasional commissions; 770 by 31 October. Getbeel does not prepare the file sent to the Agenzia and does not sign the CU: this is the data to check and give to whoever files it (often the accountant), or to type into the Agenzia's software. ## Sources [#sources] - [FatturaPA technical specifications, Allegato A, version 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) and [XSD 1.2.3](https://www.fatturapa.gov.it/it/norme-e-regole/documentazione-fattura-elettronica/formato-fatturapa/): `DatiRitenuta` (0..N), `TipoRitenuta` RT01–RT06, `CausalePagamento`, `Ritenuta` on lines and cassa, controls 00411 and 00415. - Art. 25 and 25-bis DPR 600/1973 (20% withheld when the fee is paid; commissions) and art. 18 D.Lgs. 241/1997 (payment by the 16th). - [Tax code 1040](https://www1.agenziaentrate.gov.it/servizi/codici/ricerca/SezioneErario.php?CT=1040) and [Risoluzione 13/E of 17 March 2016](https://www.agenziaentrate.gov.it/portale/documents/20143/303158/Risoluzione+n.+13+del+17+marzo+2016_RIs+13e+del+17.03.16.pdf/21945510-c111-1c5d-bc36-ea35db076953) (from 2017 code 1038 for commissions is merged into 1040). - [Certificazione Unica 2026 instructions](https://www.agenziaentrate.gov.it/portale/documents/20143/9602395/CU_istruzioni_2026.pdf/4184818b-05a3-acce-5956-70811c7d2233), "Certificazione lavoro autonomo, provvigioni e redditi diversi"; Modello 770/2026 instructions, quadro ST. # Overview (https://docs.getbeel.com/en/guide/analytics/dashboard) The app's first page: the month's activity, the Get started list and the next tax deadlines. **Overview** is the page that opens after you log in. It tells you what happened this month and what is left to do. ## Before you start [#before-you-start] - **A team** where you have the **Owner** or **Member** role. The **Accountant** does not see the Overview. - **No setup needed**: the page fills in as you use Getbeel. - **Cost:** the page is free ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Read the month's activity [#read-the-months-activity] Open **Overview** in the sidebar. Under the title you find, for example, "This month: 42 invoices collected · 8 issued · 8 SDI sends". ### Complete the Get started list [#complete-the-get-started-list] **Get started** shows the missing steps, in order. Choose your path in **Set up for**: **Business**, **Developer** or **Accountant**. To change it, use **Change path**. Click a step to open the right page. When you are done, choose **Hide**. ### Check the tax deadlines [#check-the-tax-deadlines] For Italian companies, **Next tax deadlines** lists the upcoming payments. Choose **All deadlines** to open **Taxes**. ### Go where you need to [#go-where-you-need-to] In the **Go to** column you find **Received invoices**, **Issued invoices**, **Taxes**, **Reconciliation**, **Settings** and **API keys & MCP**. ## What just happened [#what-just-happened] - **You know the month's numbers**: invoices collected, issued and sent to SDI. - **The setup steps are done**, and the list ticks itself off. - **You know what is due**, with a link to each deadline. - **The main pages** are one click away. ## The Get started steps [#the-get-started-steps] | Path | Steps | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Business** | Complete your company details, Connect an inbox, Connect your bank, Issue your first e-invoice, Connect Stripe, Create an API key | | **Developer** | Complete your company details, Create a test key, Send a test invoice, Connect Claude or Cursor, Connect an inbox, Connect your bank | | **Accountant** | Complete your company details, Add a client company, Connect an inbox, Connect your bank, Issue your first e-invoice, Create an API key | Issuing invoices and connecting Stripe appear only for Italian companies. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------ | ---------------------------------------------------------- | ------------------------------- | | "We couldn't update the list. Try again." | The change to the list was not saved | Reload the page and try again | | "We couldn't save your choice. Try again." | The chosen path was not saved | Choose the path again | | "No deadlines in the next months." | There are no payments due, or the tax settings are missing | Check the settings in **Taxes** | | The **Get started** list is gone | You hid it | Choose **Show “Get started”** | ## Next steps [#next-steps] The Get started steps, explained one by one. The Overview's deadlines, with amounts and F24. Spending and earnings from bank transactions. # Analytics and dashboard (https://docs.getbeel.com/en/guide/analytics) Where to see your company's numbers: the Overview, the list of received invoices and the Analytics of bank transactions. Getbeel shows your company's numbers on three pages. Each one starts from different data: knowing which stops you comparing figures that do not add up. ## The three pages [#the-three-pages] | Page | From which data | What it is for | | --------------------- | --------------------------------------- | --------------------------------------------------------- | | **Overview** | The month's activity and deadlines | See what is left to set up and the next deadlines | | **Received invoices** | Supplier invoices | Search, filter and export invoices | | **Analytics** | Bank transactions in **Reconciliation** | Spending, earnings, vendors and profit and loss by period | ## Overview [#overview] It is the first page after you log in. It shows the invoices collected, issued and sent to SDI this month, the **Get started** list and the **Next tax deadlines**. See [Overview](/en/guide/analytics/dashboard). ## Received invoices [#received-invoices] The list of supplier invoices, from email, SDI and uploads. Search by vendor or number, filter by category, source and dates, and export to CSV, Excel or ZIP. See [Invoice list and search](/en/guide/analytics/invoice-list). ## Analytics [#analytics] Analytics counts **bank transactions**, not invoices. Without uploaded statements or a connected bank it is empty. See [Spending analytics](/en/guide/analytics/spending-analytics). For numbers calculated from invoices (accrual profit and loss, receivables by due date) use the [management reports](/en/guide/report-e-commercialista) in **Taxes**. ## Who sees them [#who-sees-them] **Owner** and **Member** see all three pages. The **Accountant** does not see **Overview** and **Analytics**; they see their clients' invoices from their own sidebar. ## Related [#related] The month's summary and the steps left to complete. Find and export received invoices. Spending and earnings from bank transactions. Reports from invoices and the export for your accountant. # Invoice list and search (https://docs.getbeel.com/en/guide/analytics/invoice-list) Find a received invoice, filter by period, category and source, and export the list to CSV, Excel or ZIP. **Received invoices** is the list of supplier invoices, from email, SDI and uploads. Here you search for an invoice, filter the list and export it. ## Before you start [#before-you-start] - **Invoices in Getbeel**: from a [connected inbox](/en/guide/invoice-management/gmail-integration), from SDI or uploaded by hand. - **Any role.** Everyone can search and export; the **Accountant** cannot delete or change categories. - **Cost:** searching and exporting are free ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Open the list [#open-the-list] Open **Received invoices** in the sidebar. The **All** tab shows every invoice; **Missing PDF** only those without a document. ### Search for an invoice [#search-for-an-invoice] Type in **Search vendor or invoice #...**. The list updates as you type. ### Filter the list [#filter-the-list] Narrow it down with the filters: - **Status**: **All statuses** or **Missing PDF**. - **Category**: **All categories** or a single one. - Source: **All sources**, **SDI** or **Email and uploads**. - **Date range**: **All time**, **This month**, **Last month**, **Last 3 months**, **This year** or **Select dates**. Click a column header to sort by vendor, number, date, amount or category. ### Open the details [#open-the-details] Click a row, or choose **View details** from the row menu. The panel shows **Vendor information**, **Invoice details** (number, type, date, due date, category), the **Line items** and **Subtotal**, **Tax** and **Total**, next to the document. ### Export [#export] Select the rows, or **Select all … invoices** in the filter, and choose **Export**. Pick the format, then **Download**: - **CSV**: plain comma-separated values. - **Excel**: a formatted spreadsheet (.xlsx). - **ZIP**: the data file with the PDF attachments. ## What just happened [#what-just-happened] - **You see the invoices** in the tab you need. - **The search** found the invoice by vendor or number. - **The filters** stay in the page address: you can share it with your team. - **The details** show the data read by the AI next to the document. - **The export** is downloaded in the format you chose. ## Other actions [#other-actions] - **Download** (row menu): the original document. - **Delete** (row or selection): removes the invoices. It cannot be undone. - **Category**: change it from the row; see [Categories and rules](/en/guide/invoice-management/categories-rules). - **Rows** per page: 25, 50, 100 or 250. Invoice statuses and review are in [Invoice workflow](/en/guide/invoice-management/invoice-workflow). ## If it fails [#if-it-fails] | Message | Cause | Fix | | --------------------------- | --------------------------------------------- | ------------------------------------------------- | | "No invoices found" | No invoice matches the search and filters | Use **Clear** on the filters or widen the period | | "No PDF attachments found" | The selected invoices have no document | Export to CSV or Excel, or upload the missing PDF | | "Export failed" | The file could not be created | Try again with fewer invoices | | "Failed to delete invoices" | You lack the permission or the request failed | Check your role and try again | ## Next steps [#next-steps] Invoice statuses and how to review them. Sort invoices by category, automatically too. The full export of the period for your accountant. # Spending analytics (https://docs.getbeel.com/en/guide/analytics/spending-analytics) The Analytics page: spending, earnings, vendors and profit and loss by period, calculated from the bank transactions in Reconciliation. **Analytics** shows the trend of the transactions in **Reconciliation**: how much went out, how much came in and whom you paid. The numbers come from bank transactions, not from invoices. ## Before you start [#before-you-start] - **Bank transactions in Getbeel**: [upload a statement](/en/guide/bank-reconciliation/statement-upload) or [connect your bank](/en/guide/collega-la-banca). Without transactions the page is empty. - **The Owner or Member role.** The **Accountant** does not see Analytics. - **No need** for the transactions to be matched to invoices yet. - **Cost:** the page is free ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Open Analytics [#open-analytics] Open **Analytics** in the sidebar. It opens on **This month**. ### Choose the period [#choose-the-period] Choose **This month**, **Last month**, **This quarter**, **This year** or **All time**. For other dates, pick a range in the calendar. ### Read the totals [#read-the-totals] At the top you find **Total spent**, **Total earnings**, **Total transactions** and **Unique vendors**. Spent and earnings show the percentage change against the previous period. ### Look at spending and profit and loss [#look-at-spending-and-profit-and-loss] **Monthly spending** splits each month's payments out by vendor. **Profit and loss** compares **Revenue** and **Expenses**, with **Net profit / loss**. Open an expense line to see the vendors. ### Compare vendors [#compare-vendors] **All vendors** lists whom you paid, with **Total spent**, **Avg transaction**, **Count** and **Last transaction**. ## What just happened [#what-just-happened] - **You opened the page** on the current month's transactions. - **The chosen period** applies to all totals, charts and the list. - **The totals** show whether you spend or earn more than in the previous period. - **Profit and loss** shows the balance between money in and money out of the account. - **The vendor list** shows where the spending goes. ## How Getbeel counts [#how-getbeel-counts] - **Money out**: every transaction with a negative amount. **Money in**: every positive transaction. - **Revenue** is grouped by counterparty. **Expenses** by the bank's transaction type, not by invoice category. - **Previous period**: the month before, the quarter before or the year before. **All time** and hand-picked dates have no comparison. - **Currency**: amounts are added up as they are, without conversion. These numbers are cash movements, VAT included. For the accrual profit and loss, from invoices and net of VAT, use the [management reports](/en/guide/report-e-commercialista). ## If it fails [#if-it-fails] | Message | Cause | Fix | | -------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------ | | "Upload a bank statement to generate your profit and loss statement" | There are no bank transactions | Upload a statement or connect your bank | | "No data available" | No transactions in the chosen period | Choose **All time** or another range | | "No revenue recorded" | No money came in during the period | Check that the statement also contains money coming in | | A month is missing | That month's statement was not uploaded | Upload the missing statement in **Reconciliation** | ## Next steps [#next-steps] Profit and loss and cash flow from invoices. Where the Analytics transactions come from. Supplier invoices, one by one. # Autofatture (https://docs.getbeel.com/en/guide/autofatture) Purchases from foreign suppliers, from the bank statement to the self-invoice sent to SDI. *Video tutorial coming soon.* When you buy from a foreign supplier, for example a software subscription, you account for the VAT with an **autofattura** (self-invoice) and send it to SDI. Getbeel finds these purchases in your bank movements and prepares the XML. ![The list of autofatture with their SDI status: delivered, issued in the cassetto fiscale, already issued (duplicate).](/screenshots/autofatture.en.webp) ## Which document type [#which-document-type] Getbeel suggests the document type for each purchase. You check it before sending. | Code | Official description | Example | | ------ | ------------------------------------------------------------------------ | ------------------------------------------------- | | `TD17` | Integrazione/autofattura per acquisto servizi dall'estero | SaaS subscription, online advertising | | `TD18` | Integrazione per acquisto di beni intracomunitari | Goods bought from an EU supplier | | `TD19` | Integrazione/autofattura per acquisto di beni ex art. 17 c. 2 DPR 633/72 | Goods already in Italy sold by a foreign supplier | Source: Agenzia delle Entrate, [FatturaPA technical specifications, Allegato A, version 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1), and [Guida alla compilazione delle fatture elettroniche e dell'esterometro](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guida_compilazione-fe-esterometro-v1-10_aprile_2025), version 1.10 (April 2025). All codes: [Tipo documento](/en/api/reference-data/tipo-documento). ## Foreign invoices you receive become proposals [#foreign-invoices-you-receive-become-proposals] When an invoice from a foreign supplier reaches Getbeel through the email scan, the forwarding address or an upload, Getbeel proposes the autofattura on its own. This applies to Italian companies, and only to invoices that do not come through SDI. - **The rule decides the document type, not the AI.** Services from a foreign supplier (for example Vercel, Cloudflare, OpenRouter, Supabase, Resend in the United States, Trigger.dev in the United Kingdom): `TD17`. Goods shipped from another EU country: `TD18`. Goods already in Italy: `TD19`. Goods imported from outside the EU go through customs: no TD, no proposal. - **The XML is generated as a draft.** Sending it to SDI is always your action. - **One autofattura per purchase.** If the purchase already has one from a bank payment matched to the invoice, or the same invoice (supplier and number) was already proposed or imported, Getbeel does not create another. The **Import sources** import also skips an invoice that already has one. - **Your changes stay.** If you delete a proposal or edit it (for example you set the country), Getbeel never brings it back or overwrites it when the invoice is saved again. Deleting the received invoice deletes its proposal if it was not sent to SDI; one already sent stays and is marked. - **The exchange rate** is the one of the invoice date (art. 13, c. 4, DPR 633/72). - **The date of the purchase** (non-EU suppliers) is taken from the invoice date. By law a service takes place when it is completed or, if periodic, when the fee falls due, or earlier when you pay it earlier (art. 6, c. 6, DPR 633/72): if it differs, correct the **Data** in the details. Some proposals are listed **to check** and are not generated on their own: unknown supplier country (**Country missing**: enter it in **IdPaese**), goods or services unclear, VAT charged by the supplier, only a payment notice, deadline already passed, possible duplicate of a bank payment, date of receipt unknown (EU suppliers: the deadline is then counted from the invoice date), supplier in Northern Ireland. When the supplier's tax ID is missing the XML uses `OO99999999999`: a common convention, but not written in the Agenzia's guide or specifications, so the row is flagged to check. ### When to send it [#when-to-send-it] By the **15th of the following month** (art. 1, c. 3-bis, lett. b, d.lgs. 127/2015): | Supplier | The month that counts | Autofattura date (`Data`) | | ----------------------------------------- | ---------------------------- | -------------------------------------------- | | EU (integrazione), Northern Ireland goods | receipt of the invoice | date of receipt, or a date in the same month | | Non-EU, San Marino (services), Vatican | the purchase (effettuazione) | date of the purchase | The date of receipt is the date of the email for the email scan and the forwarding address, and the invoice date for an upload (the earliest it can be). **Northern Ireland (`XI`).** Under the Windsor Framework EU VAT rules still apply to goods in Northern Ireland: goods from an `XI` supplier are an intra-EU purchase (`TD18`), services follow the UK (`TD17`). Whether SDI accepts `XI` as **IdPaese** is not confirmed, so these proposals are always to check. Getbeel shows the deadline in the list (**Send by …**), always the 15th, without moving it when it falls on a Saturday or a public holiday. In the [VAT registers](/en/guide/tasse) a foreign purchase received since these proposals exist, with no autofattura sent, is listed as missing. It counts as covered by any autofattura sent for the same supplier with the same invoice number, or with a close amount in the same or the next month, even when it is not matched to the invoice. Older purchases are never listed, so closed periods do not change. and a foreign invoice whose country is unknown is not counted as Italian: its VAT is not deducted. Sources: AdE, Guida alla compilazione delle fatture elettroniche e dell'esterometro v1.10 (1 April 2025), sections TD17, TD18, TD19; Specifiche tecniche Allegato A v1.9.1 (checks 00473 and 00475); DPR 633/72 arts. 7-ter, 13, 17 c. 2, 21 c. 4 lett. d, 6 c. 6; DL 331/93 arts. 46 and 47; Ris. 89/E/2010; Circ. 26/E/2022; Northern Ireland: Windsor Framework (Protocol on Ireland/Northern Ireland, art. 8) and the European Commission's guidance on the GB and XI codes. From 1 January 2027 the Testo unico IVA (D.Lgs. 10/2026) renumbers the articles: art. 17 → 64, 7-ter → 17, 13 → 27, 21 → 72, DL 331/93 art. 46 → 97, art. 47 → 98, d.lgs. 127/2015 art. 1 c. 3-bis → art. 77 c. 4. ## Before you start [#before-you-start] - **An Italian company**: **Autofatture** appears in the sidebar only for Italian companies. - **Complete tax details** in **Settings → Company**: the autofattura carries your details as the buyer (cessionario). - **Bank movements** in **Reconciliation**, from a bank statement or a [connected bank](/en/guide/collega-la-banca). Alternatively, import invoices or a CSV of foreign suppliers. - **The SDI add-on turned on.** Each autofattura you send counts as one SDI send ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Bring foreign payments into Autofatture [#bring-foreign-payments-into-autofatture] Movements from the statements in **Reconciliation** arrive on their own. For other sources press **Import sources** and choose **Bank statement**, **Single invoice** or **Foreign providers CSV**. ### Generate the autofatture [#generate-the-autofatture] Select the rows and press **Generate**, or press **Create** on a single row. Getbeel fills in the supplier, country, amount and document type. ### Check the data [#check-the-data] Open the row with **Details**. Correct it with **Edit details**, then press **Regenerate XML** to apply the changes. ### Send to SDI [#send-to-sdi] On the detail page press **Send to SDI**, or select several rows and press **Send to SDI**. Follow the status as for [issued invoices](/en/guide/emettere-fatture). ## What just happened [#what-just-happened] - **Foreign payments became rows to self-invoice**, one per movement. - **The XML was generated** with the document type, natura and legal reference. - **Your checks are in the XML**: each change applies after **Regenerate XML**. - **The autofattura is at SDI.** The status updates on its own: **Delivered**, **Issued · in cassetto fiscale**, **Rejected** or **Already issued · duplicate**. You cannot delete an autofattura already sent to SDI: **Delete** skips it. ## If it fails [#if-it-fails] | Message | Cause | Fix | | -------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | "No foreign-provider transactions to generate from this bank statement." | The statement has no payments to foreign suppliers | Choose another statement or import the invoices | | **SDI add-on required** | The account has no SDI add-on | Open **Settings → Usage & billing** | | "SDI would reject this XML: nothing was sent. …" | A field fails the SDI checks | Correct it with **Edit details** or regenerate the XML, then send it again | | "IdDocumento must be a 1-20 character supplier reference, not a transaction ID." | The reference to the supplier's invoice is not valid | Enter the supplier's invoice number | | **Issued · in cassetto fiscale** | SDI could not deliver it to you | It is issued: do not resend it. Register your [codice destinatario](/en/guide/codice-destinatario) | | **Country missing** | The supplier's country is unknown | Open **Details**, enter the country code in **IdPaese** (e.g. `US`, `IE`) and press **Create** | | "TD18 is only for goods from another EU country. …" | TD18 chosen for a supplier outside the EU | Use `TD17` (services) or `TD19` (goods already in Italy); imported goods need no autofattura | ## Next steps [#next-steps] Upload the statements that autofatture come from. Autofatture go into the VAT registers and the liquidazione IVA. Receive your autofatture as the recipient too. # AI transaction matching (https://docs.getbeel.com/en/guide/bank-reconciliation/ai-matching) The rules Getbeel uses to match each payment out of your account to a received invoice, and when it confirms on its own. Getbeel matches each payment out of your account to a received invoice only if amount, date and supplier agree. A doubtful suggestion is never confirmed on its own: you decide it. ## The rules [#the-rules] | Rule | What Getbeel checks | | ---------------- | ---------------------------------------------------------------------------------- | | Direction | Payments out only. Money coming in is not matched to invoices | | Amount | Equal to the invoice, with at most 1 cent of difference | | Foreign currency | Invoice in another currency: compared with the converted amount, 5% tolerance | | Date | Within 7 days of the invoice date or its due date | | Supplier | The name on the transaction must match the invoice's supplier | | One to one | Each transaction goes with one invoice only, and each invoice with one transaction | The AI suggests the pairs. Getbeel re-checks amount and date before saving and drops the suggestions that do not agree. ## Which invoices it considers [#which-invoices-it-considers] Getbeel looks at received invoices dated within the statement's period, widened by 30 days before and after. When the file has no period, it looks at the last 90 days. Invoices with status **Missing PDF** are left out. For a connected bank, invoices already matched to another payment are left out too. ## Supplier names [#supplier-names] Banks often shorten a name or use a trading name. Getbeel recognises, for example, "Bunnycdn" as "BUNNYWAY" or "Google Workspace" as "Google Cloud Italy". Before comparing, it removes company forms (S.r.l., Inc., GmbH, Ltd) and punctuation. ## What each transaction becomes [#what-each-transaction-becomes] Each suggestion has a confidence score from 0 to 1. The score decides whether you need to check it. - **Reconciled** straight away: confidence 0.9 or higher. Amount and supplier agree and no other invoice was plausible. - **To confirm**: confidence below 0.9. This happens when several invoices were plausible or the amount is not identical to the cent. - **Missing invoice**: no invoice meets the rules. Money coming in stays without an invoice and does not count towards the statement's progress. ## Different currencies [#different-currencies] If the invoice is in dollars and the account in euros, Getbeel uses the invoice amount converted into the company's currency. The 5% tolerance covers exchange differences and fees. Without a converted amount, the invoice is not suggested. ## If it fails [#if-it-fails] | Problem | Cause | Fix | | ---------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | A payment stays **Missing invoice** but the invoice exists | Different amount (partial payment) or a date beyond 7 days | Link it by hand with **Add invoice** ([Review workflow](/en/guide/bank-reconciliation/review-workflow)) | | The invoice is never suggested | It is **Missing PDF**, or its date is outside the period | Upload the PDF in **Received invoices**, then **Redo matching** | | Matched to the wrong invoice | Two invoices with the same amount and supplier | **Not this invoice**, then link the right one | | Money coming in has no invoice | Getbeel matches payments out only | Nothing to do: money coming in does not count towards progress | ## Next steps [#next-steps] Confirm the suggestions and resolve the missing invoices. More readable transactions, more exact matches. The invoices Getbeel searches for a match. # Bank reconciliation (https://docs.getbeel.com/en/guide/bank-reconciliation) Upload a bank statement or connect your bank: Getbeel matches each payment to the supplier invoice and you confirm. *Video tutorial coming soon.* **Reconciliation** matches each payment out of your account to the supplier invoice behind it. Getbeel suggests the matches; you confirm the right ones and flag what is missing. ![The Reconciliation page: statements uploaded or downloaded from the bank, with status, period, transactions and match rate.](/screenshots/reconciliation.en.webp) ## At a glance [#at-a-glance] | What | How it works | | ---------------------------- | ---------------------------------------------------------------------------------------------------- | | Where transactions come from | From a statement you upload, or from your [connected bank](/en/guide/collega-la-banca) every 6 hours | | What gets matched | Only payments out, to received invoices | | Who decides | You: confirm, reject or link by hand | | When it is finished | When you choose **Complete reconciliation** | ## Where transactions come from [#where-transactions-come-from] You have two ways in, and you can use both. - **Upload a statement.** CSV, PDF, Excel, text or a CBI, CAMT.053 or MT940 bank file, up to 50 MB. See [Statement upload](/en/guide/bank-reconciliation/statement-upload). - **Connect your bank.** Transactions arrive on their own every 6 hours. Getbeel creates one statement per account and per month. See [Connect your bank](/en/guide/collega-la-banca). ## How Getbeel matches [#how-getbeel-matches] For each payment out, Getbeel looks for a received invoice with the same amount, a close date and the same supplier. Each invoice goes with one transaction only. Money coming in is not matched. The exact rules are in [AI transaction matching](/en/guide/bank-reconciliation/ai-matching). ## The status of each transaction [#the-status-of-each-transaction] Every statement row has a status. The status tells you the next action. | Status | What it means | What you do | | --------------------- | ----------------------------------------------------- | ----------------------------------------- | | **To confirm** | Getbeel found an invoice | **Confirm match** or **Not this invoice** | | **Reconciled** | The match is confirmed | Nothing | | **Missing invoice** | A payment out with no invoice | **Add invoice**, or **No invoice needed** | | **No invoice needed** | You marked that no invoice is needed (e.g. bank fees) | Nothing | | **Rejected** | The match was rejected | Link the right invoice | How to work through these statuses is explained in [Review workflow](/en/guide/bank-reconciliation/review-workflow). ## The status of a statement [#the-status-of-a-statement] | Status | What it means | | ------------------- | --------------------------------------------------------- | | **Pending** | The file is uploaded and about to be read | | **Processing** | Getbeel is reading the transactions in the file | | **Matching** | Getbeel is looking for the invoice of each payment out | | **Ready to review** | The matches are ready for you | | **Completed** | You completed the reconciliation: it can no longer change | | **Failed** | The file could not be read: use **Retry** | The page refreshes on its own while a statement is processing. ## The Reconciliation page [#the-reconciliation-page] The list shows each statement with **File**, **Status**, **Period**, **Transactions**, **Match rate** and **Uploaded**. Filter by month with **All months**. At the top you see your **Total statements**, how many are **Pending review** and the **Total matched**. From the **More actions** menu (⋯) open **Connect your bank**. ## Who can do what [#who-can-do-what] - **Owner** and **Member** upload statements, connect the bank and review matches. - **Accountant** sees statements and matches and exports them, but changes nothing. See [Roles and permissions](/en/guide/team-collaboration/roles-permissions). ## From the API and the AI assistant [#from-the-api-and-the-ai-assistant] The same operations are available through the [API](/en/api/bank-reconciliation) and the MCP tools: `upload_bank_statement`, `list_bank_statements`, `get_bank_statement`, `get_reconciliation`, `list_unmatched`, `approve_match`, `match_manually` and `start_reconciliation`. ## Related [#related] The accepted formats and what happens after the upload. Transactions arrive on their own, with no files to upload. The rules Getbeel uses to suggest an invoice. Confirm, correct and complete a statement. # Review workflow (https://docs.getbeel.com/en/guide/bank-reconciliation/review-workflow) Confirm the suggested matches, resolve missing invoices and complete the reconciliation of a bank statement. Getbeel suggests the matches; you decide. A statement is finished when every payment out is **Reconciled** or **No invoice needed** and you choose **Complete reconciliation**. ## Before you start [#before-you-start] - **A statement in status Ready to review.** Upload one ([Statement upload](/en/guide/bank-reconciliation/statement-upload)) or [connect your bank](/en/guide/collega-la-banca). - **The Owner or Member role.** The **Accountant** role sees and exports, but cannot change anything. - **No need** to check rows already **Reconciled**: Getbeel confirmed them because it was sure. - **Cost:** confirming is free. Uploading a missing invoice uses one invoice credit ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Open the statement [#open-the-statement] Open **Reconciliation** and click the statement. At the top you see the progress, for example "12 of 40 expenses done". ### Show only what needs you [#show-only-what-needs-you] Use the filters above the table: - **All**, **To confirm**, **Missing invoice** or **Done**. - **Expenses**, **Earnings** or **All directions**. When the statement opens, you see only **Expenses**. - **Search transactions** by name or description. ### Confirm the suggestions [#confirm-the-suggestions] On **To confirm** rows, check the transaction and the invoice. Click the invoice to open its details. Then choose **Confirm match** (✓) or **Not this invoice** (✕). To confirm many at once, select them and choose **Confirm matches** in the bar at the bottom. ### Resolve missing invoices [#resolve-missing-invoices] On a **Missing invoice** row, choose **Add invoice**. In **Link invoice**, search for an existing invoice, or drop the PDF or image (up to 10 MB). If the transaction has no invoice, such as a bank fee, open the row menu and choose **No invoice needed**. ### Add a missing transaction [#add-a-missing-transaction] If the file did not contain a transaction, choose **Add transaction**. Enter the date, counterparty, description, amount and type (**Debit** or **Credit**). ### Complete the reconciliation [#complete-the-reconciliation] When you are done, choose **Complete reconciliation** and then **Complete**. After that you can no longer change the statement. ## What just happened [#what-just-happened] - **You opened the statement** and saw how many payments out are still to decide. - **You filtered** the rows that need an action. - **The right suggestions are Reconciled.** The wrong ones went back to **Missing invoice**. - **Every payment out has its invoice**, or is marked **No invoice needed**. - **The added transaction** appears in the statement like the others. - **The statement is Completed** and stays read-only. ## Correct a decision [#correct-a-decision] - **Remove match** (row menu): the row goes back to **Missing invoice**. - **Needs an invoice**: undoes a **No invoice needed**. - **Delete transaction**: removes the transaction and its match from the statement. - **Redo matching** (at the top): deletes transactions and matches and reads the file again from scratch. For a connected bank it only redoes the matches. ## Export [#export] Select the rows, or **Select all … matches** in the filter, and choose **Export**. The formats are: - **CSV**, which opens in spreadsheets. - **Excel**, with formatted columns. - **ZIP archive**, with the data file and the PDFs of the matched invoices. - **Autofattura XML**, for rows that have an _autofattura_ (self-invoice). The columns include date, transaction, counterparty, amount, matched invoice, match type and status. On an uploaded statement, confirmations and manual links are deleted and rebuilt from the original file. Use it only if the file was read wrongly. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | "Could not save the change" | The change did not reach the server | Reload the page and try again | | "No matches to confirm in this selection" | The selected rows are not **To confirm** | Filter **To confirm** and select again | | "No missing invoices in this selection" | The selected rows already have an invoice | Filter **Missing invoice** and select again | | "No invoice credits left. Upgrade your plan or buy more invoices." | Uploading an invoice uses a credit | Add credits in **Settings → Usage & billing**, or link an existing invoice | | "Could not restart matching. Try again or contact support." | Too many restarts today, or an _autofattura_ from the file is already at SDI | Try again tomorrow; if the statement has sent _autofatture_, correct it by hand | | "Could not complete the reconciliation" | Saving failed, or the statement is no longer **Ready to review** | Reload the page, check the status and try again | ## From the AI assistant [#from-the-ai-assistant] With MCP, `get_reconciliation` reads the rows and `list_unmatched` the payments out with no invoice. `approve_match` confirms a row, or rejects it with `decision: "reject"`. `match_manually` links an invoice by hand. See [Connect your AI](/en/guide/connect-ai). ## Next steps [#next-steps] Payments to foreign suppliers become _autofatture_. Cash flow and the export use the matched transactions. Why a row is To confirm or Missing invoice. # Statement upload (https://docs.getbeel.com/en/guide/bank-reconciliation/statement-upload) Upload a bank statement (CSV, PDF, Excel, text, CBI, CAMT.053 or MT940): Getbeel reads the transactions and matches them to invoices. Upload your bank statement and Getbeel reads its transactions, then matches them to your received invoices. CBI, CAMT.053 and MT940 bank files are read exactly, without AI. ## Before you start [#before-you-start] - **The statement file**, downloaded from your online banking. Accepted formats: - **CBI** (_Rendicontazione movimenti_, the Italian transaction report), **CAMT.053** (XML) and **MT940**: read field by field, without AI. - **CSV**, **PDF** and **text**: read with AI. - **Spreadsheets** (XLS, XLSX, ODS): not read. Export the sheet as CSV and upload the CSV. - **A file up to 50 MB.** You can upload several at once. - **The Owner or Member role.** The **Accountant** cannot upload statements. - **An active plan.** Reading and matching use AI ([Pricing](/en/api/pricing)). - **Not needed** if you [connected your bank](/en/guide/collega-la-banca): transactions arrive on their own. ## Steps [#steps] ### Open the upload [#open-the-upload] Open **Reconciliation** and choose **Upload statement**. ### Choose the files [#choose-the-files] Drop the files in the box or choose **browse**. You can add more before uploading; each file becomes a statement. ### Set the currency [#set-the-currency] In **Statement currency**, choose the account's currency (euro by default). CBI, CAMT.053 and MT940 files already declare their currency. ### Upload [#upload] Choose **Upload & process**. The statement moves from **Processing** to **Matching**, then to **Ready to review**. The page refreshes on its own. ## What just happened [#what-just-happened] - **You opened the upload** on the Reconciliation page. - **Each file is a statement** in the list, with its name, period and number of transactions. - **The currency** applies to transactions in files that do not state one. - **Getbeel read the transactions** and looked for the invoice of each payment out. You can now [review the matches](/en/guide/bank-reconciliation/review-workflow). ## How bank files are read [#how-bank-files-are-read] Getbeel recognises the format from the content, not from the file name. - **CAMT.053**: ISO 20022 XML `BankToCustomerStatement`, versions 001.02 to 001.13. - **CBI**: 120-character records, RH (transactions) or EC (statement) flow. - **MT940**: SWIFT message with the tags `:20:`, `:25:`, `:60F:`, `:61:`, `:86:`, `:62F:`. The opening balance plus the transactions must equal the file's closing balance. If it does not, a transaction was misread: Getbeel reads the file again with AI. A file with more than 50,000 transactions is not imported. Split it by period. ## Manage statements [#manage-statements] From each row's menu you can: - **View statement** and **Download file**: the original file. - **Rename**: change the name shown. - **Redo matching** or, if it is **Failed**, **Retry**: reads the file again from scratch. - **Delete**: removes the statement with its transactions and matches. It cannot be undone. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------- | | "statement.xls" is a spreadsheet: Getbeel does not read Excel or ODS files. Export the sheet as CSV and upload the CSV. | The file is a spreadsheet (even if renamed) | Export the sheet as CSV and upload the CSV | | "statement.zip" is not a supported statement file. Use CSV, PDF or text. | Extension not accepted | Export from your bank as CSV, PDF or a bank format | | "statement.pdf" is larger than 50MB. | The file is larger than 50 MB | Download a shorter period | | Could not process "statement.csv". Try again or contact support. | The upload did not start | Try again; if it happens again, contact support | | Status **Failed** | Unreadable file, or more than 50,000 transactions | Split the file, then **Retry** from the row menu | | The upload asks for a plan | Reading and matching need an active plan | Choose a plan in **Settings → Usage & billing** | | "Could not restart matching. Try again or contact support." | Too many restarts today | Try again tomorrow | ## Sources [#sources] The exact readers follow the official specifications, cited in the code (`apps/web/lib/bank-statements/parsers`): - **CBI**: CBI Consortium, "CBI-RND-001 Rendicontazioni – Standard tecnici" v6.05 (05-03-2013), §2.1–2.8. The official distribution is reserved to CBI members; the text was read from a public copy. - **CAMT.053**: official schemas camt.053.001.02–.13 (iso20022.org, Message Definitions) and ISO 20022 MDR Part 2 "Bank-to-Customer Cash Management" 2020-2021 (§6.1.5.2, §6.1.9.2). - **MT940**: SWIFT Standards MT, Category 9. The SWIFT manual is restricted and was not read directly: the field rules come from DK "DFÜ-Abkommen" Anlage 3 v3.7 (05.04.2023) §8, checked against ING's MT940/MT942 description (2016). ## Next steps [#next-steps] Confirm the matches of the statement you just uploaded. Stop uploading files: transactions arrive every 6 hours. Upload statements from code or with `upload_bank_statement`. # Fixed assets and depreciation (https://docs.getbeel.com/en/guide/cespiti) Register business assets, also from a received invoice: Getbeel computes the tax depreciation, disposals and the year's libro cespiti. In **Taxes → Fixed assets** you keep your business assets (_cespiti_): computers, machinery, furniture, vehicles, software. Each year Getbeel computes the quota, accumulated depreciation and residual value, the gain or loss on sale, and the **libro cespiti** (fixed asset register). Getbeel computes **tax** depreciation from the data you enter. Your accountant checks categories, statutory depreciation and year-end entries: Getbeel keeps no general ledger. ## Before you start [#before-you-start] - **The asset's data**: cost, purchase date and the date it entered into use. If the asset is on a received invoice in Getbeel, the rest comes from there. - **No need** to know the coefficient: you pick it with the category. - **Cost**: saving fixed assets is free ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Open the form [#open-the-form] Open **Taxes → Fixed assets** and choose **Add asset**. ### Start from the received invoice [#start-from-the-received-invoice] In **Received invoice**, pick the asset's invoice: date, supplier and number fill in on their own. In **Invoice line**, pick the asset's line to take over description and cost. Without an invoice, choose **None (enter by hand)**. ### Choose the category [#choose-the-category] In **Category (ministerial coefficient)**, pick the asset's entry: each has its own coefficient. If it is not there, choose **Other category: I enter the coefficient**. ### Enter cost and dates [#enter-cost-and-dates] Enter **Cost (€)**, net of deductible VAT and including ancillary costs. Then **Purchase date** and **In use since**. Leave **In use since** empty if the asset is not in use yet. ### Save [#save] Choose **Save**. The asset appears in the **Libro cespiti** with the year's quota. ## What just happened [#what-just-happened] - **The asset is in the libro cespiti** with cost, coefficient, accumulated depreciation and residual value for the chosen year. - **Depreciation replaces the cost**: in the [tax estimate](/en/guide/stima-imposte) the asset's invoice no longer counts as a cost; the quota counts instead. ## How depreciation is computed [#how-depreciation-is-computed] - Depreciation starts in the **year the asset enters into use**, not the purchase year (art. 102 c. 1 TUIR). - Each year you deduct at most **cost × ministerial coefficient**, **halved in the first year** (art. 102 c. 2). The half applies whatever the date: Getbeel does not count days. - The coefficient is a ceiling: you can deduct less, and the plan lasts more years. Quotas deducted in past years are recorded through the API (`depreciation_overrides`). - Tangible assets with a **unit cost up to €516.46** can be deducted in full in the year (art. 102 c. 5). For the self-employed the threshold is €516.40 (art. 54-quinquies). Turn on **Deduct in full this year**. - **Software, patents and know-how**: up to 50% a year. **Trademarks and goodwill**: up to 1/18 a year (art. 103). No first-year halving for intangible assets. - Amounts are rounded down to the cent, so they never exceed the maximum quota. ### Coefficients [#coefficients] The categories come from the **DM 31 dicembre 1988**, in the table in force since 16 May 1996 (DM 28 marzo 1996). Getbeel shows them with their official Italian names. These are the groups small businesses and professionals use most: | Asset ("Attività non precedentemente specificate – Altre attività") | Coefficient | | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | Edifici (buildings) | 3% | | Fabbricati destinati alla grande distribuzione (buildings for large-scale retail) | 6% | | Costruzioni leggere (light structures) | 10% | | Impianti e mezzi di sollevamento, carico, scarico, pesatura (lifting, loading and weighing equipment) | 7.5% | | Macchinari, apparecchi e attrezzature varie (machinery and equipment) | 15% | | Arredamento (fittings and furnishings) | 15% | | Mobili e macchine ordinarie d'ufficio (office furniture and ordinary office machines) | 12% | | Macchine d'ufficio elettromeccaniche ed elettroniche, computer, sistemi telefonici elettronici (computers and electronic office equipment) | 20% | | Impianti di allarme e di ripresa (alarm and camera systems) | 30% | | Autoveicoli da trasporto (goods vehicles) | 20% | | Autovetture, motoveicoli e simili (cars, motorcycles and similar) | 25% | There are also the entries of Gruppo 19 (hotels, restaurants, bars) and Gruppo XXII specie I (personal services). Professionals use the coefficient of the same asset in the matching business activity (art. 2 of the DM). Some limits are not computed. Getbeel flags them next to the category: - **cars**: 20% deductible (80% for agents), with a maximum cost of €18,075.99 (art. 164 TUIR); - **phones**: quotas 80% deductible (art. 102 c. 9); - **buildings**: the share of the cost for the land is not depreciated. ## Sell or scrap an asset [#sell-or-scrap-an-asset] ### Record the disposal [#record-the-disposal] On the asset's row, choose **Disposal**. Enter **Disposal date** and **Price (€)**: 0 if the asset was scrapped. Choose **Save**. Getbeel computes: - **gain** (_plusvalenza_) = price − cost not yet depreciated (art. 86 c. 2 TUIR); - **loss** (_minusvalenza_) if the price is lower (art. 101 c. 1). In the year of disposal Getbeel computes no quota: the whole residual value goes into the gain or loss. From 2026 the gain on a single asset is taxed in full in the year. Spreading over five years remains only for the sale of the business (art. 86 c. 4, as replaced by L. 199/2025 art. 1 c. 42). An asset entered by mistake is not a disposal. Select it, then **Delete**: it leaves the libro cespiti of every year. ## Libro cespiti and closing entries [#libro-cespiti-and-closing-entries] Pick the year and download the **Libro cespiti** with **CSV** or **Excel**. For each asset you get cost, coefficient, accumulated depreciation at 1 January, the year's quota, accumulated depreciation at 31 December, residual value and any disposal. Below it you find **closing entries (summary)**: depreciation quotas by category, assets deducted in full, and gains or losses. Give it to your accountant, who records them in the books. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------- | | "The coefficient is above the category's ministerial one (art. 102 c. 2 TUIR)." | The coefficient you entered is above the maximum | Use an equal or lower coefficient | | "Full deduction is only for tangible assets with a unit cost up to €516.46." | The asset costs more, or is intangible | Turn off **Deduct in full this year** | | "It cannot enter into use before the purchase date." | The dates are the wrong way round | Fix **Purchase date** or **In use since** | | "Give both the disposal date and the price." | A disposal field is missing | Enter both; 0 if the asset was scrapped | | "The received invoice you picked no longer exists." | The invoice was deleted | Choose **None (enter by hand)** | | "Saving needs an active plan: pick one in Settings → Usage & billing." | The account has no plan | Choose a plan in **Settings → Usage & billing** | ## Sources [#sources] - TUIR (DPR 917/1986), art. 86, 101, 102, 103, 164, 54-quinquies, text in force at 31 December 2026 ([Normattiva](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.presidente.repubblica:1986-12-22;917~art102!vig=2026-10-01)). From 1 January 2027 the TUIR is replaced by the Testo unico D.Lgs. 117/2026. - DM 31 dicembre 1988, depreciation coefficients ([Agenzia delle Entrate copy](https://www.agenziaentrate.gov.it/portale/documents/20143/1704562/Decreto+del+31_12_1988+-+Min.+Finanze+coefficienti+di+ammortamento.pdf/f7d5c11d-cc79-ecf7-efc8-f1fc90cc00a3)). - L. 30 dicembre 2025, n. 199, art. 1 c. 42–43 ([Normattiva](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2025-12-30;199~art1)). Not confirmed by an official source: that no quota is deducted in the year of disposal. It is the practice Getbeel follows. ## Next steps [#next-steps] Depreciation feeds the IRES, IRAP or forfettario estimate. Hand the libro cespiti and data to your accountant. Register fixed assets from your code or the AI assistant. # Codice destinatario (https://docs.getbeel.com/en/guide/codice-destinatario) What the codice destinatario is, how to register it with the Agenzia delle Entrate, and what changes with Getbeel. The **codice destinatario** (recipient code) is the 7-character code that tells SDI where to deliver the invoices addressed to you. If you register it as your _indirizzo telematico_ (electronic address), it applies to all your invoices, whatever code the supplier writes. ![An undelivered invoice (MC): it counts as issued, it has been in the cassetto fiscale since the date shown, and it must not be sent again.](/screenshots/invoice-not-delivered.en.webp) ## The rules in short [#the-rules-in-short] | | How it works | | ---------------------- | ---------------------------------------------------------------------------------------------------------------- | | Who assigns it | The channel that receives invoices for you: a software or an intermediary. Alternatively, you use a PEC address. | | Indirizzo telematico | The code (or PEC) you register in the **Fatture e Corrispettivi** portal. It overrides the one on the invoice. | | No registered address | SDI uses the code or PEC written by the supplier. | | Undeliverable invoices | They stay in your reserved area in Fatture e Corrispettivi. | | Sending invoices | You don't need to register anything: the code only concerns receiving. | Source: Agenzia delle Entrate, [La fattura elettronica e i servizi gratuiti](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guida_fattura_elettronica_dicembre_2025) (December 2025), pp. 18–20 and 25. ## Getbeel's codice destinatario [#getbeels-codice-destinatario] Getbeel can receive your suppliers' invoices straight from SDI. They arrive in **Received invoices** with the **SDI** badge, already read from the XML, next to the ones collected from email. If the same invoice arrives both by email and from SDI, Getbeel keeps it only once. ### Before you start [#before-you-start] - **An Italian company** with a P.IVA (or codice fiscale), tax regime and address in **Settings → Company**. - **The SDI add-on turned on**, from **Settings → Usage & billing**. Each invoice received from SDI is paid ([Pricing](/en/api/pricing)). - **Access to Fatture e Corrispettivi** with SPID, CIE or CNS, as legal representative or with a delegation. - **The right role**: only members who manage the team settings can turn receiving on. ### Steps [#steps] ### Check what is missing [#check-what-is-missing] Open **Settings → SDI receiving**. The **What is missing** list shows the steps to complete, each with its link. ### Turn on receiving [#turn-on-receiving] Press **Turn on receiving**. Getbeel shows **Your codice destinatario**, with a **Copy** button. ### Register the code as your indirizzo telematico [#register-the-code-as-your-indirizzo-telematico] Press **Open Fatture e Corrispettivi** and sign in. Open **Fatturazione elettronica e Conservazione**, then **Registrazione dell'indirizzo telematico**. In some versions it is called **Registrazione delle modalità di ricezione**. Choose **Codice destinatario**, paste the code and confirm. The Agenzia shows you the registration receipt. ### Confirm in Getbeel [#confirm-in-getbeel] Go back to **Settings → SDI receiving** and press **I registered the code**. ### What just happened [#what-just-happened] - **Getbeel receives for your P.IVA.** The receiving status is **Active**. - **SDI delivers everything to Getbeel.** The registered address overrides the code written by suppliers. - **Your previous address is replaced.** If you used another software or a PEC, from now on invoices arrive only in Getbeel. - **Invoices show up in Received invoices** with the **SDI** badge. Filter them with **See SDI invoices**. If you don't register the code, Getbeel only gets invoices from suppliers who write it on the invoice. ### If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------- | | "Complete the company data first (P.IVA, regime fiscale, address)." | Company details are missing | Complete **Settings → Company** | | "Receiving through SDI needs the SDI add-on. Turn it on in Billing." | The SDI add-on is missing | Open **Settings → Usage & billing** | | "Another Getbeel workspace already receives invoices for this P.IVA. Write to us if it is yours." | The P.IVA is active in another team | Contact support | | "The SDI channel did not answer. Try again in a few minutes." | The receiving channel did not answer | Press **Try again** | | "Only members who manage the workspace settings can turn receiving on." | Your role cannot do this | Ask an Owner | With **Turn off receiving**, Getbeel stops receiving for this P.IVA. Change your indirizzo telematico in the portal, or new invoices will only reach your cassetto fiscale. ## Frequently asked questions [#frequently-asked-questions] **If I don't register anything, do I lose invoices?** No. Undeliverable invoices stay in your reserved area in Fatture e Corrispettivi. But you have to go and fetch them yourself. **Do I still need to give the code to suppliers?** The registered address is what counts. Giving suppliers the right code avoids confusion. **Can I keep using email?** Yes. Connected mailboxes and forwarding keep bringing invoices into Getbeel, without duplicates. ## Related [#related] The recommended step after receiving, on the same page. Where invoices from SDI and email arrive. Status and checklist with `GET /sdi-receiving` and the MCP tools. # Connect your bank (https://docs.getbeel.com/en/guide/collega-la-banca) Your account transactions arrive in Getbeel on their own, without uploading statements. Step-by-step guide. With your bank connected, Getbeel downloads your accounts' transactions every 6 hours and matches them to invoices. You no longer upload statements. The connection goes through **Enable Banking**, a European service authorised to read accounts with your consent. You use an Enable Banking application **in your company's name**: Getbeel reads transactions with your key, and only for the accounts you authorise. ## Before you start [#before-you-start] - **Access to your company's online banking.** - **Credit on the prepaid balance.** Each connected account costs €2 a month and each imported movement €0.02 ([Pricing](/en/api/pricing)). Enable Banking is free. If you signed up before 13 November 2026, connected bank accounts are included in your active paid plan: no balance needed. - **The Owner or Member role.** The **Accountant** sees the connected banks but cannot manage them. - **About 10 minutes**, once, in the **same browser** from start to finish. - **No need** to upload statements: transactions arrive on their own. ## Steps [#steps] ### Create an Enable Banking account [#create-an-enable-banking-account] Go to [enablebanking.com](https://enablebanking.com/sign-in/) and sign up with your company email. ### Create an application [#create-an-application] In the [control panel](https://enablebanking.com/cp/applications), open **Applications → Register new application**: - Environment: **Production**. - Name: for example "Getbeel - Rossi S.r.l.". - Key: choose **Generate in the browser** and export the private key. Keep the `.pem` file: you need it in step 5. - If it asks for privacy and terms URLs, use those of your company website. Note the **Application ID** shown under the name. ### Add Getbeel's redirect URL [#add-getbeels-redirect-url] In the same application, under **Allowed redirect URLs**, paste exactly: ```text https://getbeel.com/api/open-banking/callback ``` In Getbeel you also find it on the bank page, with the **Copy** button. ### Activate the application by linking your accounts [#activate-the-application-by-linking-your-accounts] Choose **Activate by linking accounts** and log in to your bank. The application becomes active in **restricted mode**: it reads only the accounts you link here. Link every account you want to see in Getbeel. ### Upload the ID and the key to Getbeel [#upload-the-id-and-the-key-to-getbeel] In Getbeel, open **Reconciliation**, then **More actions** (⋯) → **Connect your bank**. Enter: - the **Application ID**; - the **Private key (.pem)**, with **Choose the .pem file**; - the **Account type**: **Business account** (S.r.l. companies and VAT-registered businesses with business online banking) or **Personal account**; - the **Bank country**. Choose **Verify and continue**. ### Choose the bank and log in [#choose-the-bank-and-log-in] Find your bank in **Search for your bank** and choose **Go to the bank**. Log in as usual and authorise reading the accounts. You have 30 minutes, in the same browser. ## What just happened [#what-just-happened] - **You have an Enable Banking account** in your company's name. - **The application is yours**, with your private key. - **Getbeel can receive the return** from the bank at the authorised URL. - **The application is active** and sees only the accounts you linked. - **Getbeel verified the key** with Enable Banking and stored it encrypted (AES-256): nobody can see it any more, not even you. - **The bank is connected.** The last 90 days of transactions arrive in **Reconciliation** within minutes, one statement per account and per month, already matched to invoices. ## After connecting [#after-connecting] - **Updates**: every 6 hours. **Sync now** updates straight away. - **Consent**: the bank grants it for up to 180 days (some banks less). Seven days before it expires, and again if it expires, Getbeel emails the team owners and shows a notice in Reconciliation. Choose **Reconnect** and log in to the bank again. Transactions already downloaded stay. - **Pending transactions**: those the bank has not booked yet appear under the account as **Pending**. They are not matched; once the bank books them, they become normal transactions. - **Foreign suppliers**: as with uploaded statements, the AI spots payments to foreign suppliers and suggests them in **Autofatture**. - **More banks**: with **Connect another bank** you connect up to 10. - **Disconnect**: closes the consent at the bank and deletes the key. Statements and matches stay. Getbeel uses the key only to read transactions of the authorised accounts. It cannot make payments. ## If it fails [#if-it-fails] | Message | Cause | Fix | | --------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | "This is not the private key file" | You uploaded a file other than the key | Upload the `.pem` file exported in step 2 (it starts with `-----BEGIN PRIVATE KEY-----`), not the certificate | | "Enable Banking does not recognise the application ID or the key" | ID and key from different applications, or application not active | Check they belong to the same application and redo step 4 | | "Your Enable Banking application does not allow Getbeel's redirect URL" | The URL is missing from the Allowed redirect URLs | Redo step 3: the URL must be identical | | "The bank shared no accounts" | The application is in restricted mode with no accounts | Link the accounts in Enable Banking (step 4), then **Reconnect** | | "Finish the bank login in the same browser where you started it in Getbeel" | You finished the login in another browser or device | Start again from Getbeel with **Reconnect** and finish the bank login in that browser, not on another device | | "The connection expired (you have 30 minutes to finish the bank login)" | More than 30 minutes passed | Try again from step 6 | | "Access was cancelled or refused by the bank" | You cancelled, or the bank refused | Try again whenever you like | | "You already connected 10 banks" | You reached the limit | Disconnect a bank to add another | | "The bank consent expired: reconnect the bank." | The consent days ran out, or you revoked it | Choose **Reconnect** | ## Next steps [#next-steps] Confirm the matches for the transactions that just arrived. Payments to foreign suppliers, ready as _autofatture_ (self-invoices). Connect the bank from code or from the AI assistant. # Linking POS terminals to telematic tills (https://docs.getbeel.com/en/guide/collegamento-pos-rt) Since 2026 every POS must be linked to the till (RT) in the Agenzia delle Entrate portal. Getbeel keeps the links, tells you when to communicate them and prepares the CSV for the bulk upload. Since 1 January 2026, anyone who certifies takings (_corrispettivi_) with a **registratore telematico** (RT, telematic till) must link every **POS** they take payments with to the RT. You communicate the link in the Agenzia delle Entrate **Fatture e Corrispettivi** area (L. 207/2024, art. 1 c. 74 and 77; AdE provv. prot. 424470 of 31 October 2025). In **Taxes → POS and tills** you enter the links. Getbeel tells you **by when** to communicate them and prepares the **CSV file** for the bulk upload. You do the upload to the portal yourself. ## Before you start [#before-you-start] - **The RT serial number** (_matricola_, or the Server RT's). - **The POS data**, from your contract with the bank or provider: acquirer, POS type, Terminal ID, contract number (_convenzione_). - **Access to the Agenzia's reserved area** with SPID, CIE, CNS, Fisconline or Entratel. Getbeel never asks for these credentials. - **Cost**: saving the links is free ([Pricing](/en/api/pricing)). ## By when [#by-when] - **POS already active in January 2026**: within 45 days of the service opening (5 March 2026), that is by **20 April 2026**. - **New POS and changes** (POS moved to another RT, new RT, POS or RT retired): from the **6th day** to the **last working day of the second month after** the link. - Example: a POS activated on 1 February is communicated between 6 and 30 April. - Saturday is not a working day. A communication by the last day of the month is still not late. ## Steps [#steps] ### Add the link [#add-the-link] Open **Taxes → POS and tills** and choose **Add link**. Fill in the fields described in [What to enter](#what-to-enter) and choose **Save**. ### Download the file [#download-the-file] Choose **Download the CSV**. Each file has at most 1,000 rows: if there are more, Getbeel splits them into parts. ### Sign in to the portal [#sign-in-to-the-portal] Choose **Open Fatture e Corrispettivi** and sign in. Pick the user you work as: your company, or the direct delegation if you are an intermediary with the "Accreditamento e censimento dispositivi" delegation. ### Open the bulk link page [#open-the-bulk-link-page] In the **Corrispettivi** box, choose **vai a Corrispettivi**, then **Accedi ai servizi** under **Gestore ed Esercente**. In the **Collegamento dispositivi – POS** menu, open **Gestione collegamenti → Collegamento massivo**. ### Upload the file [#upload-the-file] Choose **Scegli il file**, select Getbeel's CSV and choose **Invia**. ### Check the outcome [#check-the-outcome] Open **Storico richieste massive** on the portal. If everything is processed, go back to Getbeel and choose **I uploaded the file: mark as communicated**. ## What just happened [#what-just-happened] - **The links are recorded** in Getbeel, with the date by which to communicate them. - **The file is uploaded** to the Agenzia's portal, which links the POS to your RTs. - **The links show as Communicated** in Getbeel and can no longer be changed. ## What to enter [#what-to-enter] For each POS used with an RT: - **Till serial number (matricola RT)**: the serial number of the till or the Server RT; - **Acquirer**: the bank or provider that gave you the POS, Italian or foreign, with codice fiscale and name (11 digits for Italian ones, e.g. 04107060966 for Nexi); - **POS type**: physical (SoftPOS included) with its **Terminal ID**, or virtual (online payments); - **Contract number (convenzione)**: the contract with the acquirer; - **Shop address** (street, number, town, province, postcode), or **Itinerant till** if the RT is always used on the move; - **Used with this till since**: the date the deadline depends on. One RT can have several POS. A physical POS can go on several RTs only at the same address. A link already communicated cannot be changed. Choose **End**, enter the **End date** and add a new one. ## The file format [#the-file-format] Columns and values follow the Agenzia's Manuale operativo (April 2026): - `TipoAcquirer`, `IdentificativoAcquirer`, `DenominazioneAcquirer`; - `TipoPos` (00 physical, 01 virtual) and `TerminalId` (physical POS only); - `Convenzione`, `Matricola`, `Operazione` (I links, C closes); - `Ambulante` (1 or 0), `UbicazioneProv`, `UbicazioneComune`, `UbicazioneIndirizzo`, `UbicazioneCivico`, `UbicazioneCap`; - `DataFine` (MMYYYY, only for C). Leading zeros are kept. The separator, encoding and exact header names are in no official document. Getbeel uses semicolons and UTF-8. If the portal rejects the file, download the template from the portal, choose **Copy the rows for the AdE template** and paste them there. The bulk upload links only POS that the acquirer has already reported to the Agenzia. A POS that does not appear must be added with the portal's single-entry procedure ("Aggiungi nuovo POS"). For the **Documento Commerciale online**, the link is made inside that web procedure, not with the file. ## If it fails [#if-it-fails] | Message | Cause | Fix | | -------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | | "This link was already communicated: end it with an end date and add a new one." | You tried to change a communicated link | Choose **End** and add a new link | | "This POS is already linked to this till." | The link already exists | Use the existing one | | "A physical POS needs its Terminal ID." | The Terminal ID is missing | Copy it from the POS receipt or the contract | | "An Italian acquirer's codice fiscale has 11 digits." | The acquirer's code is incomplete | Enter it with its leading zeros | | "Do not use semicolons, quotes or line breaks: they would break the CSV file." | A field contains characters that are not allowed | Remove them from the field | | The portal rejects the file | The portal's template uses a different format | Choose **Copy the rows for the AdE template** and paste them in the template | ## Sources [#sources] - [Collegamento POS-RT](https://www.agenziaentrate.gov.it/portale/collegamento-pos-rt), Agenzia delle Entrate. - [Provvedimento prot. 424470 of 31 October 2025](https://www.agenziaentrate.gov.it/portale/documents/d/guest/decreto-legislativo-del-05_08_2015-n-127_), points 2 and 3. - [Manuale operativo](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-2_-manuale-operativo2026-04-29) (29 April 2026), "Procedura di collegamento massivo", pp. 15–17. - [Guida operativa POS-RT](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guidaoperativa_pos-rt) (February 2026) and [FAQ](https://www.agenziaentrate.gov.it/portale/documents/d/guest/faq_collegamento_pos_rt_2503) (25 March 2026). ## Next steps [#next-steps] The company's other tax deadlines. Manage POS–RT links from your code. # Connect Claude, ChatGPT or Cursor (https://docs.getbeel.com/en/guide/connect-ai) How to connect your AI assistant to Getbeel, step by step. *Video tutorial coming soon.* Getbeel connects to AI assistants through MCP, the standard that lets an assistant use outside tools. You add one address and sign in with your Getbeel account: no key to copy. ![The API keys & MCP page: test and live keys, permissions and the MCP server address.](/screenshots/api-keys-mcp.en.webp) ## Before you start [#before-you-start] - **A Getbeel account** with a team where you can manage settings. - **An assistant** that accepts remote MCP connectors: Claude (web, desktop or Claude Code), ChatGPT, Cursor. - **The server address**: `https://www.getbeel.com/api/mcp`. You also find it in **Settings → API keys & MCP**. - **No API key needed**: you sign in with your account. - **Cost**: the MCP server has no separate charge. Invoices sent live to SDI follow the price list ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Add Getbeel to the assistant [#add-getbeel-to-the-assistant] On claude.ai or in Claude Desktop, open **Settings → Connectors** and choose **Add custom connector**. Name `Getbeel`, URL `https://www.getbeel.com/api/mcp`. Then choose **Connect**. In ChatGPT, open **Settings → Apps & Connectors** and turn on developer mode. Create a connector with URL `https://www.getbeel.com/api/mcp` and **OAuth** authentication. Then choose **Connect**. In **Settings → MCP**, add a server, or create the file `.cursor/mcp.json`: ```json title=".cursor/mcp.json" { "mcpServers": { "getbeel": { "url": "https://www.getbeel.com/api/mcp" } } } ``` Then click **Needs login** next to the server. In the terminal: ```bash claude mcp add --transport http getbeel https://www.getbeel.com/api/mcp ``` Then run `/mcp` in Claude Code and choose **Authenticate**. ### Sign in to Getbeel [#sign-in-to-getbeel] A Getbeel page opens: **Connect … to Getbeel**, with the app's name. Sign in, or create an account. ### Check where you go back to [#check-where-you-go-back-to] The page shows where **Allow** takes you: the full host, such as `claude.ai`, or an app on your device. Only Claude (`claude.ai`) and ChatGPT (`chatgpt.com`) are verified. For any other app, Cursor and Claude Code included, you see **Getbeel has not verified this app**. Allow it only if you started the connection yourself and you recognise the destination. ### Choose team, mode and permissions [#choose-team-mode-and-permissions] - **Team**: the company the assistant works on. - **Mode**: **Test** to try it out, nothing reaches SDI; **Live** for real invoices. - **Permissions**: what it can read and do. The defaults are fine to start. ### Allow access [#allow-access] Choose **Allow**. You go back to the assistant, already connected. ### Test the connection [#test-the-connection] Ask: **"With Getbeel, who am I?"**. The assistant uses the `whoami` tool and answers with your company's name and the mode. ## What just happened [#what-just-happened] - **The assistant acts as you** on that team, with the permissions you chose. - **In Test mode** it works in the sandbox: no invoice reaches SDI. - **The connection shows up** in **Settings → API keys & MCP → Connected apps**, with when it was last used. ## Security [#security] - **Start with Test.** Reconnect in **Live** only when you trust the flow. - **Ask for confirmation before sending.** Keep tool approval on in the assistant, at least for `send_invoice`. - **Revoke in a moment.** In **Connected apps**, choose **Revoke**: the assistant loses access at once. In **Live**, `send_invoice` issues a real invoice with fiscal value, and it cannot be undone. Check customer, amounts and VAT before you confirm. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------- | | "This link is not valid" | The connection request has expired or is not valid | Go back to the assistant and connect it again | | "To connect an app you need a team where you can manage settings." | You have no team, or your role cannot manage settings | Create a team or ask an owner for access | | "Getbeel has not verified this app" | The app is not Claude or ChatGPT | Continue only if you started the connection and recognise the destination | | "Could not connect the app" | The connection did not go through | Try again from the assistant | | The assistant does not find Getbeel | The connector is not on in the conversation | Turn it on and start the request with "With Getbeel…" | Clients that only accept a header can use an API key: see the [MCP server reference](/en/api/mcp#with-an-api-key). ## Next steps [#next-steps] What to ask the assistant, with the tools it uses. All 128 tools, with scopes and arguments. How to get every SDI outcome without sending anything. # Free conservazione by the Agenzia delle Entrate (https://docs.getbeel.com/en/guide/conservazione) E-invoices must be preserved to legal standards. The Agenzia delle Entrate offers a free service: here is how to switch it on. E-invoices, issued and received, must be preserved to legal standards (_conservazione a norma_): a copy in a folder or a software is not enough. The Agenzia delle Entrate preserves the invoices that went through SDI for free, if you join its service. ## The rules in short [#the-rules-in-short] | | The Agenzia's conservazione service | | ----------------------- | ----------------------------------------------------------------------- | | Cost | Free | | What it preserves | Invoices issued and received through SDI, from the date you join onward | | Who joins | The company, or an intermediary with its delegation | | Length of the agreement | Three years, then it must be renewed | | Where | The **Fatture e Corrispettivi** portal | Source: Agenzia delle Entrate, [Servizio di conservazione elettronica](https://www.agenziaentrate.gov.it/portale/aree-tematiche/fatturazione-elettronica/guida-fatturazione-elettronica/i-servizi-dell-agenzia-fe/servizio-conservazione-elettronica). ## What Getbeel does and doesn't do [#what-getbeel-does-and-doesnt-do] - **It archives** the XML, PDF and SDI receipts of every invoice in your account, viewable from the app. - **It is not a conservatore** (certified preservation provider). Getbeel's archive does not replace legal conservazione. - **It cannot join for you.** The company joins, or an intermediary with a delegation, for example your accountant. - **It sends through SDI.** Invoices sent and received with Getbeel go through SDI, so the service covers them. ## Join and record it in Getbeel [#join-and-record-it-in-getbeel] ### Sign in to Fatture e Corrispettivi [#sign-in-to-fatture-e-corrispettivi] Sign in to [Fatture e Corrispettivi](https://ivaservizi.agenziaentrate.gov.it/portale/) with SPID, CIE or CNS. ### Join the service [#join-the-service] Open **Fatturazione elettronica e Conservazione**, then **Conservazione** and **Adesione al servizio di conservazione**. Accept the service agreement. ### Enter the date in Getbeel [#enter-the-date-in-getbeel] Open **Settings → SDI receiving**, panel **Legal storage (conservazione)**. Enter the **Date joined** and press **Save**. ## What just happened [#what-just-happened] - **Invoices that went through SDI are preserved** by the Agenzia, from the date you joined. - **Getbeel calculates the end date** three years later and shows **Joined on …, ends on …**. - **The status shows in the What is missing list**: **Active**, **Expired** or **Not active**. Through the API it is the `conservazione` field of `GET /sdi-receiving`. ## If it fails [#if-it-fails] | Message | Cause | Fix | | --------------------------------------------- | ---------------------------------------- | -------------------------------------------------------- | | "Check the date: it cannot be in the future." | The date you joined is after today | Enter the date on the joining receipt | | **Expired** | Three years have passed since you joined | Renew the agreement in the portal and enter the new date | ## What is left out [#what-is-left-out] The service only preserves invoices that went through SDI. Other documents need another way: foreign invoices as PDF or on paper, contracts, accounting records. Ask your accountant or a conservatore. This page is for information and does not replace advice from your accountant. What the Agenzia delle Entrate publishes is authoritative. ## Related [#related] Receive invoices from SDI on the same settings page. The conservazione status in `GET /sdi-receiving`. # Annual VAT return (https://docs.getbeel.com/en/guide/dichiarazione-iva) The data of your annual VAT return from Getbeel's VAT registers, the LIPE checked against the official schema, and what you or your accountant still do. Getbeel prepares the **data** of the annual VAT return (_dichiarazione IVA_) from the VAT registers and the settlements saved during the year. It does not prepare the file to send: you or your accountant copy the lines, check them and send. ![The Taxes section: deadlines, VAT settlement, F24 and returns to prepare.](/screenshots/taxes.en.webp) ## Before you start [#before-you-start] - **The year's settlements saved** in **Taxes → VAT settlements**. Line VL30 counts only those and the VAT F24s marked as paid in Getbeel ([Taxes](/en/guide/tasse)). - **Last year's VAT credit**, if any: the credit from the previous return (VX5) minus what you already offset with F24. - **No need** for the Agenzia's software to prepare the data: you need it later, to fill in and send. - **Cost**: preparing the data is free; it is charged once, when you record it as filed ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Open the deadline [#open-the-deadline] From 1 January, open **Taxes → Deadlines** and find **Annual VAT return**. Choose **Prepare the data**. ### Enter the previous year's credit [#enter-the-previous-years-credit] In the field **Previous year's VAT credit still available (optional)**, enter the credit or leave it empty. It goes in line VL25. Then choose **Prepare the data**. ### Check the flagged points [#check-the-flagged-points] At the top you find the **points to check**. For example: documents not yet in the registers, transactions without a clear line, domestic reverse charge (TD16), foreign suppliers without an autofattura, non-deductible VAT, unsaved settlements. ### Review the lines [#review-the-lines] Below you find the lines of sections VE, VF, VJ, VL and VX, in whole euros. Each line has the field code from the technical specifications. Further down you see the year's settlements: how much was due and how much was paid. ### Download the data [#download-the-data] Choose **Download Excel**, **Download CSV** or **Download JSON**. Send the file to your accountant, or copy the lines into the Agenzia's free "Software di compilazione Iva". ### Upload the receipt [#upload-the-receipt] After sending, upload the Agenzia's receipt under **Did you file the VAT return?**. The deadline shows as filed. ## What just happened [#what-just-happened] - **The data is ready** from the VAT registers and saved settlements, not from manual entry. - **The points to check** tell you what Getbeel could not know. - **The downloaded file** is a summary to copy, not the electronic filing. - **The deadline is closed** with the receipt kept in Getbeel. ## What is left to do outside Getbeel [#what-is-left-to-do-outside-getbeel] - **Fill in the parts Getbeel does not know**: front page, signatures, sections VA, VC, VO, VT and the others. - **Check and send** with the Agenzia's checking procedure, from Fisconline, Entratel or an intermediary. The window runs from **1 February to 30 April** (art. 8, c. 1, DPR 322/1998). - **Pay any balance** (VX1) with F24, tax code **6099**, by **16 March** (IVA 2026 instructions). - **To offset a credit above €5,000** in F24 you need a professional's **visto di conformità** (compliance stamp) (art. 10, c. 1, lett. a), n. 7, DL 78/2009). ## Which model [#which-model] The lines follow the latest published model: **IVA 2026**, tax year 2025, approved by AdE provv. prot. 51732 of 15 January 2026. The model for tax year 2026 is not out yet. Getbeel flags this in the summary: check it again when the new one is out. ## The LIPE [#the-lipe] Getbeel checks the quarterly LIPE file against the official schema (IVP18) as soon as it creates it. The Agenzia's checking software is a desktop program: you run it, Getbeel cannot. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ---------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- | | "Settlement not saved" next to a period | That month or quarter is not saved, so VL30 does not count it | Save it in **Taxes → VAT settlements**, then choose **Compute again** | | "Changed invoices or settlements? Prepare the data again." | A document or settlement changed after you prepared the data | Choose **Compute again** | | "The return model for … is not published yet" | The Agenzia has not published the new model yet | Use the data and check it again when the model is out | | "Some checks of the technical specifications fail" | An internal Getbeel check does not add up | Report it to Getbeel support and do not copy those lines | | "Preparing filings needs an active plan." | The account has no plan | Choose a plan in **Settings → Usage & billing** | ## Sources [#sources] - [IVA 2026](https://www.agenziaentrate.gov.it/portale/iva-2026/modello-e-istruzioni) model and instructions, AdE provv. prot. 51732 of 15 January 2026; technical specifications, provv. prot. 50925 of 11 February 2026. - Filing deadlines: art. 8, c. 1, DPR 322/1998. - Visto di conformità: art. 10, c. 1, lett. a), n. 7, DL 78/2009, as amended by art. 3 DL 50/2017. ## Next steps [#next-steps] Registers, settlements, F24 and LIPE during the year. Exports and read-only access for your accountant. Ask the assistant how much VAT you owe, from your own data. # Issue and send an invoice (https://docs.getbeel.com/en/guide/emettere-fatture) From draft to SDI in a minute, and how to read the outcome. *Video tutorial coming soon.* In **Issued invoices** you create e-invoices (FatturaPA), send them to SDI and follow the outcome. SDI is the Sistema di Interscambio, the Agenzia delle Entrate's exchange system. ![The list of issued invoices with each one's SDI status: draft, delivered, rejected, issued in the cassetto fiscale.](/screenshots/issued-invoices.en.webp) ## Before you start [#before-you-start] - **An Italian company** with complete details in **Settings → Company**: partita IVA (VAT number) or codice fiscale (tax code), address and tax regime. - **Your customer's details**: name, address, partita IVA or codice fiscale. For delivery, their [codice destinatario](/en/guide/codice-destinatario) or PEC (certified email) address. - **You don't need** to register anything with the Agenzia delle Entrate to send: Getbeel sends through its own channel. - **Cost.** Real sends to SDI follow the price list ([Pricing](/en/api/pricing)). Drafts and checks are free. ## Steps [#steps] ### Create the draft [#create-the-draft] In **Issued invoices** press **New invoice** and choose **New invoice**. Fill in the **Customer** section. Getbeel checks the VAT number on VIES and shows **VAT number verified**. The number follows your [numbering](/en/guide/numerazione-fatture): it is assigned when you save, as the next one for the year. ### Add the lines [#add-the-lines] In **Line items** enter the description, **Qty**, **Unit price** and **VAT %**. For a line without VAT, choose the natura (for example N2.2). Press **Add line** for more lines. Totals are calculated for you. ### Save the draft [#save-the-draft] Press **Save draft**. While it is a draft, you can edit or delete it. ### Send it to SDI [#send-it-to-sdi] Open the invoice's menu in the list, or its detail page, and choose **Send to SDI**. Getbeel shows **Send this invoice to SDI?**: confirm. Before sending, Getbeel checks the XML against the official schema and the SDI checks. If a check fails, nothing is sent and Getbeel shows the error. ### Follow the outcome [#follow-the-outcome] The status updates on its own when the SDI receipt arrives. Each status is explained below. ## What just happened [#what-just-happened] - **The draft took its number** from the chosen numbering. - **The XML passed the checks** before sending, with the SDI rules. - **The invoice is a tax document.** You can no longer edit or delete it: you correct it with a credit note (TD04). - **The outcome arrives on its own** and shows in the **Status** column. | Status | What it means | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Sent to SDI** | SDI received it and has not answered yet. | | **Delivered** | The customer received it. | | **Issued · in cassetto fiscale** | SDI could not deliver it, but the invoice counts as issued. It is in the customer's reserved area (cassetto fiscale): do not resend it. | | **Rejected** | An SDI check failed and the invoice counts as not issued. The detail page shows the code. | | **Already issued · duplicate** | SDI already accepted the same document (`00404`): it is issued, do not send it again. | Correct a rejected invoice and send it again with the same number and date. An undelivered invoice (MC) counts as issued from the date it was made available. Source: Agenzia delle Entrate, [La fattura elettronica e i servizi gratuiti](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guida_fattura_elettronica_dicembre_2025) (December 2025), pp. 17–18, and circolare 13/E of 2 July 2018. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | "At 0% VAT, give the natura (N1–N7): without it SDI would reject the invoice." | A 0% line has no natura | Choose the line's natura | | "This invoice number is already used." | The number you typed already exists | Keep the automatic number or pick a free one | | "This month's SDI quota is used up." | Your plan's sends have run out | Open **Settings → Usage & billing** | | "You need an active SDI add-on subscription to use issued invoices. Please upgrade your plan." | The account has no SDI add-on | Press **See plans** | | "We couldn't send the invoice to SDI because of a problem with our transmission provider. …" | The transmission channel did not answer | Nothing was sent: try again later | | **Rejected** | SDI found an error; the code and reason are in the detail | Press **Correct and resend**: the invoice goes back to draft with the same number and date. Fix it and send it | Every rejection code is explained in [SDI rejection codes](/en/api/reference-data/sdi-errors). The statuses in detail are in the [SDI lifecycle](/en/api/sdi-lifecycle). You cannot undo a send to SDI. Check the customer, lines and total before you confirm. ## Next steps [#next-steps] How Getbeel numbers invoices and how to create a separate series. What to ask your customer so they receive the invoice. Preserve the invoices that went through SDI to legal standards, for free. # Example prompts (https://docs.getbeel.com/en/guide/example-prompts) What to ask your assistant once it is connected to Getbeel. Write to the assistant as you would write to a colleague. Next to each request you find the MCP tool the assistant uses. ## Before you start [#before-you-start] - **An assistant connected** to Getbeel: see [Connect Claude, ChatGPT or Cursor](/en/guide/connect-ai). - **With several tools connected**, start with "With Getbeel…": the assistant picks the right one. - **Test mode** to try things out. Tools that change fiscal data (fixed assets, withholdings, filings) and company data work only in **Live**. - **Cost**: requests have no separate charge. Live sends to SDI follow the price list ([Pricing](/en/api/pricing)). ## Check where things stand [#check-where-things-stand] | Request | Tool | | --------------------------------------------------------------------------------------------------------------- | ------------------------------ | | "With Getbeel, which invoices issued in October did SDI reject? Tell me why." | `list_invoices`, `get_invoice` | | "List the invoices issued in the last 30 days that ended up in the cassetto fiscale, with customer and amount." | `list_invoices` | | "How much have I invoiced Rossi S.r.l. in total this year?" | `list_invoices` | | "Which invoices are overdue and still unpaid?" | `list_overdue_invoices` | | "List the credit notes for invoice 12." | `list_credit_notes` | ## Supplier invoices [#supplier-invoices] | Request | Tool | | ----------------------------------------------------------------------------- | -------------------------------- | | "Which invoices received in September came by email? Group them by supplier." | `list_received_invoices` | | "How much have I spent on software in the last three months?" | `list_received_invoices` | | "Receive a test invoice in the sandbox and show it to me." (Test only) | `create_sandbox_inbound_invoice` | ## Before sending [#before-sending] | Request | Tool | | ------------------------------------------------------------------------------ | ------------------ | | "Check this FatturaPA XML and tell me what to fix." (attach or paste the file) | `validate_invoice` | | "This invoice has zero VAT for a German customer: which natura should I use?" | none | For the last question the assistant can read these docs. For unclear cases, ask your accountant (commercialista). ## Prepare and send [#prepare-and-send] | Request | Tool | | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | "Prepare a draft for Bianchi S.p.A., P.IVA 01234567890, codice destinatario M5UXCR1: October consulting, 1,000 euros plus 22% VAT. Do not send it." | `create_invoice_draft` | | "Show me the draft and, if everything is right, send it." | `get_invoice`, `send_invoice` | | "Make a credit note that cancels invoice 12." | `create_credit_note` | Before `send_invoice` the assistant must show you the invoice and ask you to confirm. In **Live**, sending issues a real invoice and cannot be undone. Check customer, amounts and VAT in the draft before you confirm. ## Bank [#bank] | Request | Tool | | -------------------------------------------------------------------------------------------- | -------------------------------------------- | | "Show me the latest bank statement: period, balances and how many transactions are matched." | `list_bank_statements`, `get_bank_statement` | | "Which transactions are not matched to an invoice yet?" | `list_unmatched` | ## Taxes [#taxes] | Request | Tool | | -------------------------------------------------------- | ------------------------- | | "Which tax deadlines do I have in the next 30 days?" | `get_tax_calendar` | | "How much VAT do I have to pay for October?" | `get_vat_settlement` | | "Can I offset my VAT credit?" | `ask_accountant_question` | | "How much should I set aside for this year's taxes?" | `get_tax_estimate` | | "Prepare the 2026 CU data for the professionals I paid." | `get_withholdings_cu` | ## Correct data [#correct-data] | Request | Tool | | ------------------------------------------------------------------ | ----------------------------------------- | | "Delete the fixed asset I registered by mistake." | `list_fixed_assets`, `delete_fixed_asset` | | "Delete the withholding recorded twice for Verdi's fee note." | `list_withholdings`, `delete_withholding` | | "Update the registered office address: Via Roma 10, 20121 Milano." | `list_companies`, `update_company` | The assistant must ask you to confirm before it deletes or changes data. A withholding already paid with an F24 cannot be deleted. Company data goes on every invoice you issue. ## What invoice statuses mean [#what-invoice-statuses-mean] The assistant uses the same statuses you see in **Issued invoices**. What matters is whether the invoice is issued: | In Getbeel | What it means | What to do | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **Sent to SDI** | SDI is running its checks (from a few minutes up to 5 days) | Wait for the outcome, do not send it again | | **Delivered** | Delivered to the customer: it is issued | Nothing | | **Issued · in cassetto fiscale** | SDI could not deliver it, but it is **issued**: the customer finds it in their reserved area of Fatture e Corrispettivi | Tell the customer. **Do not send it again**: it would be a duplicate | | **Rejected** | SDI refused it: it counts as **never issued**. The details show the code and the reason | Choose **Correct and resend**: it goes back to draft with the same number and date; fix it and send it | | **Already issued · duplicate** | SDI rejected a second send with code 00404 because it already accepted the same invoice: it is **issued** | Nothing: do not resend it. Support links the accepted send | For details and official sources: [SDI lifecycle](/en/api/sdi-lifecycle) and [rejection codes](/en/api/reference-data/sdi-errors). ## If it fails [#if-it-fails] | Assistant message | Cause | Fix | | ----------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | | `livemode_required` | The tool changes real data and the connection is in Test | Reconnect the assistant in **Live** | | `test_mode_required` | The sandbox works only in Test | Use a **Test** connection | | `subscription_required` | The tool needs an active plan | Choose a plan in **Settings → Usage & billing** | | `withholding_remitted` | The withholding is already in a paid F24 | Leave it as it is and talk to your accountant | | `insufficient_scope` | The connection lacks that permission | Revoke the app in **Connected apps** and reconnect with the right permission | You can also ask directly: - "Invoice 118 was rejected with code 00305. What does it mean and how do I fix it?" - "The invoice for Verdi shows Issued · in cassetto fiscale. What should I do?" - "Why does invoice 121 say Already issued · duplicate?" ## Next steps [#next-steps] The full list of tools, with scopes and arguments. Try every SDI outcome and received invoices without sending anything. What Getbeel computes on its own and what you prepare. # Getting started (https://docs.getbeel.com/en/guide/getting-started) What Getbeel does and where to begin: company details, mailboxes, bank and your first e-invoice. *Video tutorial coming soon.* Getbeel collects your suppliers' invoices, issues your e-invoices and matches them to your bank movements. This section takes you from sign-up to your first invoice sent to SDI. ![The Getbeel Overview: the "Get started" list, the AI assistant connection over MCP and recent activity.](/screenshots/overview.en.webp) ## Where to begin [#where-to-begin] After you sign up, open **Overview**. The **Get started** list shows the steps left, in the right order. The [quick start](/en/guide/getting-started/quick-start) explains them one by one. ## What you find in the app [#what-you-find-in-the-app] Each item is a page in the sidebar. - **Received invoices.** Supplier invoices from mailboxes, forwarding, uploads and SDI. The AI reads and classifies them. - **Autofatture.** Purchases from foreign suppliers become _autofatture_ (self-invoices) to send to SDI. Italian companies only. - **Issued invoices.** You create e-invoices (FatturaPA), send them to SDI and follow the outcome. Italian companies only. - **Taxes.** Deadlines, VAT registers, _liquidazioni IVA_ (VAT settlements) and F24 forms prepared from your invoices. Italian companies only. - **Reconciliation.** Bank movements, from a bank statement or your [connected bank](/en/guide/collega-la-banca), matched to invoices. - **Analytics.** The bank movements from Reconciliation by period: monthly spend, cash-based profit and loss, and suppliers. See [Spending analytics](/en/guide/analytics/spending-analytics). - **Drive.** Invoices, bank files and shared documents, in folders. - **Client companies.** For accountants: each client company has its own data and invoices, from a single account. In **Settings** you find company details, members, mailboxes, categories, AI rules and billing. ## Before you start [#before-you-start] - **Roles.** Invite your team or your accountant as **Owner**, **Member** or **Accountant** (read-only). - **Cost.** Scans use invoice credits; SDI sends and receipts have a price list ([Pricing](/en/api/pricing)). ## Next steps [#next-steps] The five steps of the "Get started" list, in ten minutes. How they arrive and how the AI reads them. From draft to SDI, and how to read the outcome. Match each movement to its invoice. # Quick start (https://docs.getbeel.com/en/guide/getting-started/quick-start) Set up your company, connect a mailbox and issue your first e-invoice, in the order of the Overview's "Get started" list. Set up Getbeel in about ten minutes: company details, a mailbox for supplier invoices, your bank and your first invoice to SDI. The **Get started** list on **Overview** follows the same steps. ![The Overview: the "Get started" list with the steps to complete and the upcoming tax deadlines.](/screenshots/overview.en.webp) ## Before you start [#before-you-start] - **An account.** Sign up at [getbeel.com](https://www.getbeel.com) with Google or your email. Create a team with your company's name. - **Your company details**: legal name, partita IVA (VAT number) or codice fiscale (tax code), registered address and tax regime. - **You don't need** to install anything or set up SDI: Getbeel sends through its own channel. - **Cost.** Connecting mailboxes in the app needs a plan with invoice credits. Sends to SDI follow the price list ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Complete your company details [#complete-your-company-details] Open **Settings → Company**. Fill in the legal name, country, partita IVA or codice fiscale, address and **Tax Regime**. Press **Save company profile**. ### Connect a mailbox [#connect-a-mailbox] Open **Settings → Email** and choose the **Gmail**, **Outlook** or **Other email** (IMAP) tab. Press the connect button and allow reading. Getbeel asks for read-only access. To look for the invoices of the last few months right away, open **Received invoices** and press **Scan now**. ### Connect your bank [#connect-your-bank] Open **Reconciliation → Connect your bank**, or upload a bank statement. Getbeel matches each movement to its invoice. ### Issue your first e-invoice [#issue-your-first-e-invoice] Open **Issued invoices**, press **New invoice** and choose **New invoice**. Fill in the customer and the lines, then press **Save draft**. From the invoice menu choose **Send to SDI** and confirm. ### Invite your team [#invite-your-team] Open **Settings → Members** and press **Invite members**. Choose a role for each person: - **Owner**: full access, including billing, members and settings. - **Member**: scans email, manages invoices and sees analytics. - **Accountant**: read-only; sees and exports invoices, taxes and bank data, but cannot change, approve or delete anything. ## What just happened [#what-just-happened] - **Your company is set up.** Every invoice you issue carries these details, and the pre-send checks use them. - **Supplier invoices arrive on their own.** Getbeel checks the mailbox once a day and the AI reads them into **Received invoices**. - **Bank movements are matched** to invoices in **Reconciliation**. - **Your first invoice is at SDI.** Its status updates on its own when the receipt arrives. - **Your team works in Getbeel** with the access of their role. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ---------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------- | | "Your company profile is not saved yet: complete Settings → Company first." | Company details are missing | Complete step 1 | | "You need an active SDI add-on subscription to use issued invoices. Please upgrade your plan." | The account has no SDI add-on | Open **Settings → Usage & billing** | | "Your email connection limit has been reached." | Your plan allows fewer mailboxes | Disconnect a mailbox or change plan | | **No credits** in the scan history | Your invoice credits have run out | Add credits in **Settings → Usage & billing** | | **Rejected** on the invoice | An SDI check did not pass | Press **Correct and resend** ([Issue an invoice](/en/guide/emettere-fatture)) | ## Next steps [#next-steps] Receive supplier invoices straight from SDI. Tell the AI how to read and classify your costs. Work in Getbeel from Claude, ChatGPT or Cursor. # Getbeel in your AI assistant (https://docs.getbeel.com/en/guide) Look up and prepare Italian e-invoices from Claude, ChatGPT or Cursor, without writing code. Connect Claude, ChatGPT or Cursor to Getbeel and ask in plain language for what you now look up by hand. For example: "which invoices were rejected this month?" or "is this XML correct?". The assistant uses Getbeel's MCP tools. MCP is the standard that lets an assistant use outside services. ## What the assistant can do [#what-the-assistant-can-do] | Request | MCP tool | | ----------------------------------------- | ------------------------------------------------------------------ | | Read issued invoices and their SDI status | `list_invoices`, `get_invoice` | | Read invoices received from suppliers | `list_received_invoices` | | Check a FatturaPA XML before sending it | `validate_invoice` | | Prepare a draft invoice | `create_invoice_draft` | | Send an invoice to SDI, after you confirm | `send_invoice` | | Approve or reject a received invoice | `approve_collected_document` | | Receive supplier invoices from SDI | `get_sdi_receiving_status`, `enable_sdi_receiving` | | Read bank statements and reconciliation | `list_bank_statements`, `get_bank_statement`, `get_reconciliation` | The full list, with the permissions of each tool, is in the [MCP reference](/en/api/mcp). ## Before you start [#before-you-start] - **A Getbeel account** with a team and your company details in **Settings → Company**. - **An assistant that supports MCP**: Claude, ChatGPT, Cursor or Claude Code. - **You don't need** to copy an API key: you sign in with your Getbeel account when you connect the assistant. - **Cost**: the MCP connection is free. Real SDI sends and receipts are paid, as in the app ([Pricing](/en/api/pricing)). When you connect the assistant, you choose the team and the mode. In **Test** mode no invoice reaches SDI. The assistant sees only the chosen team and does only what its permissions allow. ## Next steps [#next-steps] Claude, ChatGPT, Cursor and Claude Code, step by step. What to ask, from the first question to sending. Receive your suppliers' invoices in Getbeel from SDI. The Agenzia delle Entrate's free service and how to record it. ## Guides to the app [#guides-to-the-app] Set up your company and collect your first invoices. Mailboxes, AI reading, categories and rules. Match bank movements to invoices. Roles and invitations for your team and your accountant. # AI data extraction (https://docs.getbeel.com/en/guide/invoice-management/ai-extraction) What Getbeel's AI reads from each invoice, and how to upload files by hand. Getbeel's AI reads every invoice that arrives by email, forwarding or upload and extracts its data. Invoices from SDI don't go through the AI: Getbeel reads them from the XML. ## What it extracts [#what-it-extracts] - **Supplier**: name, email, address, VAT number, country and city. - **Document**: number, date, due date, currency and type. - **Amounts**: taxable amount, VAT and total, in the original currency. - **Lines**: description, quantity, unit price and amount. - **Other**: category, payment status, whether it recurs and whether it is a credit note. The type is one of these: **Invoice**, **Receipt**, **Subscription**, **Refund** or **Bill**. If the AI is not sure the invoice is addressed to your company, the detail page shows **Company match uncertain**. Check the recipient details. ## Upload invoices by hand [#upload-invoices-by-hand] ### Before you start [#before-you-start] - **Formats**: PDF, JPG, PNG or WebP, up to 10 MB each, up to 20 files at a time. - **A plan with invoice credits**: without one, the **Upload** button is disabled. - **Cost**: each file read uses one invoice credit ([Pricing](/en/api/pricing)). ### Steps [#steps] ### Open the upload [#open-the-upload] In **Received invoices** press **Upload**. **Upload invoices** opens. ### Choose the files [#choose-the-files] Drag the files into the box or click to browse. ### Start reading [#start-reading] Press **Upload & process**. ### What just happened [#what-just-happened] - **The files are uploaded.** Getbeel shows, for example, "3 file(s) uploaded. Processing will begin shortly." - **The AI reads them.** While it reads, the list shows **Processing invoices...** and updates on its own. - **The invoices appear in Received invoices** with the extracted data and the category. ## When the PDF is missing [#when-the-pdf-is-missing] Sometimes an email confirms a payment but doesn't attach the invoice. Getbeel puts it in the **Missing PDF** tab with the **Missing PDF** badge. 1. Open the invoice. The **Payment confirmation** panel shows the supplier's link, if there is one. 2. Press **Download invoice**. The link can expire: download it right away. 3. Drag the file into the box. Getbeel reads it and completes the invoice. ## Get better results [#get-better-results] - **AI rules**: plain-language instructions the AI follows for new invoices ([Categories and AI rules](/en/guide/invoice-management/categories-rules)). - **Company profile**: your legal name and VAT number in **Settings → Company** help the AI recognize invoices addressed to you. - **Categories**: precise categories give better classification. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------ | ---------------------------------------- | -------------------------------------------------- | | "invoice.docx: Unsupported file type. Use PDF, JPG, PNG, or WebP." | The format is not allowed | Convert the file to PDF or an image | | "invoice.pdf: File too large. Maximum 10MB." | The file is over 10 MB | Compress the PDF or split it | | "Maximum 20 files allowed" | More than 20 files | Upload in several rounds | | "Processing Failed" | The AI could not read the document | Upload the file again, or a sharper image | | **Company match uncertain** | The recipient doesn't match your details | Check the invoice; complete **Settings → Company** | ## Next steps [#next-steps] Check, approve and export the invoices the AI read. Give the AI your own instructions. # Categories and AI rules (https://docs.getbeel.com/en/guide/invoice-management/categories-rules) Organize expenses with categories and give the AI plain-language instructions for reading invoices. **Categories** group received invoices by type of expense. **AI rules** are plain-language instructions the AI follows when it reads a new invoice. ## Default categories [#default-categories] Every team starts with 10 categories, marked **Default**: | Category | For example | | ------------------------- | ------------------------------ | | **Software & SaaS** | Subscriptions, licenses, APIs | | **Cloud Infrastructure** | Hosting and cloud services | | **Utilities** | Internet, phone, energy | | **Travel** | Flights, hotels, transport | | **Food & Dining** | Business lunches and dinners | | **Hardware** | Computers, monitors, equipment | | **Professional Services** | Legal and accounting advice | | **Marketing** | Advertising, tools, agencies | | **Office Supplies** | Stationery and office supplies | | **Other** | Everything else | You cannot delete the default categories. ## Create a category [#create-a-category] ### Open the categories [#open-the-categories] Open **Settings → Categories** and press **Add category**. ### Give it a name and a color [#give-it-a-name-and-a-color] Enter the **Label**, for example "Legal fees", and choose a **Color**. Press **Create**. You can also create a category from the list: in an invoice's **Category** column, type a new name and choose **Create "…"**. When you delete one of your own categories, its invoices move to **Other**. You cannot undo this. ## Add an AI rule [#add-an-ai-rule] ### Open the rules [#open-the-rules] Open **Settings → AI Rules** and press **Add rule**. ### Write the rule [#write-the-rule] Write it as you would tell a colleague, in at most 500 characters. For example: - _"Exclude invoices from billing@shopify.com"_ - _"For Cloudflare invoices, set the due date to net 30 days"_ - _"Google Workspace invoices go in Software & SaaS"_ ### Save it and turn it on [#save-it-and-turn-it-on] Leave **Active** on and save. ## What just happened [#what-just-happened] - **The category is available** in the filters, in the list and to the AI. - **The rule applies to new invoices.** The AI follows it when it reads the next invoices, not the ones it already read. - **Rules apply in order**, from first to last. The AI follows only the active ones. To test the effect of a rule, turn it off with the switch instead of deleting it. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ---------------------------------------------- | -------------------------------- | ------------------------------------------------------- | | "Label is required" | The name is empty | Enter a label | | "Label must be at most 100 characters" | The name is too long | Shorten it | | "Rule text is required" | The rule is empty | Write the rule | | An invoice already read has the wrong category | Rules only apply to new invoices | Change the category from the list's **Category** column | ## Next steps [#next-steps] Check and export the classified invoices. Spending by category over time. # Email connections (https://docs.getbeel.com/en/guide/invoice-management/gmail-integration) Connect Gmail, Outlook, IMAP or email forwarding: Getbeel finds supplier invoices in your mailbox. Getbeel reads the mailboxes you connect and imports the emails with invoices. You can connect several mailboxes per team, for example admin@ and invoices@. ## Before you start [#before-you-start] - **A plan with invoice credits.** Without a plan, the connect buttons are disabled. - **Your plan's limit.** **Settings → Email** shows how many email connections you use out of the total. - **You don't need** to give Getbeel your Gmail or Outlook password: access goes through Google or Microsoft, read-only. - **Cost.** Each invoice read uses one credit; email forwarding is a paid add-on ([Pricing](/en/api/pricing)). ## Connect a mailbox [#connect-a-mailbox] ### Open the email settings [#open-the-email-settings] Open **Settings → Email**. The tabs are **Gmail**, **Outlook**, **Other email** and **Email forwarding**. ### Choose your provider and authorize [#choose-your-provider-and-authorize] - **Gmail**: press **Connect Gmail** and allow email reading on Google's screen. - **Outlook**: press **Connect Outlook** and sign in with your Microsoft account (Outlook.com or Microsoft 365). - **Other email** (IMAP): press **Connect IMAP**. Choose the **Email provider**, then enter your address and an app password. For IMAP, Getbeel uses SSL/TLS on port 993. Servers that offer only other ports or STARTTLS are not supported. ### Look for past invoices [#look-for-past-invoices] Open **Received invoices** and press **Scan now**. Choose a period, for example **Last 3 months**, and press **Start scan**. ## What just happened [#what-just-happened] - **The mailbox is connected.** After the first successful sign-in, its status is **Email access verified**. - **Getbeel checks it once a day** and imports new invoices on its own. - **The scan of the period has started.** **Received invoices** shows the progress and updates on its own. - **The AI reads each invoice found** and puts it in **Received invoices**. ## Forward invoices [#forward-invoices] Forwarding helps when you don't want to connect the whole mailbox. It is a paid add-on. 1. Open **Settings → Email → Email Forwarding** and press **Set up forwarding**. 2. Copy the **Forwarding address**. 3. Forward invoices to that address, by hand or with a rule in your email app. Getbeel processes each email as soon as it arrives. ## Manage your connections [#manage-your-connections] Each mailbox shows its address and status. From the row's menu: - **Reconnect** (Gmail): renews the authorization if Google revoked it. - **Disconnect**: Getbeel stops reading the mailbox. Invoices already imported stay. **Scan history**, on the same page, lists every scan with its type, status, and the invoices found and processed. Open a row to see the outcome of each email: | Outcome | What it means | | -------------------------- | ------------------------------------------------------------ | | **Invoice created** | The invoice is in **Received invoices** | | **Needs invoice document** | The email mentions an invoice but has no readable attachment | | **Duplicate** | The invoice is already there | | **Not an invoice** | For example a newsletter | | **No invoice content** | The email or attachment has no readable text | | **No credits** | Skipped: your invoice credits have run out | | **Error** | An unexpected error; Getbeel retries on its own | ## If it fails [#if-it-fails] | Message | Cause | Fix | | --------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------ | | **Reconnect required**: "GetBeel cannot read this mailbox. …" | Google revoked access | From the mailbox's menu choose **Reconnect** | | "Choose the same Google account as the mailbox you are reconnecting." | You chose a different account | Reconnect with the right account | | "Your Google Workspace administrator blocked Gmail access. …" | Your domain blocks outside apps | Ask your administrator to allow Getbeel, or upload the files | | "Your email connection limit has been reached." | Your plan allows fewer mailboxes | Disconnect a mailbox or change plan | | "Email Routing is a paid add-on. …" | The forwarding add-on is missing | Press **Go to Usage & billing** | | **Scans need attention** | Imports keep failing | Getbeel retries on its own; if it continues, reconnect the mailbox | After reconnecting, press **Scan now** for the missing period. ## Next steps [#next-steps] What the AI reads from each invoice. Exclude senders or correct data automatically. Receive e-invoices from SDI as well. # Invoice management (https://docs.getbeel.com/en/guide/invoice-management) Collect supplier invoices from email, uploads and SDI: the AI reads and classifies them. *Video tutorial coming soon.* **Received invoices** collects your suppliers' invoices in a single list. The AI reads each document and extracts the supplier, amounts, dates and lines. ![The list of received invoices, with search, category filters and the Missing PDF tab.](/screenshots/received-invoices.en.webp) ## Where they come from [#where-they-come-from] | Source | How | Guide | | ---------- | --------------------------------------------------- | ------------------------------------------------------------------------------------ | | Mailboxes | Gmail, Outlook or IMAP, checked every day | [Email connections](/en/guide/invoice-management/gmail-integration) | | Forwarding | You forward emails to your Getbeel address | [Email connections](/en/guide/invoice-management/gmail-integration#forward-invoices) | | Upload | **Upload** in **Received invoices**: PDFs or images | [AI extraction](/en/guide/invoice-management/ai-extraction) | | SDI | Your suppliers' e-invoices, with the **SDI** badge | [Codice destinatario](/en/guide/codice-destinatario) | If the same invoice arrives from two sources, Getbeel keeps it only once. ## What happens to each invoice [#what-happens-to-each-invoice] 1. **It arrives** from one of the sources above. 2. **The AI reads it**: supplier, number, dates, amounts, VAT and lines. 3. **It gets a category**, following your [categories and AI rules](/en/guide/invoice-management/categories-rules). 4. **You check it** on its detail page and export it for your accountant. The full path and the statuses are in [Invoice workflow](/en/guide/invoice-management/invoice-workflow). ## Before you start [#before-you-start] - **An active plan.** Connecting mailboxes and uploading files need a plan. - **Cost.** Each document the AI reads uses one invoice credit. Invoices received from SDI have their own price ([Pricing](/en/api/pricing)). - **Your company details** in **Settings → Company**: they help the AI recognize invoices addressed to you. ## Next steps [#next-steps] Connect Gmail, Outlook, IMAP or forwarding. What the AI reads and how to upload files by hand. Check, approve and export. Organize your expenses your way. # Invoice workflow (https://docs.getbeel.com/en/guide/invoice-management/invoice-workflow) From the invoice the AI read to the export for your accountant: check, approve and export received invoices. Every received invoice goes through the same statuses, from the AI reading to the export. In **Received invoices** you check and export it; you approve it with the AI assistant or the API. ## The statuses [#the-statuses] | Status | API value | What it means | | ------------------ | ------------------ | ---------------------------------------------------- | | **Processing** | `processing` | The AI is reading the document. | | **Pending review** | `pending_review` | Read, waiting for your check. | | **Approved** | `verified` | You confirmed the data is correct. | | **Rejected** | `rejected` | It is not a valid invoice for you. | | **Exported** | `exported` | Already handed over to accounting. | | **Missing PDF** | `missing_document` | The email confirms a payment but the PDF is missing. | You can approve an invoice from **Pending review** or **Rejected**, and reject it from **Pending review** or **Approved**. In **Taxes**, an invoice not yet approved still goes into the VAT registers, marked **Not reviewed yet**. ## Before you start [#before-you-start] - **Invoices in Getbeel**, from email, forwarding, upload or SDI ([Invoice management](/en/guide/invoice-management)). - **The right role**: **Owner** or **Member** manage invoices; **Accountant** is read-only and can export. - **To approve**: a [connected AI assistant](/en/guide/connect-ai). The app has no approve button. ## Steps [#steps] ### Find the invoice [#find-the-invoice] In **Received invoices** search by supplier or number. Filter by **Category**, by period or by source: **SDI** or **Email and uploads**. ### Check the data [#check-the-data] Open the invoice. **Invoice details** shows the supplier, number, dates, amounts and **Line items**, next to the document preview. Correct the category from the list's **Category** column. ### Complete the invoices without a PDF [#complete-the-invoices-without-a-pdf] Open the **Missing PDF** tab. For each invoice, download the document from the supplier and upload it into the box ([When the PDF is missing](/en/guide/invoice-management/ai-extraction#when-the-pdf-is-missing)). ### Approve or reject [#approve-or-reject] Ask the assistant, for example: _"Show me the received invoices pending review and approve the ones from Aruba."_ The assistant uses `list_received_invoices` and `approve_collected_document`, with `decision: "reject"` to reject. It asks you to confirm before each change. ### Export for your accountant [#export-for-your-accountant] Select the invoices and press **Export**. In **Export invoices** choose **CSV**, **Excel** or **ZIP** (data and PDF attachments), then press **Download**. ## What just happened [#what-just-happened] - **You found the invoices** with search and filters, without opening them one by one. - **The data is checked** against the original document. - **No invoice is left without a document**: the **Missing PDF** tab is empty. - **Approved invoices are Approved**, and in **Taxes** they lose the **Not reviewed yet** mark. - **Your accountant has the file** with the data and, in the ZIP, the PDFs. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------- | | "Export failed" | The file was not created | Try again with fewer invoices | | "No PDF attachments found" | The chosen invoices have no PDF | Export as **CSV** or **Excel** | | "Failed to delete invoices" | The invoices were not deleted | Try again; check your role | | The assistant says the invoice cannot be approved | It is still **Processing**, **Missing PDF** or **Exported** | Wait for the reading or upload the PDF | You cannot undo deleting an invoice. ## Next steps [#next-steps] Match invoices to bank payments. Exports and read-only access for your accountant. More questions to ask the assistant about invoices. # Invoice numbering (https://docs.getbeel.com/en/guide/numerazione-fatture) How Getbeel numbers issued invoices: 1, 2, 3… restarting at 1 every year, as the Agenzia delle Entrate allows. Every invoice has a progressive number that identifies it uniquely (art. 21, paragraph 2, letter b, DPR 633/1972). Getbeel assigns it for you and writes it in the FatturaPA `Numero` field. ![The list of issued invoices with each one's number, date and SDI status.](/screenshots/issued-invoices.en.webp) ## The rule in short [#the-rule-in-short] | | Standard numbering | | -------------------- | ----------------------------------------------------------------- | | Format | `1`, `2`, `3`… with the invoice date alongside | | 1 January | Restarts at 1, unless you choose otherwise | | Number typed by hand | Can be the next one or fill a gap, never jump ahead | | What goes to SDI | Exactly the number you see in Getbeel, with no year or other text | | SDI limits | At most 20 characters, at least one digit (error `00425`) | ## Restart at 1 every year [#restart-at-1-every-year] The first invoice of 2027 is number 1. The number follows the date: an invoice dated 2027 takes the next 2027 number. This is allowed. The Agenzia delle Entrate's [Risoluzione n. 1/E of 10 January 2013](https://www.agenziaentrate.gov.it/portale/documents/20143/304338/Risoluzione+1++10012013a_risoluzione+1e.pdf/71b92d56-5b2e-6e70-a1c1-47cf4d365a29) accepts "qualsiasi tipologia di numerazione progressiva che garantisca l'identificazione univoca della fattura, se del caso, anche mediante riferimento alla data" (any progressive numbering that identifies the invoice uniquely, where needed by reference to its date). It also accepts a single sequence across years, and formats such as `1/2013` or `2013/1`. SDI spots a duplicate invoice (error `00404`) by seller, year of the date and number. Invoice 1 of 2026 and invoice 1 of 2027 are not duplicates. Source: [FatturaPA technical specifications, Allegato A, version 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1). ## Continue the numbering across years [#continue-the-numbering-across-years] For a single sequence that never restarts, open **Issued invoices**. In the **More actions** menu choose **Quotes**, then the **Numbering** tab. On the **Standard** row, turn off the switch in the **Restarts every year** column. You can change it at any time. Each new number is higher than the last one of the same year, so the numbering stays progressive and without duplicates. ## Invoices issued before November 2026 [#invoices-issued-before-november-2026] Until November 2026 the Standard numbering added a trailing slash, for example `45/`. Those invoices stay as they are: that is the number already sent to SDI. The next invoice continues the same sequence without the slash. | Date | Number | | -------------------------------- | ------ | | 28 October 2026 (already issued) | `45/` | | 20 November 2026 | `46` | | 10 January 2027 | `1` | ## Sezionali (separate series) [#sezionali-separate-series] A _sezionale_ (separate series) keeps some invoices apart, for example online sales. It has a prefix or a suffix (`FT-12`, `12/A`) and its own sequence. The prefix and suffix are part of the number sent to SDI. To create one, open the **Numbering** tab and press **New series**. Choose a **Prefix** or **Suffix**, whether it should **Restart from 1 every year**, and whether to use it for new invoices or for credit notes. The prefix, suffix and yearly restart cannot change after the first invoice. To change them, create a new series. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------- | | "This invoice number is already used." | The number already exists in that year | Leave the number empty: Getbeel assigns the next one | | "A series with this prefix and suffix already exists." | An identical series already exists | Use that one, or change the prefix or suffix | | "Prefix and suffix: up to 10 letters, digits or / \_ . -, and different from the Standard numbering (add e.g. /A)." | The format is not allowed | Correct the prefix or suffix | | "Invoices already use this series: prefix, suffix and yearly restart can no longer change. Create a new series." | The series is already in use | Press **New series** | ## Related [#related] Where the number is assigned, from draft to sending. Read and create series with the API or MCP. What `00404` and `00425` mean. # Reports and your accountant (https://docs.getbeel.com/en/guide/report-e-commercialista) Profit and loss, cash flow and receivables aging; the export for your accountant and how to invite them read-only. In **Taxes → VAT and reports**, below your VAT position, you find the company's **Management reports** and the **For your accountant** section. From here you hand your data to your _commercialista_ (accountant), or give them direct read-only access. ![The Drive: documents, invoices and bank statements sorted by month, ready for your accountant.](/screenshots/drive.en.webp) The reports help you follow how the company is doing. They are not the annual financial statements (_bilancio d'esercizio_): they are net of VAT and ignore accruals and deferrals, depreciation, staff, inventory and taxes. Your accountant's figures prevail. ## Before you start [#before-you-start] - **An Italian company.** **Taxes** appears only for companies whose country is Italy. - **Invoices and transactions in Getbeel.** Review supplier invoices in **Received invoices**, and connect your bank or upload statements in **Reconciliation**. - **To invite your accountant**: the **Owner** or **Member** role, and their email. - **No need** for your accountant to use Getbeel: the export opens in their accounting software. - **Cost:** the reports are free; for plans see [Pricing](/en/api/pricing). ## Steps [#steps] ### Open the reports [#open-the-reports] Open **Taxes** and the **VAT and reports** tab. Scroll down to **Management reports**. ### Choose the report and the period [#choose-the-report-and-the-period] Choose **Profit and loss**, **Cash flow** or **Receivables aging**. Then choose the period: the current year, last year or one of the last four quarters. ### Download the export for your accountant [#download-the-export-for-your-accountant] In **Export for your accountant**, choose the **Period** and then **Download ZIP**. ### Invite your accountant [#invite-your-accountant] In **Invite your accountant**, choose **Invite your accountant**. Enter the **Accountant's email** and choose **Send invitation**. ## What just happened [#what-just-happened] - **You opened the reports** calculated from your invoices and bank transactions. - **The period's report** is ready, with a month-by-month breakdown. - **You have the ZIP** with what the period's bookkeeping needs. - **Your accountant received an email** with the link. They log in with their own account and see the company read-only. Until they accept, it shows **Invitation sent**. ## The reports [#the-reports] - **Profit and loss**: revenue from issued invoices accepted by SDI and costs from the supplier invoices you reviewed. By document date, VAT excluded, month by month. Costs are split by category. Credit notes subtract; _autofatture_ (self-invoices) and the other VAT-only documents (TD16–TD23, TD27) are not revenue. Below, you see what was left out: invoices still at SDI and supplier invoices to review. - **Cash flow**: money in and out of connected accounts and uploaded statements, month by month, by booking date. Payments out matched to a supplier invoice are grouped by its category. Payments you record by hand on issued invoices are shown separately. - **Receivables aging**: what customers still owe you today. It is split into not yet due, overdue by 1–30, 31–60, 61–90 and over 90 days, by customer and by invoice. The balance deducts withholding tax, credit notes, split-payment VAT (paid by the public body) and recorded payments. If an invoice has no due date, Getbeel counts 30 days from its date: the statutory term for commercial transactions (art. 4 D.Lgs. 231/2002). Accrual by document date follows art. 2423-bis of the Civil Code (c.c.). ## What is in the ZIP [#what-is-in-the-zip] - the issued and received **XML** e-invoices and the _autofatture_, exactly as they went through SDI; - the **_prima nota IVA_** (VAT journal) as CSV, one line per document and rate, with the XML file name; - the sales and purchase **VAT registers** (_registri IVA_) for each settlement period; - the period's **bank transactions**; - a `LEGGIMI.txt` file that explains the contents and lists any missing documents. TeamSystem, Zucchetti, Profis and other accounting packages import the invoice XML files directly. The CSV files open in Excel. ## What your accountant sees [#what-your-accountant-sees] The **Accountant** role is read-only. They see issued and received invoices, _autofatture_, reconciliation, Drive and the **Taxes** section (deadlines, registers, settlements, reports) and can export. They cannot change anything. If they follow several companies on Getbeel, they find them all in their sidebar, under **Clients**. Remove access whenever you like from **Settings → Members**, or with **Manage access**. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------ | | "Too many documents for this period: choose a quarter or a month." | The period has too many documents for one report | Choose a quarter | | "Too many documents for one file: choose a quarter." | The year's ZIP would be too large | Download one quarter at a time | | "Available for Italian companies only." | The company's country is not Italy | Set Italy in **Settings → Company** | | "The export failed. Try again." | The file could not be created | Try again in a few minutes | | "The invitation failed. Try again." | The invitation was not sent | Check the email and try again | | The profit and loss has few costs | The supplier invoices are not reviewed | Review them in **Received invoices** | ## From the API and the AI assistant [#from-the-api-and-the-ai-assistant] The same data is available through the API (`GET /v1/companies/me/reports/{type}`, `GET /v1/companies/me/accountant-export`) and the MCP tools `get_report` and `get_accountant_export`: see [Reports and export](/en/api/reports). To invite or remove your accountant from code, use `invite_advisor` and `remove_advisor`: see [Advisors (your accountant)](/en/api/advisors). ## Next steps [#next-steps] Registers, settlements and F24 next to the reports. What each role can do, the accountant included. Complete cash flow without uploading statements. # Withholding tax (ritenute) (https://docs.getbeel.com/en/guide/ritenute) Invoices with ritenuta and cassa previdenziale, withholdings to pay when you pay a professional, F24 code 1040 and data for the Certificazione Unica. The _ritenuta d'acconto_ (withholding tax on fees) concerns Getbeel in two cases: when you **issue** an invoice as a professional, and when you **pay** a professional or an agent. ## Before you start [#before-you-start] - **To issue**: complete company data in **Settings → Company**. - **To pay withholdings**: in **Taxes → Deadlines**, answer **Yes** to "Do you pay professionals (lawyers, consultants, freelancers) with a withholding (ritenuta d'acconto)?". - **Not needed** in the _regime forfettario_ (flat-rate scheme) and the minimi scheme: no withholding applies to the fees you pay (art. 1, c. 69, L. 190/2014). - **Cost**: recording fees and preparing the F24 are free; the F24 is charged once, when you record its receipt ([Pricing](/en/api/pricing)). ## Issue an invoice with a withholding [#issue-an-invoice-with-a-withholding] ### Open the withholding fields [#open-the-withholding-fields] In **Issued invoices → New invoice**, choose **Show more fields** and turn on **Withholding tax (ritenuta d'acconto)**. ### Choose type, rate and causale [#choose-type-rate-and-causale] The type is RT01 if you are an individual, RT02 if you are a company. Enter the rate (usually 20%) and the **Payment reason (causale)**. It is the code the customer will use in the Certificazione Unica: A for regular self-employment, M for occasional work, R for a multi-firm agent's commissions. ### Compute the amount [#compute-the-amount] Choose **Use € …** under the amount. Getbeel computes the withholding on the lines subject to it, plus the pension fund contribution if it is subject too. Lines with natura N1 (expenses paid in the customer's name and on their behalf) are not subject. For commissions the withholding applies only to a share: 50%, or 20% if the agent uses employees or third parties (art. 25-bis DPR 600/1973). Enter the amount yourself. ### Add the cassa previdenziale [#add-the-cassa-previdenziale] If needed, add the **Pension fund contribution** and say whether it is subject to withholding (for example the 4% INPS rivalsa). The contributo integrativo of the professional funds is not part of the fee. ### Add withheld contributions [#add-withheld-contributions] If the customer also withholds a contribution, choose **Add a contribution withheld (INPS, ENASARCO…)**. In the totals you see **Withheld by the customer** and **Net amount due**. The net is what the customer pays you and the payment amount in the e-invoice. The document total does not change. ## Pay withholdings when you pay a professional [#pay-withholdings-when-you-pay-a-professional] If you pay fee notes or commissions, you are a **sostituto d'imposta** (withholding agent). You withhold the amount and pay it with F24, **tax code 1040**, by the **16th of the month after the payment** (art. 25 DPR 600/1973; art. 18 D.Lgs. 241/1997). ### Collect the fees [#collect-the-fees] Open **Taxes → Withholdings**. Professionals' invoices received from SDI with a withholding show up on their own in **Fees to pay**. For those that arrived earlier, choose **Import from received invoices**. ### Add fees without an SDI invoice [#add-fees-without-an-sdi-invoice] For a paper fee note or occasional work, choose **Add a fee**. Enter the professional, codice fiscale, causale, gross fee without VAT and amounts not subject. ### Mark the payment [#mark-the-payment] When you pay, choose **Mark paid** and enter the **Payment date**. The withholding happens on payment: an October invoice paid in November is due by 16 December. ### Prepare the F24 [#prepare-the-f24] In **Withholdings to pay** you find each month's total with its deadline. Choose **Prepare the F24**: you get the values to copy into F24 web or your bank (Erario section, code 1040, month and year). ### Upload the receipt [#upload-the-receipt] After paying, choose **I paid: upload the receipt** on the F24 page. The withholdings become **Remitted** and can no longer be changed. Getbeel takes the CU amounts from the invoice: gross fee without VAT, amounts not subject, taxable amount and withholding. If something does not add up, the fee is flagged **To check**: fix it with **Edit**. ## Prepare the CU and 770 data [#prepare-the-cu-and-770-data] ### Choose the year [#choose-the-year] At the bottom of **Taxes → Withholdings**, open **Certificazione Unica and 770** and choose the year. What counts is the year you paid the fee, not the invoice year. ### Download the file [#download-the-file] For each professional and causale you find gross (box 4), amounts not subject (box 7), taxable amount (box 8) and withholdings (box 9). For the **770** you find each month's withholdings with their F24. Choose **Download Excel** or **Download CSV** and give the file to whoever files the CU and the 770. Getbeel does not prepare the electronic file for the Agenzia. The deadlines, per the CU 2026 instructions: - the CU to the professional by **16 March**; - the CU to the Agenzia by 16 March, or by **30 April** if it holds only regular self-employment or non-occasional commissions; - the **770** by 31 October. For fees paid in 2026 the CU 2027 instructions apply, expected in January 2027: check them. ## What just happened [#what-just-happened] - **The issued invoice** carries the withholding and the net amount due in the FatturaPA file. - **The fees you received** are recorded, with the payment date that sets the month of the payment to the Erario. - **The month's F24** is ready and, after the receipt, paid. - **The CU and 770 data** are ready to hand over. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------- | | "The professional's codice fiscale is missing: the CU needs it." | The invoice or fee has no codice fiscale | Choose **Edit** and add it | | "First record the day you paid the fee." | The fee is not marked as paid | Choose **Mark paid** | | "This F24 does not match the fees recorded for the month" | You added or changed fees after preparing the F24 | Choose **Compute again** before paying | | "This withholding was already paid with an F24: it can no longer change." | The fee is in a paid F24 | Leave it as it is; fix it with your accountant | | "This invoice already has a withholding: edit that one." | That invoice's withholding is already recorded | Open the existing row and choose **Edit** | | A withholding was in an F24 paid outside Getbeel | Getbeel does not know about that payment | Choose **Already paid** on the row | ## Sources [#sources] - [FatturaPA technical specifications, Allegato A, version 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) and [XSD schema 1.2.3](https://www.fatturapa.gov.it/it/norme-e-regole/documentazione-fattura-elettronica/formato-fatturapa/) - Art. 25 and 25-bis DPR 600/1973; art. 18 D.Lgs. 241/1997; art. 1, c. 69, L. 190/2014 - [Tax code 1040](https://www1.agenziaentrate.gov.it/servizi/codici/ricerca/SezioneErario.php?CT=1040) and [Risoluzione 13/E of 17 March 2016](https://www.agenziaentrate.gov.it/portale/documents/20143/303158/Risoluzione+n.+13+del+17+marzo+2016_RIs+13e+del+17.03.16.pdf/21945510-c111-1c5d-bc36-ea35db076953) - [Certificazione Unica 2026 instructions](https://www.agenziaentrate.gov.it/portale/documents/20143/9602395/CU_istruzioni_2026.pdf/4184818b-05a3-acce-5956-70811c7d2233) and the Modello 770/2026 instructions ## Next steps [#next-steps] All the deadlines, with the month's withholdings F24. The rest of the invoice, up to the SDI outcome. Record fees and read the CU data from your code. # Tax estimate (https://docs.getbeel.com/en/guide/stima-imposte) How much to set aside for IRES and IRAP (companies), IRPEF and its surcharges (individuals in the ordinary regime), the forfettario or minimi substitute tax, and INPS, with the dates of advances and balance. An estimate to check with your accountant. In **Taxes → Tax estimate** Getbeel estimates the year's taxes from your invoices and fixed assets. It also shows when to pay the advances and the balance, so you can plan cash. It is not the amount to pay. Your accountant computes the final taxes with the income tax return. ## Before you start [#before-you-start] - **The year's invoices in Getbeel**: issued and accepted by SDI, received and already reviewed. - **Your registered [fixed assets](/en/guide/cespiti)**, if any: depreciation counts instead of their cost. - **The data Getbeel does not know**: staff costs, other costs and revenue, your region's IRAP rate, last year's taxes. - **No need** for any link to the Agenzia: the estimate uses only the data in Getbeel. - **Not available** for partnerships and other special regimes. - **Cost**: saving your data is free ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Open the estimate [#open-the-estimate] Open **Taxes → Tax estimate**. With no saved data you see the default values. ### Choose legal form and regime [#choose-legal-form-and-regime] In **Legal form and regime**, choose **Company (IRES + IRAP)**, **Regime forfettario**, **Individual, ordinary regime (IRPEF)** or **Minimi regime**. ### Fill in your data [#fill-in-your-data] Enter what Getbeel cannot know. For a company: staff, IRES tax adjustments, IRAP rate, last year's taxes. For the forfettario: ATECO code, pension scheme, contributions paid, last year's substitute tax. ### Save [#save] Choose **Save and recompute**. Getbeel saves the data for this year and updates the estimate. ### Check the warnings [#check-the-warnings] Read **Missing or to check**: for example received invoices still to review, or documents in a foreign currency that are not counted. ### Read the deadlines [#read-the-deadlines] In **Advance payments and balance** you find dates, F24 tax codes and estimated amounts. Dates marked **To confirm** follow today's rules but are not confirmed yet. ## What just happened [#what-just-happened] - **The estimate uses your documents**: the year's revenue, costs, depreciation and gains. - **Your data is saved** for the year: change it when needed, and the estimate updates. - **You have the dates** of advances and balance with the tax codes, to check with your accountant. ## Where the numbers come from [#where-the-numbers-come-from] - **Revenue**: the year's issued invoices accepted by SDI, net of VAT. Credit notes subtract; autofatture are not revenue. For the forfettario, what counts is the **collections** recorded on invoices (cash basis), or the invoices if you choose **Invoiced in the year**. - **Costs**: the year's received invoices already reviewed, net of VAT, without assets registered as fixed assets. **Depreciation** and assets deducted in full count instead. - **Gains and losses** on fixed assets sold. Received invoices still to review and documents in a foreign currency are not counted: Getbeel flags them. ## Companies: IRES and IRAP [#companies-ires-and-irap] - **IRES 24%** on profit plus the tax adjustments you enter (art. 77 TUIR). The reduced 20% IRES of L. 207/2024 applied to 2025 only. - **IRAP 3.9%** (art. 16 D.Lgs. 446/1997) on the value of production: revenue minus costs, **without** staff costs. Permanent employees are the exception: they are deductible (art. 5 and art. 11 c. 4-octies). - Regions can change the IRAP rate by 0.92 points: enter your region's rate. Getbeel does not compute prior-year losses, limits on interest expense or IRAP deductions for small tax bases. ## Regime forfettario [#regime-forfettario] Income is revenue × the **profitability coefficient** of the ATECO group (Allegato 4 L. 190/2014): | Group | ATECO | Coefficient | | ------------------------------------------------------------------------------------------ | ------------------------------ | ----------- | | Food and beverage industries | 10–11 | 40% | | Wholesale and retail trade | 45; 46.2–46.9; 47.1–47.7; 47.9 | 40% | | Street trade in food and beverages | 47.81 | 40% | | Street trade in other products | 47.82–47.89 | 54% | | Construction and real estate | 41–43; 68 | 86% | | Trade intermediaries | 46.1 | 62% | | Accommodation and food service | 55–56 | 40% | | Professional, scientific, technical, health, education, financial and insurance activities | 64–66; 69–75; 85; 86–88 | 78% | | Other economic activities | all others | 67% | - The **pension contributions paid** in the year are subtracted from income (c. 64). - **Substitute tax 15%**, or **5%** for the first five years of a new business (c. 65). - Above **€85,000** of revenue you leave the regime the next year; above **€100,000** you leave at once (c. 54 and 71). ATECO 2025 codes use the coefficient of the matching ATECO 2007 code (D.Lgs. 81/2025). If the group derived from the code is wrong, pick it by hand in **Activity group (Allegato 4)**. ### INPS contributions 2026 [#inps-contributions-2026] - **Gestione separata** (professionals without their own fund): 26.07% of income, up to €122,295 (INPS circolare n. 8 of 3 February 2026). - **Artisans and traders**: fixed contributions on the minimum income of €18,808, that is €4,521.36 for artisans and €4,611.64 for traders, maternity included. On income above the minimum, add 24% (artisans) or 24.48% (traders), plus one point above €56,224 (INPS circolare n. 14 of 9 February 2026). - Forfettario artisans and traders who asked for it pay 35% less (c. 77). - **Professional funds** (casse professionali): enter the amount yourself in **Contributions of the year (€)**. ## Individuals in the ordinary regime (IRPEF) [#individuals-in-the-ordinary-regime-irpef] - Income is revenue minus costs of the year; the impatriati reduction from your tax profile applies to professional income. - With **rientro docenti e ricercatori** in your tax profile, only 10% of professional income is taxed (DL 78/2010 art. 44). With the **neo-residenti** option, the yearly flat tax on foreign income (TUIR art. 24-bis) is added as its own line, paid in one go with F24 ELIDE (code NRPP) by the balance date. - INPS is subtracted, then IRPEF by bracket: 23% up to €28,000, 33% (35% in 2025) up to €50,000, 43% above (TUIR art. 11). - The self-employment deduction (TUIR art. 13 c. 5) is computed on the income before INPS; withholding tax your clients kept (ritenute) is subtracted. - Regional (1.23% base) and municipal surcharges are due only when net IRPEF is due (D.Lgs. 446/1997 art. 50). ## Minimi regime (regime di vantaggio) [#minimi-regime-regime-di-vantaggio] For those still in the regime (entered by 2015, for five years and until the year they turn 35: DL 98/2011 art. 27): - Income is what you **collected** minus the expenses of the year; fixed assets are deducted **in full** in the year you buy them (L. 244/2007 c. 104). - The INPS contributions are subtracted up to the income, then earlier losses (**Losses of earlier years (€)**). - **Substitute tax 5%**, instead of IRPEF and the surcharges. - Above **€30,000** of revenue the regime ends from next year; above **€45,000** it ends this year (c. 111). - If you sell an asset, the whole sale price is income: add it to **Other revenue**. ## Advance payments and balance [#advance-payments-and-balance] Getbeel lists the deadlines with the F24 tax codes: | Tax | First advance | Second advance | Balance | | -------------------------- | ------------- | -------------- | ------- | | IRES | 2001 | 2002 | 2003 | | IRAP | 3812 | 3813 | 3800 | | Forfettario substitute tax | 1790 | 1791 | 1792 | | IRPEF | 4033 | 4034 | 4001 | | Regional surcharge | — | — | 3801 | | Municipal surcharge | 3843 (30%) | — | 3844 | | Minimi substitute tax | 1793 | 1794 | 1795 | - **Balance and first advance** by 30 June, or within the next 30 days with 0.40% more. **Second advance** by 30 November (art. 17 DPR 435/2001). - In 2026, ISA taxpayers and forfettari paid by 20 July (DL 89/2026). - The advance is 100% of the previous year's tax: 40% and 60%, or 50% and 50% for ISA taxpayers and forfettari (art. 58 DL 124/2019; ris. AdE 93/E/2019). - If the first advance is up to €103, you pay it all in November. - No advance is due if the previous year's tax is up to €20.66 (IRES and IRAP) or below €52 (IRPEF and the substitute taxes). - Without last year's tax, the advances are computed on this year's estimate (forecast method). The 2027 dates are marked **To confirm**: from 2027 payments move to the Testo unico D.Lgs. 33/2025. ## If it fails [#if-it-fails] | Message | Cause | Fix | | -------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------- | | "… received invoices of the year are still to review: their costs are not counted." | Some supplier invoices are not reviewed | Review them in **Received invoices** | | "Give the ATECO code or group: without the coefficient the income cannot be computed." | The ATECO code is missing | Enter **ATECO code** or pick the **Activity group (Allegato 4)** | | "Deducted contributions assumed equal to the year's: enter those paid in the year." | **Contributions paid in the year (€)** is empty | Enter the contributions paid and choose **Save and recompute** | | "Car or phone depreciation is counted in full: the deductible part is smaller …" | You have fixed assets with limited deductibility | Adjust the estimate with your accountant | | "No estimate for this legal form." | Partnership or another special regime | Ask your accountant for the estimate | | "Saving needs an active plan …" | The account has no plan | Choose a plan in **Settings → Usage & billing** | ## Sources [#sources] - TUIR (DPR 917/1986) art. 77, text in force at 31 December 2026. - D.Lgs. 446/1997 art. 5, 11, 16 and the IRAP 2026 instructions. - L. 190/2014 art. 1 c. 54–89 and Allegato 4; AdE circolare 9/E of 10 April 2019; D.Lgs. 81/2025 art. 1. - INPS circolari [n. 8 of 3 February 2026](https://www.inps.it/content/dam/inps-site/it/scorporati/circolari-e-messaggi/2026/02/Circolare_15153/Allegati/16573_Circolare-numero-8-del-03-02-2026.pdf) and [n. 14 of 9 February 2026](https://www.inps.it/content/dam/inps-site/it/scorporati/circolari-e-messaggi/2026/02/Circolare_15162/Allegati/16561_Circolare-numero-14-del-09-02-2026.pdf). - Art. 17 DPR 435/2001; art. 58 DL 124/2019; ris. AdE 93/E/2019; DL 89/2026 art. 6; Redditi 2026 instructions. Not confirmed by an official source: - the dates and split of the advances from 2027 (Testo unico versamenti); - whether forfettari INPS contributions are computed on income before deducting contributions (Getbeel does so); - the advances on INPS contributions, which Getbeel does not compute. ## Next steps [#next-steps] Register your business assets: the estimate uses their depreciation. The year's VAT, stamp duty and withholding deadlines. Read the estimate from your code or the AI assistant. # Taxes (https://docs.getbeel.com/en/guide/tasse) Deadlines, VAT registers and settlements kept up to date from your invoices. Getbeel prepares the F24; you check and pay. *Video tutorial coming soon.* **Taxes** keeps deadlines, VAT registers and VAT settlements (_liquidazione IVA_) up to date from the documents in Getbeel. You check the flagged rows, prepare the F24 payment form when you are ready, and pay it yourself. ![The Taxes page: the month's deadlines with the amount, status and action of each.](/screenshots/taxes.en.webp) ## Before you start [#before-you-start] - **Your tax settings**, once. In **Taxes → Deadlines**, answer **How do you pay VAT?** and the question about professionals paid with a withholding. Getbeel builds the deadlines from these. - **Your documents in Getbeel**: issued invoices, supplier invoices (from SDI, from email or uploaded) and autofatture (self-billed invoices). Getbeel counts only what is in Getbeel. - **No need** to fill in the registers by hand. Getbeel does not ask for your Agenzia delle Entrate credentials and does not pay for you. - **Cost**: preparing the F24 and the LIPE is free; each filing is charged once, when it is paid or filed ([Pricing](/en/api/pricing)). ## What Getbeel updates on its own [#what-getbeel-updates-on-its-own] - **VAT registers.** Getbeel computes them from the documents each time you open them. A supplier invoice read by the AI but not yet reviewed goes in at once, flagged **Not reviewed yet**. - **VAT settlements.** They are also recomputed from the registers each time you open them: output VAT, deductible VAT and the result. - **Carry-over from the previous period.** The credit (line VP8) or the debt up to €100 (line VP7) comes from the saved settlement. If you did not save it, Getbeel computes it from its registers. An amount you enter replaces the computed one. - **Deadlines.** The VAT payment shows the computed amount, followed by **so far**, until you save the settlement. Stamp duty (bollo) and withholdings do the same until the period is closed. At the top of **VAT registers** and **VAT settlements** you read **Updated at** with the time of the calculation and how many rows need checking. Getbeel does not prepare the F24 and the LIPE on its own: they stay **To prepare** until you prepare them. ## Steps [#steps] ### Check the rows to review [#check-the-rows-to-review] Open **Taxes → VAT registers** and pick the period. Rows marked **Not reviewed yet** lose that flag when you review the invoice in **Received invoices**. If a purchase is not deductible, or only partly, choose **Edit** on the row. Then **Exclude from the settlement** or **Enter the VAT that counts**, always with a reason. For a purchase with non-deductible VAT, enter 0. ### Check the settlement [#check-the-settlement] Open **Taxes → VAT settlements** and pick the period. The lines are the same as in the LIPE. The fields **Previous period's credit** and **Debt up to €100 not paid** are already filled in by Getbeel. Change them only if your accountant gives you a different amount. ### Save the settlement [#save-the-settlement] Once the period is closed, choose **Save and prepare the F24**. If there is something to pay, Getbeel prepares the F24; otherwise you see **Settlement saved: nothing to pay now.** ### Pay the F24 [#pay-the-f24] Choose **Open the F24**. Use **Download the F24 reminder (PDF)** or copy the values with **Copy**. Pay from F24 web or from your bank. ### Upload the receipt [#upload-the-receipt] On the same page, choose **I paid: upload the receipt** (PDF, PNG or JPEG up to 10 MB). The deadline becomes **Paid**. ### Prepare the quarter's LIPE [#prepare-the-quarters-lipe] Once the quarter is closed and all its settlements are saved, choose **Prepare the LIPE file** in **Taxes → VAT settlements**. The LIPE is the quarterly report of VAT settlements. For a company, enter **Tax code of the signer** and **Role**. ### Send the LIPE [#send-the-lipe] Choose **Open the LIPE** and **Download the LIPE file (XML)**. Check it with the Agenzia's software, then upload it to Fatture e Corrispettivi, or give it to your accountant. Finally, upload the receipt under **Did you send the LIPE?**. ## What just happened [#what-just-happened] - **The registers were already complete**: you checked only the rows Getbeel was unsure about. - **The settlement is saved** with its amounts, which feed the next settlement and the LIPE. - **The F24 is ready**, with the values to copy and the PDF reminder. - **The deadline is paid**, with the receipt kept in Getbeel. - **The LIPE is ready** from the saved settlements, already checked against the official IVP18 schema. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------- | | "Answer two questions to see all your deadlines." | The tax settings are missing | Answer the two questions in **Taxes → Deadlines** | | "No data for the previous period in Getbeel: enter any credit or debt carried." | It is the first period of the year with data in Getbeel | Enter the credit or debt from the previous settlement | | "The registers changed since you saved this settlement: save it again." | A document of the period changed after you saved | Save the settlement again before paying | | "Being read by the AI" or "Euro amounts missing" in **VAT registers** | The document has no amounts yet, or none in euros | Wait for the reading; for foreign currency, fill in the euro amounts | | "Save the settlements of the quarter first." | A saved settlement is missing for the LIPE | Save each month, or the quarter, in **Taxes → VAT settlements** | | "Preparing filings needs an active plan." | The account has no plan | Choose a plan in **Settings → Usage & billing** | Getbeel prepares; you and your accountant check before paying or sending. ## Sources [#sources] - Monthly payment by the 16th and debt up to €100 carried forward: art. 1, c. 1 and 4, DPR 100/1998. - Quarterly payment with 1% interest: art. 7 DPR 542/1999. - Lines VP7, VP8 and the LIPE: model and technical specifications IVP18 approved by AdE provv. prot. 125654 of 14 March 2024 ([Liquidazioni periodiche IVA](https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/liquidazioni-periodiche-iva)). ## Next steps [#next-steps] The annual data, from the registers and the saved settlements. Withholdings on fees paid to professionals, F24 code 1040 and the CU. Exports and read-only access for your accountant. # Team collaboration (https://docs.getbeel.com/en/guide/team-collaboration) Each company is a team with its own members: Owner, Member or Accountant, each with their own permissions. In Getbeel each company is a **team**: its data is kept apart and each person joins with a role. The role decides what they see and what they can change. ## At a glance [#at-a-glance] | What | Rule | | ----------------- | ---------------------------------------------------------------- | | A team | One company, with its invoices, banks, settings and subscription | | Several companies | You create a team for each and switch between them | | Who gets in | Only people you invite by email, with a role | | Roles | **Owner**, **Member**, **Accountant** | ## Teams [#teams] A team keeps invoices, inboxes, connected banks, settings and subscription apart. People in one team see nothing of the others. Create another team from **Switch workspace** → **Create a team**. If you follow several companies, as a _commercialista_ (accountant) does, you can manage them from **Client companies**. ## Roles [#roles] - **Owner**: full access. Manages billing, members and settings. - **Member**: works on invoices, reconciliation and analytics, and changes settings. Does not manage the subscription or roles. - **Accountant**: read-only. Sees and exports invoices, reconciliation, Drive and Taxes, but changes nothing. The details are in [Roles and permissions](/en/guide/team-collaboration/roles-permissions). ## The primary owner [#the-primary-owner] Whoever creates the team is its **Primary owner**. Only they can delete the team and transfer ownership to another member. ## Related [#related] What each role can do, page by page. Invite a person and manage pending invitations. Invite your accountant read-only from the Taxes page. # Roles and permissions (https://docs.getbeel.com/en/guide/team-collaboration/roles-permissions) What the Owner, Member and Accountant can do, and how to change a person’s role. Each person in the team has a role: **Owner**, **Member** or **Accountant**. You can manage only people with a lower role than yours. ## Before you start [#before-you-start] - **To change a role** you need the **Owner** role. A **Member** can invite but cannot change roles. - **The person must already be in the team.** To add them, see [Team invitations](/en/guide/team-collaboration/team-invitations). - **Cost:** roles cost nothing ([Pricing](/en/api/pricing)). ## The roles compared [#the-roles-compared] | What | Owner | Member | Accountant | | ---------------------------------------------------- | ---------------------- | ------ | ---------- | | See received and issued invoices and _autofatture_ | Yes | Yes | Yes | | Upload, categorise and delete invoices | Yes | Yes | No | | Scan inboxes | Yes | Yes | No | | See Reconciliation and export | Yes | Yes | Yes | | Upload statements, connect the bank, confirm matches | Yes | Yes | No | | See Taxes | Yes | Yes | Yes | | Make changes in Taxes | Yes | Yes | No | | See Drive | Yes | Yes | Yes | | See Overview and Analytics | Yes | Yes | No | | Open Settings (Company, Email, Categories, AI Rules) | Yes | Yes | No | | Create API keys and webhooks | Yes | Yes | No | | Invite people | Yes | Yes | No | | Change roles and remove members | Yes | No | No | | Change plan and payment details | Yes | No | No | | Transfer ownership, delete the team | Only the primary owner | No | No | You can invite people with your role or a lower one. So a **Member** invites **Members** and **Accountants**. ## Change a person's role [#change-a-persons-role] ### Open the members [#open-the-members] Open **Settings → Members**. In **Team members** you find each person with their role. ### Open the person's menu [#open-the-persons-menu] Click ⋯ next to the person and choose **Update role**. ### Choose the role [#choose-the-role] In **Update member's role**, choose the new role and confirm with **Update role**. ## What just happened [#what-just-happened] - **You opened the list** of people in the team. - **The menu** shows only the actions your role allows. - **The new role applies straight away**: on their next page the person sees only what the role allows. ## Other actions on members [#other-actions-on-members] - **Remove from account**: the person loses access to the team. - **Transfer ownership**: only the primary owner, to another member. - **Leave team**: from **Settings → Danger Zone**, by typing `LEAVE`. The primary owner cannot leave the team. The company's invoices, bank and taxes are visible to anyone with this role. Invite them only if they need to follow the bookkeeping. ## If it fails [#if-it-fails] | Message | Cause | Fix | | ------------------------------------------------------------ | ----------------------------------------------------------------- | ---------------------------------------------- | | The ⋯ menu is missing next to a person | The person has a role equal to or higher than yours, or it is you | Ask an Owner | | "Role must be different from the current one" | You chose the same role | Choose another role | | "Sorry, we couldn't update the role of the selected member." | The update failed | Reload the page and try again | | "Sorry, we couldn't remove the selected member." | The removal failed | Try again; the primary owner cannot be removed | ## Next steps [#next-steps] Add a person with the right role. Invite your accountant straight from Taxes. Teams, companies and the primary owner. # Team invitations (https://docs.getbeel.com/en/guide/team-collaboration/team-invitations) Invite people to the team by email with a role, and manage pending invitations: role, renewal and removal. Invite a person by email and choose their role. When they accept, they join the team with that role's permissions. ## Before you start [#before-you-start] - **The Owner or Member role.** The **Accountant** cannot invite. - **The person's email.** If they have no Getbeel account, they create one from the invitation link. - **The right role**: you can assign your role or a lower one. See [Roles and permissions](/en/guide/team-collaboration/roles-permissions). - **For your accountant** there is also **Invite your accountant** in **Taxes** ([Reports and your accountant](/en/guide/report-e-commercialista)). - **Cost:** invitations are free ([Pricing](/en/api/pricing)). ## Steps [#steps] ### Open the members [#open-the-members] Open **Settings → Members**. In **Team members**, choose **Invite members** (the **+** button). ### Enter the email and role [#enter-the-email-and-role] Type the email and choose the role: **Owner**, **Member** or **Accountant**. To invite more people, choose **Add another one**. ### Send [#send] Choose **Send invites**. Each person receives an email with the link. ### The person accepts [#the-person-accepts] From the link, the person logs in or signs up, then sees **Join** with the team's name. They choose **Continue as** with their email. ## What just happened [#what-just-happened] - **You opened the list** of members and invitations. - **Each invitation has a role**, chosen by you. - **The invitation is in Pending Invites**, with "Invited … · expires …". It is valid for 7 days. - **The person is in the team** and disappears from the pending invitations. ## Manage pending invitations [#manage-pending-invitations] In **Pending invites**, open an invitation's ⋯ menu: - **Update invitation**: change the role before it is accepted. - **Renew invitation**: for an **Expired** invitation, extends it by 7 days. - **Remove invitation**: cancels the invitation; the link stops working. Updating, renewing and removing invitations need the **Owner** role. ## If it fails [#if-it-fails] | Message | Cause | Fix | | -------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------- | | "Sorry, members could not be invited. Please try again." | The invitation was not sent, for example a repeated email | Check the emails you entered and try again | | "Invite not found or expired" | 7 days have passed, or the invitation was removed | Ask the owner to use **Renew invitation** or to invite you again | | "This invitation link is invalid. Please contact the team owner to send a new invite." | The link is incomplete or altered | Open the link from the email, or ask for a new invitation | | You want to accept with another account | You logged in with the wrong account | Choose **Sign in with a different account** | | You do not see **Invite members** | Your role is **Accountant** | Ask an Owner or a Member | ## Next steps [#next-steps] What the person you invited will be able to do. Give your accountant read-only access. The other steps to set up your company. # The prepaid balance (https://docs.getbeel.com/en/api/reference/billing/getBillingBalance) ## GET /billing/balance ```json { "operationId": "getBillingBalance", "summary": "The prepaid balance", "description": "Spendable balance (expired credit excluded), credit expiring in 30 days, auto top-up and low-balance alert settings (the alert email starts once there is paid credit: a top-up), pricing, and welcome_credit: whether the €1 welcome credit was granted and, if not, why (card_already_used: it applies only once per card). pricing is pay_as_you_go for an account that signed up on or after 13 November 2026, or legacy_plan for one that signed up before: it keeps its plan and everything it includes, nothing is paid from a balance, the amounts are 0 and topup_url is null. A client company (Getbeel-Company) sees its gestore’s balance with billed_to_parent true. Usage, top-ups and card links answer 409 not_pay_as_you_go for a legacy_plan account.", "tags": [ "Billing" ], "x-required-scope": "account:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'account:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Usage of a month (https://docs.getbeel.com/en/api/reference/billing/getBillingUsage) ## GET /billing/usage ```json { "operationId": "getBillingUsage", "summary": "Usage of a month", "description": "Quantity and amount per item, the next unit price at this month’s tier, and per client company for a gestore.", "tags": [ "Billing" ], "x-required-scope": "account:read", "parameters": [ { "name": "month", "in": "query", "required": false, "description": "YYYY-MM (UTC); default: this month", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingUsage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'account:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The price list (https://docs.getbeel.com/en/api/reference/billing/getBillingPrices) ## GET /billing/prices ```json { "operationId": "getBillingPrices", "summary": "The price list", "description": "Every billable item with its unit and tiers (per billing account per calendar month). The same list as the pricing page.", "tags": [ "Billing" ], "x-required-scope": "account:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'account:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Add credits (payment link) (https://docs.getbeel.com/en/api/reference/billing/createBillingTopup) ## POST /billing/topups ```json { "operationId": "createBillingTopup", "summary": "Add credits (payment link)", "description": "Returns a Stripe Checkout link for a person to pay (VAT added at checkout, one invoice per top-up); the API never charges a card. Checkout opens in the key creator’s language (else the owner’s, else Italian for an Italian company) and offers only the current default card. Live keys, billing:write, created by someone who can manage billing; not for a client company.", "tags": [ "Billing" ], "x-required-scope": "billing:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTopupRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupCheckout" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'billing:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change the card (setup link) (https://docs.getbeel.com/en/api/reference/billing/createBillingCardLink) ## POST /billing/payment-method ```json { "operationId": "createBillingCardLink", "summary": "Change the card (setup link)", "description": "Returns a Stripe Checkout link (setup mode, nothing is charged) for a person to enter a new card; it becomes the default card and the one auto top-ups charge. The same card saved twice is kept once. Live keys, billing:write, created by someone who can manage billing; not for a client company; 409 no_card (application/problem+json, the same shape as the 402) when no card is saved yet. The Checkout opens in the key creator’s language (else the owner’s, else Italian for an Italian company).", "tags": [ "Billing" ], "x-required-scope": "billing:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardCheckout" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'billing:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No card saved yet (no_card), as application/problem+json like the 402 insufficient_balance", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List AI rules (https://docs.getbeel.com/en/api/reference/ai-rules/listAiRules) ## GET /ai-rules ```json { "operationId": "listAiRules", "summary": "List AI rules", "description": "The team's AI rules, by type and in the order the AI reads them (only active ones are followed). Filter with type; without it, the rules of every type the key can read. The scope follows the rule type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes. Both key modes.", "tags": [ "AI rules" ], "x-required-scope": "received_invoices:read", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "invoice_scan", "fattura_emessa" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRuleList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Add an AI rule (https://docs.getbeel.com/en/api/reference/ai-rules/createAiRule) ## POST /ai-rules ```json { "operationId": "createAiRule", "summary": "Add an AI rule", "description": "Adds a rule at the end of its type (default invoice_scan), active unless active is false. It applies to the next invoices the AI reads; invoices already read stay as they are. The scope follows the rule type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes. Live keys only.", "tags": [ "AI rules" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiRuleRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRule" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change or pause an AI rule (https://docs.getbeel.com/en/api/reference/ai-rules/updateAiRule) ## PATCH /ai-rules/{id} ```json { "operationId": "updateAiRule", "summary": "Change or pause an AI rule", "description": "Changes the text, or pauses (active false) or resumes the rule; the type stays. The scope follows the rule type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes. Live keys only.", "tags": [ "AI rules" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiRuleRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRule" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete an AI rule (https://docs.getbeel.com/en/api/reference/ai-rules/deleteAiRule) ## DELETE /ai-rules/{id} ```json { "operationId": "deleteAiRule", "summary": "Delete an AI rule", "description": "Deletes the rule and returns it as it was. To stop it for a while, pause it instead. The scope follows the rule type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes. Live keys only.", "tags": [ "AI rules" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRule" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Tax rules in force (https://docs.getbeel.com/en/api/reference/tax-rules/getTaxRules) ## GET /tax-rules ```json { "operationId": "getTaxRules", "summary": "Tax rules in force", "description": "Every rule value by date (origin code: shipped with getbeel; db: added since), the values missing in the next 13 months, and the proroghe in force. pending (the proposals of the rules watch) and watch_runs are null unless the key is a live key of a getbeel administrator. Both key modes.", "tags": [ "Tax rules" ], "x-required-scope": "taxes:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRules" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Add a rule value (https://docs.getbeel.com/en/api/reference/tax-rules/createTaxRuleValue) ## POST /tax-rules/values ```json { "operationId": "createTaxRuleValue", "summary": "Add a rule value", "description": "Adds a value of a known key for its dates. status active puts it in force at once, only with an official source (agenziaentrate.gov.it, mef.gov.it, finanze.gov.it, gazzettaufficiale.it, inps.it, normattiva.it, fatturapa.gov.it; 400 official_source_required otherwise); pending (default) waits for approval. Two active values of a key never overlap (409 rule_value_overlap). Tax rules apply to every company: only getbeel administrators change them, with a live key that has the admin-only tax_rules:admin scope (created in the admin page; 403 insufficient_scope otherwise, 403 live_key_required with a test key, 403 super_admin_required when its creator is no longer an administrator). Recorded in the audit log.", "tags": [ "Tax rules" ], "x-required-scope": "tax_rules:admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaxRuleValueRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRuleValue" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'tax_rules:admin' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Add a proroga (https://docs.getbeel.com/en/api/reference/tax-rules/createTaxCalendarOverride) ## POST /tax-rules/overrides ```json { "operationId": "createTaxCalendarOverride", "summary": "Add a proroga", "description": "Moves the deadlines of deadline_kind (all: every tax deadline; never the EU OSS return or the bilancio deposit) whose legal date is in nominal_from–nominal_to to new_due_date, from valid_from. status active applies it at once (official source required), updates prepared unpaid filings and tells the teams it affects in the app; pending (default) waits for approval. Tax rules apply to every company: only getbeel administrators change them, with a live key that has the admin-only tax_rules:admin scope (created in the admin page; 403 insufficient_scope otherwise, 403 live_key_required with a test key, 403 super_admin_required when its creator is no longer an administrator). Recorded in the audit log.", "tags": [ "Tax rules" ], "x-required-scope": "tax_rules:admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaxCalendarOverrideRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxCalendarOverride" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'tax_rules:admin' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Approve or reject a proposal (https://docs.getbeel.com/en/api/reference/tax-rules/decideTaxRule) ## POST /tax-rules/decisions ```json { "operationId": "decideTaxRule", "summary": "Approve or reject a proposal", "description": "Approves (in force at once) or rejects a pending rule value or proroga. Through the API only a proposal with an official source can be approved, and a rules-watch proposal only when its quote was found word for word in the source (400 quote_not_verified: a PDF; approve it in the admin page after reading it). 404 proposal_not_found when it was already decided. Tax rules apply to every company: only getbeel administrators change them, with a live key that has the admin-only tax_rules:admin scope (created in the admin page; 403 insufficient_scope otherwise, 403 live_key_required with a test key, 403 super_admin_required when its creator is no longer an administrator). Recorded in the audit log.", "tags": [ "Tax rules" ], "x-required-scope": "tax_rules:admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideTaxRuleRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRuleDecision" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'tax_rules:admin' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Receiving from SDI: status and readiness (https://docs.getbeel.com/en/api/reference/received-invoices/getSdiReceiving) ## GET /sdi-receiving ```json { "operationId": "getSdiReceiving", "summary": "Receiving from SDI: status and readiness", "description": "Whether the company receives its supplier invoices through getbeel's SDI channel (openapi.com), the codice destinatario to give suppliers and register as indirizzo telematico in the AdE area, a readiness checklist (company data, SDI add-on, receiving on, indirizzo telematico confirmed, conservazione) and the AdE conservazione status. Received invoices appear in GET /received-invoices with source sdi. Both key modes.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdiReceiving" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Turn on receiving from SDI (https://docs.getbeel.com/en/api/reference/received-invoices/enableSdiReceiving) ## POST /sdi-receiving ```json { "operationId": "enableSdiReceiving", "summary": "Turn on receiving from SDI", "description": "Configures the company on the SDI provider so its supplier invoices reach getbeel, and returns the status with the codice destinatario. Then register the code as indirizzo telematico in the AdE area (Fatture e Corrispettivi) and confirm it in the app. Safe to call again. Live keys only (403 livemode_required); test keys use POST /sandbox/inbound-invoices.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdiReceiving" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "No SDI plan: rate card or add-on (sdi_addon_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another getbeel workspace already receives for this P.IVA (fiscal_id_taken)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Company data incomplete (company_not_ready)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The SDI provider refused or did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Turn off receiving from SDI (https://docs.getbeel.com/en/api/reference/received-invoices/disableSdiReceiving) ## DELETE /sdi-receiving ```json { "operationId": "disableSdiReceiving", "summary": "Turn off receiving from SDI", "description": "Stops the SDI provider receiving the company's supplier invoices (sending to SDI is untouched; invoices already received stay) and returns the status. Change or remove the indirizzo telematico in the AdE area afterwards, or new invoices only reach the cassetto fiscale. Safe to call again. Receiving also turns off by itself when the SDI add-on or rate card ends. Live keys only (403 livemode_required).", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdiReceiving" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The SDI provider refused or did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Receive an invoice in the sandbox (https://docs.getbeel.com/en/api/reference/received-invoices/createSandboxInboundInvoice) ## POST /sandbox/inbound-invoices ```json { "operationId": "createSandboxInboundInvoice", "summary": "Receive an invoice in the sandbox", "description": "Test keys only (403 test_mode_required with a live key). Receives a FatturaPA (your XML or base64 .p7m, or a sample addressed to your company when the body is empty) as if a supplier sent it through SDI: it is parsed like a real one, listed by GET /received-invoices with the test key (source sdi, status pending_review) and fires received_invoice.created to test webhook endpoints. Nothing reaches the app.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxInboundInvoiceRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Not a readable FatturaPA (invoice_unreadable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Upload a supplier invoice or receipt (https://docs.getbeel.com/en/api/reference/received-invoices/uploadReceivedInvoice) ## POST /received-invoices/uploads ```json { "operationId": "uploadReceivedInvoice", "summary": "Upload a supplier invoice or receipt", "description": "Uploads a document (PDF, JPEG, PNG or WEBP, up to 50 MB; the type is read from the file, not its name) by file_url (public https, no redirects) or file_base64 with file_name. The AI reads it as an upload in the app does: the invoice then appears in GET /received-invoices with status pending_review. Check progress with GET /received-invoices/uploads/{id}. Uses one invoice credit per file. Live keys only (403 livemode_required).", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadReceivedInvoiceRequest" } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInvoiceUpload" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "No invoice credits left (credits_exhausted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Larger than 50 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Not a PDF, JPEG, PNG or WEBP (unsupported_file_type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Status of an upload (https://docs.getbeel.com/en/api/reference/received-invoices/getReceivedInvoiceUpload) ## GET /received-invoices/uploads/{id} ```json { "operationId": "getReceivedInvoiceUpload", "summary": "Status of an upload", "description": "Where an upload is: pending or processing while the AI reads it, completed (the invoice is in GET /received-invoices), or failed with the error.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInvoiceUpload" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List invoice categories (https://docs.getbeel.com/en/api/reference/received-invoices/listCategories) ## GET /categories ```json { "operationId": "listCategories", "summary": "List invoice categories", "description": "The team's categories for received invoices (expense categories), in the app's order. The slug is what received invoices carry in category. Both key modes.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Add a category (https://docs.getbeel.com/en/api/reference/received-invoices/createCategory) ## POST /categories ```json { "operationId": "createCategory", "summary": "Add a category", "description": "Adds a category; its slug comes from the label (made unique in the team) and, without a colour, it gets the next preset. Live keys only.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCategoryRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Rename or recolour a category (https://docs.getbeel.com/en/api/reference/received-invoices/updateCategory) ## PATCH /categories/{id} ```json { "operationId": "updateCategory", "summary": "Rename or recolour a category", "description": "Changes the label or colour; the slug stays. Live keys only.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCategoryRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete a category (https://docs.getbeel.com/en/api/reference/received-invoices/deleteCategory) ## DELETE /categories/{id} ```json { "operationId": "deleteCategory", "summary": "Delete a category", "description": "Deletes a category and moves its invoices to \"other\". Default categories cannot be deleted (409 default_category). Live keys only.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A default category (default_category)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Set the category of a received invoice (https://docs.getbeel.com/en/api/reference/received-invoices/setReceivedInvoiceCategory) ## POST /received-invoices/{id}/category ```json { "operationId": "setReceivedInvoiceCategory", "summary": "Set the category of a received invoice", "description": "Sets a received invoice's category to one of the team's (a slug from GET /categories; 422 unknown_category otherwise). Live keys only.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetInvoiceCategoryRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Not a category of this team (unknown_category)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List received (supplier) invoices, newest invoice_date first (https://docs.getbeel.com/en/api/reference/received-invoices/listReceivedInvoices) ## GET /received-invoices ```json { "operationId": "listReceivedInvoices", "summary": "List received (supplier) invoices, newest invoice_date first", "description": "Invoices received through SDI (source sdi) and collected from email, forwarding or uploads. With a test key: only the invoices received in the sandbox (POST /sandbox/inbound-invoices).", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "search", "in": "query", "required": false, "description": "Supplier name or invoice number, case-insensitive", "schema": { "examples": [ "Enel" ], "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "source", "in": "query", "required": false, "description": "sdi (received through SDI, see GET /sdi-receiving), email (found by a mailbox scan), forwarded (sent to the forwarding address), manual (uploaded), bank_transaction (created from a bank movement)", "schema": { "type": "string", "enum": [ "email", "forwarded", "manual", "bank_transaction", "sdi" ] } }, { "name": "status", "in": "query", "required": false, "description": "pending_review: extracted, waiting for a person; verified: approved; rejected; exported; missing_document: a payment without its document yet; processing: being extracted", "schema": { "type": "string", "enum": [ "processing", "pending_review", "verified", "rejected", "exported", "missing_document" ] } }, { "name": "date_from", "in": "query", "required": false, "description": "invoice_date on or after (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "date_to", "in": "query", "required": false, "description": "invoice_date on or before (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInvoiceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Approve a collected document (status verified) (https://docs.getbeel.com/en/api/reference/received-invoices/approveReceivedInvoice) ## POST /received-invoices/{id}/approve ```json { "operationId": "approveReceivedInvoice", "summary": "Approve a collected document (status verified)", "description": "Moves a received invoice from pending_review (or rejected) to verified, like reviewing it in the app. Already verified: no change. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not reviewable (processing, missing_document or exported)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Reject a collected document (status rejected) (https://docs.getbeel.com/en/api/reference/received-invoices/rejectReceivedInvoice) ## POST /received-invoices/{id}/reject ```json { "operationId": "rejectReceivedInvoice", "summary": "Reject a collected document (status rejected)", "description": "Moves a received invoice from pending_review (or verified) to rejected. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Received invoices" ], "x-required-scope": "received_invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'received_invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not reviewable (processing, missing_document or exported)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Remove a VAT register adjustment (https://docs.getbeel.com/en/api/reference/taxes/deleteVatAdjustment) ## DELETE /companies/me/vat-adjustments/{key} ```json { "operationId": "deleteVatAdjustment", "summary": "Remove a VAT register adjustment", "description": "The row counts as getbeel computed it again. deleted is false when it had no adjustment. Live keys only.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "The key of a row of GET /companies/me/vat-registers: register:source:document_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedVatAdjustment" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Exclude or correct a VAT register row (https://docs.getbeel.com/en/api/reference/taxes/setVatAdjustment) ## PUT /companies/me/vat-adjustments/{key} ```json { "operationId": "setVatAdjustment", "summary": "Exclude or correct a VAT register row", "description": "The same as Rettifica in Tasse → Registri IVA: exclude keeps the row out of the liquidazione; adjust sets the VAT that counts (vat_amount), for example the deductible share of a car or phone cost. A reason is required and kept with the row for the accountant. It replaces an earlier adjustment of the row. GET vat-registers and vat-settlements show the effect; a liquidazione already saved stays as it was until it is prepared again (POST /filings, type vat_payment). Live keys only.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "The key of a row of GET /companies/me/vat-registers: register:source:document_id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetVatAdjustmentRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatAdjustment" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not a row of this company’s VAT registers (resource_missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The company's Italian tax deadlines (https://docs.getbeel.com/en/api/reference/taxes/getTaxCalendar) ## GET /companies/me/tax-calendar ```json { "operationId": "getTaxCalendar", "summary": "The company's Italian tax deadlines", "description": "Deadlines between from and to (default: 90 days ago to a year ahead), already moved off weekends, holidays and 1–20 August: imposta di bollo on e-invoices (amount computed from the issued invoices), withholding taxes (1040), VAT payments, VAT advance and balance, LIPE, the annual VAT return, the OSS return (never moved), and for companies (IRES subjects) the income-tax saldo and acconti (IRES/IRAP), the Redditi SC and IRAP returns, the diritto camerale and the bilancio deposit. Each has its legal source. Deadlines that depend on settings the app cannot infer (VAT monthly or quarterly, withholding agent, OSS registration, the income-tax answers saved in Stima imposte) appear once they are set in the app (missing_settings). Companies outside Italy get applicable false and no deadlines.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First due date, default 90 days ago", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "examples": [ "2026-10-29" ] } }, { "name": "to", "in": "query", "required": false, "description": "Last due date, default a year from today", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "examples": [ "2026-10-29" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxCalendar" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The tax calendar as an iCal feed (https://docs.getbeel.com/en/api/reference/taxes/getTaxCalendarIcs) ## GET /companies/me/tax-calendar.ics ```json { "operationId": "getTaxCalendarIcs", "summary": "The tax calendar as an iCal feed", "description": "For Google, Outlook or Apple calendars. Authenticated by the secret feed token from the app (Taxes → Add to calendar), not by an API key; rotating it there cuts off old subscriptions. Unknown tokens get 404.", "tags": [ "Taxes" ], "security": [], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,64}$" } } ], "responses": { "200": { "description": "iCalendar (RFC 5545)", "content": { "text/calendar": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown token" } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # VAT for a month or quarter (estimate) (https://docs.getbeel.com/en/api/reference/taxes/getVatPosition) ## GET /companies/me/vat-position ```json { "operationId": "getVatPosition", "summary": "VAT for a month or quarter (estimate)", "description": "Sales VAT from the issued e-invoices accepted by SDI (credit notes subtract, split payment left out, deferred VAT apart) and an estimate of purchase VAT from reviewed supplier invoices in euros. reliable is always false: deductibility, the month of receipt and reverse charge are not known, so treat it as an estimate to check with the accountant (\"da verificare\"). It is never used for an F24.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "period", "in": "query", "required": true, "description": "A month (2026-10) or a quarter (2026-Q3)", "schema": { "type": "string", "pattern": "^\\d{4}-(Q[1-4]|0[1-9]|1[0-2])$", "examples": [ "2026-Q3", "2026-10" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatPosition" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Draft of the quarterly OSS return (https://docs.getbeel.com/en/api/reference/taxes/getOssReturn) ## GET /companies/me/oss-return ```json { "operationId": "getOssReturn", "summary": "Draft of the quarterly OSS return", "description": "For a company registered in the OSS union scheme: per Member State of the consumer, the taxable amount and the VAT of the quarter from the issued invoices with Natura N7 to EU consumers, at each State's standard rate on the invoice date (VAT rounded per line, then added up; vat_country_level shows the per-country computation, rounding_gap when they differ by more than €0.01). Credit notes on earlier quarters are corrections; a State's negative balance is refunded, never offset. doubtful lists the invoices that need a decision (reason). deadline is the nominal date, never moved; reference is the payment reference. Free and read-only: the return is entered and paid in the AdE Portale OSS with the company's own credentials, never with F24. reliable is always false (reduced rates and goods are not modelled).", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "period", "in": "query", "required": true, "description": "A quarter (2026-Q3): the OSS return is quarterly", "schema": { "type": "string", "pattern": "^\\d{4}-Q[1-4]$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OssReturnDraft" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # VAT registers of a month or quarter (https://docs.getbeel.com/en/api/reference/taxes/getVatRegisters) ## GET /companies/me/vat-registers ```json { "operationId": "getVatRegisters", "summary": "VAT registers of a month or quarter", "description": "Registro IVA vendite and acquisti, row by row with the amounts per rate and natura: issued e-invoices accepted by SDI (credit notes subtract; split payment recorded but not due; deferred VAT counted when paid or after a year), supplier invoices as soon as the AI has read them, those not reviewed yet flagged unreviewed (by the period of receipt; foreign VAT never counts) and autofatture TD16–TD19/TD28 on both sides (reverse charge). vat_counted is what enters the liquidazione after the user's exclusions and adjustments (made in the app, with a reason). missing lists the documents of the period not in the registers yet. Always to check (\"da verificare\").", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "period", "in": "query", "required": true, "description": "A month (2026-10) or a quarter (2026-Q3)", "schema": { "type": "string", "pattern": "^\\d{4}-(Q[1-4]|0[1-9]|1[0-2])$", "examples": [ "2026-Q3", "2026-10" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatRegisters" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # VAT settlement (liquidazione) of a month or quarter (https://docs.getbeel.com/en/api/reference/taxes/getVatSettlement) ## GET /companies/me/vat-settlements ```json { "operationId": "getVatSettlement", "summary": "VAT settlement (liquidazione) of a month or quarter", "description": "The liquidazione IVA computed now from the VAT registers, in the rows of the LIPE (VP2–VP14): VAT due and deducted, debt up to €100 or credit carried from the previous period of the same year (saved, or else computed by getbeel from its registers: see previous), prior-year credit used, 1% interest for quarterly payers, acconto in December/Q4. amount_to_pay is what the F24 pays now. The period must match the VAT periodicity set in the app. saved is the version last saved with POST /v1/filings (type vat_payment), which the LIPE reports. Always to check (\"da verificare\").", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "period", "in": "query", "required": true, "description": "A month (monthly VAT) or a quarter (quarterly VAT), as the company settles VAT", "schema": { "type": "string", "pattern": "^\\d{4}-(Q[1-4]|0[1-9]|1[0-2])$", "examples": [ "2026-Q3", "2026-10" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatSettlement" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Management report: P&L, cash flow or receivables aging (https://docs.getbeel.com/en/api/reference/taxes/getReport) ## GET /companies/me/reports/{type} ```json { "operationId": "getReport", "summary": "Management report: P&L, cash flow or receivables aging", "description": "Management figures from the invoices and bank movements in getbeel, net of VAT: NOT the statutory financial statements (bilancio), always to check with the accountant (\"da verificare\"). profit-and-loss: revenue from issued e-invoices accepted by SDI and costs from reviewed supplier invoices, by document date as the competence date (art. 2423-bis c.c.); credit notes subtract; autofatture and other VAT-only documents (TD16–TD23, TD27–TD29) are left out; TD26 (fixed-asset sales) and documents still at SDI or not reviewed are listed in not_included. cash-flow: money in and out of the bank accounts (uploaded statements and connected banks) by booking date, outflows by the category of the matched supplier invoice; payments recorded on issued invoices are shown apart. aging: what customers still owe on issued invoices today, by days past the due date (not due, 1–30, 31–60, 61–90, over 90); without a due date, 30 days after the invoice date (art. 4 D.Lgs. 231/2002). period, from and to are ignored. period is a year (2026), quarter (2026-Q3) or month (2026-10), or send from and to (at most two years); default the current year.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "profit-and-loss", "cash-flow", "aging" ] } }, { "name": "period", "in": "query", "required": false, "description": "A year (2026), quarter (2026-Q3) or month (2026-10). Default: the current year. Not used by aging", "schema": { "type": "string", "pattern": "^\\d{4}(-(Q[1-4]|0[1-9]|1[0-2]))?$", "examples": [ "2026", "2026-Q3", "2026-10" ] } }, { "name": "from", "in": "query", "required": false, "description": "First day, with to, instead of period (at most two years)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "examples": [ "2026-10-29" ] } }, { "name": "to", "in": "query", "required": false, "description": "Last day, with from", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "examples": [ "2026-10-29" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # ZIP for the accountant (XML, prima nota, VAT registers) (https://docs.getbeel.com/en/api/reference/taxes/getAccountantExport) ## GET /companies/me/accountant-export ```json { "operationId": "getAccountantExport", "summary": "ZIP for the accountant (XML, prima nota, VAT registers)", "description": "Everything an accountant imports for a year, quarter or month: the FatturaPA XML files of issued invoices (as sent to SDI), of received invoices (as received, or the attached file) and of the autofatture getbeel sent; prima-nota-iva.csv (one line per document and VAT rate or natura, with the XML file name); the VAT registers of each settlement period (CSV); bank movements (CSV); and LEGGIMI.txt listing any file that could not be read. Accounting packages (TeamSystem, Zucchetti, Profis and others) import the XML files with their e-invoice import; no vendor-specific layout is produced. CSV: semicolon, decimal comma, UTF-8. Italian companies only. Needs the invoices:read, received_invoices:read and bank:read scopes too. 422 too_many_documents when the period is too large for one file: ask for a quarter or a month.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "period", "in": "query", "required": true, "description": "A year (2026), quarter (2026-Q3) or month (2026-10)", "schema": { "type": "string", "pattern": "^\\d{4}(-(Q[1-4]|0[1-9]|1[0-2]))?$", "examples": [ "2026", "2026-Q3", "2026-10" ] } } ], "responses": { "200": { "description": "ZIP archive", "content": { "application/zip": { "schema": { "type": "string", "contentMediaType": "application/zip" } } } }, "400": { "description": "Invalid period, or not an Italian company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read', 'invoices:read', 'received_invoices:read' or 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "too_many_documents: choose a shorter period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List prepared filings, latest due date first (https://docs.getbeel.com/en/api/reference/taxes/listFilings) ## GET /filings ```json { "operationId": "listFilings", "summary": "List prepared filings, latest due date first", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "bollo", "withholdings", "vat_payment", "lipe", "vat_return", "redditi_pf" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ready", "needs_review", "changes_requested", "approved", "skipped", "filed", "paid" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Prepare a filing (F24, LIPE or VAT return data) (https://docs.getbeel.com/en/api/reference/taxes/prepareFiling) ## POST /filings ```json { "operationId": "prepareFiling", "summary": "Prepare a filing (F24, LIPE or VAT return data)", "description": "Prepares a filing for a period, or recomputes it while it is not paid or filed: bollo for a closed quarter (amount computed from the issued invoices; 422 nothing_due when no invoice needs it), withholdings for a month (the ritenute of the fees recorded in /withholdings and paid in that month, codice 1040; or send amount for fees outside getbeel; 422 nothing_due when none; the receipt locks the fees it paid), vat_payment for a closed month or quarter (saves the liquidazione computed from the VAT registers and returns its F24; 422 nothing_due, with the liquidazione saved and an unpaid F24 of the period deleted, for a credit, for up to €100 carried forward and for Q4 of quarterly payers; 409 filing_completed once the F24 is paid or the LIPE of the quarter is filed), lipe for a closed quarter (the XML of the Comunicazione liquidazioni periodiche IVA from the saved liquidazioni; 400 settlements_missing until they are saved; companies send declarant_fiscal_code; the file is checked against the official IVP18 XSD, reported in checks.xsd), vat_return for a closed year (period 2026: the data sheet of the Dichiarazione IVA, quadri VE, VF, VJ, VL and VX in whole euros, from the registers of every settlement period, the saved liquidazioni and the VAT F24 marked paid, with issues to check; previous_year_credit fills VL25; amount is the VX1 balance, F24 6099; not the telematic file). checks.ade_control_software is always not_run: the AdE control software is a desktop program the client runs. Returns next_steps (file, AdE page, values to copy, email drafts). Nothing is paid, signed or sent. Webhook filing.ready. Live keys only (403 livemode_required). Preparing is free: the filing is charged once, when it is paid or filed.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFilingRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Filing" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The filing for this period is already paid or filed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different request, or nothing_due", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # A filing with its F24 lines and next steps (https://docs.getbeel.com/en/api/reference/taxes/getFiling) ## GET /filings/{id} ```json { "operationId": "getFiling", "summary": "A filing with its F24 lines and next steps", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Filing" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The F24 reminder PDF, the LIPE XML or the VAT return data (https://docs.getbeel.com/en/api/reference/taxes/getFilingFile) ## GET /filings/{id}/file ```json { "operationId": "getFilingFile", "summary": "The F24 reminder PDF, the LIPE XML or the VAT return data", "description": "A \"promemoria F24\": the values to enter in F24 web or home banking, not the ministerial form. For a lipe filing, the XML file (IVP18) to check with the AdE control software, sign and upload in \"Fatture e corrispettivi\". For a vat_return, the data sheet (format csv, xlsx or json): rows, points to check and periods, to copy into the AdE \"Iva\" software or the accountant's.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "vat_return: the data sheet as csv (default), xlsx or json; redditi_pf: csv (default) or json (xlsx is refused)", "schema": { "type": "string", "enum": [ "csv", "xlsx", "json" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } }, "application/xml": { "schema": { "type": "string", "contentMediaType": "application/xml" } }, "text/csv": { "schema": { "type": "string", "contentMediaType": "text/csv" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "contentMediaType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" } }, "application/json": { "schema": { "type": "string", "contentMediaType": "application/json" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Upload the receipt and mark the filing paid or filed (https://docs.getbeel.com/en/api/reference/taxes/uploadFilingReceipt) ## POST /filings/{id}/receipt ```json { "operationId": "uploadFilingReceipt", "summary": "Upload the receipt and mark the filing paid or filed", "description": "Multipart `file`: the F24 quietanza or AdE receipt, PDF, PNG or JPEG up to 10 MB. The filing becomes paid (a LIPE or VAT return becomes filed; webhook filing.filed). The receipt is stored, not read. Live keys only. Pay as you go: the filing is charged once, now, from the prepaid balance (prices in GET /billing/prices).", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Filing" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the filing (insufficient_balance; pay as you go charges a filing once, when it is paid or filed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The filing is already paid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File larger than 10 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Not multipart/form-data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Move a filing in the commercialista review (https://docs.getbeel.com/en/api/reference/taxes/setFilingStatus) ## POST /filings/{id}/status ```json { "operationId": "setFilingStatus", "summary": "Move a filing in the commercialista review", "description": "approved (visto bueno: approved_at, approved_by), changes_requested (reason required; only the commercialista, who reviews in the app), skipped (not to be done: reason required; never prepared automatically again, never charged), needs_review (back to review, or reopen a skipped filing: one skipped before it was prepared goes back to to_prepare), filed (a LIPE, annual VAT return or Redditi PF return sent: reference = its protocol number). When the team requires the commercialista's approval (tax settings require_accountant_approval), an API key cannot approve and a receipt waits for the approval (409 approval_required). Every change goes in the history (/filings/{id}/events), the audit log and webhooks filing.needs_review, filing.changes_requested, filing.approved, filing.skipped and filing.filed. Pay as you go: filed completes the filing and charges it once from the prepaid balance, with the same charge as its receipt (never twice); approving, changes_requested, skipping and reopening are free. Live keys only.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFilingStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingStatusResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "filed only: the balance does not cover the filing (insufficient_balance; nothing changes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "status_not_allowed, accountant_only, team_only, approval_required, not_a_return or filing_changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Mark a deadline as not to be done (https://docs.getbeel.com/en/api/reference/taxes/skipFiling) ## POST /filings/skip ```json { "operationId": "skipFiling", "summary": "Mark a deadline as not to be done", "description": "For a type and period (prepared or not): skipped, with the reason. getbeel never prepares it automatically afterwards and never charges it; reminders and funds alerts stop. Reopen with POST /filings/{id}/status needs_review. Webhook filing.skipped. Live keys only.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkipFilingRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Filing" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The filing is already paid or filed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The history of a filing (comments and status changes) (https://docs.getbeel.com/en/api/reference/taxes/listFilingEvents) ## GET /filings/{id}/events ```json { "operationId": "listFilingEvents", "summary": "The history of a filing (comments and status changes)", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingEventList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Comment on a filing (https://docs.getbeel.com/en/api/reference/taxes/commentFiling) ## POST /filings/{id}/events ```json { "operationId": "commentFiling", "summary": "Comment on a filing", "description": "Adds a comment to the history, read by the team and the commercialista. Live keys only.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentFilingRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingEvent" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List withholdings (ritenute owed), newest first (https://docs.getbeel.com/en/api/reference/taxes/listWithholdings) ## GET /withholdings ```json { "operationId": "listWithholdings", "summary": "List withholdings (ritenute owed), newest first", "description": "Ritenute d’acconto the company withholds as sostituto d’imposta on fees paid to professionals and agents, one per received fee. Fees on professionals’ invoices received from SDI (DatiRitenuta RT01/RT02) are recorded on arrival; set paid_on when you pay the fee: the ritenuta is then due with F24 code 1040 by the 16th of the next month (art. 25 DPR 600/1973, art. 18 D.Lgs. 241/1997).", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "paid_in", "in": "query", "required": false, "description": "Fees paid in this month (2026-10) or year (2026): what the F24 of the month or the CU of the year contains", "schema": { "type": "string", "pattern": "^\\d{4}(-(0[1-9]|1[0-2]))?$" } }, { "name": "status", "in": "query", "required": false, "description": "unpaid: the fee is not paid yet (nothing withheld yet); withheld: paid, ritenuta to pay with F24 1040 by due_date; remitted: paid with an F24 recorded in getbeel", "schema": { "type": "string", "enum": [ "unpaid", "withheld", "remitted" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithholdingList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Record a fee subject to withholding (https://docs.getbeel.com/en/api/reference/taxes/createWithholding) ## POST /withholdings ```json { "operationId": "createWithholding", "summary": "Record a fee subject to withholding", "description": "A fee not received through SDI (paper invoice, notula of occasional work). withheld_amount is computed when left out. Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithholdingRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withholding" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The received invoice already has a withholding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # A withholding (https://docs.getbeel.com/en/api/reference/taxes/getWithholding) ## GET /withholdings/{id} ```json { "operationId": "getWithholding", "summary": "A withholding", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withholding" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change a withholding (e.g. the day the fee was paid) (https://docs.getbeel.com/en/api/reference/taxes/updateWithholding) ## PATCH /withholdings/{id} ```json { "operationId": "updateWithholding", "summary": "Change a withholding (e.g. the day the fee was paid)", "description": "Changing the rate or the amounts recomputes withheld_amount unless you send it. 409 withholding_remitted once an F24 recorded in getbeel paid it (the CU and the 770 rely on it). Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWithholdingRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withholding" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already paid with an F24", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete a withholding (https://docs.getbeel.com/en/api/reference/taxes/deleteWithholding) ## DELETE /withholdings/{id} ```json { "operationId": "deleteWithholding", "summary": "Delete a withholding", "description": "409 withholding_remitted once an F24 paid it. Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withholding" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already paid with an F24", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Read withholdings from received SDI invoices (https://docs.getbeel.com/en/api/reference/taxes/syncWithholdings) ## POST /withholdings/sync ```json { "operationId": "syncWithholdings", "summary": "Read withholdings from received SDI invoices", "description": "Reads the invoices received from SDI that have no withholding yet and records those with DatiRitenuta RT01/RT02. Up to 100 per call; call again while has_more. Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithholdingSync" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # CU and 770 data of a year (https://docs.getbeel.com/en/api/reference/taxes/getWithholdingsCu) ## GET /withholdings/cu ```json { "operationId": "getWithholdingsCu", "summary": "CU and 770 data of a year", "description": "Per percipiente and causale, the fees paid in the year (cash principle) as the Certificazione Unica (lavoro autonomo, provvigioni e redditi diversi) reports them: punto 4 gross, 7 not subject, 8 taxable, 9 ritenute; the 770 quadro ST lines per month (codice 1040). Deadlines from the CU 2026 instructions: CU to each percipiente by 16 March; to the AdE by 16 March, or 30 April for lavoro autonomo abituale and non-occasional provvigioni; 770 by 31 October. format=csv returns a spreadsheet (text/csv). Not the telematic file.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "year", "in": "query", "required": true, "description": "The year the fees were paid (cash principle)", "schema": { "type": "integer", "minimum": 2020, "maximum": 2100, "examples": [ 2026 ] } }, { "name": "format", "in": "query", "required": false, "description": "csv: one row per percipiente and causale (semicolons, Italian decimals, for Excel)", "schema": { "default": "json", "type": "string", "enum": [ "json", "csv" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithholdingsCu" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Get the tax settings (https://docs.getbeel.com/en/api/reference/taxes/getTaxSettings) ## GET /companies/me/tax-settings ```json { "operationId": "getTaxSettings", "summary": "Get the tax settings", "description": "VAT periodicity and whether the company is a withholding agent, as Tasse → Impostazioni. null means not set: the deadlines that depend on it are left out of the tax calendar (missing_settings). Both key modes.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxSettings" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change the tax settings (https://docs.getbeel.com/en/api/reference/taxes/updateTaxSettings) ## PATCH /companies/me/tax-settings ```json { "operationId": "updateTaxSettings", "summary": "Change the tax settings", "description": "Changes only what it sends. The VAT periodicity decides the VAT periods (months or quarters) of the registers, liquidazioni and F24: change it only as the company actually settles VAT (ask the accountant). Live keys only.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaxSettingsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxSettings" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Get the tax profile (https://docs.getbeel.com/en/api/reference/taxes/getTaxProfile) ## GET /companies/me/tax-profile ```json { "operationId": "getTaxProfile", "summary": "Get the tax profile", "description": "Which taxes apply to the company: legal form, regime, VAT periodicity, withholding agent, employees, foreign suppliers, Intrastat, OSS (sales evidence and the registration), liquidation, first tax year, social security and special income tax regimes, each with its `effect` for the current year (rate or taxed share, until when, F24 codes, the official source of each number) and `regime_warnings`. Each value is yours (sources: user) or a high-confidence detection (detected), with the evidence in `detection`; low-confidence values are never applied and come back in `questions` to ask the user once. Both key modes. Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxProfile" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change the tax profile (https://docs.getbeel.com/en/api/reference/taxes/updateTaxProfile) ## PATCH /companies/me/tax-profile ```json { "operationId": "updateTaxProfile", "summary": "Change the tax profile", "description": "Changes only what it sends and marks it confirmed; null clears a value (back to the detection); `confirm` confirms detected values as they are; `regimes` replaces the special income tax regimes; their `params` are typed per kind and getbeel computes the numbers from them. A value you set always wins over the detection and changes which deadlines the tax calendar lists. Ask the user, never guess. Recorded in the audit log. Live keys only.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaxProfileRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxProfile" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Detect the tax profile now (https://docs.getbeel.com/en/api/reference/taxes/detectTaxProfile) ## POST /companies/me/tax-profile/detect ```json { "operationId": "detectTaxProfile", "summary": "Detect the tax profile now", "description": "Re-runs the detection from the company data (name, regime, issued and received invoices, recorded withholdings), stores it and returns it with the profile. It never changes a value you set. New obligations (e.g. B2C sales above the OSS threshold) also add a notice in the app. getbeel runs it every month by itself. Live keys only.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxProfileDetection" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Depreciation categories and coefficients (https://docs.getbeel.com/en/api/reference/taxes/listFixedAssetCategories) ## GET /fixed-asset-categories ```json { "operationId": "listFixedAssetCategories", "summary": "Depreciation categories and coefficients", "description": "The ministerial coefficients of DM 31 December 1988 (as amended by DM 28 March 1996) for the groups most small companies and professionals use (\"Attività non precedentemente specificate – Altre attività\", hotels and restaurants, personal services), and the art. 103 TUIR limits for software, patents, trademarks and goodwill. Any other coefficient can be given by hand when creating an asset.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetCategories" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List fixed assets (cespiti) (https://docs.getbeel.com/en/api/reference/taxes/listFixedAssets) ## GET /fixed-assets ```json { "operationId": "listFixedAssets", "summary": "List fixed assets (cespiti)", "description": "Newest purchase first, each with its tax depreciation schedule, status, fondo and residual at the end of year (default: this year).", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "year", "in": "query", "required": false, "description": "Status, fondo and residual at the end of this year (default: this year)", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Register a fixed asset (https://docs.getbeel.com/en/api/reference/taxes/createFixedAsset) ## POST /fixed-assets ```json { "operationId": "createFixedAsset", "summary": "Register a fixed asset", "description": "Registers a bene strumentale, often bought with a received invoice (received_invoice_id fills purchase date, supplier and number). Depreciation starts in the year it enters into function (art. 102 c. 1 TUIR) at most at the ministerial coefficient, halved in the first year (c. 2); a tangible asset up to 516.46 can be deducted in full (c. 5). The asset’s cost is then left out of the year’s costs in the tax estimate. Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFixedAssetRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAsset" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # A fixed asset with its schedule (https://docs.getbeel.com/en/api/reference/taxes/getFixedAsset) ## GET /fixed-assets/{id} ```json { "operationId": "getFixedAsset", "summary": "A fixed asset with its schedule", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Status, fondo and residual at the end of this year", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAsset" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change a fixed asset or record its disposal (https://docs.getbeel.com/en/api/reference/taxes/updateFixedAsset) ## PATCH /fixed-assets/{id} ```json { "operationId": "updateFixedAsset", "summary": "Change a fixed asset or record its disposal", "description": "Send only what changes. disposal_date and disposal_amount record a sale or elimination: the gain or loss is price minus the cost not yet depreciated (art. 86 and 101 TUIR); no quota is computed in the disposal year. depreciation_overrides records smaller deductions of past years. Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFixedAssetRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAsset" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete a fixed asset (https://docs.getbeel.com/en/api/reference/taxes/deleteFixedAsset) ## DELETE /fixed-assets/{id} ```json { "operationId": "deleteFixedAsset", "summary": "Delete a fixed asset", "description": "Removes it from the register. Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedFixedAsset" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Libro cespiti of a year (https://docs.getbeel.com/en/api/reference/taxes/getFixedAssetsRegister) ## GET /companies/me/fixed-assets-register ```json { "operationId": "getFixedAssetsRegister", "summary": "Libro cespiti of a year", "description": "Every asset owned during the year with the fondo at 1 January and 31 December, the quota of the year and any disposal; totals per category and a summary of the closing entries for the accountant (no general ledger is kept). format=csv or xlsx returns the file. Always to check (\"da verificare\").", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "year", "in": "query", "required": true, "description": "Tax year, e.g. 2026", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "format", "in": "query", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "csv", "xlsx" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetsRegister" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Tax estimate of a year (stima) (https://docs.getbeel.com/en/api/reference/taxes/getTaxEstimate) ## GET /companies/me/tax-estimate ```json { "operationId": "getTaxEstimate", "summary": "Tax estimate of a year (stima)", "description": "An estimate, to check with the accountant: for a company (società di capitali) IRES 24% and IRAP (3.9% or the regional rate given); for the regime forfettario the imposta sostitutiva (15%, or 5% for start-ups) on revenue × the ATECO group coefficient minus contributions, and the INPS contributions (gestione separata 26.07%, artigiani/commercianti with the 2026 minimale). Figures come from getbeel: issued invoices (or payments recorded, for forfettari), reviewed received invoices without the fixed assets, depreciation and gains of the year. installments lists acconti and saldo with F24 codes and dates (art. 17 DPR 435/2001); dates not yet confirmed by a source in force are confirmed false.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Tax year (default: this year)", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxEstimate" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Save the inputs of the tax estimate (https://docs.getbeel.com/en/api/reference/taxes/saveTaxEstimate) ## PUT /companies/me/tax-estimate ```json { "operationId": "saveTaxEstimate", "summary": "Save the inputs of the tax estimate", "description": "The figures getbeel cannot know (legal form, ATECO, personnel costs, INPS scheme, last year’s taxes for the acconti…), stored per year and merged over the saved ones; returns the recomputed estimate. Next year starts from these answers. Live keys only (403 livemode_required); saving the inputs is free (nothing is charged to the balance).", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveTaxEstimateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxEstimate" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List POS–RT links (https://docs.getbeel.com/en/api/reference/taxes/listPosRtLinks) ## GET /pos-rt-links ```json { "operationId": "listPosRtLinks", "summary": "List POS–RT links", "description": "Each payment terminal linked to a registratore telematico, with its status (to_file, filed, end_to_file, ended) and, when something is still to communicate, the window of provv. AdE 424470/2025 (from the 6th to the last working day of the second month after the change).", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "to_file", "filed", "end_to_file", "ended" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosRtLinkList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Record a POS linked to an RT (https://docs.getbeel.com/en/api/reference/taxes/createPosRtLink) ## POST /pos-rt-links ```json { "operationId": "createPosRtLink", "summary": "Record a POS linked to an RT", "description": "The fields of the AdE bulk CSV: RT matricola, acquirer (codice fiscale, name, IT or ES), POS type (00 physical with its TerminalId, 01 virtual), contract number, address of the unità locale or itinerant, and the first day of use. Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePosRtLinkRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosRtLink" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This POS is already linked to this RT (pos_rt_link_exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # A POS–RT link (https://docs.getbeel.com/en/api/reference/taxes/getPosRtLink) ## GET /pos-rt-links/{id} ```json { "operationId": "getPosRtLink", "summary": "A POS–RT link", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosRtLink" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change or end a POS–RT link (https://docs.getbeel.com/en/api/reference/taxes/updatePosRtLink) ## PATCH /pos-rt-links/{id} ```json { "operationId": "updatePosRtLink", "summary": "Change or end a POS–RT link", "description": "Before the link is communicated anything can change. After, only label and ended_on: setting ended_on (last day of use) makes the end the next thing to communicate (operation C, DataFine). 409 link_already_filed otherwise. Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePosRtLinkRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosRtLink" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already communicated (link_already_filed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete a POS–RT link not communicated yet (https://docs.getbeel.com/en/api/reference/taxes/deletePosRtLink) ## DELETE /pos-rt-links/{id} ```json { "operationId": "deletePosRtLink", "summary": "Delete a POS–RT link not communicated yet", "description": "A communicated link is ended instead (409 link_already_filed). Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedPosRtLink" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already communicated (link_already_filed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The bulk CSV for the AdE portal (https://docs.getbeel.com/en/api/reference/taxes/exportPosRtLinks) ## GET /pos-rt-links/export ```json { "operationId": "exportPosRtLinks", "summary": "The bulk CSV for the AdE portal", "description": "Everything still to communicate (I to associate, C to end) in the 15 columns of the AdE \"Manuale operativo\" (April 2026), at most 1,000 rows per file (part). The separator, encoding and header names are not in any official document: the template downloadable in the portal is the reference, and tsv has the same rows to paste into it. next_steps has the path in Fatture e Corrispettivi. getbeel never uploads it for you. format=csv returns the file.", "tags": [ "Taxes" ], "x-required-scope": "taxes:read", "parameters": [ { "name": "part", "in": "query", "required": false, "description": "Which file, when more than 1,000 links are pending (1,000 rows per file): 1-based, default 1", "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "format", "in": "query", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "csv" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosRtExport" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Mark links communicated (https://docs.getbeel.com/en/api/reference/taxes/markPosRtLinksFiled) ## POST /pos-rt-links/mark-filed ```json { "operationId": "markPosRtLinksFiled", "summary": "Mark links communicated", "description": "After the AdE processed the upload (\"Storico richieste massive\"): the pending operation of each link becomes filed (associations, then ends). Live keys only (403 livemode_required). Free.", "tags": [ "Taxes" ], "x-required-scope": "taxes:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkPosRtFiledRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkPosRtFiledResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'taxes:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # An autofattura with its SDI status (https://docs.getbeel.com/en/api/reference/autofatture/getAutofattura) ## GET /autofatture/{id} ```json { "operationId": "getAutofattura", "summary": "An autofattura with its SDI status", "description": "The autofattura of a foreign purchase: TD type, number, whether the XML is ready, and the SDI status (null until sent, then queued, sent_to_sdi, consegnata, scartata…). Both key modes.", "tags": [ "Autofatture" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Autofattura" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Send an autofattura to SDI (https://docs.getbeel.com/en/api/reference/autofatture/sendAutofattura) ## POST /autofatture/{id}/send ```json { "operationId": "sendAutofattura", "summary": "Send an autofattura to SDI", "description": "Sends a generated autofattura to SDI, exactly like the Send to SDI button: the XML must be generated, and the send is paid from the prepaid balance at the SDI send price (402 insufficient_balance when it does not cover it). It is queued and returns the autofattura with sdi.status = queued; read it again for the SDI answer. Safe to repeat: a second call never sends or charges again (409 autofattura_already_queued or autofattura_already_sent). A corrected resend after an SDI rejection is not charged again. Live keys only.", "tags": [ "Autofatture" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Autofattura" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the SDI send (insufficient_balance)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "autofattura_already_queued, autofattura_already_sent, autofattura_xml_missing (generate it first), autofattura_not_generated, sdi_monthly_cap_reached, sdi_not_available (legacy plan without the SDI service)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List a month or folder of the Drive (https://docs.getbeel.com/en/api/reference/drive/getDrive) ## GET /drive ```json { "operationId": "getDrive", "summary": "List a month or folder of the Drive", "description": "The folders and files of one month (month=2026-10: invoice files by invoice date, statements and uploads by upload date) or of one uploads folder (folder=contratti or 2026-10/contratti), newest first. Invoice files also need received_invoices:read and bank statements bank:read; without them they are left out. Both key modes.", "tags": [ "Drive" ], "x-required-scope": "drive:read", "parameters": [ { "name": "month", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Drive" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'drive:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Upload a document to the Drive (https://docs.getbeel.com/en/api/reference/drive/uploadDriveFile) ## POST /drive/files ```json { "operationId": "uploadDriveFile", "summary": "Upload a document to the Drive", "description": "Uploads a document into a folder that takes uploads (writable true in GET /drive: a month, documents or a custom folder; a month folder is created if missing), by public https file_url or file_base64. PDF, PNG, JPEG, DOC or DOCX, up to 25 MB, the type read from the content (413 payload_too_large, 415 unsupported_file_type). It is only stored: to have the AI read a supplier invoice, use POST /received-invoices/uploads. Live keys only.", "tags": [ "Drive" ], "x-required-scope": "drive:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDriveFileRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveFile" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'drive:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Larger than 25 MB (payload_too_large)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Not a PDF, PNG, JPEG, DOC or DOCX (unsupported_file_type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Download a Drive file (https://docs.getbeel.com/en/api/reference/drive/downloadDriveFile) ## GET /drive/files/{id}/download ```json { "operationId": "downloadDriveFile", "summary": "Download a Drive file", "description": "A private link to the file (id from GET /drive), valid 15 minutes. Invoice files also need received_invoices:read and bank statements bank:read; without them they are left out.", "tags": [ "Drive" ], "x-required-scope": "drive:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveFileDownload" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'drive:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete a Drive file (https://docs.getbeel.com/en/api/reference/drive/deleteDriveFile) ## DELETE /drive/files/{id} ```json { "operationId": "deleteDriveFile", "summary": "Delete a Drive file", "description": "Deletes the file (id from GET /drive) for good, as Delete in the Drive page: a received invoice’s file (the invoice stays, without its file; also needs received_invoices:write), an uploaded bank statement (also needs bank:write) or an uploaded document. A statement holding autofatture that are or may be at SDI cannot be deleted (409 statement_has_sent_autofatture). Live keys only.", "tags": [ "Drive" ], "x-required-scope": "drive:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedDriveFile" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'drive:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A statement with autofatture at SDI (statement_has_sent_autofatture)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Create a Drive folder (https://docs.getbeel.com/en/api/reference/drive/createDriveFolder) ## POST /drive/folders ```json { "operationId": "createDriveFolder", "summary": "Create a Drive folder", "description": "A new uploads folder at the root or inside a month (that month’s folder is created if missing). Its path comes from the name; a name shaped like a month is refused. 409 folder_exists when one with that name is already there. Live keys only.", "tags": [ "Drive" ], "x-required-scope": "drive:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDriveFolderRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveFolder" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'drive:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A folder with this name exists (folder_exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete a Drive folder (https://docs.getbeel.com/en/api/reference/drive/deleteDriveFolder) ## DELETE /drive/folders ```json { "operationId": "deleteDriveFolder", "summary": "Delete a Drive folder", "description": "Deletes a custom folder (path from GET /drive, kind custom) and every file in it, for good. Month and system folders cannot be deleted. Live keys only.", "tags": [ "Drive" ], "x-required-scope": "drive:write", "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "contratti or 2026-10/contratti" }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedDriveFolder" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'drive:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List bank connections (https://docs.getbeel.com/en/api/reference/bank-connections/listBankConnections) ## GET /bank-connections ```json { "operationId": "listBankConnections", "summary": "List bank connections", "description": "Banks connected for automatic transaction feeds, with their accounts, balances, consent expiry and last sync. Synced transactions appear in GET /bank-statements (source open_banking, one statement per account and month) and GET /bank-transactions.", "tags": [ "Bank connections" ], "x-required-scope": "bank:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnectionList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Connect a bank (https://docs.getbeel.com/en/api/reference/bank-connections/createBankConnection) ## POST /bank-connections ```json { "operationId": "createBankConnection", "summary": "Connect a bank", "description": "Checks the Enable Banking application (a real call with your key), saves it and starts the bank login. Open authorization_url in a browser: a getbeel page names your team, the user continues to the bank, logs in and lands in the getbeel app, and the first sync (last 90 days) starts right away. Add getbeel's redirect URL (https://getbeel.com/api/open-banking/callback) to your application's allowed redirect URLs first. Pay as you go: €2.00 per connected bank account per month and €0.02 per imported movement, from the prepaid balance (402 insufficient_balance when it does not cover them). Each team uses its own Enable Banking application (application id + RSA private key from the Enable Banking control panel); getbeel stores the key encrypted and never returns it. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank connections" ], "x-required-scope": "bank:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBankConnectionRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBankConnectionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The prepaid balance does not cover it (insufficient_balance)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Ten banks connected already", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Enable Banking refused the application id or key (bank_credentials_invalid) or the redirect URL (redirect_url_not_allowed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The bank or Enable Banking refused the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enable Banking did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Get a bank connection (https://docs.getbeel.com/en/api/reference/bank-connections/getBankConnection) ## GET /bank-connections/{id} ```json { "operationId": "getBankConnection", "summary": "Get a bank connection", "tags": [ "Bank connections" ], "x-required-scope": "bank:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnection" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Disconnect a bank (https://docs.getbeel.com/en/api/reference/bank-connections/deleteBankConnection) ## DELETE /bank-connections/{id} ```json { "operationId": "deleteBankConnection", "summary": "Disconnect a bank", "description": "Closes the consent at the bank and deletes the stored key. Synced statements, transactions and matches stay. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank connections" ], "x-required-scope": "bank:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedBankConnection" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Reconnect a bank (https://docs.getbeel.com/en/api/reference/bank-connections/reconnectBankConnection) ## POST /bank-connections/{id}/reconnect ```json { "operationId": "reconnectBankConnection", "summary": "Reconnect a bank", "description": "Starts a new bank login for a connection whose consent is expiring (expires_soon), expired or revoked (status requires_reconnect), or whose first login was never finished. Open authorization_url in a browser: a getbeel page names your team, then the user gives the bank a new consent and lands in the getbeel app; the old consent is closed and the first sync runs right away. Banks end a consent after at most 180 days (PSD2), so plan one reconnect per bank every few months; getbeel emails the owners and sends the bank_connection.expiring webhook 7 days before. Pay as you go (402 insufficient_balance when the prepaid balance does not cover the account month). Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank connections" ], "x-required-scope": "bank:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconnectBankConnectionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconnectBankConnectionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The prepaid balance does not cover it (insufficient_balance)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No bank chosen yet for this connection (bank_connection_conflict)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Enable Banking refused the application id or key (bank_credentials_invalid) or the redirect URL (redirect_url_not_allowed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The bank or Enable Banking refused the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enable Banking did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Sync a bank connection now (https://docs.getbeel.com/en/api/reference/bank-connections/syncBankConnection) ## POST /bank-connections/{id}/sync ```json { "operationId": "syncBankConnection", "summary": "Sync a bank connection now", "description": "getbeel already syncs every 6 hours. Banks allow about four unattended fetches a day, and this call counts as one (429 bank_daily_limit when they are used up). New transactions are deduplicated, added to the month's synced statement and matched in the background (webhooks bank_statement.parsed, then reconciliation.completed). New movements cost €0.02 each, from the prepaid balance. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank connections" ], "x-required-scope": "bank:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnectionSync" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The prepaid balance does not cover it (insufficient_balance)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Sync running or just ran (sync_in_progress), bank login not finished (bank_connection_inactive) or consent expired (bank_connection_requires_reconnect)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The bank or Enable Banking failed; retried automatically", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The account and its client companies (https://docs.getbeel.com/en/api/reference/companies/listCompanies) ## GET /companies ```json { "operationId": "listCompanies", "summary": "The account and its client companies", "description": "The account the key belongs to, then the client companies the key can act on (its member must manage them). The Getbeel-Company header does not apply to /companies.", "tags": [ "Companies" ], "x-required-scope": "account:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'account:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Add a client company (https://docs.getbeel.com/en/api/reference/companies/createCompany) ## POST /companies ```json { "operationId": "createCompany", "summary": "Add a client company", "description": "Creates a client company under the key's account with its company data. The key's member becomes its owner, so the same key can act on it at once with the Getbeel-Company header. A client company cannot have client companies (409 company_nesting_not_allowed). Each company has its own plan: live SDI sends from a client company need its own SDI add-on. Live keys only (403 livemode_required with a test key): companies are real accounts, there is no sandbox for them.", "tags": [ "Companies" ], "x-required-scope": "companies:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompanyRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyAccount" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'companies:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The key belongs to a client company, or Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Get the account or one of its client companies (https://docs.getbeel.com/en/api/reference/companies/getCompany) ## GET /companies/{id} ```json { "operationId": "getCompany", "summary": "Get the account or one of its client companies", "tags": [ "Companies" ], "x-required-scope": "account:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A client company id, or the key's own account id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyAccount" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'account:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change company data (https://docs.getbeel.com/en/api/reference/companies/updateCompany) ## PATCH /companies/{id} ```json { "operationId": "updateCompany", "summary": "Change company data", "description": "Changes only the fields sent. sdi_readiness shows what is still missing to issue invoices through SDI. Live keys only (403 livemode_required with a test key): company data is real, there is no sandbox for it.", "tags": [ "Companies" ], "x-required-scope": "companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A client company id, or the key's own account id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyAccount" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'companies:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The account, company and API key making the request (https://docs.getbeel.com/en/api/reference/account/getAccount) ## GET /me ```json { "operationId": "getAccount", "summary": "The account, company and API key making the request", "tags": [ "Account" ], "x-required-scope": "account:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'account:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # This month's SDI usage and plan (https://docs.getbeel.com/en/api/reference/account/getUsage) ## GET /usage ```json { "operationId": "getUsage", "summary": "This month's SDI usage and plan", "description": "Live SDI transactions, sent and received, one per document (the sandbox and documents collected from email are not counted), the plan, and on the pay-per-use rate card (new accounts: sends €0.10 / €0.06 / €0.035 with the first 10 a month free; receiving from SDI €0.10 per invoice) the free allowance and the estimated amounts, sent and received separately. A client company (Getbeel-Company) is billed to its parent: it sees its own transactions and billed_to; the parent sees the total and the split per company.", "tags": [ "Account" ], "x-required-scope": "account:read", "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Month (UTC), default the current one", "schema": { "examples": [ "2026-10" ], "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'account:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List issued invoices, newest invoice_date first (https://docs.getbeel.com/en/api/reference/invoices/listInvoices) ## GET /invoices ```json { "operationId": "listInvoices", "summary": "List issued invoices, newest invoice_date first", "tags": [ "Invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "sending", "sent", "delivered", "not_delivered", "rejected" ] } }, { "name": "date_from", "in": "query", "required": false, "description": "invoice_date on or after (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "date_to", "in": "query", "required": false, "description": "invoice_date on or before (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "payment_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid" ] } }, { "name": "overdue", "in": "query", "required": false, "description": "true: only overdue invoices (issued, unpaid, due_date before today)", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "search", "in": "query", "required": false, "description": "Customer name, subject or number as shown (\"12\", \"12/A\", \"12/2026\"), case-insensitive", "schema": { "examples": [ "Bianchi" ], "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Create a draft invoice (https://docs.getbeel.com/en/api/reference/invoices/createInvoice) ## POST /invoices ```json { "operationId": "createInvoice", "summary": "Create a draft invoice", "description": "Creates a draft issued invoice (fattura emessa). Totals are computed by getbeel. The number defaults to the next one (separate sequences for test and live keys) and the date to today in Italy. Live keys need an SDI plan, the pay-per-use rate card or an SDI add-on, and count toward its monthly quota (402 sdi_addon_required or sdi_quota_exhausted otherwise); test keys create sandbox invoices for free.", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Live key without an SDI plan (rate card or add-on), or its quota used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Invoice number already used, or Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Retrieve an issued invoice with its lines (https://docs.getbeel.com/en/api/reference/invoices/getInvoice) ## GET /invoices/{id} ```json { "operationId": "getInvoice", "summary": "Retrieve an issued invoice with its lines", "tags": [ "Invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Edit a draft invoice (https://docs.getbeel.com/en/api/reference/invoices/updateInvoice) ## PATCH /invoices/{id} ```json { "operationId": "updateInvoice", "summary": "Edit a draft invoice", "description": "Changes a draft with the same rules as the app's edit form and as create (a 0% line needs a natura, totals are recomputed). Each field sent replaces that part: lines replaces every line, customer and payment are sent whole. When the draft has a withholding or cassa and you change lines, withholding or cassa_previdenziale, send them again (null removes them). A number from a numbering series and the type of a credit note cannot change. Only drafts: a rejected invoice is reopened first (POST /invoices/{id}/reopen); a sent one is corrected with a credit note.", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvoiceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not a draft (invoice_not_draft), being sent (invoice_send_in_progress), number taken (invoice_number_taken), or Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Number out of sequence, date moved to another year for a series number, credit note above what is left to credit (invoice_invalid), or Idempotency-Key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Reopen a rejected invoice for correction (https://docs.getbeel.com/en/api/reference/invoices/reopenInvoice) ## POST /invoices/{id}/reopen ```json { "operationId": "reopenInvoice", "summary": "Reopen a rejected invoice for correction", "description": "An invoice SDI rejected (status rejected) goes back to draft with the same number and date, as AdE advises for a scartata (it counts as never issued; resend it with the same number and date). The SDI errors stay on the invoice until it is sent again. Then PATCH /invoices/{id} to correct it and POST /invoices/{id}/send. Works the same with test keys for sandbox rejections.", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not rejected (invoice_not_rejected), an automatic fix is running, or Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Send a draft invoice to SDI (https://docs.getbeel.com/en/api/reference/invoices/sendInvoice) ## POST /invoices/{id}/send ```json { "operationId": "sendInvoice", "summary": "Send a draft invoice to SDI", "description": "Generates the FatturaPA XML, validates it and sends it to SDI. Test key: the sandbox answers at once (200, status sent) and the outcome follows a few seconds later (webhook invoice.delivered, invoice.not_delivered or invoice.rejected). Live key: the real submission is queued (202, status sending, then sent).", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "202": { "description": "Live key: the submission is queued (status sending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Live key without an SDI plan (rate card or add-on)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not a draft, already being sent, or Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The invoice or the company profile is not valid for SDI (error.message says why), or Idempotency-Key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Email the invoice to the customer (https://docs.getbeel.com/en/api/reference/invoices/emailInvoice) ## POST /invoices/{id}/email ```json { "operationId": "emailInvoice", "summary": "Email the invoice to the customer", "description": "Sends the PDF courtesy copy (copia di cortesia; the legal invoice is the one SDI delivers) and optionally the FatturaPA XML to the customer (default: the customer's email on the invoice), with the payment link when the invoice has one. Only issued invoices (sent to SDI) and proformas. The attempt is stored (GET /invoices/{id}/deliveries) and sent to webhooks (invoice.emailed or invoice.email_failed); a failed send answers 502 email_failed. Test keys (gb_test_…) only reach sandbox invoices, and their emails go to the team owner only, never to the customer (sent_to shows where it went).", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInvoiceEmailRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEmail" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not issued yet (invoice_not_issued), PDF not ready (invoice_pdf_missing), or Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No recipient: the invoice has no customer email (customer_email_missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The email provider refused the email (email_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Invoice and reminder emails sent for an invoice (https://docs.getbeel.com/en/api/reference/invoices/listInvoiceDeliveries) ## GET /invoices/{id}/deliveries ```json { "operationId": "listInvoiceDeliveries", "summary": "Invoice and reminder emails sent for an invoice", "tags": [ "Invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEmailList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Payments recorded on an invoice, oldest first (https://docs.getbeel.com/en/api/reference/invoices/listInvoicePayments) ## GET /invoices/{id}/payments ```json { "operationId": "listInvoicePayments", "summary": "Payments recorded on an invoice, oldest first", "tags": [ "Invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Record a payment (mark as paid) (https://docs.getbeel.com/en/api/reference/invoices/recordInvoicePayment) ## POST /invoices/{id}/payments ```json { "operationId": "recordInvoicePayment", "summary": "Record a payment (mark as paid)", "description": "Records a payment on an issued invoice (or proforma). Without amount it records everything still due (amount_due − amount_paid) and the invoice becomes paid (webhook invoice.paid); a smaller amount makes it partially_paid. amount_due is the total less the ritenuta d'acconto.", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordPaymentRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordPaymentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already paid (invoice_already_paid), not issued, or Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "More than what is still due (amount_exceeds_balance)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Create a Stripe payment link (https://docs.getbeel.com/en/api/reference/invoices/createPaymentLink) ## POST /invoices/{id}/payment-link ```json { "operationId": "createPaymentLink", "summary": "Create a Stripe payment link", "description": "A Stripe payment link for what is still due, on the team's connected Stripe account (Stripe Connect). Returns the existing link (200) when the invoice has one. Invoice emails and reminders include it while the invoice is unpaid; payments made through it are recorded within the hour. Sandbox invoices need a Stripe test-mode connection.", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The invoice already had a link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stripe not connected (stripe_not_connected: connect it in the app or with POST /connections/stripe), Stripe live connection with a sandbox invoice (stripe_mode_mismatch), already paid or not issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Stripe refused or did not answer (stripe_error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Email a payment reminder (sollecito) (https://docs.getbeel.com/en/api/reference/invoices/sendPaymentReminder) ## POST /invoices/{id}/reminders ```json { "operationId": "sendPaymentReminder", "summary": "Email a payment reminder (sollecito)", "description": "Emails a payment reminder for an unpaid issued invoice, with the PDF and the payment link. Automatic reminders (days after the due date) are set per company in the app. Test keys (gb_test_…) only reach sandbox invoices, and their emails go to the team owner only, never to the customer (sent_to shows where it went).", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReminderRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEmail" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already paid, not issued, PDF not ready, or Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No recipient (customer_email_missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The email provider refused the email (email_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Validate a FatturaPA XML without sending it (https://docs.getbeel.com/en/api/reference/invoices/validateInvoice) ## POST /invoices/validate ```json { "operationId": "validateInvoice", "summary": "Validate a FatturaPA XML without sending it", "description": "Validates locally against the official FatturaPA XSD (v1.2.3) and the SDI content controls of Allegato A v1.9.1 (Appendice 1) that depend on the file alone, the same check that runs before every send (no SDI call, nothing stored). Errors carry the AdE code and wording (00200 for XSD errors, with the line). Not checked: signatures, AdE registries (partita IVA, codice destinatario), duplicates. Returns 200 with `valid` and `errors` for any FatturaPA document; 413 above 5 MB.", "tags": [ "Invoices" ], "x-required-scope": "invoices:validate", "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidateInvoiceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:validate' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List the credit notes of an invoice (https://docs.getbeel.com/en/api/reference/invoices/listCreditNotes) ## GET /invoices/{id}/credit-notes ```json { "operationId": "listCreditNotes", "summary": "List the credit notes of an invoice", "tags": [ "Invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Create a credit note (TD04) for an invoice (https://docs.getbeel.com/en/api/reference/invoices/createCreditNote) ## POST /invoices/{id}/credit-notes ```json { "operationId": "createCreditNote", "summary": "Create a credit note (TD04) for an invoice", "description": "Copies an invoice SDI accepted into a TD04 draft that credits all its lines or the ones you pick (optionally with a smaller quantity), with the invoice's number and date in DatiFattureCollegate. Numbered in the team's credit-note series, else the invoice's series. Send it with POST /invoices/{id}/send. Once SDI accepts it, the invoice's amount_credited grows and its amount_due, payment status, reminders and overdue events take it into account. Credit notes (not rejected) can add up to the invoice total at most.", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCreditNoteRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Live: no SDI plan or quota (sdi_addon_required, sdi_quota_exhausted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The invoice was not accepted by SDI or is a credit note (invoice_not_issued, invoice_not_creditable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Lines out of range (parameter_invalid) or more than the invoice total (credit_exceeds_invoice)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Get the payment reminder settings (https://docs.getbeel.com/en/api/reference/invoices/getReminderSettings) ## GET /companies/me/reminder-settings ```json { "operationId": "getReminderSettings", "summary": "Get the payment reminder settings", "description": "Automatic payment reminders (solleciti): off by default; days after the due date when they go out. Both key modes.", "tags": [ "Invoices" ], "x-required-scope": "invoices:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderSettings" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change the payment reminder settings (https://docs.getbeel.com/en/api/reference/invoices/updateReminderSettings) ## PATCH /companies/me/reminder-settings ```json { "operationId": "updateReminderSettings", "summary": "Change the payment reminder settings", "description": "Changes only what it sends. When on, getbeel emails the customer of each live overdue invoice the latest step reached, once. They apply to invoices due on or after the day they were switched on (enabled_at), so switching them on never mails every customer with an old unpaid invoice. Live keys only.", "tags": [ "Invoices" ], "x-required-scope": "invoices:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReminderSettingsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderSettings" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List recurring invoices, newest first (https://docs.getbeel.com/en/api/reference/recurring-invoices/listRecurringInvoices) ## GET /recurring-invoices ```json { "operationId": "listRecurringInvoices", "summary": "List recurring invoices, newest first", "tags": [ "Recurring invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many to return, 1–100 (default 100)", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoiceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Make an invoice recurring (https://docs.getbeel.com/en/api/reference/recurring-invoices/createRecurringInvoice) ## POST /recurring-invoices ```json { "operationId": "createRecurringInvoice", "summary": "Make an invoice recurring", "description": "Copies the invoice into a new draft every month, quarter or year (daily at about 08:00 Italian time), dated that day, with the next number and the same payment term. With auto_send the draft is also sent to SDI (sandbox for test keys). One schedule per invoice.", "tags": [ "Recurring invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecurringInvoiceRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The invoice already has a schedule (recurring_invoice_exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The invoice cannot be copied (invoice_not_copyable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Retrieve a recurring invoice (https://docs.getbeel.com/en/api/reference/recurring-invoices/getRecurringInvoice) ## GET /recurring-invoices/{id} ```json { "operationId": "getRecurringInvoice", "summary": "Retrieve a recurring invoice", "tags": [ "Recurring invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Change interval, next date, auto_send or active (https://docs.getbeel.com/en/api/reference/recurring-invoices/updateRecurringInvoice) ## PATCH /recurring-invoices/{id} ```json { "operationId": "updateRecurringInvoice", "summary": "Change interval, next date, auto_send or active", "tags": [ "Recurring invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecurringInvoiceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete a schedule (the invoices it created stay) (https://docs.getbeel.com/en/api/reference/recurring-invoices/deleteRecurringInvoice) ## DELETE /recurring-invoices/{id} ```json { "operationId": "deleteRecurringInvoice", "summary": "Delete a schedule (the invoices it created stay)", "tags": [ "Recurring invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedRecurringInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Pause a schedule (https://docs.getbeel.com/en/api/reference/recurring-invoices/pauseRecurringInvoice) ## POST /recurring-invoices/{id}/pause ```json { "operationId": "pauseRecurringInvoice", "summary": "Pause a schedule", "tags": [ "Recurring invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Resume a schedule (https://docs.getbeel.com/en/api/reference/recurring-invoices/resumeRecurringInvoice) ## POST /recurring-invoices/{id}/resume ```json { "operationId": "resumeRecurringInvoice", "summary": "Resume a schedule", "description": "A next_date in the past moves to the next date of the series: no catch-up invoices.", "tags": [ "Recurring invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List bank statements, newest first (https://docs.getbeel.com/en/api/reference/bank-reconciliation/listBankStatements) ## GET /bank-statements ```json { "operationId": "listBankStatements", "summary": "List bank statements, newest first", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "parsed", "matching", "review", "completed", "failed" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Upload a bank statement and reconcile it (https://docs.getbeel.com/en/api/reference/bank-reconciliation/uploadBankStatement) ## POST /bank-statements ```json { "operationId": "uploadBankStatement", "summary": "Upload a bank statement and reconcile it", "description": "Multipart `file` (PDF, CSV or TXT, or a bank file: CBI (Italian RH flat file), CAMT.053 (ISO 20022 XML) or MT940; up to 50 MB; export spreadsheets as CSV) with optional `currency`, or JSON `{ file_url }` for a public https file. Starts reading the statement and matching its payments to received invoices, like an upload in the app: CBI, CAMT.053 and MT940 files are recognised by their content and read exactly (no AI); PDF and CSV are read with AI. Answers 202 with status pending, then parsed (webhook bank_statement.parsed) and review (webhook reconciliation.completed). A movement already imported for the same bank account (the same file again, an overlapping period) is not saved again, and a movement already imported is not charged again: transactions.total counts the new movements this statement saved, and a file with nothing new ends with 0, not an error. A statement whose bank account is not recognised (no bank name or last 4 digits) saves every movement. Idempotency-Key is honoured (multipart uploads are identified by the file's SHA-256, name and currency). Request bodies are limited to about 4 MB by the hosting platform: send larger files with file_url. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "currency": { "type": "string", "examples": [ "EUR" ] } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/UploadBankStatementFromUrl" } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatement" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency-Key in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File larger than 50 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Not a PDF, CSV, TXT, XML, CBI or MT940 file (spreadsheets: export as CSV)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Retrieve a bank statement with its balances (https://docs.getbeel.com/en/api/reference/bank-reconciliation/getBankStatement) ## GET /bank-statements/{id} ```json { "operationId": "getBankStatement", "summary": "Retrieve a bank statement with its balances", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatement" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List bank transactions, newest first (https://docs.getbeel.com/en/api/reference/bank-reconciliation/listBankTransactions) ## GET /bank-transactions ```json { "operationId": "listBankTransactions", "summary": "List bank transactions, newest first", "description": "Filter by statement, date range and reconciliation state (status).", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "statement_id", "in": "query", "required": false, "description": "Bank statement id, as returned when listing or uploading statements; it is also the id of its reconciliation", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "from", "in": "query", "required": false, "description": "Transaction date on or after (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "to", "in": "query", "required": false, "description": "Transaction date on or before (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "status", "in": "query", "required": false, "description": "to_confirm: an invoice was found, waiting for approval; reconciled: invoice confirmed; missing_invoice: no invoice found for the payment; no_invoice_needed: marked as not needing one; rejected: the suggested match was rejected", "schema": { "type": "string", "enum": [ "to_confirm", "reconciled", "missing_invoice", "no_invoice_needed", "rejected" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransactionList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Run the AI matching of a statement again (https://docs.getbeel.com/en/api/reference/bank-reconciliation/createReconciliation) ## POST /reconciliations ```json { "operationId": "createReconciliation", "summary": "Run the AI matching of a statement again", "description": "For a statement in review, completed or failed: re-reads it and matches its transactions again (the previous transactions and matches are replaced), like Retry in the app. A new upload is reconciled automatically. 202; webhook reconciliation.completed when done. Refused (409) while a run is in progress or when an autofattura of the statement was sent to SDI. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReconciliationRequest" } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reconciliation" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already running, or locked by an SDI autofattura", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Retrieve a reconciliation (id = statement id) (https://docs.getbeel.com/en/api/reference/bank-reconciliation/getReconciliation) ## GET /reconciliations/{id} ```json { "operationId": "getReconciliation", "summary": "Retrieve a reconciliation (id = statement id)", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reconciliation" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List the matches of a reconciliation (https://docs.getbeel.com/en/api/reference/bank-reconciliation/listReconciliationMatches) ## GET /reconciliations/{id}/matches ```json { "operationId": "listReconciliationMatches", "summary": "List the matches of a reconciliation", "description": "One row per transaction, newest transaction first: the invoice found (exact, fuzzy or manual) with its confidence, or unmatched.", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "state", "in": "query", "required": false, "description": "to_confirm: an invoice was found, waiting for approval; reconciled: invoice confirmed; missing_invoice: no invoice found for the payment; no_invoice_needed: marked as not needing one; rejected: the suggested match was rejected", "schema": { "type": "string", "enum": [ "to_confirm", "reconciled", "missing_invoice", "no_invoice_needed", "rejected" ] } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationMatchList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Link a received invoice to a transaction by hand (https://docs.getbeel.com/en/api/reference/bank-reconciliation/createManualMatch) ## POST /reconciliations/{id}/matches ```json { "operationId": "createManualMatch", "summary": "Link a received invoice to a transaction by hand", "description": "Replaces the transaction's match with the given received invoice (match_type manual, review_status modified). Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationMatch" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Approve a match (https://docs.getbeel.com/en/api/reference/bank-reconciliation/approveMatch) ## POST /reconciliations/{id}/matches/{matchId}/approve ```json { "operationId": "approveMatch", "summary": "Approve a match", "description": "Confirms the invoice found; for an unmatched payment, confirms that no invoice is needed. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "matchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationMatch" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Reject a match (https://docs.getbeel.com/en/api/reference/bank-reconciliation/rejectMatch) ## POST /reconciliations/{id}/matches/{matchId}/reject ```json { "operationId": "rejectMatch", "summary": "Reject a match", "description": "The suggested invoice is wrong. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "matchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationMatch" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Payments without an invoice (https://docs.getbeel.com/en/api/reference/bank-reconciliation/listUnmatchedPayments) ## GET /unmatched/payments ```json { "operationId": "listUnmatchedPayments", "summary": "Payments without an invoice", "description": "Money out from the uploaded statements with no invoice found and not marked as needing none: the documents to collect.", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "description": "Date on or after (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "to", "in": "query", "required": false, "description": "Date on or before (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransactionList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Invoices without a payment (https://docs.getbeel.com/en/api/reference/bank-reconciliation/listUnmatchedInvoices) ## GET /unmatched/invoices ```json { "operationId": "listUnmatchedInvoices", "summary": "Invoices without a payment", "description": "Received invoices (pending_review, verified or exported) that no bank transaction is matched to.", "tags": [ "Bank reconciliation" ], "x-required-scope": "bank:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "description": "Date on or after (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "to", "in": "query", "required": false, "description": "Date on or before (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInvoiceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'bank:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List mailbox, forwarding and Stripe connections (https://docs.getbeel.com/en/api/reference/connections/listConnections) ## GET /connections ```json { "operationId": "listConnections", "summary": "List mailbox, forwarding and Stripe connections", "tags": [ "Connections" ], "x-required-scope": "connections:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'connections:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Connect a mailbox (https://docs.getbeel.com/en/api/reference/connections/createEmailConnection) ## POST /connections/email ```json { "operationId": "createEmailConnection", "summary": "Connect a mailbox", "description": "gmail / outlook: 200 with a link to the OAuth consent; the user opens it in a browser signed in to getbeel and lands back in the app (the connection then shows in GET /connections). imap: tests the login (port 993, TLS) and saves the mailbox, 201. Counts toward the plan mailbox limit (402). Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Connections" ], "x-required-scope": "connections:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailConnectionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailConnectionResponse" } } } }, "201": { "description": "IMAP mailbox saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailConnectionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Mailbox limit of the plan reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'connections:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "IMAP login failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Scan a mailbox for invoices in a date range (https://docs.getbeel.com/en/api/reference/connections/scanMailbox) ## POST /connections/{id}/scan ```json { "operationId": "scanMailbox", "summary": "Scan a mailbox for invoices in a date range", "description": "Gmail, Outlook or IMAP; at most 366 days. Runs in the background (202); found invoices appear in GET /received-invoices with source email (webhook received_invoice.created). Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Connections" ], "x-required-scope": "connections:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanMailboxRequest" } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxScan" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'connections:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Forwarding address, inactive mailbox or no company profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # The address to forward supplier invoices to (https://docs.getbeel.com/en/api/reference/connections/getForwardingAddress) ## GET /forwarding-address ```json { "operationId": "getForwardingAddress", "summary": "The address to forward supplier invoices to", "tags": [ "Connections" ], "x-required-scope": "connections:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardingAddress" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'connections:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Link to connect Stripe (https://docs.getbeel.com/en/api/reference/connections/createStripeConnection) ## POST /connections/stripe ```json { "operationId": "createStripeConnection", "summary": "Link to connect Stripe", "description": "Returns a link to Stripe Connect; the user opens it signed in to getbeel and lands back on the fatture emesse page. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Connections" ], "x-required-scope": "connections:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionLink" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'connections:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Import Stripe invoices as fatture emesse (https://docs.getbeel.com/en/api/reference/connections/syncStripe) ## POST /connections/stripe/sync ```json { "operationId": "syncStripe", "summary": "Import Stripe invoices as fatture emesse", "description": "Like Sync in the app (default: the last 30 days). Needs an SDI plan (rate card or add-on) and its quota; with auto_send_sdi on, the invoices are also sent to SDI. 202, runs in the background. Live keys only (403 livemode_required with a test key): bank and connection data is real, there is no sandbox for it.", "tags": [ "Connections" ], "x-required-scope": "connections:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeSyncRequest" } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeSync" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "No SDI plan (rate card or add-on), or its quota used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'connections:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stripe not connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Company profile incomplete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List quotes, newest first (https://docs.getbeel.com/en/api/reference/quotes/listQuotes) ## GET /quotes ```json { "operationId": "listQuotes", "summary": "List quotes, newest first", "tags": [ "Quotes" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "sent", "accepted", "declined", "expired" ] } }, { "name": "limit", "in": "query", "required": false, "description": "How many quotes to return, 1–100 (default 100)", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Create a quote (https://docs.getbeel.com/en/api/reference/quotes/createQuote) ## POST /quotes ```json { "operationId": "createQuote", "summary": "Create a quote", "description": "Same customer, lines, payment and notes as POST /invoices, plus valid_until. Numbered per year (12/2026), separately for test and live keys.", "tags": [ "Quotes" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuoteRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid quote (quote_invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Retrieve a quote (https://docs.getbeel.com/en/api/reference/quotes/getQuote) ## GET /quotes/{id} ```json { "operationId": "getQuote", "summary": "Retrieve a quote", "tags": [ "Quotes" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Update a quote (https://docs.getbeel.com/en/api/reference/quotes/updateQuote) ## PATCH /quotes/{id} ```json { "operationId": "updateQuote", "summary": "Update a quote", "description": "Not after it was converted (quote_converted) or accepted (quote_not_editable).", "tags": [ "Quotes" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQuoteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Converted or accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete a quote (its invoice, if any, stays) (https://docs.getbeel.com/en/api/reference/quotes/deleteQuote) ## DELETE /quotes/{id} ```json { "operationId": "deleteQuote", "summary": "Delete a quote (its invoice, if any, stays)", "tags": [ "Quotes" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedQuote" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Email the quote PDF to the customer (https://docs.getbeel.com/en/api/reference/quotes/sendQuote) ## POST /quotes/{id}/send ```json { "operationId": "sendQuote", "summary": "Email the quote PDF to the customer", "description": "Marks a draft quote sent. Test keys: the email goes to the team owner only, with a [TEST] subject.", "tags": [ "Quotes" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendQuoteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendQuoteResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Converted (quote_converted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No recipient (customer_email_missing) or incomplete company profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The email provider refused the email (email_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Mark a quote accepted (https://docs.getbeel.com/en/api/reference/quotes/acceptQuote) ## POST /quotes/{id}/accept ```json { "operationId": "acceptQuote", "summary": "Mark a quote accepted", "tags": [ "Quotes" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Mark a quote declined (https://docs.getbeel.com/en/api/reference/quotes/declineQuote) ## POST /quotes/{id}/decline ```json { "operationId": "declineQuote", "summary": "Mark a quote declined", "tags": [ "Quotes" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Turn a quote into an invoice draft (https://docs.getbeel.com/en/api/reference/quotes/convertQuote) ## POST /quotes/{id}/convert ```json { "operationId": "convertQuote", "summary": "Turn a quote into an invoice draft", "description": "Creates the invoice draft (today unless date is sent; same rules as POST /invoices: live keys need an SDI plan and reserve quota) and marks the quote accepted. A quote converts once (409 quote_converted).", "tags": [ "Quotes" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertQuoteRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Live: no SDI plan or quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already converted, or declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Download the quote PDF (https://docs.getbeel.com/en/api/reference/quotes/getQuotePdf) ## GET /quotes/{id}/pdf ```json { "operationId": "getQuotePdf", "summary": "Download the quote PDF", "tags": [ "Quotes" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Company profile incomplete (company_profile_incomplete)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List saved items, by name (https://docs.getbeel.com/en/api/reference/items/listItems) ## GET /items ```json { "operationId": "listItems", "summary": "List saved items, by name", "tags": [ "Items" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Part of the item name, case-insensitive", "schema": { "examples": [ "consulenza" ], "type": "string", "maxLength": 100 } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return, 1–200 (default 200)", "schema": { "default": 200, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Save an item or service (https://docs.getbeel.com/en/api/reference/items/createItem) ## POST /items ```json { "operationId": "createItem", "summary": "Save an item or service", "tags": [ "Items" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateItemRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Retrieve an item (https://docs.getbeel.com/en/api/reference/items/getItem) ## GET /items/{id} ```json { "operationId": "getItem", "summary": "Retrieve an item", "tags": [ "Items" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Update an item (past invoices keep their values) (https://docs.getbeel.com/en/api/reference/items/updateItem) ## PATCH /items/{id} ```json { "operationId": "updateItem", "summary": "Update an item (past invoices keep their values)", "tags": [ "Items" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Delete an item (https://docs.getbeel.com/en/api/reference/items/deleteItem) ## DELETE /items/{id} ```json { "operationId": "deleteItem", "summary": "Delete an item", "tags": [ "Items" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedItem" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List numbering series with their next number (https://docs.getbeel.com/en/api/reference/numbering-series/listNumberingSeries) ## GET /numbering-series ```json { "operationId": "listNumberingSeries", "summary": "List numbering series with their next number", "description": "Next numbers are for today in the key's mode (test and live keys number separately). default_numbering is the numbering used without a series: plain numbers (1, 2, 3, no suffix) that restart every calendar year, or one sequence across years if yearly_reset is false. The number shown is always the XML Numero.", "tags": [ "Numbering series" ], "x-required-scope": "invoices:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberingSeriesList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Create a numbering series (https://docs.getbeel.com/en/api/reference/numbering-series/createNumberingSeries) ## POST /numbering-series ```json { "operationId": "createNumberingSeries", "summary": "Create a numbering series", "description": "A prefix and/or suffix (\"FT-\", \"/A\"), restarting every year unless yearly_reset is false. Live keys only (403 livemode_required).", "tags": [ "Numbering series" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNumberingSeriesRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberingSeries" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A series with this prefix and suffix exists, or the format is the default numbering (numbering_series_exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Retrieve a numbering series (https://docs.getbeel.com/en/api/reference/numbering-series/getNumberingSeries) ## GET /numbering-series/{id} ```json { "operationId": "getNumberingSeries", "summary": "Retrieve a numbering series", "tags": [ "Numbering series" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberingSeries" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Rename, set as default or archive a series (https://docs.getbeel.com/en/api/reference/numbering-series/updateNumberingSeries) ## PATCH /numbering-series/{id} ```json { "operationId": "updateNumberingSeries", "summary": "Rename, set as default or archive a series", "description": "prefix, suffix and yearly_reset change only while no invoice uses the series (409 numbering_series_in_use). Live keys only.", "tags": [ "Numbering series" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNumberingSeriesRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberingSeries" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'invoices:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "In use or duplicate format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # List the commercialisti with access (https://docs.getbeel.com/en/api/reference/advisors/listAdvisors) ## GET /advisors ```json { "operationId": "listAdvisors", "summary": "List the commercialisti with access", "description": "Active advisors (id mem_…, members with the auditor role) and pending invitations (id inv_…). Not paginated: has_more is always false.", "tags": [ "Advisors" ], "x-required-scope": "advisors:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvisorList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'advisors:read' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ] } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Invite a commercialista (https://docs.getbeel.com/en/api/reference/advisors/createAdvisor) ## POST /advisors ```json { "operationId": "createAdvisor", "summary": "Invite a commercialista", "description": "Emails the standard team invitation with the read-only auditor role (201); the advisor appears with status invited until they accept. An address that already has a pending advisor invitation gets it back (200) and no second email. 409 already_member for an address already in the team, already_invited for one invited to another role. Live keys only (403 livemode_required). The key’s member needs the invites.manage permission (to invite or revoke) or members.manage (to remove a member), the same rules as the app; otherwise 403.", "tags": [ "Advisors" ], "x-required-scope": "advisors:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdvisorRequest" } } } }, "responses": { "200": { "description": "Already invited: the pending invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advisor" } } } }, "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advisor" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'advisors:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already a member, or invited to another role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Invite a commercialista to several companies (https://docs.getbeel.com/en/api/reference/advisors/inviteAdvisorToCompanies) ## POST /advisors/invitations ```json { "operationId": "inviteAdvisorToCompanies", "summary": "Invite a commercialista to several companies", "description": "Invites one commercialista (read-only auditor role) to this account and/or several of its client companies at once (company_ids, at most 25; without them, the company of the Getbeel-Company header, else this account). Each company is invited exactly like POST /advisors, with its own permissions and invitation policies. Always 200 with one result per company: invited, already_invited (the pending invitation, no second email), or failed with the reason (company_not_found for an id that is not this account or a client company you manage, already_member, invite_not_allowed, subscription_required, credits_exhausted, rate_limited, invite_failed). One company failing never stops the others. A test key gets 403 livemode_required before anything is sent. Live keys only (403 livemode_required). The key’s member needs the invites.manage permission (to invite or revoke) or members.manage (to remove a member), the same rules as the app; otherwise 403.", "tags": [ "Advisors" ], "x-required-scope": "advisors:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteAdvisorToCompaniesRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvisorInvitations" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'advisors:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # Revoke an invitation or remove a commercialista (https://docs.getbeel.com/en/api/reference/advisors/deleteAdvisor) ## DELETE /advisors/{id} ```json { "operationId": "deleteAdvisor", "summary": "Revoke an invitation or remove a commercialista", "description": "inv_… revokes the pending invitation; mem_… removes the member from the team, who loses access at once. Live keys only (403 livemode_required). The key’s member needs the invites.manage permission (to invite or revoke) or members.manage (to remove a member), the same rules as the app; otherwise 403.", "tags": [ "Advisors" ], "x-required-scope": "advisors:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Getbeel-Company", "in": "header", "required": false, "description": "Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedAdvisor" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the 'advisors:write' scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or company_not_found (Getbeel-Company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error; quote X-Request-Id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ``` Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.sent (https://docs.getbeel.com/en/api/reference/unknown/invoice.sent) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.delivered (https://docs.getbeel.com/en/api/reference/unknown/invoice.delivered) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.not_delivered (https://docs.getbeel.com/en/api/reference/unknown/invoice.not_delivered) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.rejected (https://docs.getbeel.com/en/api/reference/unknown/invoice.rejected) Full OpenAPI document: https://docs.getbeel.com/openapi.json # bank_statement.parsed (https://docs.getbeel.com/en/api/reference/unknown/bank_statement.parsed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # reconciliation.completed (https://docs.getbeel.com/en/api/reference/unknown/reconciliation.completed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # received_invoice.created (https://docs.getbeel.com/en/api/reference/unknown/received_invoice.created) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.emailed (https://docs.getbeel.com/en/api/reference/unknown/invoice.emailed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.email_failed (https://docs.getbeel.com/en/api/reference/unknown/invoice.email_failed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.paid (https://docs.getbeel.com/en/api/reference/unknown/invoice.paid) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.overdue (https://docs.getbeel.com/en/api/reference/unknown/invoice.overdue) Full OpenAPI document: https://docs.getbeel.com/openapi.json # filing.ready (https://docs.getbeel.com/en/api/reference/unknown/filing.ready) Full OpenAPI document: https://docs.getbeel.com/openapi.json # filing.filed (https://docs.getbeel.com/en/api/reference/unknown/filing.filed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # tax_deadline.upcoming (https://docs.getbeel.com/en/api/reference/unknown/tax_deadline.upcoming) Full OpenAPI document: https://docs.getbeel.com/openapi.json # tax_deadline.insufficient_funds (https://docs.getbeel.com/en/api/reference/unknown/tax_deadline.insufficient_funds) Full OpenAPI document: https://docs.getbeel.com/openapi.json # bank_connection.expiring (https://docs.getbeel.com/en/api/reference/unknown/bank_connection.expiring) Full OpenAPI document: https://docs.getbeel.com/openapi.json # bank_connection.expired (https://docs.getbeel.com/en/api/reference/unknown/bank_connection.expired) Full OpenAPI document: https://docs.getbeel.com/openapi.json