# Commercialista (advisors) (https://docs.getbeel.com/it/api/advisors) Invitare un commercialista con accesso in sola lettura, vedere chi ha accesso, revocare un invito o rimuoverlo. Un **advisor** è il commercialista dell'azienda: un membro del team con il ruolo in sola lettura `auditor` (nell'app **Commercialista**). Dopo aver accettato l'invito può leggere ed esportare fatture emesse e ricevute, movimenti bancari e la sezione Tasse, senza modificare nulla. È lo stesso invito di [Invita il tuo commercialista](/it/guide/report-e-commercialista#invita-il-tuo-commercialista) nell'app. Scope: `advisors:read` per l'elenco, `advisors:write` per invitare e rimuovere. Invitare o rimuovere qualcuno dà accesso a dati reali a una persona reale, quindi serve una **chiave live** (`403 livemode_required` con una chiave di test). `advisors:write` non è mai selezionato di default quando crei una chiave: va spuntato di proposito. Il membro che ha creato la chiave deve poter fare lo stesso nell'app: `invites.manage` per invitare o revocare un invito, `members.manage` per rimuovere un membro (mai il proprietario principale né sé stesso). Altrimenti `403 invite_not_allowed` o `remove_not_allowed`. ## Invitare [#invitare] ```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` con l'advisor, `status: "invited"`. L'email di invito parte subito e scade dopo 7 giorni (`expires_at`). Un indirizzo che ha già un invito da commercialista in attesa riceve quell'invito con `200`, senza una seconda email, quindi i tentativi ripetuti sono sicuri; revocalo per inviarne uno nuovo. Un indirizzo già nel team risponde `409 already_member`; uno invitato con un altro ruolo `409 already_invited`. Una policy di invito che rifiuta risponde `403 invite_not_allowed` con il motivo. ```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 } ``` ## Elenco [#elenco] `GET /v1/advisors` restituisce gli advisor attivi (`id` `mem_…`, `status: "active"`, `joined_at`) e gli inviti in attesa (`inv_…`). Gli altri membri del team non compaiono. L'elenco non è paginato (`has_more` è sempre `false`). ## Rimuovere [#rimuovere] `DELETE /v1/advisors/{id}`: `inv_…` revoca l'invito, `mem_…` toglie il commercialista dal team, che perde subito l'accesso. Risponde `{ "id", "object": "advisor", "deleted": true }`. ## Aziende clienti [#aziende-clienti] Con l'header `Getbeel-Company` un account principale invita il commercialista di una delle sue aziende clienti, con le stesse regole. Per invitare lo stesso commercialista a più aziende insieme (questo account e le sue aziende clienti), indicale in `company_ids` (al massimo 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` risponde `200` con un risultato per azienda, nell'ordine inviato: `invited`, `already_invited` (l'invito in sospeso, nessuna seconda email) o `failed` con il motivo (`company_not_found` per un id che non è questo account né un'azienda cliente che gestisci, `already_member`, `invite_not_allowed`, `subscription_required`, `credits_exhausted`, `rate_limited`). Ogni azienda è invitata esattamente come con `POST /v1/advisors`; se una non riesce, le altre proseguono. Senza `company_ids` invita all'azienda dell'header `Getbeel-Company`, altrimenti a questo account. Una chiave di test riceve `403 livemode_required`. Nell'app: **Aziende clienti → Invita il commercialista**. ## MCP e SDK [#mcp-e-sdk] - MCP: `list_advisors`, `invite_advisor`, `invite_accountant` (più aziende) e `remove_advisor`. L'assistente deve confermare con te l'indirizzo email prima di invitare. - 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")`. # Autenticazione (https://docs.getbeel.com/it/api/authentication) Chiavi API di test e live, scope e buone pratiche. Ogni richiesta porta una chiave API nell'header `Authorization`: ![La pagina Chiavi API e MCP: chiavi di test e live, permessi e indirizzo del server MCP.](/screenshots/api-keys-mcp.it.webp) ```bash curl https://www.getbeel.com/api/v1/me \ -H "Authorization: Bearer gb_test_..." ``` ## Chiavi di test e live [#chiavi-di-test-e-live] | Prefisso | Modalità | Cosa succede all'invio | | ---------- | -------- | --------------------------------------------------------------------------- | | `gb_test_` | Test | L'invio va alla [sandbox](/it/api/sandbox): nessuna fattura arriva allo SDI | | `gb_live_` | Live | La fattura viene trasmessa allo SDI e ha valore fiscale | Gli endpoint sono gli stessi. Sviluppa e collauda con una chiave di test e passa a una chiave live solo in produzione. Le letture (`GET`) restituiscono i dati del tuo account in entrambe le modalità. ## Creare e gestire le chiavi [#creare-e-gestire-le-chiavi] Le chiavi si creano in **Impostazioni → Chiavi API e MCP** nell'app. - La chiave viene mostrata **una sola volta**. Getbeel conserva solo un hash e il prefisso (es. `gb_live_a1B2`), che vedi nell'elenco. - Puoi impostare una scadenza e revocare una chiave in qualsiasi momento. - Una chiave appartiene a un team e agisce come il membro che l'ha creata: vede solo i dati di quel team. - Se il membro esce dal team, le sue chiavi vengono revocate. Se perde il permesso di gestire le impostazioni (per esempio diventa revisore), le sue chiavi restano sospese. ## Scope [#scope] Quando crei una chiave scegli cosa può fare. Una richiesta a un endpoint fuori dagli scope della chiave riceve `403 insufficient_scope`. | Scope | Consente | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `account:read` | `GET /me`, strumento MCP `whoami` | | `invoices:read` | `GET /invoices`, `GET /invoices/{id}`, strumenti `list_invoices`, `get_invoice` | | `received_invoices:read` | `GET /received-invoices`, strumento `list_received_invoices` | | `invoices:validate` | `POST /invoices/validate`, strumento `validate_invoice` | | `invoices:write` | `POST /invoices`, `POST /invoices/{id}/send`, strumenti `create_invoice_draft`, `send_invoice` | | `received_invoices:write` | `POST /received-invoices/{id}/approve` e `/reject`, strumento `approve_collected_document` (chiavi live) | | `bank:read` | Estratti conto, movimenti, riconciliazioni, abbinamenti, elenchi dei non abbinati | | `bank:write` | Caricare estratti conto, avviare riconciliazioni, approvare, rifiutare e collegare abbinamenti (chiavi live) | | `connections:read` | `GET /connections`, `GET /forwarding-address`, strumento `list_connections` | | `connections:write` | Collegare caselle email e Stripe, scansionare caselle, sincronizzare Stripe (chiavi live) | | `taxes:read` | Scadenzario fiscale (anche `.ics`), adempimenti preparati, posizione IVA stimata | | `taxes:write` | Preparare un adempimento (F24) e caricare la quietanza (chiavi live) | | `advisors:read` | `GET /advisors`, strumento `list_advisors` | | `advisors:write` | Invitare o rimuovere un commercialista con accesso in sola lettura: `POST /advisors`, `DELETE /advisors/{id}` (chiavi live) | | `drive:read` | Cartelle, file e link di download: `GET /drive`, `GET /drive/files/{id}/download`, strumenti `list_drive`, `get_drive_file`. I file delle fatture richiedono anche `received_invoices:read`, gli estratti conto `bank:read` | | `drive:write` | Creare una cartella: `POST /drive/folders`, strumento `create_drive_folder` (chiavi live) | | `billing:write` | Creare un link "Aggiungi credito" da far pagare a una persona (`POST /billing/topups`, strumento `create_billing_topup`) e un link "Cambia carta" (`POST /billing/payment-method`, strumento `create_billing_card_link`) (chiavi live; mai selezionato di default) | Gli endpoint che creano e inviano fatture richiedono lo scope `invoices:write`. Le nuove chiavi hanno tutti gli scope selezionati tranne `advisors:write`, che dà a una persona un accesso duraturo ai dati dell'azienda: togli quelli che a un'integrazione non servono. Gli scope non si possono modificare dopo: crea una nuova chiave. Dai a ogni integrazione solo gli scope che le servono: una chiave che legge soltanto non può inviare fatture. ## Errori di autenticazione [#errori-di-autenticazione] Tutti con stato `401` e `type: "authentication_error"`: | `code` | Significato | | ------------------- | --------------------------------------------- | | `missing_api_key` | Manca l'header `Authorization: Bearer …` | | `invalid_api_key` | La chiave non esiste o è scritta male | | `api_key_revoked` | La chiave è stata revocata | | `api_key_expired` | La chiave è scaduta | | `api_key_suspended` | Chi l'ha creata non può più gestire le chiavi | ## Buone pratiche [#buone-pratiche] - Tieni la chiave sul server, in una variabile d'ambiente come `GETBEEL_API_KEY`. Mai nel codice, nel browser o in un'app mobile. - Usa una chiave per integrazione, così puoi revocarne una senza fermare le altre. - Se una chiave finisce in un repository o in un log, revocala e creane una nuova. Claude, ChatGPT e Cursor si collegano al [server MCP](/it/api/mcp) con l'accesso (OAuth 2.1). Il collegamento ha un team, una modalità e degli scope come una chiave, e compare in Impostazioni → Chiavi API e MCP → App collegate. # Autofatture (https://docs.getbeel.com/it/api/autofatture) Leggi un'autofattura in reverse charge (TD17, TD18, TD19) e inviala allo SdI, esattamente come il pulsante Invia allo SdI. Un'autofattura è il documento che invii allo SdI per un acquisto da un fornitore estero (reverse charge): **TD17** per servizi dall'estero, **TD18** per beni da un altro paese UE, **TD19** per beni già in Italia. getbeel le propone e le genera dai tuoi addebiti bancari, dall'import Autofatture e dalle fatture estere che ricevi. L'id è quello della pagina Autofatture (la transazione bancaria a cui appartiene). La lettura richiede `invoices:read` (entrambe le modalità di chiave). L'invio richiede `invoices:write` e una **chiave live**: è un atto fiscale reale. ## Leggere un'autofattura [#leggere-unautofattura] ```bash curl "https://www.getbeel.com/api/v1/autofatture/$AUTOFATTURA_ID" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` ```json title="Risposta" { "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` è l'XML: `generated` vuol dire pronta da inviare. `sdi.status` è `null` finché non la invii, poi `queued`, `sending`, `sent_to_sdi` e la risposta dello SdI: `consegnata`, `non_consegnata`, `scartata` (con `sdi.error`). ## Inviarla allo SdI [#inviarla-allo-sdi] ```bash curl -X POST "https://www.getbeel.com/api/v1/autofatture/$AUTOFATTURA_ID/send" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Fa gli stessi passaggi del pulsante **Invia allo SdI** della pagina Autofatture: - l'XML deve essere generato (altrimenti `409 autofattura_xml_missing` o `autofattura_not_generated`); - l'invio si paga dal credito prepagato al prezzo dell'invio SdI (vedi [Prezzi](/it/api/pricing)). Se il credito non basta la risposta è `402 insufficient_balance` ([Errori](/it/api/errors#insufficient_balance)) e non viene inviato nulla; - viene messa in coda: la risposta è l'autofattura con `sdi.status: "queued"`. Rileggila più tardi per la risposta dello SdI. **Si può ripetere senza rischi.** Una seconda chiamata non invia e non addebita di nuovo: `409 autofattura_already_queued` mentre è in viaggio, `409 autofattura_already_sent` quando lo SdI l'ha presa. Un reinvio corretto dopo uno scarto non viene addebitato di nuovo. Altri rifiuti: `409 sdi_monthly_cap_reached` (il limite mensile degli invii live), `409 sdi_not_available` (un account ancora su un piano precedente senza il servizio SDI), `404 resource_missing`, `403 livemode_required` con una chiave di test. I tool MCP `get_autofattura` e `send_autofattura_to_sdi` fanno lo stesso (vedi [MCP](/it/api/mcp)). # Collegamento banca (https://docs.getbeel.com/it/api/bank-connections) Movimenti bancari automatici con Enable Banking, usando l'applicazione Enable Banking della tua azienda. Getbeel scarica i movimenti dei conti correnti ogni 6 ore e li abbina alle fatture, come se ogni mese arrivasse un estratto conto. Il collegamento passa da [Enable Banking](https://enablebanking.com) con **la tua applicazione Enable Banking**: tu la registri a nome della tua azienda, Getbeel firma le chiamate con la sua chiave privata. Scope: `bank:read` per leggere, `bank:write` per collegare, ricollegare, sincronizzare e scollegare. La lettura funziona con qualsiasi chiave; le modifiche richiedono una chiave live (`403 livemode_required`). Ogni conto collegato costa 2 € al mese e ogni movimento importato 0,02 €, dal saldo prepagato (`402 insufficient_balance` se non basta). ## Prima di iniziare [#prima-di-iniziare] 1. Crea un account su [Enable Banking](https://enablebanking.com/sign-in/). 2. Nel [pannello di controllo](https://enablebanking.com/cp/applications) registra un'applicazione nell'ambiente **Production** (o **Sandbox** per provare con la banca di prova "Mock ASPSP"). Scegli "Generate in the browser" ed esporta la chiave privata `.pem`. 3. In "Allowed redirect URLs" aggiungi esattamente: ```text https://getbeel.com/api/open-banking/callback ``` 4. Attiva l'applicazione con "Activate by linking accounts": in modalità limitata l'applicazione legge solo i conti collegati lì. Enable Banking descrive la modalità limitata come pensata per la valutazione e per l'uso "individuale non commerciale". Verifica con Enable Banking che il tuo uso rientri nelle condizioni, o firma con loro un contratto. ## Collega una banca [#collega-una-banca] ```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 @- < I dati bancari sono reali: non c'è una sandbox. Le chiavi di test (`gb_test_…`) possono leggere estratti conto, movimenti e abbinamenti; caricare e verificare richiede una chiave live (`gb_live_…`), altrimenti `403 livemode_required`. Ogni movimento nuovo di un estratto caricato costa 0,02 € dal saldo prepagato (`402 insufficient_balance` se non basta). Scope: `bank:read` per leggere, `bank:write` per caricare e verificare. ## 1. Carica un estratto conto [#1-carica-un-estratto-conto] PDF, CSV o TXT, oppure un file della banca: CBI (rendicontazione RH), CAMT.053 (XML ISO 20022) o MT940; fino a 50 MB (esporta prima un foglio di calcolo in CSV). I file CBI, CAMT.053 e MT940 vengono riconosciuti dal contenuto e letti in modo esatto, senza IA; PDF e CSV vengono letti con l'IA. Invia il file in 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" ``` Le richieste sono limitate a circa 4 MB. Per file più grandi (fino a 50 MB) metti il file online e invia JSON con `file_url` (`https` pubblico, senza redirect): ```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" }' ``` La risposta è `202` con l'estratto conto in stato `pending`. L'elaborazione prosegue in background: | Stato | Significato | | ------------ | --------------------------------------------------------------------------------- | | `pending` | In coda | | `processing` | Lettura del file | | `parsed` | Movimenti salvati (webhook `bank_statement.parsed`) | | `matching` | Abbinamento AI alle fatture ricevute | | `review` | Fatto: gli abbinamenti aspettano la verifica (webhook `reconciliation.completed`) | | `completed` | Segnato come concluso nell'app | | `failed` | Non leggibile: riprova con `POST /reconciliations` | `GET /bank-statements/{id}` restituisce anche la banca, il periodo e il saldo iniziale e finale (quando l'estratto conto riporta il saldo progressivo). ## 2. Verifica gli abbinamenti [#2-verifica-gli-abbinamenti] Una riconciliazione ha lo stesso id del suo estratto conto: ```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" ``` Ogni movimento ha un abbinamento. `match_type` è `exact`, `fuzzy` (da controllare), `manual` o `unmatched`, con una `confidence` da `0.00` a `1.00`. `state` dice cosa fare: | Stato | Significato | | ------------------- | ----------------------------------------------------------- | | `to_confirm` | È stata trovata una fattura: approvala o rifiutala | | `reconciled` | Confermato | | `missing_invoice` | Nessuna fattura trovata per questo pagamento | | `no_invoice_needed` | Confermato che non serve (commissioni, imposte, giroconti…) | | `rejected` | Il suggerimento era sbagliato | Poi: - `POST /reconciliations/{id}/matches/{matchId}/approve`: la fattura è giusta (per un pagamento senza fattura: non ne serve una). - `POST /reconciliations/{id}/matches/{matchId}/reject`: il suggerimento è sbagliato. - `POST /reconciliations/{id}/matches` con `{ "transaction_id", "invoice_id" }`: collega a mano una fattura ricevuta. - `POST /reconciliations` con `{ "statement_id" }`: rilegge e riabbina da capo (sostituisce movimenti e abbinamenti). ## 3. Cosa manca [#3-cosa-manca] - `GET /unmatched/payments`: uscite senza fattura, cioè i documenti da chiedere ai fornitori. - `GET /unmatched/invoices`: fatture ricevute a cui non è abbinato nessun pagamento. Entrambi accettano `from` e `to` (`YYYY-MM-DD`) e la consueta [paginazione](/it/api/pagination). `GET /bank-transactions` elenca tutti i movimenti, con i filtri `statement_id`, `from`, `to` e `status`. ## Con un assistente AI [#con-un-assistente-ai] Il [server MCP](/it/api/mcp) ha `upload_bank_statement`, `get_bank_statement`, `get_reconciliation`, `list_unmatched`, `approve_match` e `match_manually`. L'assistente ti chiede conferma prima di ogni modifica. # Changelog (https://docs.getbeel.com/it/api/changelog) Le modifiche all'API di Getbeel che possono toccare un'integrazione, dalla più recente. Le modifiche che possono toccare un'integrazione esistente, dalla più recente. I nuovi endpoint e strumenti sono nel [riferimento](/it/api/reference) e nelle loro pagine. ## 2026-11-12 [#2026-11-12] ### `authorization_url` apre prima una pagina di Getbeel [#authorization_url-apre-prima-una-pagina-di-getbeel] `POST /bank-connections` e `POST /bank-connections/{id}/reconnect` restituiscono ancora `authorization_url`, valido 30 minuti. Ora apre `https://getbeel.com/bank-login?t=…`, una pagina che mostra il nome del tuo team, invece della pagina della banca. **Continua** porta alla banca, e il resto dell'accesso non cambia. - **Perché.** Chi accede alla banca vede a quale team vanno i suoi conti prima di condividere qualcosa. Un link bancario avviato da altri non può più passare per il tuo. - **Cosa cambiare.** Niente, se apri l'URL in un browser come prima. Se il tuo codice controllava che l'URL fosse su `enablebanking.com` o `tilisy.com`, accetta anche `getbeel.com`. - Lo strumento MCP `reconnect_bank_connection` restituisce lo stesso nuovo URL. ## Correlati [#correlati] - [Collegamenti bancari](/it/api/bank-connections): l'accesso alla banca passo per passo. - [Errori](/it/api/errors): il formato degli errori. # CLI (https://docs.getbeel.com/it/api/cli) Invia fatture, carica estratti conto e controlla le scadenze dal terminale. Il comando `getbeel` usa l'[SDK TypeScript](/it/api/sdk-typescript). Node.js 20.19+. ```bash npm install -g @getbeel/cli # oppure: npx @getbeel/cli whoami getbeel login # incolla una chiave da Impostazioni → Chiavi API e MCP getbeel whoami ``` `login` verifica la chiave e la salva in `~/.config/getbeel/config.json` (leggibile solo da te). `GETBEEL_API_KEY` o `--api-key` hanno la precedenza (e vanno all'host predefinito, non a un base URL salvato con un'altra chiave); `getbeel logout` la dimentica. Inizia con una chiave di test (`gb_test_…`): gli invii vanno alla [sandbox](/it/api/sandbox). ## Comandi [#comandi] | Comando | Cosa fa | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `invoices list [--status s] [--limit n] [--cursor c] [--all]` | Fatture emesse | | `invoices get ` | Una fattura | | `invoices create --file fattura.json` | Crea una bozza da un file JSON [CreateInvoiceRequest](/it/api/reference) | | `invoices validate --file fattura.xml` | Controlla un XML FatturaPA | | `invoices send ` | Invia una bozza allo SDI (alla sandbox con una chiave di test) | | `received list [--status s] [--source s] [--all]` | Fatture ricevute | | `bank statements upload [--currency EUR]` | Carica un estratto conto (PDF, CSV, TXT, CBI, CAMT.053, MT940) | | `bank statements list [--all]` | Estratti conto e il loro stato | | `bank connections list` | Banche collegate | | `bank connections sync ` | Sincronizza ora una banca | | `taxes calendar [--from data] [--to data]` | Scadenze fiscali | | `taxes registers --period 2026-Q3` | Registri IVA vendite e acquisti di un mese o trimestre | | `taxes settlement --period 2026-10` | Liquidazione IVA del periodo (da verificare) | | `taxes report --type profit-and-loss --period 2026` | Report gestionale: conto economico, flussi di cassa, crediti | | `filings prepare --type bollo\|withholdings --period 2026-Q3 [--amount 200.00]` | Prepara un F24 | | `filings prepare --type vat_payment\|lipe --period 2026-10` | Salva la liquidazione IVA e prepara l'F24, o il file LIPE di un trimestre | | `filings list [--all]` | Adempimenti preparati | ## Opzioni [#opzioni] - `--json`: stampa il JSON dell'API (per script e `jq`); gli errori vanno su stderr in JSON. - `--company `: agisci su un'[azienda cliente](/it/api/companies). - `--idempotency-key `: per `create`, `send`, `upload` e `prepare` (altrimenti una casuale). - `--base-url `: un altro host dell'API (https; http solo per localhost). Codici di uscita: `0` ok, `1` errore dell'API (stampato con codice e request id), `2` comando o opzioni errati. ```bash getbeel invoices create --file fattura.json --json | jq -r .id | xargs getbeel invoices send ``` # Più aziende (multi-company) (https://docs.getbeel.com/it/api/companies) Software house, marketplace e commercialisti gestiscono le aziende dei clienti da un solo account, con una sola chiave API. Ogni azienda su Getbeel è un account separato, con i suoi dati fiscali, fatture, banca e invio SDI. Un account **principale** (il tuo studio, la tua software house o il tuo marketplace) può avere delle **aziende clienti**: le crei tu, ci lavori dall'app passando dall'una all'altra, e la chiave API (o la connessione MCP) dell'account principale può agire su ciascuna. ## Le regole [#le-regole] - Chi aggiunge un'azienda cliente ne diventa **proprietario**. Vede l'azienda solo chi ne è membro: i colleghi dello studio vanno invitati dalla pagina **Membri** dell'azienda, come il cliente. - Una chiave dell'account principale agisce su un'azienda cliente solo se il membro che l'ha creata può gestire quell'azienda (proprietario o membro, non revisore). Altrimenti la risposta è `404 company_not_found`, come per un'azienda che non esiste. - Un solo livello: un'azienda cliente non può avere aziende clienti. Un'azienda cliente non vede l'account principale né le altre aziende clienti. - Se l'account principale viene eliminato, le aziende clienti restano, con i loro dati e i loro membri. - Per ora ogni azienda ha il suo piano: per inviare fatture reali allo SDI da un'azienda cliente serve l'add-on SDI su quell'azienda. Con una chiave di test la sandbox funziona su tutte, ma solo una chiave live può aggiungere aziende o modificarne i dati (`403 livemode_required`). ## Nell'app [#nellapp] In **Aziende clienti** trovi l'elenco con lo stato SDI di ogni azienda (dati fiscali completi o cosa manca, invio SDI attivo) e **Aggiungi azienda**. Bastano ragione sociale e partita IVA; il resto si completa dopo in **Dati aziendali**. Per lavorare su un'azienda usa **Apri** o il selettore in alto nella barra laterale. La voce **Aziende clienti** compare nella barra laterale dei team che hanno scelto **Commercialista** nei primi passi o che hanno già un'azienda cliente. Per tutti gli altri la pagina è in **Impostazioni → Azienda → Gestisci aziende clienti**. Dentro un'azienda cliente la voce non c'è: un'azienda cliente non può avere a sua volta aziende clienti. ## Con l'API [#con-lapi] Crea l'azienda (scope `companies:write`, chiave live). Il membro della chiave ne diventa proprietario, quindi la stessa chiave può usarla subito: ```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" }' ``` La risposta è l'azienda, con `id` e `sdi_readiness` (`ready` e i campi `missing`). Poi invia il suo `id` nell'header **`Getbeel-Company`** su qualsiasi altro endpoint: ```bash curl https://www.getbeel.com/api/v1/invoices \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Getbeel-Company: $COMPANY_ID" ``` Senza l'header le richieste agiscono sull'account della chiave. `GET /v1/me` con l'header mostra l'azienda su cui stai agendo. | Endpoint | Scope | | | -------------------------- | ----------------- | ------------------------------------------------------------ | | `GET /v1/companies` | `account:read` | L'account della chiave e le aziende clienti su cui può agire | | `POST /v1/companies` | `companies:write` | Aggiunge un'azienda cliente | | `GET /v1/companies/{id}` | `account:read` | Un'azienda (o l'account stesso) | | `PATCH /v1/companies/{id}` | `companies:write` | Modifica solo i campi inviati | `/v1/companies` è sempre relativo all'account della chiave: lì l'header `Getbeel-Company` non si applica. Una chiave di un'azienda cliente non può creare aziende (`409 company_nesting_not_allowed`). Le chiavi create prima di questa funzione non hanno lo scope `companies:write`: per creare aziende via API crea una nuova chiave. Leggere e agire sulle aziende funziona con le chiavi esistenti. ## Con un assistente AI (MCP) [#con-un-assistente-ai-mcp] Lo strumento `list_companies` elenca le aziende, `create_company` ne aggiunge una e `update_company` ne cambia i dati (chiave live); ogni altro strumento accetta `company_id` per agire su un'azienda cliente. Chiedi ad esempio: _"Elenca le aziende clienti e dimmi quali non sono pronte per lo SDI"_, oppure _"Crea una bozza di fattura per Rossi Srl…"_. I client che permettono header personalizzati possono usare anche `Getbeel-Company`. ## Webhook [#webhook] Gli eventi di un'azienda cliente vanno agli endpoint configurati **su quell'azienda** (Impostazioni → Chiavi API e MCP dell'azienda) e agli endpoint corrispondenti dell'account principale, finché chi ha aggiunto l'endpoint dell'account principale può ancora gestire l'azienda. La copia per l'account principale contiene `company_id` (l'id dell'azienda, il valore di `Getbeel-Company`); quella dell'azienda no. # Connessioni (https://docs.getbeel.com/it/api/connections) Collega caselle email e Stripe, cerca le fatture dei fornitori e verifica i documenti raccolti. Getbeel raccoglie le fatture dei fornitori dalla posta (Gmail, Outlook, IMAP o un indirizzo di inoltro) e trasforma le fatture Stripe in fatture elettroniche. L'API espone le stesse connessioni di **Impostazioni → Email** e della pagina fatture emesse. Scope: `connections:read` per leggere, `connections:write` per collegare, scansionare e sincronizzare; `received_invoices:write` per approvare i documenti raccolti. La lettura funziona con qualsiasi chiave; le modifiche richiedono una chiave live (altrimenti `403 livemode_required`). Ogni documento letto con l'AI si paga dal saldo prepagato (`402 insufficient_balance` se non basta). ## Elenco delle connessioni [#elenco-delle-connessioni] ```bash curl https://www.getbeel.com/api/v1/connections \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Ogni connessione ha `provider` (`gmail`, `outlook`, `imap`, `forwarding`, `stripe`), `active` e `health.status`: `healthy`, `reconnect_required` (va ricollegata), `error` o `unknown`. ## Collega una casella [#collega-una-casella] Gmail e Outlook usano OAuth, che deve approvare una persona. L'API restituisce un 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" }' ``` Apri `url` in un browser con l'accesso a Getbeel come membro del team (altrimenti ti chiede di accedere), approva l'accesso e torni nell'app. La casella compare poi in `GET /connections`. IMAP si collega direttamente: Getbeel prova l'accesso (porta 993, TLS) e salva la password cifrata. Usa una password per le app. ```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": "password-app", "host": "imap.example.it" }' ``` Le nuove caselle contano nel limite del piano (`402` quando è raggiunto). ## Scansiona una casella [#scansiona-una-casella] ```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" }' ``` Al massimo un anno per richiesta. La scansione prosegue in background (`202`); ogni fattura trovata invia `received_invoice.created` e compare in `GET /received-invoices?source=email`. ## Indirizzo di inoltro [#indirizzo-di-inoltro] `GET /forwarding-address` restituisce l'indirizzo a cui inoltrare le fatture dei fornitori, oppure `null` finché non lo attivi nell'app (serve l'add-on di instradamento email). Le fatture inoltrate hanno `source: forwarded`. ## Verifica dei documenti raccolti [#verifica-dei-documenti-raccolti] I documenti raccolti sono le [fatture ricevute](/it/api/reference) con una `source` (`email`, `forwarded`, `manual`, `bank_transaction`). Quelli che aspettano una persona hanno `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` imposta `verified`, `reject` imposta `rejected`. I documenti ancora in lettura, i segnaposto di documento mancante e quelli esportati non si possono verificare (`409`). ## Stripe [#stripe] - `POST /connections/stripe` restituisce un link a Stripe Connect; dopo l'approvazione torni alla pagina fatture emesse. - `POST /connections/stripe/sync` (facoltativo `{ "from", "to" }`, di default gli ultimi 30 giorni) importa le fatture Stripe come fatture emesse. Richiede l'add-on SDI e la quota; se la connessione ha l'invio automatico attivo, le fatture vanno anche allo SDI. ## Con un assistente AI [#con-un-assistente-ai] Il [server MCP](/it/api/mcp) ha `list_connections`, `connect_mailbox` (restituisce il link), `scan_mailbox`, `list_collected_documents` e `approve_collected_document`. Le password IMAP non passano mai dall'assistente: collega IMAP nell'app o con l'API. # Drive (https://docs.getbeel.com/it/api/drive) Leggi il Drive dell'azienda per mese o cartella, scarica un file, carica documenti e gestisci le cartelle. Il Drive contiene i documenti dell'azienda come li mostra l'app: i file delle fatture ricevute, gli estratti conto caricati e i documenti caricati, per mese e cartella. Le letture richiedono `drive:read`, le scritture `drive:write` e una chiave live. Il Drive non mostra mai a una chiave più di quanto potrebbe leggere altrove: i file delle fatture ricevute richiedono anche `received_invoices:read`, gli estratti conto `bank:read`. Senza, quei file non compaiono nell'elenco e il download viene rifiutato. ## Elencare un mese o una cartella [#elencare-un-mese-o-una-cartella] ```bash curl "https://www.getbeel.com/api/v1/drive?month=2026-10" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Invia `month` (`2026-10`) oppure `folder` (un percorso da `folders[].path`, come `contratti` o `2026-10/contratti`), uno dei due: un Drive intero può essere molto grande. ```json title="Risposta" { "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` è `invoice` (il file di una fattura ricevuta), `reconciliation` (un estratto conto caricato) o `document`. Le cartelle sono `system` (fatture, riconciliazione), `month` o `custom`; si carica solo nelle cartelle con `writable: true`. ## Scaricare un file [#scaricare-un-file] ```bash curl https://www.getbeel.com/api/v1/drive/files/$FILE_ID/download \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` La risposta ha `download_url`, un link privato valido 15 minuti, ed `expires_at`. Dai il link a chi serve il file; non salvarlo. Un file che non è di questa azienda, o che lo storage rifiuta, risponde `404`. ## Caricare un documento [#caricare-un-documento] ```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` è un mese (la sua cartella si crea se manca), `documents` o una cartella personalizzata esistente. - Invia `file_url` (`https` pubblico) oppure `file_base64` con `file_name`. PDF, PNG, JPEG, DOC o DOCX fino a 25 MB; il tipo si legge dal contenuto. - Il file viene solo archiviato, l'AI non lo legge. Per registrare una fattura fornitore, [caricala come fattura ricevuta](/it/api/received-invoices#caricare-una-fattura). | Stato | `code` | Quando | | ----- | ----------------------- | --------------------------------------------------- | | 404 | `resource_missing` | La cartella non esiste, o è una cartella di sistema | | 413 | `payload_too_large` | Oltre 25 MB | | 415 | `unsupported_file_type` | Non è un PDF, PNG, JPEG, DOC o DOCX | ## Cartelle [#cartelle] ```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" }' ``` - Una cartella va nella radice, o dentro un mese con `month`. Il percorso viene dal nome (`2026-10/contratti`). Un nome a forma di mese è rifiutato, e un nome già usato lì risponde `409 folder_exists`. - `DELETE /drive/folders?path=2026-10/contratti` elimina definitivamente una cartella personalizzata e tutti i suoi file. Le cartelle dei mesi e di sistema non si eliminano. ## Eliminare un file [#eliminare-un-file] ```bash curl -X DELETE https://www.getbeel.com/api/v1/drive/files/$FILE_ID \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Elimina il file definitivamente, come Elimina nell'app. Il file di una fattura ricevuta richiede anche `received_invoices:write` (la fattura resta, senza il file); un estratto conto richiede `bank:write`. Un estratto conto con autofatture che sono, o potrebbero essere, allo SDI è un documento fiscale: non si elimina (`409 statement_has_sent_autofatture`). ## MCP [#mcp] `list_drive`, `get_drive_file`, `upload_drive_file`, `create_drive_folder`, `delete_drive_file`, `delete_drive_folder`. ## Correlati [#correlati] - [Fatture ricevute](/it/api/received-invoices): i file che l'AI legge. - [Riconciliazione bancaria](/it/api/bank-reconciliation): gli estratti conto nella cartella di riconciliazione. - [Autenticazione](/it/api/authentication): gli scope `drive:read` e `drive:write`. # Errori (https://docs.getbeel.com/it/api/errors) La forma degli errori, gli stati HTTP e ogni codice che l'API può restituire, con cosa fare. Ogni errore ha la stessa forma: ```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` indica la categoria. - `code` è stabile: usalo nel codice per decidere cosa fare. - `message` è per le persone e può cambiare. - `param`, quando c'è, indica il campo, il parametro o l'header da correggere. Ogni risposta, anche di successo, ha un header `X-Request-Id` (`req_…`). Indicalo quando contatti il supporto. ## Tipi e stati HTTP [#tipi-e-stati-http] | `type` | Stato | Quando | | ----------------------- | ---------------------------- | ----------------------------------------------------------------- | | `authentication_error` | 401 | Chiave o token mancante, errato, revocato, scaduto o sospeso | | `permission_error` | 402, 403 | Manca uno scope, un piano o la modalità giusta (test o live) | | `invalid_request_error` | 400, 404, 409, 413, 415, 422 | La richiesta non è valida, o non lo è nello stato attuale | | `not_found_error` | 404 | La risorsa non esiste o non appartiene al tuo team | | `rate_limit_error` | 429 | Troppe richieste, vedi [Limiti di richieste](/it/api/rate-limits) | | `api_error` | 500, 502, 503, 504 | Errore nostro o di un servizio esterno: riprova più tardi | Regola generale: correggi i `4xx` prima di ripetere la richiesta (salvo `409` di concorrenza e `429`, indicati sotto); ripeti `5xx` ed errori di rete con un backoff e la stessa [chiave di idempotenza](/it/api/idempotency). ## Codici [#codici] L'elenco viene dal codice dell'API (ogni `ApiError` che un endpoint o uno strumento MCP può restituire). ### Autenticazione e permessi [#autenticazione-e-permessi] | `code` | Stato | Significato | Cosa fare | | ----------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `missing_api_key` | 401 | Manca l'header `Authorization` | Invia `Authorization: Bearer gb_…` | | `invalid_api_key` | 401 | Chiave inesistente o malformata | Controlla la chiave in Impostazioni → Chiavi API e MCP | | `api_key_revoked` | 401 | Chiave revocata, o chi l'ha creata non è più nel team | Crea una nuova chiave | | `api_key_expired` | 401 | Chiave scaduta | Crea una nuova chiave | | `api_key_suspended` | 401 | Chi ha creato la chiave non può più gestire le chiavi | Fai creare la chiave a un membro con quel permesso | | `invalid_token` | 401 | Token OAuth (`gb_oat_…`) scaduto, revocato o non valido | Rinnova con il refresh token; se non basta, ricollega l'app | | `insufficient_scope` | 403 | Manca lo scope richiesto (indicato nel messaggio) | Crea una chiave con quello scope (le chiavi non si modificano) o ricollega l'app | | `insufficient_permissions` | 403 | Chi ha creato la chiave non può aggiungere aziende clienti | Usa la chiave di un membro con quel permesso | | `livemode_required` | 403 | L'operazione cambia dati reali e serve una chiave live | Usa una chiave `gb_live_…` | | `test_mode_required` | 403 | La sandbox di ricezione accetta solo chiavi di test | Usa una chiave `gb_test_…` | | `company_not_eligible` | 403 | Per emettere fatture serve un profilo aziendale italiano | Completa Impostazioni → Azienda | | `invite_not_allowed` | 403 | Chi ha creato la chiave non può invitare un commercialista | Usa la chiave di un membro con quel permesso | | `remove_not_allowed` | 403 | Chi ha creato la chiave non può rimuovere quel commercialista | Come sopra | | `sdi_addon_required` | 402 | Le fatture live (o la sincronizzazione Stripe) richiedono il piano SDI | Attivalo in Impostazioni → Utilizzo e fatturazione (per un'azienda cliente, sull'account principale); in test usa la sandbox | | `sdi_quota_exhausted` | 402 | La quota SDI del mese è finita | Aumenta il piano SDI, o aspetta il mese successivo | | `insufficient_balance` | 402 | Il saldo prepagato non copre l'azione (paghi quanto usi); la risposta è `application/problem+json` con `balance_cents`, `required_cents` e `topup_url` (per un'azienda cliente solo `required_cents`) | Aggiungi credito da `topup_url` (Impostazioni → Fatturazione e utilizzo) o attiva la ricarica automatica | | `no_card` | 409 | Non c'è ancora una carta salvata da cambiare (`POST /billing/payment-method`); `application/problem+json` come `insufficient_balance` | Aggiungi una carta con una ricarica o in Impostazioni → Fatturazione e utilizzo | | `not_pay_as_you_go` | 409 | Consumi, ricariche e carta valgono per gli account che pagano quanto usano | L'account (registrato prima del 13 novembre 2026) mantiene il suo piano: vedi `GET /usage` | | `billing_permission_required` | 403 | Chi ha creato la chiave non può gestire la fatturazione | Usa la chiave di un membro con il permesso di fatturazione | | `billed_to_parent` | 403 | Un'azienda cliente paga dal saldo del gestore (anche saldo e consumi: con la chiave dell'azienda non si leggono) | Aggiungi credito dall'account principale | | `subscription_required` | 402 | Serve il prodotto a pagamento (elaborazione fatture, riconciliazione) | Scegli un piano in Impostazioni → Utilizzo e fatturazione | | `limit_reached` | 402 | Raggiunto il numero di caselle email del piano | Scollega una casella o cambia piano | ### Richiesta [#richiesta] | `code` | Stato | Significato | Cosa fare | | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `parameter_unknown` | 400 | Parametro di query sconosciuto (il messaggio elenca quelli ammessi) o, su `PATCH /invoices/{id}`, campo del corpo sconosciuto | Toglilo o correggine il nome (per esempio `cursor`, non `starting_after`) | | `rate_limit_exceeded` | 429 | Troppe richieste per la chiave | Attendi i secondi di `Retry-After`, poi riprova ([Limiti di richieste](/it/api/rate-limits)) | | `parameter_invalid` | 400 | Un parametro, un campo o un header non è valido (vedi `param`) | Correggi il valore | | `parameter_missing` | 400 | Manca un parametro obbligatorio | Aggiungilo | | `invalid_json` | 400 | Il corpo non è JSON valido | Invia JSON valido con `Content-Type: application/json` | | `invalid_multipart` | 400 | Il corpo multipart non si legge | Invia `multipart/form-data` con il campo `file` | | `file_url_unusable` | 400, 413 | `file_url` non è un link https pubblico che risponde 200 senza redirect, o il file supera 50 MB | Usa un link diretto e pubblico, o carica il file | | `payload_too_large` | 413 | Corpo JSON oltre 1 MB; XML oltre 5 MB (il limite SDI per un file); estratto conto oltre 50 MB; ricevuta oltre 10 MB | Riduci il file | | `file_invalid` | 413 | La ricevuta di un adempimento supera 10 MB | Carica un file più piccolo | | `unsupported_media_type` | 415 | `Content-Type` non supportato | Usa quello indicato nel messaggio | | `unsupported_file_type` | 415 | Tipo di estratto conto non supportato (per esempio un foglio di calcolo) | Carica PDF, CSV, TXT, CBI, CAMT.053 o MT940 | | `resource_missing` | 404 | Nessuna risorsa con quell'id nel tuo team | Controlla l'id (e `Getbeel-Company` o `company_id`) | | `company_not_found` | 404 | L'azienda cliente indicata non esiste o non è più disponibile | Usa un id da `GET /companies` | | `numbering_series_not_found` | 404 | Il sezionale indicato non esiste | Usa un id da `GET /numbering-series` | | `received_invoice_not_found` | 400 | La fattura ricevuta indicata per il cespite non esiste in questa azienda | Usa un id da `GET /received-invoices` | ### Idempotenza e concorrenza [#idempotenza-e-concorrenza] | `code` | Stato | Significato | Cosa fare | | -------------------------- | ----- | --------------------------------------------------------------- | ----------------------------------------------------- | | `idempotency_key_in_use` | 409 | Una richiesta con la stessa `Idempotency-Key` è ancora in corso | Riprova tra qualche secondo con la stessa chiave | | `idempotency_key_reused` | 422 | La chiave è già stata usata per una richiesta diversa | Usa una chiave nuova per una richiesta nuova | | `invoice_send_in_progress` | 409 | Un invio di questa fattura è già in corso | Non ripetere: leggi lo stato con `GET /invoices/{id}` | | `sync_in_progress` | 409 | Un aggiornamento di questa banca è in corso o appena terminato | Riprova tra un minuto | | `filing_conflict` | 409 | L'adempimento è in preparazione in questo momento | Riprova tra qualche secondo | | `reconciliation_conflict` | 409 | L'abbinamento è cambiato nel frattempo | Rileggi la riconciliazione e riprova | ### Fatture emesse e invio allo SDI [#fatture-emesse-e-invio-allo-sdi] | `code` | Stato | Significato | Cosa fare | | -------------------------------- | ----- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invoice_not_draft` | 409 | Solo una bozza si può inviare o modificare: questa è già stata inviata | Non reinviarla: leggi lo stato e l'esito in `sdi` ([ciclo di vita SDI](/it/api/sdi-lifecycle)). Con `PATCH`: una fattura scartata si riapre prima (`POST /invoices/{id}/reopen`), una inviata si corregge con una nota di credito | | `invoice_not_sendable` | 409 | Una fattura proforma non si invia allo SDI | Crea una fattura vera | | `invoice_not_rejected` | 409 | Si può riaprire solo una fattura scartata dallo SDI, e non mentre una correzione automatica è in corso | Controlla lo stato: una fattura `delivered`, `not_delivered` o con `00404` è emessa e non si riapre. Una `draft` si modifica così com'è (`PATCH`); una consegnata si corregge con una nota di credito | | `invoice_invalid` | 422 | La fattura non passa i controlli locali (XML FatturaPA o regole della nota di credito) | Correggi quanto indicato nel messaggio | | `invoice_number_taken` | 409 | Esiste già una fattura con questo numero | Ometti il numero (getbeel assegna il successivo) o scegline uno libero | | `invoice_number_out_of_sequence` | 422 | Il numero salterebbe avanti nella numerazione | Usa il prossimo numero o uno che colma un buco | | `company_profile_incomplete` | 422 | Il profilo aziendale non ha i dati per emettere (nome, partita IVA o codice fiscale…) | Completa Impostazioni → Azienda | | `credit_exceeds_invoice` | 422 | La nota di credito supera quanto resta da accreditare sulla fattura | Riduci le righe | | `invoice_not_issued` | 409 | Serve una fattura accettata dallo SDI (per una nota di credito, un pagamento, un link) | Aspetta l'esito, o scegli un'altra fattura | | `invoice_not_creditable` | 409 | Questa fattura non si può accreditare (proforma o nota di credito) | Scegli la fattura originale | | `sdi_send_failed` | 502 | L'invio non è partito: la fattura resta in bozza | Riprova più tardi | | `internal_error` | 500 | Errore interno (per esempio creazione della fattura non riuscita) | Riprova; se persiste, contatta il supporto con `X-Request-Id` | Uno **scarto dello SDI** non è un errore dell'API: l'invio va a buon fine, poi lo SDI risponde. Vedi sotto. ### Preventivi, sezionali e incasso [#preventivi-sezionali-e-incasso] | `code` | Stato | Significato | Cosa fare | | -------------------------- | ----- | --------------------------------------------------------------------- | ------------------------------------------- | | `quote_not_editable` | 409 | Il preventivo non è più modificabile | Creane uno nuovo | | `quote_converted` | 409 | Il preventivo è già diventato fattura | Usa la fattura creata | | `quote_invalid` | 422 | Il preventivo non è valido | Correggi quanto indicato | | `numbering_series_exists` | 409 | Esiste già un sezionale con questo prefisso o suffisso | Scegline un altro | | `numbering_series_in_use` | 409 | Il sezionale ha fatture e non si può cambiare o eliminare | Creane uno nuovo | | `numbering_series_invalid` | 422 | Il sezionale non è valido | Correggi quanto indicato | | `natura_required` | 422 | Un articolo con IVA 0% non ha la `natura` (SdI la scarterebbe: 00400) | Indica la `natura` (N1–N7) o un'aliquota | | `customer_email_missing` | 422 | Il cliente non ha un indirizzo email | Passa `to` o aggiungi l'email al cliente | | `email_failed` | 502 | L'email non è partita | Riprova più tardi | | `invoice_already_paid` | 409 | La fattura è già pagata | Nessuna azione | | `amount_exceeds_balance` | 422 | Il pagamento supera il dovuto | Riduci l'importo | | `invoice_pdf_missing` | 409 | Il PDF della fattura non è ancora pronto | Riprova tra poco | | `invoice_not_copyable` | 422 | La fattura non si può ripetere (per esempio una nota di credito) | Usa una fattura ordinaria | | `recurring_invoice_exists` | 409 | Questa fattura ha già una ripetizione | Modifica quella esistente | | `stripe_not_connected` | 409 | Nessun collegamento Stripe attivo | Collega Stripe (`POST /connections/stripe`) | | `stripe_mode_mismatch` | 409 | Il collegamento Stripe è in un'altra modalità (test o live) | Usa la chiave della stessa modalità | | `stripe_error` | 502 | Errore di Stripe | Riprova più tardi | ### Banca, connessioni e documenti [#banca-connessioni-e-documenti] | `code` | Stato | Significato | Cosa fare | | ------------------------------------ | -------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `bank_connection_inactive` | 409 | Il collegamento non è attivo | Completa l'accesso alla banca o ricollegala | | `bank_connection_requires_reconnect` | 409 | Il consenso è scaduto o revocato | Ricollega la banca | | `bank_connection_conflict` | 409 | Il collegamento è cambiato nel frattempo | Rileggi e riprova | | `bank_connection_limit` | 409 | Raggiunto il numero massimo di banche collegate | Scollegane una | | `bank_credentials_invalid` | 422 | Credenziali dell'app Enable Banking non valide | Controlla le credenziali | | `redirect_url_not_allowed` | 422 | L'URL di ritorno non è ammesso | Usa un URL https consentito | | `bank_daily_limit` | 429 | La banca ammette circa quattro aggiornamenti al giorno, esauriti | getbeel riprova da solo più tardi | | `bank_error`, `bank_sync_failed` | 502 | Errore della banca o di Enable Banking | getbeel riprova; riprova più tardi | | `bank_unavailable` | 503 | Servizio bancario non disponibile | Riprova più tardi | | `connection_not_scannable` | 409 | La casella non si può scansionare ora | Leggi il messaggio (collegamento scaduto, scansione in corso) | | `reconnect_required` | 409 | Autorizzazione della casella scaduta o revocata; nessuna scansione creata | Ricollega la casella nell'app, poi scansiona di nuovo | | `imap_connect_failed` | 422 | Connessione IMAP non riuscita | Controlla email, password, server e porta (993) | | `rate_limited` | 429 | Troppi tentativi di collegamento IMAP | Riprova più tardi | | `unavailable` | 503 | Funzione non disponibile su questa installazione, o servizio esterno non raggiungibile | Riprova più tardi | | `internal` | 500 | Errore interno nel collegamento IMAP | Riprova; contatta il supporto con `X-Request-Id` | | `invoice_not_reviewable` | 409 | Il documento raccolto non è in attesa di verifica | Nessuna azione | | `workflow_unavailable` | 503 | L'elaborazione in background non è disponibile | Riprova più tardi | | `storage_error` | 500, 503 | Il file non è stato salvato | Riprova | | `file_url_unreachable` | 502, 504 | Non è stato possibile scaricare `file_url` | Riprova o carica il file | | `file_empty` | 400 | Il file inviato è vuoto | Invia di nuovo il file | | `credits_exhausted` | 402 | Crediti fattura esauriti per il caricamento | Acquista un pacchetto o cambia piano in Utilizzo e fatturazione | | `processing_unavailable` | 503 | Il caricamento non è riuscito ad avviare la lettura del file | Riprova | | `default_category` | 409 | Una categoria predefinita non si elimina | Elimina un'altra categoria, o rinomina questa | | `unknown_category` | 422 | Non è una categoria di questo team | Usa uno slug da `GET /categories` | | `folder_exists` | 409 | Lì esiste già una cartella del Drive con quel nome | Scegli un altro nome | | `folder_too_large` | 503 | La cartella del Drive ha troppi file da eliminare in una volta | Riprova: ogni chiamata ne elimina altri | | `statement_has_sent_autofatture` | 409 | L'estratto conto contiene autofatture allo SDI: è un documento fiscale | Conservalo; non si può eliminare | ### Ricezione SDI e aziende clienti [#ricezione-sdi-e-aziende-clienti] | `code` | Stato | Significato | Cosa fare | | ----------------------------- | ----- | --------------------------------------------------------- | -------------------------------------------------- | | `company_not_ready` | 422 | L'azienda non ha ancora i dati per ricevere dallo SDI | Completa i passaggi in `GET /sdi-receiving` | | `fiscal_id_taken` | 409 | La partita IVA è già configurata per la ricezione altrove | Contatta il supporto | | `invoice_unreadable` | 422 | L'XML di prova non si legge | Correggi l'XML (per esempio la data del documento) | | `sdi_provider_unavailable` | 502 | Il canale di ricezione non risponde | Riprova più tardi | | `company_nesting_not_allowed` | 409 | Un'azienda cliente non può avere aziende clienti | Usa la chiave dell'account principale | | `already_member` | 409 | La persona fa già parte del team | Nessuna azione | | `already_invited` | 409 | Esiste già un invito per un altro ruolo | Revoca l'invito nell'app | ### Adempimenti, IVA, ritenute, cespiti, POS–RT [#adempimenti-iva-ritenute-cespiti-posrt] | `code` | Stato | Significato | Cosa fare | | ---------------------------- | -------- | ---------------------------------------------------------------------- | -------------------------------------------------- | | `taxes_not_available` | 400 | Le imposte sono disponibili solo per aziende italiane | Imposta il paese Italia nel profilo | | `vat_not_applicable` | 400 | Regime senza IVA (forfettario o minimi) | Nessun registro o liquidazione IVA da preparare | | `settings_missing` | 400 | Manca la periodicità IVA (mensile o trimestrale) | Impostala in Imposte → Impostazioni | | `settlements_missing` | 400 | Mancano le liquidazioni salvate del trimestre per la LIPE | Salva prima le liquidazioni indicate | | `period_not_closed` | 400 | Il periodo non è finito | Prepara l'adempimento dopo la fine del periodo | | `period_not_started` | 400 | Il mese non è ancora iniziato | Scegli un periodo iniziato | | `nothing_due` | 422 | Nel periodo non c'è niente da versare | Nessun F24 da preparare | | `filing_completed` | 409 | L'adempimento è già pagato o inviato e non cambia più | Nessuna azione | | `file_missing` | 400 | La ricevuta non è stata caricata | Ripeti il caricamento | | `file_invalid` | 500 | Il file LIPE generato non passa il controllo XSD ufficiale | Contatta il supporto con `X-Request-Id` | | `too_many_documents` | 400, 422 | Troppi documenti nel periodo per calcolarlo qui | Scegli un periodo più breve o contatta il supporto | | `withholding_exists` | 409 | La fattura ricevuta ha già una ritenuta | Aggiorna quella | | `withholding_remitted` | 409 | La ritenuta è già stata versata con un F24 | Non si può più cambiare né eliminare | | `withholding_unpaid` | 400 | Manca il giorno del pagamento del compenso (`paid_on`) | Registralo prima | | `no_paid_filing` | 409 | Nessun F24 delle ritenute pagato per il periodo | Preparalo e carica la quietanza | | `coefficient_above_maximum` | 400 | Coefficiente oltre il massimo ministeriale (art. 102 c. 2 TUIR) | Usa al massimo il coefficiente indicato | | `not_a_small_asset` | 400 | Deduzione integrale solo per beni fino a 516,46 € (art. 102 c. 5 TUIR) | Ammortizza il bene | | `disposal_incomplete` | 400 | Serve sia `disposal_date` sia `disposal_amount` | Passali entrambi o nessuno | | `in_service_before_purchase` | 400 | Entrata in funzione prima dell'acquisto | Correggi le date | | `too_many_assets` | 400 | Raggiunto il numero massimo di cespiti | Contatta il supporto | | `pos_rt_link_exists` | 409 | Questo POS è già collegato a questo RT | Usa il collegamento esistente | | `terminal_id_required` | 400 | Un POS fisico (`pos_type` `00`) richiede il suo `terminal_id` | Aggiungilo, o usa `01` per un POS virtuale | | `link_already_filed` | 409 | Il collegamento è già stato comunicato all'Agenzia | Chiudilo (`ended_on`) e aggiungine uno nuovo | | `too_many_links` | 400 | Raggiunto il numero massimo di collegamenti POS–RT | Chiudi quelli non più in uso | Gli errori dell'[idempotenza](/it/api/idempotency) sono descritti anche in quella pagina. ## Scarti dello SDI [#scarti-dello-sdi] Uno scarto dello SDI non è un errore dell'API: la richiesta di invio va a buon fine, poi lo SDI risponde con una ricevuta di scarto. La fattura passa a `rejected`, ricevi il webhook `invoice.rejected` e i codici sono in `sdi.errors` (codice e descrizione) e `sdi.error_codes`. Cosa significano e come correggerli: [Codici di scarto SDI](/it/api/reference-data/sdi-errors). Eccezione: `00404` su una fattura già inviata significa che lo SDI ha già una copia accettata. La fattura **è emessa**, non diventa `rejected` e non va reinviata. Vedi [ciclo di vita SDI](/it/api/sdi-lifecycle). ## Errori negli strumenti MCP [#errori-negli-strumenti-mcp] Gli strumenti MCP restituiscono gli stessi errori come risultato con `isError: true`, con il corpo `{ "error": { … } }` nel testo. Gli argomenti sconosciuti o non validi sono rifiutati prima, con un messaggio `Input validation error: …` che dice cosa correggere: vedi [Server MCP](/it/api/mcp#argomenti-rigorosi). In modalità ricerca, `call_tool` può rispondere `tool_not_found` e `tool_not_read_only`. # Adempimenti (F24, LIPE, dichiarazione IVA) (https://docs.getbeel.com/it/api/filings) Prepara l'F24 dell'imposta di bollo, delle ritenute o dell'IVA, il file della LIPE o i dati della dichiarazione IVA annuale, con i valori da copiare, il link alla pagina dell'Agenzia delle Entrate e le bozze email, poi registra la quietanza. Un adempimento (`filing`) è un pagamento preparato da Getbeel per una [scadenza](/it/api/taxes): l'importo, le righe dell'F24, un PDF promemoria e i passi successivi. Il pagamento lo fai tu, in F24 web o dalla banca; poi carichi la quietanza e l'adempimento risulta pagato. Scope: `taxes:read` per leggere, `taxes:write` per preparare e caricare la quietanza. Le scadenze fiscali sono dati reali: non c'è una sandbox. Le chiavi di test possono leggere; preparare e caricare richiede una chiave live (`403 livemode_required`). Preparare è gratis; l'adempimento si paga una volta, quando è pagato o inviato (`402 insufficient_balance` se il saldo non basta). ## Cosa prepara Getbeel (v1) [#cosa-prepara-getbeel-v1] | `type` | Periodo | Importo | | -------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bollo` | Trimestre (`2026-Q3`) | Calcolato da Getbeel: 2 € per fattura emessa con bollo virtuale, o senza ma con bollo dovuto (vedi sotto) | | `withholdings` | Mese (`2026-10`) | La somma delle [ritenute](/it/api/withholdings) sui compensi pagati nel mese (cod. 1040), o `amount` se non li registri in Getbeel | | `vat_payment` | Mese o trimestre, come l'azienda liquida l'IVA | La liquidazione IVA calcolata dai [registri IVA](/it/api/vat-registers) e salvata (codici tributo 6001–6012, 6031–6033) | | `lipe` | Trimestre (`2026-Q3`) | Nessun pagamento: il file XML della Comunicazione liquidazioni periodiche IVA, dalle liquidazioni salvate del trimestre, controllato con lo schema XSD ufficiale | | `vat_return` | Anno (`2026`), quando è finito | Il prospetto dei dati della dichiarazione IVA annuale: `amount` è il saldo da versare (VX1, codice tributo 6099). Non è il file da inviare | | `redditi_pf` | Anno (`2026`), quando è finito | Solo persone fisiche: il prospetto del Modello Redditi PF dalla [stima delle imposte](/it/api/tax-tools) dell'anno: `amount` è il saldo dell'anno. Non è il file da inviare | Per il bollo Getbeel segue le regole dell'Agenzia delle Entrate per gli elenchi del trimestre: - **Elenco A**: fatture inviate con bollo virtuale. - **Elenco B**: fatture senza bollo virtuale ma con righe esenti o non imponibili (Natura N2.1, N2.2, N3.5, N3.6, N4) per più di 77,47 € in totale: il bollo è dovuto sulla parte non soggetta a IVA. L'Agenzia le addebita comunque: Getbeel le conta e te le segnala (`invoices_without_bollo_flag`, `needs_review`). Se una non lo richiede, toglila dall'elenco nel portale "Fatture e corrispettivi". - Il trimestre è quello della consegna SDI. Le fatture ancora in attesa di esito sono in `pending_invoices` e non sono contate. - Importi piccoli: il bollo del 1° trimestre sotto i 5.000 € si può pagare entro il 30 settembre, e 1° + 2° sotto i 5.000 € entro il 30 novembre (`deferral`). Getbeel mantiene la scadenza normale e te lo segnala soltanto. Non sono contate le fatture emesse fuori da Getbeel, quelle cartacee e le autofatture. ## Preparare un F24 [#preparare-un-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" }' ``` Per le ritenute Getbeel somma i compensi registrati in [`/withholdings`](/it/api/withholdings) con `paid_on` nel mese (la ritenuta si opera al pagamento, art. 25 DPR 600/1973) e li elenca in `details.withholdings`; quando carichi la quietanza quei compensi risultano versati e non si possono più modificare. Se non li registri in Getbeel invia `amount` con il totale trattenuto. Senza compensi né `amount` la risposta è `422 nothing_due`. Risposta `201` con l'adempimento in stato `ready` (webhook `filing.ready`). Chiamare di nuovo per lo stesso periodo lo ricalcola finché non è pagato; dopo risponde `409 filing_completed`. Il bollo si prepara solo a trimestre chiuso (`period_not_closed`) e se c'è qualcosa da pagare (`nothing_due`). Anche `vat_payment` e `lipe` si preparano a periodo chiuso. `vat_payment` salva la liquidazione anche quando non c'è niente da pagare (credito, importo fino a 100 € rinviato, 4° trimestre dei trimestrali) e risponde `422 nothing_due`; `lipe` risponde `400 settlements_missing` finché non sono salvate tutte le liquidazioni del trimestre, e le società indicano `declarant_fiscal_code` e `declarant_role`. I dati in ingresso e le regole sono in [Registri IVA e liquidazioni](/it/api/vat-registers). ## LIPE: il controllo dello schema [#lipe-il-controllo-dello-schema] Quando prepara una `lipe`, Getbeel valida l'XML con lo schema ufficiale IVP18 dell'Agenzia delle Entrate ("Specifiche IVP2018_SchemaIV18.zip", schema versione 1.0, dalla [pagina delle specifiche tecniche](https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/liquidazioni-periodiche-iva/st-comunicazione-delle-liquidazioni-periodiche-iva); il provvedimento del 14 marzo 2024 non lo ha cambiato). Il risultato è in `checks.xsd`. Un file che non passa non viene mai salvato: la risposta è `500 file_invalid` (un errore di Getbeel, segnalacelo). `checks.ade_control_software` è sempre `not_run`. Il software di controllo dell'Agenzia ("Software di controllo Liquidazioni periodiche Iva" per la LIPE, la "procedura di controllo" per la dichiarazione IVA) è un programma Java desktop, avviato con Java Web Start, che si aggiorna a ogni avvio. Non ha una modalità da riga di comando documentata, e l'Agenzia non pubblica un servizio che controlli un file senza l'accesso del contribuente, né condizioni che permettano di usarlo come servizio per altri. Getbeel quindi non può eseguirlo per te in modo onesto: controlla ciò che può (lo schema per la LIPE; le regole aritmetiche delle specifiche per la dichiarazione IVA, sotto) e i passi ti dicono di usare il software di controllo prima dell'invio. ## Dichiarazione IVA [#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 somma i [registri IVA](/it/api/vat-registers) di ogni periodo di liquidazione dell'anno (12 mesi o 4 trimestri), le liquidazioni salvate e gli F24 IVA segnati come pagati, e restituisce i righi della dichiarazione in `details.vat_return`, in unità di euro come in dichiarazione, con il codice del campo delle specifiche tecniche (`VE023001` = quadro VE, rigo 23, campo 1). `previous_year_credit` è il credito della dichiarazione dell'anno scorso ancora disponibile (VX5 meno quanto già compensato): va nel rigo VL25. Scarica il prospetto con `GET /filings/{id}/file?format=csv|xlsx|json` (CSV se non indichi nulla). **Non è il file da inviare.** La dichiarazione telematica è un file a record di lunghezza fissa (record A, B, D, Z di 1.900 caratteri) con molte parti che Getbeel non conosce (frontespizio, VA, VC, VO, VT, firme). Compilala con il "Software di compilazione Iva" gratuito dell'Agenzia o con il software del commercialista, controllala con la procedura di controllo e inviala dalla tua area riservata o tramite un intermediario, tra il 1° febbraio e il 30 aprile (art. 8 DPR 322/1998). Il saldo si versa entro il 16 marzo con il codice tributo 6099. | Quadro | Righi compilati da Getbeel | Da dove | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | VE | VE20–VE23 per aliquota (4, 5, 10, 22%), VE24–VE26, VE30–VE35 per natura, VE37 (IVA esigibile negli anni successivi), VE38 (split payment), VE39, VE50 (volume d'affari) | Registro vendite | | VF | VF2, VF3, VF11, VF13 per aliquota, VF18, VF25–VF27, VF71 (IVA ammessa in detrazione) | Registro acquisti e autofatture | | VJ | VJ1 (TD28), VJ3 (TD17, TD19), VJ9 (TD18), VJ19 | Autofatture (reverse charge) | | VL | VL1–VL4, VL23, VL25, VL30 (campi 1–3), VL32, VL33, VL36, VL38, VL39 | Quanto sopra, liquidazioni salvate, F24 pagati | | VX | VX1 (da versare, non sotto 10,33 €), VX2 (a credito) | VL38, VL39 | La colonna 2 di VE20–VE23 e VF2–VF13 è l'aliquota per la colonna 1, come chiedono le specifiche; la differenza con l'IVA dei registri va in VE25 e VF26. `details.vat_return.checks` elenca i controlli delle specifiche che Getbeel esegue sul prospetto (tornano per costruzione; se uno fallisce è un errore di Getbeel). Quando carichi la ricevuta la dichiarazione passa a `filed`, e da quel momento `vat_payment` e `lipe` di quell'anno rispondono `409 filing_completed`: una modifica dopo l'invio è una dichiarazione integrativa, per il commercialista. Le vendite con IVA rettificata nei registri contano con l'IVA rettificata, come nelle liquidazioni (la differenza va in VE25). L'IVA del reverse charge interno (TD16) è nel totale VJ19 e nel saldo; il rigo lo scegli tu. `details.vat_return.issues` elenca cosa controllare prima di copiare: documenti che mancano nei registri, operazioni senza un solo rigo (natura N2.2, N5, N7, acquisti senza IVA), reverse charge interno (TD16) il cui rigo VJ dipende dal caso, fornitori esteri senza autofattura, IVA indetraibile (va in VF21/VF22, Getbeel la lascia in VF1–VF13), liquidazioni non salvate, l'acconto IVA pagato fuori da Getbeel. **Quale modello.** A novembre 2026 il modello per l'anno d'imposta 2026 ("IVA 2027") non è pubblicato, nemmeno in bozza. I righi seguono l'ultimo, "IVA 2026, periodo d'imposta 2025", approvato con provvedimento prot. 51732 del 15 gennaio 2026 ([modello e istruzioni](https://www.agenziaentrate.gov.it/portale/iva-2026/modello-e-istruzioni)), con le specifiche tecniche del provvedimento prot. 50925 dell'11 febbraio 2026. `details.vat_return.model` dice quale; il prospetto passerà al modello 2027 quando sarà pubblicato. **Non da una fonte ufficiale** (lettura di Getbeel, da verificare con il commercialista): in quale rigo va ogni codice natura (N2.1 → VE34, N3.1–N3.4 → VE30 campi 2–5, N3.5 → VE31, N3.6 → VE32, N4 → VE33, N6.1–N6.8 → VE35 campi 2–9, N6.9 → VE35 campo 1), in quale rigo VJ va ogni tipo di autofattura, e le operazioni in split payment solo in VE38 (letto dalla formula di VE50, che altrimenti le conterebbe due volte). Le istruzioni non nominano i codici FatturaPA. ## Redditi PF (persone fisiche) [#redditi-pf-persone-fisiche] Per una persona fisica la cui [stima delle imposte](/it/api/tax-tools) dell'anno è `forfettario`, `irpef` o `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` mette la stima sui righi del Modello Redditi PF 2026 (anno d'imposta 2025), come nelle istruzioni dell'Agenzia (Fascicoli 1–3): | Regime | Righi | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `forfettario` | LM22 col. 3 ricavi, LM34 col. 3 reddito, LM35 col. 2 contributi, LM38 imponibile, LM39 imposta sostitutiva | | `minimi` | LM2, LM5 col. 5, LM6, LM7 col. 2, LM49, LM9 col. 3, LM10, LM11 (5%) | | `irpef` | RE21 col. 5 reddito (un'impresa usa il quadro RG: nessun 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 e commercianti lo dividono nei righi RR2/RR3, quindi `rigo` è `null` | - `rigo: null` vuol dire che la voce non sta in un solo rigo: l'importo è mostrato con il suo significato. - `payments` elenca saldo e acconti con i codici tributo F24; `amount` è il saldo dell'anno. - È una stima: altri redditi, familiari e oneri non sono in Getbeel. `GET /filings/{id}/file?format=csv|json` scarica il prospetto. - Una società riceve `400 redditi_pf_not_applicable`. - Si completa come **presentata** con la ricevuta dell'Agenzia o il numero di protocollo (addebitata una volta, vedi Prezzi). ## Quale specifica segue ogni file [#quale-specifica-segue-ogni-file] Ogni adempimento preparato conserva la specifica ufficiale che segue il suo file, in `file_spec` (anche nell'header `Getbeel-File-Spec` di `GET /v1/filings/{id}/file`, e in MCP `get_filing_file`): | `file_spec.id` | File | Documento ufficiale | Formato ufficiale | | -------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------ | | `lipe:IVP18` | XML della LIPE | Specifiche tecniche e XSD IVP18 (Versione 1.0), provv. AdE prot. 125654 del 14 marzo 2024 | sì | | `vat_return:IVA2026` | Prospetto della dichiarazione IVA | Modello IVA 2026 (anno d'imposta 2025), provv. AdE prot. 51732 del 15 gennaio 2026 | no: i righi da riportare | | `redditi_pf:PF2026` | Prospetto Redditi PF | Modello Redditi PF 2026 (anno d'imposta 2025), provv. AdE prot. 72078 del 27 febbraio 2026 | no: i righi da riportare | | `f24:F24-2013` | Promemoria F24 (bollo, ritenute, IVA) | Modello "MOD. F24 – 2013 EURO", provv. AdE del 19 giugno 2013 | no: un promemoria | `file_spec` riporta anche nome, versione, l'atto che l'ha approvata, la pagina ufficiale (`source_url`) `other_tax_year` (una dichiarazione sul modello di un altro anno d'imposta: verifica i righi con il modello di quell'anno) e `provisional` (è il modello precedente perché il nuovo non è ancora pubblicato: da verificare quando esce). L'id si salva quando l'adempimento viene preparato; un file si genera solo su quella specifica, mai su un'altra versione: quando Getbeel passa a una nuova continua a generare la vecchia per gli adempimenti che la usano, e una specifica che non genera più risponde `409 file_spec_outdated`. Un adempimento saltato prima di essere preparato non ha file: `file_spec` è `null` e il file risponde `409 filing_file_missing`. ## I passi successivi [#i-passi-successivi] `GET /filings/{id}` restituisce `f24_lines` (sezione Erario: codice tributo, mese e anno di riferimento, importo) e `next_steps`: | Campo | Cosa | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `file_url` | Il PDF promemoria F24 (`GET /filings/{id}/file`): i valori da inserire, non il modello ministeriale; per una `lipe`, il file XML | | `deep_link` | La pagina dell'Agenzia da aprire: "Fatture e corrispettivi" per il bollo, l'area riservata (F24 web) per le ritenute. Accedi tu con SPID, CIE o CNS | | `copy_values` | I valori da copiare uno per uno: codice fiscale, codice tributo, anno, importo, saldo | | `drafts` | Bozze email (in italiano) per la banca o il commercialista. Getbeel non le invia: le rivedi e le mandi tu | | `steps` | I passi, in ordine | ## Registrare la quietanza [#registrare-la-quietanza] Dopo il pagamento carica la quietanza (PDF, PNG o JPEG, fino a 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" ``` L'adempimento passa a `paid`; una LIPE o una dichiarazione IVA, con la ricevuta dell'Agenzia, passa a `filed` (webhook `filing.filed`). La quietanza viene conservata, non letta: controlla di caricare quella giusta. ## Niente file CBI F24, per ora [#niente-file-cbi-f24-per-ora] Le aziende con il corporate banking possono importare gli F24 come file CBI. Getbeel non lo produce: lo standard CBI "Pagamenti F24" (CBI-F24-001) è distribuito solo agli utenti registrati su [cbi-org.eu](https://www.cbi-org.eu/Servizi/Standard), con la policy IPR del CBI, e l'unica copia pubblica trovata è un mirror di terzi non aggiornato (versione 6.15 del 2015). Il file richiede anche il codice SIA della tua azienda e un servizio F24 concordato con la banca. Finché Getbeel non lo costruisce dalla versione distribuita dal CBI, usa i valori da copiare, il promemoria PDF o la bozza email per la banca. ## Revisione con il commercialista [#revisione-con-il-commercialista] Invita il commercialista (POST /v1/advisors o **Tasse → Il tuo commercialista**): da quel momento ogni adempimento preparato parte da `needs_review`. Il commercialista lo apre nell'app e lo approva (`approved`, con chi e quando), lo rimanda indietro (`changes_requested`, con un commento) o lo segna da non fare (`skipped`, con il motivo). Senza commercialista un adempimento preparato è `ready`. | Stato | Significato | | ------------------- | --------------------------------------------------------------------------- | | `ready` | Preparato, nessuna revisione richiesta | | `needs_review` | Aspetta il commercialista | | `changes_requested` | Rimandato indietro: vedi la cronologia | | `approved` | Approvato: `approved_at`, `approved_by` | | `skipped` | Da non fare: `skip_reason`; mai preparato in automatico, mai addebitato | | `filed` | LIPE o dichiarazione IVA inviata: ricevuta o `filed_reference` (protocollo) | | `paid` | F24 pagato: la quietanza | - `POST /v1/filings/{id}/status` con `status` `approved`, `skipped`, `needs_review` (di nuovo in revisione, o riapre un adempimento saltato) o `filed` (con `reference`). Una chiave API agisce come il team: `changes_requested` è del commercialista, nell'app. - `POST /v1/filings/skip` con `type`, `period` e `reason` per una scadenza mai preparata. - `GET /v1/filings/{id}/events` è la cronologia (commenti e cambi di stato, chi e perché); `POST` aggiunge un commento. - Con **approvazione del commercialista obbligatoria** (impostazione `require_accountant_approval`, decisa da un titolare) solo il commercialista approva, e ricevuta o protocollo aspettano l'approvazione (`409 approval_required`). Ogni passaggio compare anche nelle notifiche dell'app e arriva per email: - un adempimento da rivedere (quando viene preparato, o quando attivi l'approvazione del commercialista) → il commercialista; - modifiche richieste, con il commento intero → i titolari e chi ha preparato l'adempimento; - approvato dal commercialista → i titolari; - con l'approvazione del commercialista obbligatoria, un adempimento che scade entro 5 giorni lavorativi e non è ancora approvato (da rivedere, o rimandato con modifiche) → il commercialista e i titolari, una volta per adempimento e scadenza (di nuovo solo se una proroga sposta la data). Ogni email è nella lingua di chi la riceve, porta all'adempimento e non va mai a chi ha fatto il cambiamento. Un'approvazione di un membro del team e un "da non fare" restano solo nell'app. Webhook: `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`. ## Con un assistente AI (MCP) [#con-un-assistente-ai-mcp] `get_tax_calendar`, `prepare_filing`, `get_filing_next_steps`, `record_filing_receipt`, `get_vat_position`, `get_vat_registers`, `get_vat_settlement` e `ask_accountant_question` (i dati dell'azienda per una domanda fiscale, le fonti ufficiali e se serve il commercialista: Getbeel non scrive la risposta, la scrive l'assistente da quei dati). L'assistente chiede conferma prima di preparare un F24 o registrare una quietanza, e non paga né invia nulla. Vedi [Server MCP](/it/api/mcp). # Idempotenza (https://docs.getbeel.com/it/api/idempotency) Ripeti in sicurezza le richieste che creano o inviano fatture con l'header Idempotency-Key. Una rete instabile può farti perdere la risposta a una richiesta andata a buon fine. Se la ripeti senza protezione rischi di creare due bozze o, peggio, di inviare due volte la stessa fattura. L'header `Idempotency-Key` lo evita. ## Come funziona [#come-funziona] Manda un valore unico (consigliamo un UUID v4) nell'header `Idempotency-Key` di ogni `POST` che crea o invia: ```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" ``` - La prima richiesta con una chiave viene eseguita e la risposta viene memorizzata per **24 ore**. - Se ripeti la stessa richiesta con la stessa chiave, ricevi la risposta memorizzata e l'operazione non viene ripetuta. - Se riusi la chiave per una richiesta diversa (altro endpoint o altro corpo), ricevi un errore invece di una risposta sbagliata. Si applica a `POST /invoices` e `POST /invoices/{id}/send`. ## Buone pratiche [#buone-pratiche] - Genera la chiave quando decidi di fare l'operazione e salvala insieme all'operazione, così un nuovo tentativo dopo un crash usa la stessa. - Usa una chiave nuova per ogni operazione diversa: due fatture, due chiavi. - Ritenta solo errori di rete, `429` e `5xx`. Un `4xx` va corretto, non ripetuto. Gli errori: `409 idempotency_key_in_use` (una richiesta con la stessa chiave è ancora in corso: riprova tra poco con la stessa chiave), `422 idempotency_key_reused` (chiave già usata per una richiesta diversa: usane una nuova), `400 parameter_invalid` con `param: "Idempotency-Key"` (la chiave deve avere da 1 a 255 caratteri ASCII visibili). Vedi [Errori](/it/api/errors). Anche senza chiave, una bozza si invia una volta sola: un secondo invio riceve `409 invoice_send_in_progress` o `409 invoice_not_draft` prima di qualsiasi chiamata allo SDI. Vedi [ciclo di vita SDI](/it/api/sdi-lifecycle#inviare-due-volte-non-crea-un-duplicato). # Introduzione (https://docs.getbeel.com/it/api) L'API REST e il server MCP di Getbeel per la fatturazione elettronica italiana. Getbeel ti permette di creare, validare e inviare fatture elettroniche (FatturaPA) allo SDI, di leggere le fatture emesse e ricevute e di seguire ogni ricevuta SDI con i webhook. Le stesse operazioni sono disponibili come strumenti MCP per gli agenti AI. ## Come è fatta [#come-è-fatta] - **REST e JSON.** Campi in `snake_case`, date ISO 8601, importi come stringhe decimali (`"122.00"`) per evitare errori di arrotondamento. - **I termini fiscali restano in italiano**: `codice_destinatario`, `tipo_documento`, `natura`, `regime_fiscale`. Tutto il resto è in inglese. - **Chiavi di test e live.** Le chiavi `gb_test_…` usano la [sandbox](/it/api/sandbox), che simula lo SDI; le chiavi `gb_live_…` trasmettono davvero. Gli endpoint sono gli stessi. - **Un'API, un server MCP.** Il [server MCP](/it/api/mcp) usa le stesse chiavi e gli stessi servizi dell'API. ## URL di base [#url-di-base] ```text https://www.getbeel.com/api/v1 ``` L'API sarà servita anche su `https://api.getbeel.com/v1`. L'URL attuale continuerà a funzionare. ## Cosa puoi fare oggi [#cosa-puoi-fare-oggi] | Endpoint | Cosa fa | | -------------------------- | --------------------------------------------------------------- | | `GET /me` | L'account, l'azienda e la chiave che fa la richiesta | | `GET /invoices` | Elenco delle fatture emesse | | `GET /invoices/{id}` | Una fattura emessa, con le righe | | `POST /invoices` | Crea una bozza di fattura | | `POST /invoices/{id}/send` | Invia la bozza allo SDI (o alla sandbox con una chiave di test) | | `POST /invoices/validate` | Controlla un XML FatturaPA senza inviarlo | | `GET /received-invoices` | Elenco delle fatture ricevute dai fornitori | Tutti i dettagli, con il playground, sono nel [riferimento API](/it/api/reference). I webhook sono descritti in [Webhook](/it/api/webhooks). Aziende multiple (`companies`), fatture ricevute via SDI sul codice destinatario di Getbeel, PDF e XML delle fatture, contatti, riconciliazione bancaria, SDK e CLI. Le pagine di questa documentazione si aggiornano quando escono. ## Prossimi passi [#prossimi-passi] # Email, pagamenti e solleciti (https://docs.getbeel.com/it/api/invoice-collection) Invia la fattura al cliente, registra i pagamenti, crea un link di pagamento Stripe e manda i solleciti. Dopo l'invio allo SDI la fattura va incassata. L'API fa le stesse cose della scheda **Incasso** di una fattura emessa nell'app: email al cliente, pagamenti, link di pagamento e solleciti. Tutti gli endpoint usano lo scope `invoices:write` (le letture `invoices:read`). Si possono inviare via email, segnare come pagate e sollecitare le fatture accettate dallo SDI (`sent`, `delivered`, `not_delivered`) e le proforma. Le bozze e le fatture scartate rispondono `409 invoice_not_issued`. Le note di credito (TD04) si possono inviare via email ma non si incassano: niente pagamenti, link o solleciti. Con una chiave `gb_test_` lavori sulle fatture sandbox e **le email non arrivano mai al cliente**: vanno solo all'indirizzo del titolare del team, con un avviso in testa e `[TEST]` nell'oggetto. Nella risposta `sandbox` è `true` e `sent_to` mostra dove è andata davvero. ## Invia la fattura al cliente [#invia-la-fattura-al-cliente] ```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": ["amministrazione@cliente.it"], "language": "it", "message": "Grazie per la collaborazione!", "attach_xml": false }' ``` Tutti i campi sono facoltativi: senza `to` usa l'email del cliente sulla fattura (`422 customer_email_missing` se manca). Il cliente riceve il PDF come **copia di cortesia**: la fattura valida ai fini fiscali resta quella consegnata dallo SDI, e l'email lo dice. Con `attach_xml: true` alleghi anche il file FatturaPA. Se la fattura ha un link di pagamento, l'email ha il pulsante **Paga ora**. La risposta (`201`) è il record dell'email con `status: sent` e `provider_message_id`. Se il provider rifiuta l'invio rispondiamo `502 email_failed`: il tentativo resta registrato e puoi riprovare con la stessa `Idempotency-Key`. ```bash curl https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/deliveries \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `GET /deliveries` elenca le email della fattura (copie e solleciti), le più recenti prima. ## Registra un pagamento [#registra-un-pagamento] ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payments \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Senza corpo registra tutto quello che resta da incassare, con la data di oggi e il metodo `bank_transfer`: la fattura diventa `paid`. Per un acconto passa l'importo: ```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" }' ``` Metodi: `bank_transfer`, `card`, `cash`, `stripe`, `other`. Un importo superiore al residuo risponde `422 amount_exceeds_balance`, una fattura già pagata `409 invoice_already_paid`. La risposta contiene `payment` e la fattura aggiornata. Ogni fattura ha ora questi campi: | Campo | Significato | | ------------------ | ------------------------------------------------------------------- | | `payment_status` | `unpaid`, `partially_paid` o `paid` | | `amount_due` | Quanto paga il cliente: il totale meno la ritenuta d'acconto | | `amount_paid` | Somma dei pagamenti registrati | | `paid_at` | Data del pagamento che ha saldato la fattura | | `overdue` | `true` se è emessa, non pagata e la scadenza (`due_date`) è passata | | `payment_link_url` | Il link di pagamento Stripe, finché non è pagata | Per le fatture da incassare o scadute: `GET /invoices?payment_status=unpaid` oppure `GET /invoices?overdue=true`. Le fatture importate da Stripe sono già pagate. ## Link di pagamento Stripe [#link-di-pagamento-stripe] ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payment-link \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Crea un [Payment Link](https://docs.stripe.com/payment-links) per il residuo sull'account Stripe collegato al team (`201`), oppure restituisce quello esistente (`200`). Senza Stripe collegato risponde `409 stripe_not_connected`: collegalo dalla pagina fatture emesse dell'app o con [`POST /connections/stripe`](/it/api/connections). La modalità di Stripe deve corrispondere alla fattura: le fatture sandbox richiedono una connessione in modalità test, quelle reali una connessione live (altrimenti `409 stripe_mode_mismatch`). Quando registri un pagamento il link viene disattivato, perché chiederebbe il vecchio residuo: creane uno nuovo per quanto resta. Quando il cliente paga, Getbeel registra il pagamento (metodo `stripe`) entro un'ora e la fattura diventa pagata. ## Solleciti [#solleciti] Un sollecito manuale: ```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": "it" }' ``` Accetta gli stessi campi dell'email (`to`, `cc`, `language`, `message`) e allega il PDF con il link di pagamento. Una fattura già pagata risponde `409`. I **solleciti automatici** si attivano per azienda nell'app (**Fatture emesse → Solleciti**): spenti di default, partono il numero di giorni dopo la scadenza che scegli (ad esempio 3, 10, 30), una volta per passaggio, solo per le fatture live con l'email del cliente e con scadenza dal giorno in cui li hai attivati. La stessa impostazione dall'API (`invoices:write`, chiavi live; la lettura richiede `invoices:read` e va con entrambe): ```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] }' ``` Un `PATCH` cambia solo quello che invia. La risposta, come `GET /companies/me/reminder-settings`, ha `enabled`, `days` (fino a 5 passaggi) e `enabled_at`, il giorno da cui partono i solleciti. Strumenti MCP: `get_reminder_settings`, `update_reminder_settings`. ## Webhook [#webhook] | Evento | Quando | `data.object` | | ---------------------- | ---------------------------------------------------- | --------------- | | `invoice.emailed` | Email o sollecito inviato | `invoice_email` | | `invoice.email_failed` | Invio non riuscito | `invoice_email` | | `invoice.paid` | I pagamenti coprono il dovuto | `invoice` | | `invoice.overdue` | Il giorno dopo la scadenza, una volta, se non pagata | `invoice` | ## Con un assistente AI [#con-un-assistente-ai] Il [server MCP](/it/api/mcp) ha `email_invoice_to_customer`, `mark_invoice_paid`, `list_overdue_invoices`, `create_payment_link` e `send_payment_reminder`. Prima di inviare un'email l'assistente ti chiede conferma dei destinatari. # Note di credito, preventivi, articoli e numerazione (https://docs.getbeel.com/it/api/invoicing) Storna una fattura con una nota di credito TD04, trasforma un preventivo in fattura, salva articoli e numera con i sezionali. Quattro strumenti per la fatturazione di tutti i giorni, con gli stessi servizi dell'app. Scrivono con lo scope `invoices:write`, leggono con `invoices:read`. Le chiavi di test lavorano sui dati sandbox (note di credito, preventivi e articoli propri), quelle live sui dati reali. ## Modificare una bozza [#modificare-una-bozza] `PATCH /invoices/{id}` modifica una bozza con le stesse regole della creazione e del modulo di modifica dell'app; la risposta è la fattura con i totali ricalcolati. - Invia solo quello che cambia. Ogni campo sostituisce quella parte: `lines` sostituisce tutte le righe (inviale tutte), `customer` e `payment` si inviano interi, `notes: null` toglie la causale. - Se la bozza ha una ritenuta o una cassa previdenziale e cambi `lines`, `withholding` o `cassa_previdenziale`, invia di nuovo anche quelle (`null` le toglie): i loro importi dipendono dalle righe. Altrimenti `400 parameter_missing`. - Il numero di un sezionale e il tipo di una nota di credito non cambiano: un valore diverso risponde `422 invoice_invalid` (lo stesso valore è accettato), e un numero di sezionale non può passare a un altro anno (`422 invoice_invalid`); un numero scritto a mano deve seguire la sequenza dell'anno (`422 invoice_number_out_of_sequence`). - Solo bozze: `409 invoice_not_draft` dopo l'invio, `409 invoice_send_in_progress` durante l'invio. Una fattura scartata si riapre prima ([ciclo di vita SDI](/it/api/sdi-lifecycle#scartata-ns--rejected)); una inviata si corregge con una nota di credito. ```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` e `reopen_rejected_invoice`. ## Note di credito (TD04) [#note-di-credito-td04] Una nota di credito storna una fattura che lo SDI ha accettato: tutta, oppure solo alcune righe (anche con una quantità minore). ```bash curl -X POST https://www.getbeel.com/api/v1/invoices/$FATTURA/credit-notes \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "lines": [{ "index": 0, "quantity": 2 }], "reason": "Reso merce" }' ``` - Senza `lines` storna l'intera fattura (ritenuta, cassa e sconti compresi). Uno storno parziale li esclude: vanno ripartiti a mano. - La nota copia cliente e dati di pagamento, richiama la fattura in `DatiFattureCollegate` (numero e data) e nasce in **bozza**: inviala con `POST /invoices/{id}/send`, come ogni fattura. Gli eventi webhook sono quelli delle fatture (`invoice.sent`, `invoice.delivered`…). - Numero: la numerazione predefinita per le note di credito, altrimenti quella della fattura. `series_id` la sceglie. - Le note non scartate possono sommare al massimo il totale della fattura (`422 credit_exceeds_invoice`). Una bozza, una proforma o un'altra nota non si stornano (`409`). Quando lo SDI accetta la nota, la fattura mostra `amount_credited` e il suo `amount_due` scende: se è stornata del tutto diventa `paid`, e solleciti e scadenze ne tengono conto. Una nota scartata smette di contare. In alternativa, `POST /invoices` con `tipo_documento: "TD04"` e `related_invoice_id` crea una nota con righe libere. Nell'app: apri una fattura inviata e scegli **Crea nota di credito**. ## Preventivi [#preventivi] Un preventivo ha gli stessi campi di una fattura (cliente, righe, pagamento, note) più `valid_until`. Numero per anno (`12/2026`), stati `draft` → `sent` → `accepted` o `declined`; una bozza o un preventivo inviato oltre `valid_until` risulta `expired`. ```bash # crea 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": "amministrazione@rossi.it" }, "lines": [{ "description": "Sito web", "unit_price": "2500", "vat_rate": "22" }], "valid_until": "2026-12-31" }' # invia il PDF al cliente curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/send \ -H "Authorization: Bearer $GETBEEL_API_KEY" # accettato: diventa una bozza di fattura curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/convert \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` - `GET /quotes/{id}/pdf` scarica il PDF. Con una chiave di test l'email arriva solo al titolare dell'account. - `convert` crea la fattura con la data di oggi (o `date`) e il numero successivo, con le stesse regole di `POST /invoices` (per le chiavi live servono il piano SDI e la quota), e segna il preventivo accettato. Un preventivo si converte una volta sola (`409 quote_converted`). - `POST /quotes/{id}/accept` e `POST /quotes/{id}/decline` registrano la risposta del cliente. - `GET /quotes/{id}` legge un preventivo; `PATCH /quotes/{id}` lo modifica finché non è convertito (`409 quote_converted`) o accettato (`409 quote_not_editable`); `DELETE /quotes/{id}` lo elimina (la sua fattura, se c'è, resta). Nell'app: **Fatture emesse → Preventivi**. ## Articoli [#articoli] Prodotti e servizi salvati con prezzo, IVA (o natura) e unità di misura, da scegliere nelle fatture e nei preventivi. ```bash curl -X POST https://www.getbeel.com/api/v1/items \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Consulenza", "unit_price": "80", "unit": "ore", "vat_rate": "22" }' ``` `GET /items?search=consul`, `PATCH /items/{id}` e `DELETE /items/{id}`. Le fatture già fatte non cambiano quando modifichi un articolo. ## Numerazione (sezionali) [#numerazione-sezionali] Senza sezionali Getbeel usa la numerazione Standard: numeri semplici senza suffisso (`1`, `2`, `3`…) che ripartono da 1 ogni anno solare, come consente l'Agenzia delle Entrate (Risoluzione 1/E del 2013); se l'azienda sceglie una sequenza unica negli anni, `default_numbering.yearly_reset` è `false`. Le fatture numerate prima restano con il numero inviato allo SdI (`45/`) e la successiva prosegue senza barra (`46`). Il campo `number` di una fattura è sempre esattamente il `Numero` dell'XML. Senza `number` in `POST /invoices` il numero è assegnato per l'anno della data; un `number` numerico può essere il prossimo o colmare un buco, non saltare avanti nella sequenza dell'anno (`422 invoice_number_out_of_sequence`). Vedi la [guida alla numerazione](/it/guide/numerazione-fatture). Un sezionale aggiunge un prefisso o un suffisso (`FT-12`, `12/A`), riparte da 1 ogni anno (se non imposti `yearly_reset: false`) e ha la sua sequenza, separata tra chiavi di test e live. Un numero non viene mai riassegnato. ```bash # elenco con il prossimo numero curl https://www.getbeel.com/api/v1/numbering-series \ -H "Authorization: Bearer $GETBEEL_API_KEY" # nuovo sezionale, predefinito per le fatture (solo chiavi live) curl -X POST https://www.getbeel.com/api/v1/numbering-series \ -H "Authorization: Bearer $GETBEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Estero", "suffix": "/E", "default_for_invoices": true }' ``` `POST /invoices`, `POST /quotes/{id}/convert` e le note di credito accettano `series_id` (`null` = numerazione standard). Prefisso, suffisso e azzeramento annuale non cambiano dopo la prima fattura (`409 numbering_series_in_use`); `GET /numbering-series/{id}` legge un sezionale, e `PATCH /numbering-series/{id}` lo rinomina, lo rende predefinito o lo archivia (`{ "archived": true }`), con una chiave live. Nell'app: **Fatture emesse → Preventivi → Numerazione**, e il menu **Numerazione** nel modulo della nuova fattura. ## Con un assistente AI [#con-un-assistente-ai] Strumenti MCP: `list_quotes`, `create_quote`, `send_quote`, `convert_quote_to_invoice`, `create_credit_note`, `list_credit_notes` e `list_items`. L'assistente chiede conferma prima di inviare un'email o di creare una nota di credito; nulla va allo SDI senza `send_invoice`. # Server MCP (https://docs.getbeel.com/it/api/mcp) Collega Claude, ChatGPT, Cursor e altri client MCP a Getbeel. Il server MCP di Getbeel dà agli agenti AI gli stessi poteri dell'API, con gli stessi controlli. ![La pagina Chiavi API e MCP: chiavi di test e live, permessi e indirizzo del server MCP.](/screenshots/api-keys-mcp.it.webp) | | | | -------------- | ----------------------------------------------------------------------------- | | URL | `https://www.getbeel.com/api/mcp` | | Trasporto | Streamable HTTP, senza sessioni (solo `POST`, risposte JSON) | | Autenticazione | Accesso con OAuth 2.1, oppure `Authorization: Bearer gb_test_…` / `gb_live_…` | ## Accesso con OAuth (senza chiave) [#accesso-con-oauth-senza-chiave] Claude (web, desktop e Claude Code), ChatGPT, Cursor e gli altri client che seguono la [specifica di autorizzazione MCP](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) si collegano con l'accesso: aggiungi l'URL qui sopra, accedi a Getbeel e scegli: - **Team**: lo spazio di lavoro su cui lavora l'app (uno per collegamento). - **Modalità**: **Test** (predefinita: sandbox, nulla arriva allo SDI) o **Live**. - **Permessi**: gli stessi [scope](/it/api/authentication) delle chiavi API. Di default tutti quelli di lettura, la validazione e la scrittura. La schermata mostra esattamente dove ti porta **Consenti**: l'host completo (`claude.ai`) o l'app sul tuo dispositivo (`localhost:6274`, `cursor://…`). Qualunque app può registrarsi con qualunque nome, quindi risultano verificate solo Claude e ChatGPT, di cui Getbeel ha controllato la destinazione. Ogni altra app mostra **Getbeel non ha verificato questa app**: autorizzala solo se hai avviato tu il collegamento. Da quel momento l'app agisce su quel team come te, come una chiave creata da te. La trovi in **Impostazioni → Chiavi API e MCP → App collegate**, con l'ultimo utilizzo, e da lì puoi revocarla: perde l'accesso subito. In claude.ai o Claude Desktop: **Impostazioni → Connettori → Aggiungi connettore personalizzato**, nome `Getbeel`, URL `https://www.getbeel.com/api/mcp`. Scegli **Connetti** e accedi. In **Impostazioni → App e connettori** (modalità sviluppatore) crea un connettore con URL `https://www.getbeel.com/api/mcp` e autenticazione **OAuth**, poi accedi. ```json title=".cursor/mcp.json" { "mcpServers": { "getbeel": { "url": "https://www.getbeel.com/api/mcp" } } } ``` Cursor mostra **Needs login** accanto al server: cliccalo e accedi. ```bash claude mcp add --transport http getbeel https://www.getbeel.com/api/mcp ``` Poi esegui `/mcp` in Claude Code e scegli **Authenticate**. Per chi sviluppa un client: una richiesta senza credenziali riceve `401` con `WWW-Authenticate: Bearer resource_metadata="https://www.getbeel.com/.well-known/oauth-protected-resource/api/mcp"`. Quel documento indica il server di autorizzazione `https://www.getbeel.com/api/auth` (metadati in `/.well-known/oauth-authorization-server/api/auth`): registrazione dinamica dei client, authorization code con PKCE (solo `S256`), refresh token (`offline_access`), risorsa `https://www.getbeel.com/api/mcp`. I token di accesso iniziano con `gb_oat_` e durano un'ora. ## Con una chiave API [#con-una-chiave-api] I client che accettano solo un header usano una chiave creata in **Impostazioni → Chiavi API e MCP**. Inizia con una chiave di test: con quella nessuna fattura arriva allo SDI. ```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}" } } } } ``` Tramite il ponte `mcp-remote` (serve Node.js). In **Impostazioni → Sviluppatore → Modifica configurazione**: ```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_..." } } } } ``` Ogni altro client che supporta server MCP remoti via HTTP con header personalizzati funziona allo stesso modo. ## Strumenti [#strumenti] L'elenco qui sotto è generato dalle definizioni degli strumenti nel codice del server (`pnpm --filter docs mcp-tools`), quindi corrisponde a quello che il tuo client riceve con `tools/list`. Le descrizioni sono quelle che il server invia all'assistente, in inglese; il server aggiunge a ciascuna lo scope richiesto. - **Scrive**: vuoto per gli strumenti di sola lettura. `invia` ed `elimina` sono segnati come distruttivi (`destructiveHint`): un invio live è una trasmissione allo SDI con valore fiscale. - Tutti gli strumenti accettano anche `company_id`, non elencato nella tabella: l'id di un'azienda cliente (da `list_companies`) su cui agire al posto dell'account della chiave. `list_companies` lo accetta e lo ignora. {/* mcp-tools:start (generated by scripts/mcp-tools.ts, do not edit) */} | Strumento | Scope | Scrive | Argomenti (\* = obbligatorio) | Descrizione | | --- | --- | --- | --- | --- | | `list_companies` | `account:read` | | nessuno | 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` | | nessuno | 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` | crea | `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` | modifica | `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` | modifica | `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` | invia | `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` | invia | `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` | modifica | `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` | crea | `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` | invia | `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` | crea | `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` | crea | `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` | modifica | `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` | modifica | `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` | | nessuno | 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` | crea | `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` | crea | `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` | modifica | `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` | crea | `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` | modifica | `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` | crea | `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` | modifica | `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` | elimina | `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` | modifica | nessuno | 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` | | nessuno | 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` | modifica | `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` | modifica | `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` | elimina | `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` | | nessuno | 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` | modifica | nessuno | 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` | modifica | nessuno | 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` | crea | `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` | crea | `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` | invia | `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` | crea | `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` | crea | `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` | modifica | `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` | elimina | `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` | modifica | `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` | modifica | `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` | crea | `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` | modifica | `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` | elimina | `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` | | nessuno | 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` | crea | `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` | modifica | `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` | modifica | `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` | modifica | `id`\*: string | No new invoices are created until it is resumed. | | `resume_recurring_invoice` | `invoices:write` | modifica | `id`\*: string | Starts creating invoices again from the next date. Confirm the next date with the user first. | | `delete_recurring_invoice` | `invoices:write` | elimina | `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` | | nessuno | 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` | crea | nessuno | 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` | crea | `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` | | nessuno | 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` | | nessuno | 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` | crea | `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` | crea | nessuno | 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` | crea | `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` | modifica | `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` | elimina | `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` | modifica | `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` | crea | `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` | modifica | `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` | modifica | `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` | | nessuno | 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` | modifica | `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` | | nessuno | 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` | modifica | `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` | | nessuno | 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` | modifica | `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` | modifica | nessuno | 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` | modifica | `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` | modifica | `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` | crea | `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` | | nessuno | 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` | crea | `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` | crea | `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` | modifica | `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` | modifica | `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` | | nessuno | 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` | invia | `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` | invia | `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` | elimina | `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` | crea | `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` | modifica | `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` | elimina | `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` | modifica | `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` | | nessuno | 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` | crea | `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` | modifica | `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` | crea | `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` | crea | `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` | elimina | `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` | elimina | `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` | crea | `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` | | nessuno | The team's categories for received invoices (expense categories), with the slug each received invoice carries in category. | | `create_category` | `received_invoices:write` | crea | `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` | modifica | `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` | elimina | `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` | modifica | `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` | modifica | `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` | elimina | `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` riceve la domanda così come l'ha scritta l'utente e restituisce cosa dicono i dati dell'azienda (scadenze aperte, adempimenti recenti, l'ultima liquidazione IVA, ritenute da versare, la stima delle imposte, conto economico e crediti, secondo gli argomenti della domanda), le fonti ufficiali da citare, gli altri strumenti da usare e `professional_needed` con i motivi per cui serve il commercialista (per esempio il visto di conformità per compensare più di 5.000 € di credito IVA, controlli e avvisi, sanzioni, dichiarazione dei redditi e bilancio, buste paga). Getbeel qui non chiama un modello linguistico: la risposta la scrive il tuo assistente da quei dati, seguendo la sua `guidance`, così ogni cifra si ritrova nei dati e Getbeel non inventa nulla. Gli strumenti su banca, connessioni e documenti raccolti lavorano su dati reali: una chiave di test può leggerli, solo una chiave live può modificarli. Ogni strumento che modifica dati chiede all'assistente di confermare prima con te. Gli strumenti restituiscono JSON con gli stessi campi dell'API. Gli errori hanno la [stessa forma](/it/api/errors), in un risultato con `isError: true`. ## Esempi [#esempi] Ogni risultato è un blocco di testo con lo stesso JSON dell'API. Gli esempi mostrano la chiamata `tools/call` e il testo del risultato. ### Una fattura non consegnata con `get_invoice` [#una-fattura-non-consegnata-con-get_invoice] La fattura è emessa: lo SDI non ha potuto recapitarla e l'ha messa nel cassetto fiscale del cliente dal giorno in `sdi.available_since`. Non va inviata di nuovo. Il significato di ogni stato è nel [ciclo di vita SDI](/it/api/sdi-lifecycle). ```json title="Chiamata" { "method": "tools/call", "params": { "name": "get_invoice", "arguments": { "id": "fe_8c1d2e4f-5a6b-4c7d-9e8f-0a1b2c3d4e5f" } } } ``` ```json title="Risultato" { "object": "invoice", "id": "fe_8c1d2e4f-5a6b-4c7d-9e8f-0a1b2c3d4e5f", "livemode": true, "number": "118", "tipo_documento": "TD01", "invoice_date": "2026-10-28", "due_date": "2026-11-27", "status": "not_delivered", "is_proforma": false, "currency": "EUR", "amount_subtotal": "1000.00", "amount_tax": "220.00", "amount_total": "1220.00", "customer": { "name": "Verdi S.r.l.", "vat_number": "01234567890", "codice_fiscale": null, "codice_destinatario": "0000000", "pec": null, "email": "amministrazione@verdi.example", "country": "IT", "address": "Via Roma 1", "postal_code": "20121", "city": "Milano", "province": "MI" }, "sdi": { "identificativo_sdi": "7731024559", "file_name": "IT13815270965_0004K.xml", "error_message": null, "error_codes": [], "errors": [], "available_since": "2026-10-30", "updated_at": "2026-10-30T10:25:05.000Z" }, "payment_status": "unpaid", "amount_due": "1220.00", "amount_credited": "0.00", "withholdings": [], "related_invoice_id": null, "series_id": null, "amount_paid": "0.00", "paid_at": null, "overdue": false, "payment_link_url": null, "lines": [ { "description": "Consulenza di ottobre", "quantity": "1", "unit_price": "1000.00", "amount": "1000.00", "vat_rate": "22.00", "natura": null } ], "created_at": "2026-10-28T09:12:44.512Z", "updated_at": "2026-10-30T10:25:06.104Z" } ``` ### Le fatture scartate con `list_invoices` [#le-fatture-scartate-con-list_invoices] `status` accetta `draft`, `sending`, `sent`, `delivered`, `not_delivered` e `rejected`. Il risultato è una pagina: se `has_more` è `true`, ripeti la chiamata con `cursor` uguale a `next_cursor`. ```json title="Chiamata" { "method": "tools/call", "params": { "name": "list_invoices", "arguments": { "status": "rejected", "date_from": "2026-10-01", "limit": 10 } } } ``` ```json title="Risultato (abbreviato)" { "object": "list", "data": [ { "object": "invoice", "id": "fe_2b7e9a10-3c4d-4e5f-8a9b-0c1d2e3f4a5b", "number": "121", "invoice_date": "2026-10-30", "status": "rejected", "customer": { "name": "Bianchi S.p.A.", "vat_number": "01234567891", "…": "…" }, "sdi": { "identificativo_sdi": "7731099120", "file_name": "IT13815270965_0004N.xml", "error_message": "00305 1.4.1.1.2 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 } ``` La fattura `121` non è emessa: va corretta la partita IVA del cliente (vedi [`00305`](/it/api/reference-data/sdi-errors)) e va inviata di nuovo con lo stesso numero e la stessa data. ## Argomenti rigorosi [#argomenti-rigorosi] Ogni strumento dichiara `additionalProperties: false` e il server rifiuta gli argomenti che non conosce, invece di ignorarli: un assistente non crede mai di aver filtrato o impostato qualcosa che non ha avuto effetto. L'errore arriva come risultato con `isError: true` e il messaggio dice cosa correggere. Un argomento sconosciuto (per esempio `starting_after` al posto di `cursor`): ```text MCP error -32602: Input validation error: Invalid arguments for tool list_invoices: Unrecognized key: "starting_after" ``` Un valore fuori dall'elenco ammesso elenca le opzioni: ```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 ``` Un numero fuori dai limiti: ```text MCP error -32602: Input validation error: Invalid arguments for tool list_invoices: Too big: expected number to be <=100 at limit ``` Gli altri errori (scope mancante, risorsa inesistente, fattura non in bozza…) hanno la [stessa forma dell'API](/it/api/errors), `{ "error": { "type", "code", "message", "param" } }`, sempre in un risultato con `isError: true`. In modalità ricerca, `call_tool` risponde anche con `tool_not_found` (nessuno strumento con quel nome) e `tool_not_read_only` (lo strumento modifica dati: chiamalo direttamente). ## Sicurezza [#sicurezza] - **Parti dalla sandbox.** Con una chiave di test `send_invoice` non raggiunge mai lo SDI. - **Dai solo gli scope necessari.** Una chiave senza scope di scrittura può leggere e validare, ma non creare né inviare. - **Chiedi conferma prima di inviare.** Configura il client perché chieda la tua approvazione prima di ogni chiamata a `send_invoice`. Un invio live emette una fattura con valore fiscale. - **Tutto è registrato.** Ogni chiamata MCP finisce nel registro delle richieste della chiave, come le chiamate API, e conta nel [limite di richieste](/it/api/rate-limits). - **Revoca in un attimo.** Revoca una chiave, o un'app collegata, in Impostazioni → Chiavi API e MCP: perde l'accesso subito. ## Risorse e prompt [#risorse-e-prompt] Oltre agli strumenti, il server offre altre due cose ai client che le supportano (Claude, Claude Code, Cursor, VS Code). Tutto funziona anche con i soli strumenti, come fa ChatGPT con Getbeel. Le **risorse** sono contesto in sola lettura che alleghi alla conversazione (per esempio con `@` in Claude). Ogni URI contiene l'azienda, l'`id` di `list_companies` (anche il tuo account), e richiede lo scope dello strumento di lettura che rispecchia. Un'azienda su cui la chiave non può agire risponde come un URI sconosciuto, mai "vietato". | URI | Cosa è | Scope | | ------------------------------------------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------- | | `getbeel://companies/{company_id}/profile` | Azienda, dati fiscali, stato della ricezione SDI, banche e caselle collegate | `account:read` | | `getbeel://companies/{company_id}/invoices/{invoice_id}` | Una fattura emessa (`fe_…`) o ricevuta, come `get_invoice`, con link al PDF | `invoices:read`, `received_invoices:read` | | `getbeel://companies/{company_id}/invoices/{invoice_id}/xml` | L'XML FatturaPA (`text/xml`), se conservato | come la fattura | | `getbeel://companies/{company_id}/tax-calendar` | Prossime scadenze, come `get_tax_calendar` | `taxes:read` | | `getbeel://companies/{company_id}/reports/{period}` | Conto economico, flusso di cassa e scadenzario per `2026`, `2026-Q3` o `2026-10` | `taxes:read` | | `getbeel://companies/{company_id}/vat/{period}` | Liquidazione IVA di `2026-10` o `2026-Q3`, da verificare | `taxes:read` | `resources/list` mostra un profilo per ogni azienda su cui la chiave può agire; gli altri URI arrivano da `resources/templates/list`, e i client completano `company_id` e `period` mentre scrivi. Gli strumenti di lettura di questi oggetti (`whoami`, `get_invoice`, `list_invoices`, `list_received_invoices`, `get_tax_calendar`, `get_report`, `get_vat_settlement`) restituiscono anche un `resource_link` all'URI corrispondente, dopo il loro risultato di sempre. I **prompt** sono flussi di lavoro che avvii tu (un comando con `/` nella maggior parte dei client). Ognuno accetta un `company_id` facoltativo (di default l'azienda della chiave) e restituisce i passi e gli strumenti da usare. Tutto ciò che scrive o invia aspetta il tuo OK esplicito, e l'assistente non presenta né paga nulla al posto tuo. | Prompt | Argomenti | Cosa fa | | ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- | | `close_month` | `month` | Movimenti bancari senza fattura, fatture non allo SDI o scartate, acquisti da rivedere, IVA, poi un riepilogo | | `vat_settlement` | `period` | Registri, liquidazione, poi (dopo il tuo OK) l'F24 e come pagarlo | | `reconcile_bank` | | Rivedi, conferma e applica gli abbinamenti bancari suggeriti | | `chase_unpaid` | | Scadenzario crediti, fatture scadute, solleciti inviati solo dopo il tuo OK | | `new_invoice` | `client` (facoltativo) | Cliente, righe, bozza, e invio allo SDI solo quando lo dici tu | | `setup_check` | | Cosa manca (codice destinatario, banca, casella, profilo fiscale, conservazione) e come sistemarlo | Risorse e prompt sono gli stessi nella [modalità ricerca](#modalità-ricerca). ## Modalità ricerca [#modalità-ricerca] Di default il server elenca tutti gli strumenti. Gli assistenti che non devono caricare tutti gli schemi all'inizio possono collegarsi a `https://www.getbeel.com/api/mcp?tools=search` (oppure inviare l'header `Getbeel-MCP-Tools: search`, per i client il cui accesso richiede l'URL semplice). Gli strumenti di sola lettura sono sostituiti da due: - `search_tools`: riceve qualche parola (`"send invoice"`, `"bank statement"`, `"F24 bollo"`) e restituisce gli strumenti corrispondenti con descrizione, scope e schema di input. Senza parole elenca tutti gli strumenti per nome. - `call_tool`: esegue uno strumento di sola lettura per `name` con i suoi `arguments` (`company_id` compreso), con gli stessi controlli di scope e la stessa validazione di una chiamata diretta. Gli strumenti che modificano dati o inviano qualcosa restano elencati con il loro nome, così il client ti chiede conferma per ciascuno: approvare `call_tool` non approva mai un invio. ```bash claude mcp add --transport http getbeel "https://www.getbeel.com/api/mcp?tools=search" ``` ## Server card e registro [#server-card-e-registro] La scheda del server ([MCP Server Card](https://github.com/modelcontextprotocol/ext-server-card)) è in `https://www.getbeel.com/api/mcp/server-card`, elencata in `https://www.getbeel.com/.well-known/ai-catalog.json`. Il nome del server nel registro MCP è `com.getbeel/mcp`. ## Server MCP della documentazione [#server-mcp-della-documentazione] Questa documentazione ha un suo server MCP pubblico, in sola lettura, con gli strumenti `list_pages`, `get_page` e `search`: ```bash claude mcp add --transport http getbeel-docs https://docs.getbeel.com/api/mcp ``` # Paginazione (https://docs.getbeel.com/it/api/pagination) Gli elenchi usano una paginazione a cursore con limit, cursor, has_more e next_cursor. Gli endpoint che restituiscono elenchi (`GET /invoices`, `GET /received-invoices`) sono ordinati per `invoice_date`, dalla più recente, e restituiscono una pagina alla volta: ```json { "object": "list", "data": [{ "object": "invoice", "id": "fe_3f1c…" }], "has_more": true, "next_cursor": "WyIyMDI2LTEwLTE1IiwiZmVfM2YxYyJd" } ``` | Parametro | Descrizione | | --------- | ----------------------------------------------- | | `limit` | Elementi per pagina, da 1 a 100. Predefinito 20 | | `cursor` | Il `next_cursor` della pagina precedente | Quando `has_more` è `false`, `next_cursor` è `null` e hai letto tutto. Il cursore è opaco: non costruirlo a mano. I filtri (per esempio `status`, `date_from`, `date_to`) vanno ripetuti su ogni pagina. ## Leggere tutte le pagine [#leggere-tutte-le-pagine] ```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); } ``` # Prezzi, saldo e consumi (https://docs.getbeel.com/it/api/pricing) Paghi quanto usi da un saldo prepagato. Il listino, il saldo, le ricariche, i consumi e l'errore 402 insufficient_balance. Usare Getbeel è gratis: app, sandbox, API, server MCP, webhook, scadenzario, registri ed esportazioni. Si paga solo quello che costa, da **un saldo prepagato in euro per account di fatturazione**. Un gestore con molte aziende clienti ha un solo saldo, e gli scaglioni contano tutte le sue aziende. Prezzi IVA esclusa. ## Listino [#listino] **Invio allo SDI** (fatture, note di credito, autofatture TD16–TD20: ogni documento inviato allo SDI), a scaglioni per mese solare: | Invii al mese | Prezzo per invio | | ------------- | ---------------- | | 1–1.000 | 0,15 € | | 1.001–10.000 | 0,12 € | | oltre 10.000 | 0,10 € | | Voce | Prezzo | | ---------------------------------------------------------------------------- | ------- | | Fattura ricevuta dallo SDI | 0,15 € | | Documento letto dall'IA (scansione email, indirizzo di inoltro, caricamento) | 0,03 € | | Conto bancario collegato, al mese | 2,00 € | | Movimento bancario importato | 0,02 € | | F24 pagato (qualsiasi F24: IVA, bollo, ritenute, INPS, acconti) | 1,00 € | | LIPE inviata | 3,00 € | | Dichiarazione OSS inviata | 3,00 € | | Dichiarazione IVA annuale inviata | 12,00 € | | Dichiarazione IRES/IRAP inviata | 9,00 € | | Dichiarazione Redditi PF inviata (autonomi, ogni regime) | 9,00 € | Una pratica si paga una volta per tipo, periodo e azienda, quando la segni come pagata o inviata (ricevuta registrata): prepararla (a mano o in automatico), rifarla e saltarla sono gratis. Salvare i dati della stima delle imposte è gratis. Un movimento bancario si paga una volta, quando viene importato (collegamento bancario o estratto caricato): importarlo di nuovo (lo stesso estratto, una sincronizzazione che lo riporta, un estratto con un periodo sovrapposto) è gratis, e un estratto caricato non salva di nuovo un movimento già importato per lo stesso conto (riconosciuto da banca e ultime 4 cifre). Il profilo fiscale, il riconoscimento del regime, il calendario e gli avvisi sono gratis. Preventivi, proforma, PDF, solleciti e il reinvio dopo uno scarto sono gratis. Esempio: 200 aziende che inviano 20 fatture e ne ricevono 30 al mese tramite SDI fanno 4.000 invii (510 €) e 6.000 ricezioni (900 €): 1.410 € al mese. `GET /billing/prices` restituisce lo stesso listino (centesimi, IVA esclusa). ## Saldo e ricariche [#saldo-e-ricariche] - **Credito di benvenuto**: 1 € una volta per account (e per carta e partita IVA), valido 90 giorni, quando salvi la prima carta. Una carta che l'ha già ricevuto su un altro team non ne riceve un secondo: Fatturazione e utilizzo mostra "Il credito di benvenuto si applica una sola volta per carta." Il credito di benvenuto è solo per gli account nuovi. - **Ricariche**: da 10 €, con una fattura per ogni ricarica (IVA al pagamento). Il credito pagato vale 12 mesi. - **Ricarica automatica**: disattivata di default; quando il saldo scende sotto una soglia aggiunge un importo con la carta salvata. Se la carta viene rifiutata riprova una volta dopo 24 ore, poi si disattiva. - **Avviso di saldo basso**: l'avviso in Fatturazione e utilizzo, il saldo rosso nella barra laterale e l'email partono quando hai credito pagato: una ricarica (a mano o automatica) non rimborsata per intero; il solo credito di benvenuto non conta. La soglia è 10 € se non la cambi. - **Saldo a zero**: le nuove azioni a pagamento si fermano. La ricezione delle fatture dallo SDI non si ferma mai: può portare il saldo fino a -10 €, scalati dalla ricarica successiva. `GET /billing/balance` restituisce `pricing` (`pay_as_you_go`, oppure `legacy_plan`: vedi [Account con un piano](#account-con-un-piano)), il saldo in centesimi (`balance_cents`), il credito in scadenza nei prossimi 30 giorni (`expiring_soon_cents`), la ricarica automatica e l'avviso di saldo basso, `welcome_credit` (`granted` e `not_granted_reason`: `card_already_used`, `legacy_plan`, `no_card` o null) e `topup_url`. Il saldo può aggiornarsi con un minuto di ritardo. `POST /billing/topups` con `amount_cents` crea un link di pagamento Stripe (`checkout_url`) da far pagare a una persona: l'API non addebita mai una carta. Servono una chiave live con lo scope `billing:write` (mai selezionato di default), creata da chi gestisce la fatturazione. Con la chiave di un'azienda cliente le API `/billing` rispondono 403 `billed_to_parent`: saldo e consumi sono sull'account del gestore. La pagina Stripe si apre nella lingua di chi ha creato la chiave (altrimenti del titolare del team, altrimenti in italiano per un'azienda italiana) e propone solo la carta predefinita attuale (Stripe Checkout non può preselezionare una carta salvata, quindi le altre lì sono nascoste; si può comunque inserire un'altra carta). ```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` (senza corpo) crea un link Stripe (`checkout_url`, in modalità setup: non addebita nulla) dove una persona inserisce una nuova carta: diventa la carta predefinita e quella delle ricariche automatiche. La stessa carta salvata due volte resta una sola. Stessa chiave e stesso scope delle ricariche; 409 `no_card` se non c'è ancora una carta salvata, come `application/problem+json` con la stessa forma del 402 qui sotto. MCP: `create_billing_card_link`. ## Consumi [#consumi] `GET /billing/usage?month=2026-12` restituisce per voce (`by_meter`) quantità, importo e prezzo del prossimo invio allo scaglione del mese, e per azienda (`by_company`) per un gestore. ## Saldo insufficiente (402) [#saldo-insufficiente-402] Un'azione a pagamento che il saldo non copre risponde **402** `application/problem+json` con `code` `insufficient_balance`, `balance_cents`, `required_cents` e `topup_url`, più il solito oggetto `error`. Qui `balance_cents` è il saldo disponibile (il saldo meno gli importi riservati per le azioni in corso), mai sotto 0. Per un'azienda cliente fatturata al suo gestore la risposta non contiene `balance_cents` né `topup_url` (il saldo è del gestore): il messaggio chiede di far aggiungere credito all'account che fattura l'azienda. I tool MCP restituiscono lo stesso testo. Vedi [Errori](/it/api/errors). ## Account con un piano [#account-con-un-piano] Chi si è registrato prima del 13 novembre 2026 mantiene il suo piano (o l'add-on SDI), con i suoi prezzi e tutto quello che include, senza scadenza: con un piano a pagamento attivo gli adempimenti fiscali e i conti bancari collegati sono inclusi, e senza piano restano chiusi come prima (402 `subscription_required`). Paghi quanto usi vale solo per gli account creati da quel giorno. Per questi account `GET /billing/balance` risponde con `pricing: "legacy_plan"`, importi a 0, `topup_url` null e `welcome_credit.not_granted_reason: "legacy_plan"`. `GET /billing/usage`, `POST /billing/topups` e `POST /billing/payment-method` rispondono 409 `not_pay_as_you_go`. `GET /usage` restituisce le transazioni SDI del mese (`sdi_transactions`, `free_allowance`, `email_extractions`, `estimated_amount`, `rate_card`, `received_unit_amount`, `email_extraction_unit_amount`). # Quickstart (https://docs.getbeel.com/it/api/quickstart) Crea una chiave di test, fai la prima chiamata, valida un XML e invia una fattura nella sandbox. Invia la tua prima fattura elettronica in circa cinque minuti, nella sandbox: niente arriva allo SDI vero e niente si paga. ## Prima di iniziare [#prima-di-iniziare] - **Un account Getbeel** con un team. Per le chiavi di test Impostazioni → Azienda non deve essere completa. - **Il permesso di gestire le impostazioni** in quel team (titolari e membri, non i revisori), per creare una chiave. - **Non servono:** una carta, un piano, una chiave live o la configurazione SDI. La sandbox e le chiavi di test sono gratuite ([Prezzi](/it/api/pricing)). Copia questo prompt in Claude Code, Cursor o 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. ``` ### Crea una chiave di test [#crea-una-chiave-di-test] Nell'app Getbeel apri **Impostazioni → Chiavi API e MCP** e crea una chiave in modalità **Test**. La chiave (`gb_test_…`) viene mostrata una volta sola: copiala subito. Possono creare chiavi i membri con il permesso di gestire le impostazioni (proprietari e membri, non i revisori). ```bash export GETBEEL_API_KEY="gb_test_..." ``` ### Fai la prima chiamata [#fai-la-prima-chiamata] ```bash curl https://www.getbeel.com/api/v1/me \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` ```json title="Risposta" { "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" ] } } ``` La risposta è abbreviata. `api_key.mode` ti conferma che stai usando una chiave di test. ### Valida un XML FatturaPA [#valida-un-xml-fatturapa] Manda un file XML così com'è, oppure in JSON come `{ "xml": "…" }`. Niente viene inviato né salvato. ```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="Risposta" { "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"] } ``` La validazione usa lo schema XSD ufficiale FatturaPA (v1.2.3) e i controlli SdI sul contenuto che dipendono dal solo file (Specifiche tecniche v1.9.1, Appendice 1: IVA e natura, totali con le tolleranze SdI, riepiloghi, regole per tipo documento), gli stessi controlli che Getbeel esegue prima di ogni invio. Ogni errore ha il codice e la descrizione dell'Agenzia delle Entrate: `00200` per lo schema (con la riga del file), `00201` oltre 50 errori di formato, `00313`–`00476` per i contenuti. Non controllati in locale: firme, anagrafe tributaria (partite IVA, codici destinatario) e duplicati. ### Crea una bozza [#crea-una-bozza] ```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": "Consulenza ottobre", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00" } ] }' ``` La risposta è la fattura con `status: "draft"` e il suo `id`. L'elenco completo dei campi è nel [riferimento API](/it/api/reference). ### Invia la bozza nella sandbox [#invia-la-bozza-nella-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)" ``` Con una chiave di test l'invio va alla sandbox, che risponde come lo SDI: la fattura passa a `sent` e poi a `delivered`. Controlla lo stato con `GET /invoices/{id}` oppure ricevi i [webhook](/it/api/webhooks). ### Prova uno scarto [#prova-uno-scarto] Crea un'altra bozza con `"partita_iva": "00000000000"` per il cliente e inviala: la sandbox la scarta con il codice `00305` (IdCodice del cliente non valido) e la fattura passa a `rejected`: correggila e inviala di nuovo con lo stesso numero e la stessa data (vedi [ciclo di vita SDI](/it/api/sdi-lifecycle)). Tutti gli esiti sono nella pagina [Sandbox](/it/api/sandbox). ## Cosa è successo [#cosa-è-successo] - **Hai creato una chiave di test.** Agisce sul tuo team con i tuoi accessi, solo sui dati della sandbox. È salvata come hash: Getbeel non può mostrarla di nuovo. - **`GET /me` l'ha verificata.** `api_key.mode` è `test` e `api_key.scopes` elenca cosa può fare la chiave. - **L'XML è stato validato** con gli stessi controlli che Getbeel fa prima di ogni invio. Non è stato salvato nulla. - **È stata creata una bozza** con `status: "draft"`, il numero successivo della sequenza di test e la data di oggi. Finché non la invii, la modifichi con `PATCH /invoices/{id}`. - **La sandbox ha risposto come lo SDI**: `sent`, poi `delivered` (oppure `rejected` con il codice SDI). Con una chiave live le stesse chiamate arrivano allo SDI vero. ## Se qualcosa non va [#se-qualcosa-non-va] | Errore | Causa | Soluzione | | ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ | | `401` `missing_api_key` | Manca l'header `Authorization` | Invia `-H "Authorization: Bearer $GETBEEL_API_KEY"` | | `401` `invalid_api_key` | La chiave è sbagliata o la variabile è vuota | `echo $GETBEEL_API_KEY`, poi copia di nuovo la chiave o creane una nuova | | `403` `insufficient_scope` | Alla chiave manca il permesso indicato nel messaggio | Crea una chiave con quel permesso (le chiavi non si modificano) | | `403` `company_not_eligible` | Per emettere serve un profilo aziendale italiano | Completa **Impostazioni → Azienda** | | `422` su `POST /invoices` | Un campo manca o non è valido; `param` dice quale | Correggi il campo e invia di nuovo con un nuovo `Idempotency-Key` | ```json title="Risposta 401" { "error": { "type": "authentication_error", "code": "missing_api_key", "message": "No API key provided. Send it as 'Authorization: Bearer gb_…'." } } ``` Tutti i codici e cosa fare: [Errori](/it/api/errors). ## Prossimi passi [#prossimi-passi] Ricevi un evento firmato per ogni esito SDI, senza interrogare l'API. Fai preparare le fatture a Claude, ChatGPT o Cursor, e approvale tu. Crea una chiave live quando il flusso nella sandbox funziona dall'inizio alla fine. Le stesse chiamate in TypeScript, Python o dal terminale. # Limiti di richieste (https://docs.getbeel.com/it/api/rate-limits) 120 richieste al minuto per chiave, con header RateLimit e Retry-After. Ogni chiave API può fare **120 richieste ogni 60 secondi**, in modalità test e live. Il conteggio è per chiave, non per indirizzo IP, e include le chiamate al [server MCP](/it/api/mcp). ## Header [#header] Ogni risposta indica a che punto sei: | Header | Valore | | --------------------- | ------------------------------------------- | | `RateLimit-Limit` | Richieste consentite nella finestra (`120`) | | `RateLimit-Remaining` | Richieste ancora disponibili | | `RateLimit-Reset` | Secondi alla fine della finestra | ## Quando superi il limite [#quando-superi-il-limite] Ricevi `429` con `type: "rate_limit_error"` e `code: "rate_limit_exceeded"`, più un header `Retry-After` con i secondi da attendere. ```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'); } ``` Anche le richieste rifiutate per scope mancante contano nel limite. Se ti serve un limite più alto, scrivici. # Fatture ricevute (https://docs.getbeel.com/it/api/received-invoices) Elenca e controlla le fatture dei fornitori, caricane una da far leggere all'AI e gestisci le categorie e le regole AI che le archiviano. Le fatture ricevute sono le fatture e le ricevute dei fornitori della tua azienda: dallo SDI (`source: "sdi"`), raccolte dalle email (`email`) o dall'indirizzo di inoltro (`forwarded`), caricate (`manual`) o lette da un movimento bancario (`bank_transaction`). È lo stesso elenco di **Fatture ricevute** nell'app. Le letture richiedono `received_invoices:read` e vanno con entrambe le modalità di chiave. Le scritture richiedono `received_invoices:write` e una chiave live: la contabilità è reale, non ne esiste una copia nella sandbox (`403 livemode_required` con una chiave di test). ## Elencare [#elencare] ```bash curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Dalla data fattura più recente, [con paginazione](/it/api/pagination). Filtra per `status` (`processing`, `pending_review`, `verified`, `rejected`, `exported`, `missing_document`), `source`, `search` e `date_from` / `date_to`. Con una chiave di test l'elenco contiene solo le fatture ricevute nella [sandbox](/it/api/sdi-receiving). MCP: `list_received_invoices`, e `list_collected_documents` per quelle ancora da controllare. ## Approvare o rifiutare [#approvare-o-rifiutare] ```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` porta una fattura da `pending_review` (o `rejected`) a `verified`, come quando la controlli nell'app. Già verificata: non cambia nulla. - `POST /received-invoices/{id}/reject` la porta da `pending_review` (o `verified`) a `rejected`: usalo per i documenti che non sono fatture. MCP: `approve_collected_document`, con `decision: "reject"` per rifiutare. ## Reverse charge sulle fatture estere [#reverse-charge-sulle-fatture-estere] Una fattura di un fornitore estero raccolta via email, dall'indirizzo di inoltro o da un caricamento porta `reverse_charge`: l'autofattura che getbeel ha proposto (`null` se non serve, per esempio fornitore italiano o fattura ricevuta dallo SDI). ```json title="reverse_charge" { "tipo_documento": "TD17", "status": "proposed", "reason": "non_eu_services", "deadline_basis": "effettuazione", "deadline": "2026-12-15" } ``` - `tipo_documento`: `TD17` servizi dall'estero, `TD18` beni da un altro stato UE, `TD19` beni già in Italia; `null` se nessun TD si applica o manca il paese del fornitore. Lo decide la regola, non l'AI. - `status`, lo stato attuale della proposta: `proposed` (la bozza XML è generata da sola), `needs_review` (verificala prima nella pagina Autofatture), `needs_country` (inserisci il paese del fornitore), `not_required` (beni importati da fuori UE: vale il documento doganale, nessun TD), `generated` (la bozza XML esiste, non inviata), `sent` (consegnata allo SDI), `dismissed` (eliminata dal team). - `reason` e `deadline` sono quelli fissati dalla regola quando la proposta è stata creata (o quando il team ne ha impostato paese e tipo). - `deadline`: il 15 del mese successivo alla ricezione della fattura (fornitori UE, `receipt`) o all'acquisto (fornitori extra UE, `effettuazione`), art. 1, c. 3-bis, lett. b, d.lgs. 127/2015. L'invio dell'autofattura allo SDI lo fa sempre una persona nell'app. Regole e fonti: [Autofatture](/it/guide/autofatture). ## Caricare una fattura [#caricare-una-fattura] Invia un PDF, JPEG, PNG o WEBP (fino a 50 MB) da far leggere all'AI, come un caricamento nell'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="Risposta" { "object": "received_invoice_upload", "id": "scan_1794408453000_k3j9x2a", "status": "pending", "files": 1, "processed": 0, "skipped": 0, "error": null } ``` - Invia `file_url` (un URL `https` pubblico, senza redirect) oppure `file_base64` con `file_name`. Il tipo si legge dal file, non dal nome. - Ogni file usa un credito fattura ([Prezzi](/it/api/pricing)). - `GET /received-invoices/uploads/{id}` lo segue: `pending` e `processing` mentre l'AI lo legge, `completed` quando la fattura è nell'elenco con `status: "pending_review"`, `failed` con il motivo in `error`. `skipped` conta i file che non erano fatture o erano duplicati. | Stato | `code` | Quando | | ----- | ----------------------- | -------------------------------------------------------------------------------------------------------- | | 413 | `payload_too_large` | Il file supera i 50 MB | | 415 | `unsupported_file_type` | Non è un PDF, JPEG, PNG o WEBP (gli XML FatturaPA arrivano dalla [ricezione SDI](/it/api/sdi-receiving)) | | 402 | `credits_exhausted` | Crediti fattura esauriti | MCP: `upload_received_invoice`, `get_received_invoice_upload`. ## Categorie [#categorie] Le categorie archiviano le fatture ricevute per tipo di costo. Una fattura ricevuta porta lo `slug` della categoria 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` le elenca nell'ordine dell'app. `POST /categories` ne aggiunge una: lo slug viene dal nome, il colore dal prossimo predefinito, se non invii `color` (`#rrggbb` o `hsl()`). - `PATCH /categories/{id}` rinomina o ricolora una categoria; lo slug resta. `DELETE /categories/{id}` la elimina e sposta le sue fatture in `other`. Le categorie predefinite non si eliminano (`409 default_category`). - `POST /received-invoices/{id}/category` con `{ "category": "software" }` imposta la categoria di una fattura (`422 unknown_category` per uno slug che il team non ha). MCP: `list_categories`, `create_category`, `update_category`, `delete_category`, `set_received_invoice_category`. ## Regole AI [#regole-ai] Istruzioni in linguaggio naturale che l'AI segue, in ordine, quando legge le tue fatture. Le stesse regole di **Impostazioni → Regole AI**. ```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` è `invoice_scan` (il predefinito: la lettura delle fatture ricevute) o `fattura_emessa` (le bozze delle fatture emesse dai pagamenti Stripe). Lo scope segue il tipo: le regole `invoice_scan` richiedono gli scope `received_invoices`, quelle `fattura_emessa` gli scope `invoices`. - Una regola nuova va in fondo al suo tipo e vale per le prossime fatture che l'AI legge; quelle già lette restano come sono. - `GET /ai-rules` le elenca (filtra con `type`). `PATCH /ai-rules/{id}` cambia il testo o mette in pausa la regola (`"active": false`). `DELETE /ai-rules/{id}` la elimina. MCP: `list_ai_rules`, `create_ai_rule`, `update_ai_rule`, `delete_ai_rule`. ## Correlati [#correlati] - [Connessioni](/it/api/connections): collega una casella e cercaci le fatture. - [Ricezione SDI](/it/api/sdi-receiving): ricevi le fatture dei fornitori direttamente dallo SDI. - [Webhook](/it/api/webhooks): `received_invoice.created` per ogni nuova fattura. # Fatture ricorrenti (https://docs.getbeel.com/it/api/recurring-invoices) Ripeti una fattura ogni mese, trimestre o anno, con l'invio allo SDI facoltativo. Una fattura ricorrente parte da una fattura che hai già (il **modello**): ogni mese, trimestre o anno Getbeel ne crea una copia in bozza con la data del giorno, il numero successivo e lo stesso termine di pagamento (la scadenza si sposta degli stessi giorni). Con `auto_send` la nuova fattura va anche allo SDI. Scope `invoices:write` (letture `invoices:read`). Nell'app: apri una fattura emessa e scegli **Rendi ricorrente**; l'elenco è in **Fatture emesse → Fatture ricorrenti**, con pausa e ripresa. ## Crea [#crea] ```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` o `yearly`. - `start_date` (facoltativo, da oggi in poi): la data della prima nuova fattura. Di default è la prima data dopo oggi nella serie `invoice_date` + n × intervallo. Una ricorrenza il 31 passa al 28 dopo febbraio (si tiene il giorno della prossima data salvata). - `auto_send`: invia allo SDI ogni nuova fattura. Con una chiave live è una trasmissione reale; con una chiave di test va alla sandbox. Le proforma non vengono mai inviate. Una sola ricorrenza per fattura (`409 recurring_invoice_exists`). Una fattura che non si può copiare (dati non validi) risponde `422 invoice_not_copyable`. ## Come gira [#come-gira] Ogni mattina Getbeel crea le fatture delle ricorrenze arrivate a `next_date` e sposta `next_date` al periodo successivo. Le fatture live seguono le stesse regole dell'app: servono l'add-on SDI e la quota. Se la creazione non riesce (ad esempio quota esaurita) `last_error` lo spiega e Getbeel riprova il giorno dopo; `last_invoice_id` è l'ultima fattura creata. Le chiavi di test vedono e creano solo ricorrenze sandbox, quelle live solo ricorrenze reali. ## Gestisci [#gestisci] ```bash # elenco curl https://www.getbeel.com/api/v1/recurring-invoices \ -H "Authorization: Bearer $GETBEEL_API_KEY" # pausa e ripresa 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" # modifica 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 }' # elimina (le fatture già create restano) curl -X DELETE https://www.getbeel.com/api/v1/recurring-invoices/$ID \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Alla ripresa, una `next_date` già passata salta al periodo successivo: niente fatture arretrate. ## Con un assistente AI [#con-un-assistente-ai] Lo strumento MCP `create_recurring_invoice` crea la ricorrenza dopo averti chiesto conferma di intervallo e data; imposta `auto_send` solo se lo chiedi tu. # Modalità di pagamento (MP) (https://docs.getbeel.com/it/api/reference-data/modalita-pagamento) I valori di ModalitaPagamento della FatturaPA, da MP01 a MP23. Corrisponde al campo `2.4.2.2 ModalitaPagamento` dei dati di pagamento. | Codice | Descrizione | | ------ | ------------------------------------------ | | `MP01` | Contanti | | `MP02` | Assegno | | `MP03` | Assegno circolare | | `MP04` | Contanti presso Tesoreria | | `MP05` | Bonifico | | `MP06` | Vaglia cambiario | | `MP07` | Bollettino bancario | | `MP08` | Carta di pagamento | | `MP09` | RID | | `MP10` | RID utenze | | `MP11` | RID veloce | | `MP12` | RIBA | | `MP13` | MAV | | `MP14` | Quietanza erario stato | | `MP15` | Giroconto su conti di contabilità speciale | | `MP16` | Domiciliazione bancaria | | `MP17` | Domiciliazione postale | | `MP18` | Bollettino di c/c postale | | `MP19` | SEPA Direct Debit | | `MP20` | SEPA Direct Debit CORE | | `MP21` | SEPA Direct Debit B2B | | `MP22` | Trattenuta su somme già riscosse | | `MP23` | PagoPA | Il caso più comune tra aziende è `MP05` (bonifico), con l'IBAN nei dati di pagamento. Fonte: Agenzia delle Entrate, Specifiche tecniche del formato FatturaPA versione 1.4. # Natura IVA (N) (https://docs.getbeel.com/it/api/reference-data/natura) I codici natura per le righe senza IVA, da N1 a N7 con i sottocodici. `natura` corrisponde al campo `Natura` della FatturaPA (`2.2.1.14` nelle righe, `2.2.2.2` nel riepilogo). Si indica **solo** quando l'aliquota IVA è zero e spiega perché l'IVA non si applica. | Codice | Descrizione | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `N1` | Escluse ex art. 15 | | `N2.1` | Non soggette ad IVA ai sensi degli artt. da 7 a 7-septies del DPR 633/72 | | `N2.2` | Non soggette – altri casi | | `N3.1` | Non imponibili – esportazioni | | `N3.2` | Non imponibili – cessioni intracomunitarie | | `N3.3` | Non imponibili – cessioni verso San Marino | | `N3.4` | Non imponibili – operazioni assimilate alle cessioni all'esportazione | | `N3.5` | Non imponibili – a seguito di dichiarazioni d'intento | | `N3.6` | Non imponibili – altre operazioni che non concorrono alla formazione del plafond | | `N4` | Esenti | | `N5` | Regime del margine / IVA non esposta in fattura | | `N6.1` | Inversione contabile – cessione di rottami e altri materiali di recupero | | `N6.2` | Inversione contabile – cessione di oro e argento puro | | `N6.3` | Inversione contabile – subappalto nel settore edile | | `N6.4` | Inversione contabile – cessione di fabbricati | | `N6.5` | Inversione contabile – cessione di telefoni cellulari | | `N6.6` | Inversione contabile – cessione di prodotti elettronici | | `N6.7` | Inversione contabile – prestazioni comparto edile e settori connessi | | `N6.8` | Inversione contabile – operazioni settore energetico | | `N6.9` | Inversione contabile – altri casi | | `N7` | IVA assolta in altro stato UE (vendite a distanza ex art. 40 commi 3 e 4 e art. 41 comma 1 lett. b, DL 331/93; prestazione di servizi di telecomunicazioni, tele-radiodiffusione ed elettronici ex art. 7-octies, comma 1 lett. a, b e art. 74-sexies, DPR 633/72) | ## Codici non più validi [#codici-non-più-validi] Dal 1° gennaio 2021 i codici generici `N2`, `N3` e `N6` non sono più ammessi: va usato il sottocodice. Una fattura che li usa viene scartata con il codice `00445`. ## Errori frequenti [#errori-frequenti] | Codice SDI | Causa | | ----------------- | -------------------------------------------------------------------------------------- | | `00400` | Aliquota zero in una riga senza `natura` | | `00401` | `natura` in una riga con aliquota diversa da zero (ammesso solo con `TD16`) | | `00429` / `00430` | Lo stesso problema nei dati di riepilogo | | `00444` | Una `natura` delle righe non compare nel riepilogo | | `00420` | Natura `N6.x` (inversione contabile) con esigibilità IVA `S` (scissione dei pagamenti) | Quale natura usare dipende dall'operazione: nel dubbio chiedi al tuo commercialista. Fonte: Agenzia delle Entrate, Specifiche tecniche del formato FatturaPA versione 1.4. # Regime fiscale (RF) (https://docs.getbeel.com/it/api/reference-data/regime-fiscale) I valori di regime_fiscale del cedente/prestatore, da RF01 a RF20. `regime_fiscale` corrisponde al campo `1.2.1.8 RegimeFiscale` del cedente/prestatore: il regime fiscale di chi emette la fattura. | Codice | Descrizione | | ------ | -------------------------------------------------------------------------------------------------------------------------- | | `RF01` | Ordinario | | `RF02` | Contribuenti minimi (art. 1, c. 96-117, L. 244/2007) | | `RF04` | Agricoltura e attività connesse e pesca (artt. 34 e 34-bis, D.P.R. 633/1972) | | `RF05` | Vendita sali e tabacchi (art. 74, c. 1, D.P.R. 633/1972) | | `RF06` | Commercio dei fiammiferi (art. 74, c. 1, D.P.R. 633/1972) | | `RF07` | Editoria (art. 74, c. 1, D.P.R. 633/1972) | | `RF08` | Gestione di servizi di telefonia pubblica (art. 74, c. 1, D.P.R. 633/1972) | | `RF09` | Rivendita di documenti di trasporto pubblico e di sosta (art. 74, c. 1, D.P.R. 633/1972) | | `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) | | `RF11` | Agenzie di viaggi e turismo (art. 74-ter, D.P.R. 633/1972) | | `RF12` | Agriturismo (art. 5, c. 2, L. 413/1991) | | `RF13` | Vendite a domicilio (art. 25-bis, c. 6, D.P.R. 600/1973) | | `RF14` | Rivendita di beni usati, di oggetti d'arte, d'antiquariato o da collezione (art. 36, D.L. 41/1995) | | `RF15` | Agenzie di vendite all'asta di oggetti d'arte, antiquariato o da collezione (art. 40-bis, D.L. 41/1995) | | `RF16` | IVA per cassa P.A. (art. 6, c. 5, D.P.R. 633/1972) | | `RF17` | IVA per cassa (art. 32-bis, D.L. 83/2012) | | `RF18` | Altro | | `RF19` | Regime forfettario (art. 1, c. 54-89, L. 190/2014) | | `RF20` | Regime transfrontaliero di Franchigia IVA (Direttiva UE 2020/285) | - `RF03` (nuove iniziative produttive) è stato eliminato nel 2017 e non è più ammesso. - `RF20` è stato aggiunto con la versione 1.9 delle specifiche tecniche (gennaio 2025). - Chi è in regime forfettario (`RF19`) di norma emette fatture senza IVA con natura `N2.2`. Fonte: Agenzia delle Entrate, Specifiche tecniche del formato FatturaPA versione 1.4. # Codici di scarto SDI (https://docs.getbeel.com/it/api/reference-data/sdi-errors) Ogni codice delle ricevute di scarto dello SDI, con la causa e come correggerlo. Quando un controllo non passa, lo SDI invia una **ricevuta di scarto (NS)** con uno o più codici a 5 cifre e una breve descrizione. In Getbeel i codici sono in `sdi.error_codes` e, con la descrizione dello SDI, in `sdi.errors` della [fattura](/it/api/reference); il webhook `invoice.rejected` porta la fattura completa in `data.object`. Una fattura scartata **si considera mai emessa**: correggi quello che dice il codice e inviala di nuovo con lo stesso numero e la stessa data, preferibilmente entro 5 giorni dalla ricevuta di scarto. L'unica eccezione è `00404` su una fattura già inviata: vedi sotto. Il quadro completo degli esiti è nel [ciclo di vita SDI](/it/api/sdi-lifecycle). ## Le ricevute dello SDI [#le-ricevute-dello-sdi] | Ricevuta | Significato | Stato in Getbeel | | ----------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------- | | RC, ricevuta di consegna | Fattura recapitata al destinatario: emessa | `delivered` | | MC, ricevuta di impossibilità di recapito | Non recapitata ma **emessa**: è nel cassetto fiscale del cliente da `sdi.available_since` | `not_delivered` | | NS, ricevuta di scarto | File rifiutato: la fattura si considera mai emessa | `rejected` | | NE, notifica di esito (PA) | Accettazione o rifiuto da parte di una Pubblica Amministrazione | Accettazione: `delivered`; rifiuto: `rejected` | | DT, decorrenza termini (PA) | La PA non ha risposto entro 15 giorni | `delivered` | ## 00404: duplicato di una fattura emessa [#00404-duplicato-di-una-fattura-emessa] `00404` ("Fattura duplicata") significa che lo SDI ha **già accettato** un documento con lo stesso cedente, lo stesso anno della data e lo stesso numero (per le autofatture TD16–TD20, TD22, TD23, TD28 e TD29 conta il cessionario). Il controllo non scatta se il documento precedente era stato scartato, e una nota di credito (`TD04`) può avere lo stesso numero di una fattura. - **Su una fattura che avevi già inviato** (per esempio un secondo invio dello stesso documento): la fattura **è emessa**, perché lo SDI ne ha una copia accettata. Non rigenerarla e non inviarla di nuovo: verrebbe scartata ancora con `00404`. Getbeel la lascia nello stato che aveva, con `00404` in `sdi.error_codes`, e nell'app la mostra come **Già emessa · duplicato**. - **Su una fattura nuova** che per errore ha il numero di un'altra già emessa nello stesso anno: questa fattura non è emessa. Dalle un numero libero (Getbeel assegna il successivo) e inviala. ## Tutti i codici [#tutti-i-codici] Codici e descrizioni dell'Allegato A alle specifiche tecniche, versione 1.9.1, Appendice 1 (pp. 112–123), e delle Specifiche tecniche del Sistema di Interscambio, versione 1.8.4 (controlli sul file: 00302, 00304, 00398, 00399). Il codice 00448 riguarda i dati fattura (Appendice 2), non le fatture elettroniche, e non è elencato. Le descrizioni dello SDI sono abbreviate; il numero prima del nome del campo (per esempio 1.4.1.1.2) è la sua posizione nel tracciato FatturaPA. ### Nome, dimensioni e firma del file [#nome-dimensioni-e-firma-del-file] Getbeel genera nome file e XML e non firma le fatture (lo SDI accetta file non firmati), quindi questi codici arrivano solo da file preparati altrove. | Codice | Messaggio SDI | Causa | Come correggere | | ------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `00001` | Nome file non valido | Il nome del file non segue lo schema `IT_.xml` | Rinomina il file secondo lo schema (Getbeel lo fa da solo) | | `00002` | Nome file duplicato | Un file con lo stesso nome è già stato inviato allo SDI, anche se scartato | Reinvia con un nuovo nome file (un nuovo progressivo) | | `00003` | Le dimensioni del file superano quelle ammesse | Il file supera il limite del canale di trasmissione | Riduci il file, per esempio gli allegati, o dividi il lotto | | `00100` | Certificato di firma scaduto | Il file è firmato con un certificato scaduto | Firma con un certificato valido, oppure invia il file senza firma | | `00101` | Certificato di firma revocato | Il certificato di firma è stato revocato | Come sopra | | `00102` | La firma elettronica apposta al file non risulta valida | Il file è stato modificato dopo la firma | Firma di nuovo il file definitivo, oppure invialo senza firma | | `00103` | Alla firma manca il riferimento temporale | Firma qualificata senza riferimento temporale | Firma con riferimento temporale, oppure invia senza firma | | `00104` | La CA del certificato non è nell'elenco delle CA affidabili | Certificato emesso da un'autorità non riconosciuta | Usa un certificato di una CA accreditata, oppure invia senza firma | | `00105` | Riferimento temporale della firma successivo alla ricezione | La data della firma è nel futuro rispetto all'invio | Correggi l'orologio di chi firma e firma di nuovo | | `00106` | Il file compresso è vuoto oppure non è leggibile | Archivio ZIP vuoto o danneggiato | Ricrea l'archivio e reinvialo | | `00107` | Il certificato di firma non è valido | Certificato non valido per altri motivi | Firma con un certificato valido, oppure invia senza firma | ### Formato [#formato] | Codice | Messaggio SDI | Causa | Come correggere | | ------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `00200` | File non conforme al formato | L'XML non rispetta lo schema XSD FatturaPA; il messaggio indica il punto esatto | Correggi il campo indicato; valida prima con `POST /invoices/validate` | | `00201` | Superato il numero massimo di errori di formato (50) | Troppi errori di formato: la ricevuta non li elenca tutti | Valida l'XML con `POST /invoices/validate` e correggi tutti gli errori | | `00428` | `FormatoTrasmissione` non coerente con l'attributo `versione` | Per esempio `FPR12` in `FormatoTrasmissione` con `versione="FPA12"` | Usa lo stesso valore nei due punti: `FPR12` per privati, `FPA12` per la PA | ### Identificativi fiscali e destinatario [#identificativi-fiscali-e-destinatario] | Codice | Messaggio SDI | Causa | Come correggere | | ------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `00300` | 1.1.1.2 `IdCodice` (trasmittente) non valido | Il codice fiscale del trasmittente non risulta in Anagrafe Tributaria | Correggi l'identificativo del trasmittente (con Getbeel è il canale di trasmissione: contatta l'assistenza) | | `00301` | 1.2.1.1.2 `IdCodice` (cedente) non valido | La partita IVA di chi emette non risulta in Anagrafe Tributaria | Controlla la partita IVA in Impostazioni → Azienda | | `00302` | 1.2.1.2 `CodiceFiscale` (cedente) non valido | Il codice fiscale di chi emette non risulta in Anagrafe Tributaria | Correggi il codice fiscale in Impostazioni → Azienda e reinvia | | `00303` | 1.3.1.1.2 o 1.4.4.1.2 `IdCodice` (rappresentante fiscale) non valido | La partita IVA del rappresentante fiscale non risulta | Correggi la partita IVA del rappresentante fiscale | | `00304` | 1.3.1.2 `CodiceFiscale` (rappresentante fiscale) non valido | Il codice fiscale del rappresentante fiscale non risulta in Anagrafe Tributaria | Correggi il codice fiscale del rappresentante fiscale e reinvia | | `00305` | 1.4.1.1.2 `IdCodice` (cessionario) non valido | La partita IVA del cliente non risulta in Anagrafe Tributaria | Verifica la partita IVA del cliente (per esempio con il servizio dell'Agenzia o VIES) e correggila | | `00306` | 1.4.1.2 `CodiceFiscale` (cessionario) non valido | Il codice fiscale del cliente non esiste (controllato solo se manca la partita IVA) | Correggi il codice fiscale del cliente | | `00311` | 1.1.4 `CodiceDestinatario` non valido | Il codice destinatario non esiste | Chiedi al cliente il codice corretto, oppure usa `0000000` con la sua PEC o senza (la fattura andrà nel suo cassetto fiscale) | | `00312` | 1.1.4 `CodiceDestinatario` non attivo | Il canale del codice destinatario è disattivato | Come sopra | | `00313` | `CodiceDestinatario` `XXXXXXX` solo per non residenti | `XXXXXXX` usato per un cliente italiano o senza `IdFiscaleIVA` estero | Per un cliente italiano usa il suo codice o `0000000`; `XXXXXXX` solo con `IdPaese` diverso da `IT` | | `00320` | `IdFiscaleIVA` e `CodiceFiscale` del cedente non coerenti | Partita IVA e codice fiscale dell'emittente appartengono a soggetti diversi | Correggi uno dei due nel profilo aziendale | | `00321` | `CodiceFiscale` del cedente di soggetto non partecipante al gruppo IVA | Con la partita IVA di un gruppo IVA, il codice fiscale non è di una società del gruppo | Indica il codice fiscale della società partecipante che emette | | `00322` | `CodiceFiscale` del cedente mancante con `IdFiscaleIVA` di gruppo IVA | Partita IVA di gruppo senza il codice fiscale della partecipante | Aggiungi il codice fiscale della società partecipante | | `00323` | `IdCodice` del cedente di una partita IVA cessata da oltre 5 anni | La partita IVA del cedente è cessata da più di 5 anni (nelle autofatture il cedente è il fornitore) | Controlla la partita IVA del cedente e usa quella attiva | | `00324` | `IdFiscaleIVA` e `CodiceFiscale` del cessionario non coerenti | Partita IVA e codice fiscale del cliente appartengono a soggetti diversi | Correggi uno dei due nei dati del cliente | | `00325` | `CodiceFiscale` del cessionario di soggetto non partecipante al gruppo IVA | Cliente con partita IVA di gruppo e codice fiscale di un soggetto esterno al gruppo | Indica il codice fiscale della società del gruppo che acquista | | `00326` | `CodiceFiscale` del cessionario mancante con `IdFiscaleIVA` di gruppo IVA | Partita IVA di gruppo del cliente senza codice fiscale della partecipante | Aggiungi il codice fiscale della società partecipante | | `00327` | `CodiceFiscale` del cessionario di gruppo IVA non riferito a un partecipante | Senza partita IVA, è indicato il codice fiscale del gruppo IVA invece di quello di una partecipante | Indica il codice fiscale della società partecipante al gruppo | | `00330` | `PECDestinatario` contenente un valore non ammesso | La PEC indicata è una casella dello SDI | Indica la PEC del cliente | | `00398` | Codice Ufficio non identificabile in IPA con `CodiceDestinatario` dell'ufficio "Centrale" | Fattura a una Pubblica Amministrazione inviata al codice dell'ufficio "Centrale" senza che lo SDI possa individuare un solo ufficio dell'ente | Usa il codice univoco dell'ufficio destinatario indicato dall'ente (IPA, indicepa.gov.it) e reinvia | | `00399` | `CessionarioCommittente` presente in IPA con `FormatoTrasmissione` `FPR12` | Il cliente è una Pubblica Amministrazione ma la fattura usa il formato tra privati | Emetti la fattura nel formato PA (`FPA12`) con il codice univoco ufficio e reinvia | | `00417` | `IdFiscaleIVA` e `CodiceFiscale` del cessionario non valorizzati | Il cliente non ha né partita IVA né codice fiscale | Indica almeno uno dei due | | `00427` | `CodiceDestinatario` di lunghezza non coerente con `FormatoTrasmissione` | 7 caratteri con `FPA12`, o 6 con `FPR12` | Privati: codice di 7 caratteri con `FPR12`. PA: codice ufficio di 6 caratteri con `FPA12` | ### Contenuto e calcoli [#contenuto-e-calcoli] | Codice | Messaggio SDI | Causa | Come correggere | | ------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | `00400` | `Natura` non presente con `AliquotaIVA` pari a zero (righe) | Una riga a IVA zero senza natura | Indica la [natura](/it/api/reference-data/natura) della riga | | `00401` | `Natura` presente con `AliquotaIVA` diversa da zero (righe) | Natura su una riga con IVA | Togli la natura (è ammessa solo con `TD16`) | | `00403` | 2.1.1.3 `Data` successiva alla data di ricezione | La data della fattura è nel futuro | Usa la data di oggi o una passata | | `00411` | `DatiRitenuta` mancante con righe soggette a ritenuta | Una riga ha `Ritenuta` = `SI` ma manca il blocco della ritenuta | Aggiungi la ritenuta (tipo, aliquota, importo, causale) | | `00413` | `Natura` mancante con aliquota zero nella cassa previdenziale | Contributo cassa a IVA zero senza natura | Indica la natura del contributo | | `00414` | `Natura` presente con aliquota diversa da zero nella cassa previdenziale | Contributo cassa con IVA e natura | Togli la natura dal contributo | | `00415` | `DatiRitenuta` mancante con cassa previdenziale soggetta a ritenuta | Contributo con `Ritenuta` = `SI` senza blocco ritenuta | Aggiungi la ritenuta | | `00418` | 2.1.1.3 `Data` antecedente a quella del documento collegato | Per esempio una nota di credito datata prima della fattura che rettifica | Usa una data uguale o successiva a quella del documento collegato | | `00419` | `DatiRiepilogo` mancante per un'aliquota IVA presente | Un'aliquota delle righe o della cassa non ha il suo riepilogo | Aggiungi un riepilogo per ogni aliquota | | `00420` | Natura `N6.x` con esigibilità IVA `S` (scissione dei pagamenti) | Reverse charge e split payment insieme | Scegli uno dei due regimi: con la natura N6 l'esigibilità non può essere `S` | | `00421` | 2.2.2.6 `Imposta` non calcolata secondo le regole | `Imposta` ≠ `ImponibileImporto` × `AliquotaIVA` / 100, arrotondata a 2 decimali (tolleranza 1 centesimo) | Ricalcola l'imposta di ogni riepilogo | | `00422` | 2.2.2.5 `ImponibileImporto` non calcolato secondo le regole | L'imponibile del riepilogo non è la somma delle righe, dei contributi e degli arrotondamenti di quell'aliquota (tolleranza 1 euro) | Somma le righe per aliquota | | `00423` | 2.2.1.11 `PrezzoTotale` non calcolato secondo le regole | Totale di riga ≠ (prezzo unitario ± sconti) × quantità (tolleranza 1 centesimo) | Ricalcola il totale della riga | | `00424` | `AliquotaIVA` non indicata in termini percentuali | Aliquota scritta come `0.22` | Scrivi `22.00` | | `00425` | 2.1.1.4 `Numero` non contenente caratteri numerici | Il numero della fattura non ha cifre | Il numero deve contenere almeno una cifra | | `00429` | `Natura` non presente con `AliquotaIVA` pari a zero (riepilogo) | Riepilogo a IVA zero senza natura | Indica la natura nel riepilogo | | `00430` | `Natura` presente con `AliquotaIVA` diversa da zero (riepilogo) | Natura in un riepilogo con IVA | Togli la natura (ammessa solo con `TD16`) | | `00437` | Sconto o maggiorazione del documento senza percentuale né importo | È indicato il tipo di sconto ma non quanto | Indica la percentuale o l'importo | | `00438` | Sconto o maggiorazione di riga senza percentuale né importo | Come sopra, su una riga | Indica la percentuale o l'importo | | `00443` | Aliquote IVA delle righe non presenti nel riepilogo | Un'aliquota delle righe o della cassa manca nei riepiloghi | Aggiungi il riepilogo di quell'aliquota | | `00444` | Nature delle righe non presenti nel riepilogo | Una natura delle righe o della cassa manca nei riepiloghi | Aggiungi il riepilogo di quella natura | | `00445` | Natura generica `N2`, `N3` o `N6` non più ammessa | Codice natura "padre" (dal 2021 non valido) | Usa il sottocodice, per esempio `N2.2` | | `00460` | Importo oltre il limite della fattura semplificata | Fattura semplificata oltre 400 euro (salvo `RF19`, `RF20` o rettifiche) | Emetti una fattura ordinaria (`TD01`) | | `00471` | Per questo tipo documento cedente e cessionario devono essere diversi | Lo stesso soggetto come cedente e cessionario con `TD01`, `TD02`, `TD03`, `TD06`, `TD16`–`TD20`, `TD24`, `TD25`, `TD28`, `TD29` (o `TD07`) | Correggi il cliente, o usa il tipo documento giusto (per esempio `TD27` per l'autoconsumo) | | `00472` | Per questo tipo documento cedente e cessionario devono coincidere | `TD21` o `TD27` con un cessionario diverso dal cedente | Indica te stesso come cessionario, o cambia tipo documento | | `00473` | Paese del cedente non ammesso per questo tipo documento | `TD17`, `TD18`, `TD19` o `TD28` con un cedente italiano, o `TD29` con un cedente estero | Indica il fornitore estero come cedente (o `IT` per `TD29`); per un fornitore italiano non serve l'autofattura | | `00474` | Per questo tipo documento non sono ammesse righe con aliquota zero | Autofattura per splafonamento (`TD21`) con righe a IVA zero | Ogni riga deve avere un'aliquota diversa da zero | | `00475` | Per questo tipo documento serve la partita IVA del cessionario | `TD16`–`TD20`, `TD22`, `TD23`, `TD28` o `TD29` senza `IdFiscaleIVA` del cessionario | Indica la partita IVA del cessionario | | `00476` | Cedente e cessionario entrambi con paese diverso da `IT` | Fattura tra due soggetti esteri | Almeno uno dei due deve avere `IdPaese` `IT`; una fattura tra soggetti esteri non passa dallo SDI | | `00477` | Non imponibilità art. 8, c. 1, lett. c) con dichiarazione d'intento invalidata | La dichiarazione d'intento citata è stata invalidata dall'Agenzia | Fattura con IVA, oppure chiedi al cliente una dichiarazione d'intento valida | ### Unicità [#unicità] | Codice | Messaggio SDI | Causa | Come correggere | | ------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `00404` | Fattura duplicata | Lo SDI ha già accettato un documento con stesso cedente (o cessionario per le autofatture), stesso anno e stesso numero | Su una fattura già inviata: **è emessa, non rigenerarla né reinviarla** (vedi sopra). Su una fattura nuova: usa un numero libero | | `00409` | Fattura duplicata nel lotto | Due fatture con lo stesso numero e anno nello stesso file | Dai un numero diverso a ogni fattura del lotto | Fonti: Agenzia delle Entrate, [Allegato A, Specifiche tecniche versione 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) (31 marzo 2026), Appendice 1 "Elenco dei codici errore relativi alla fattura ordinaria e a quella semplificata", pp. 112–123 (unicità: pp. 122–123); [Specifiche tecniche del Sistema di Interscambio versione 1.8.4](https://www.fatturapa.gov.it/export/documenti/Specifiche-tecniche-relative-al-Sistema-di-Interscambio-versione-1.8.4.pdf) (31 marzo 2026), controlli sul file; [documentazione SDI su 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), dicembre 2025, pp. 16–18; circolare 13/E del 2 luglio 2018, § 1.6 (reinvio entro 5 giorni con stessa data e numero). Le cause e le correzioni spiegano le descrizioni ufficiali; i messaggi sono abbreviati. # Tipo documento (TD) (https://docs.getbeel.com/it/api/reference-data/tipo-documento) I valori di tipo_documento ammessi dalla FatturaPA, da TD01 a TD29. `tipo_documento` corrisponde al campo `2.1.1.1 TipoDocumento` della FatturaPA. ## Fattura ordinaria [#fattura-ordinaria] | Codice | Descrizione | Note | | ------ | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `TD01` | Fattura | Il caso normale | | `TD02` | Acconto/anticipo su fattura | | | `TD03` | Acconto/anticipo su parcella | | | `TD04` | Nota di credito | Storno totale o parziale di una fattura | | `TD05` | Nota di debito | | | `TD06` | Parcella | Professionisti | | `TD16` | Integrazione fattura reverse charge interno | Autofattura | | `TD17` | Integrazione/autofattura per acquisto servizi dall'estero | Autofattura, fornitore estero | | `TD18` | Integrazione per acquisto di beni intracomunitari | Autofattura, fornitore UE | | `TD19` | Integrazione/autofattura per acquisto di beni ex art. 17 c. 2 DPR 633/72 | Autofattura | | `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) | | | `TD21` | Autofattura per splafonamento | Cedente e cessionario coincidono | | `TD22` | Estrazione beni da Deposito IVA | | | `TD23` | Estrazione beni da Deposito IVA con versamento dell'IVA | | | `TD24` | Fattura differita di cui all'art. 21, comma 4, lett. a) | Beni con DDT o servizi documentati | | `TD25` | Fattura differita di cui all'art. 21, comma 4, terzo periodo lett. b) | Triangolazioni | | `TD26` | Cessione di beni ammortizzabili e per passaggi interni (ex art. 36 DPR 633/72) | | | `TD27` | Fattura per autoconsumo o per cessioni gratuite senza rivalsa | Cedente e cessionario coincidono | | `TD28` | Acquisti da San Marino con IVA (fattura cartacea) | | | `TD29` | Comunicazione per omessa o irregolare fatturazione (art. 6, comma 8, D.Lgs. 471/97) | Dalla versione 1.9 delle specifiche | I codici da `TD07` a `TD15` non si usano nella fattura ordinaria. ## Fattura semplificata [#fattura-semplificata] | Codice | Descrizione | | ------ | ---------------------------- | | `TD07` | Fattura semplificata | | `TD08` | Nota di credito semplificata | | `TD09` | Nota di debito semplificata | ## Controlli dello SDI legati al tipo documento [#controlli-dello-sdi-legati-al-tipo-documento] - `00471`: per `TD01`, `TD02`, `TD03`, `TD06`, `TD16`–`TD20`, `TD24`, `TD25`, `TD28`, `TD29` (e `TD07`) cedente e cessionario devono essere soggetti diversi. - `00472`: per `TD21` e `TD27` cedente e cessionario devono coincidere. - `00473`: `TD17`, `TD18`, `TD19` e `TD28` non ammettono un cedente italiano; `TD29` richiede un cedente italiano. - `00475`: `TD16`–`TD20`, `TD22`, `TD23`, `TD28` e `TD29` richiedono la partita IVA del cessionario. Dettagli in [Codici di scarto SDI](/it/api/reference-data/sdi-errors). Fonte: Agenzia delle Entrate, Specifiche tecniche del formato FatturaPA versione 1.4 e Allegato A, specifiche tecniche versione 1.9 (31 gennaio 2025). # Riferimento API (https://docs.getbeel.com/it/api/reference) Ogni endpoint, generato dal documento OpenAPI, con il playground. Queste pagine sono generate dal documento OpenAPI 3.1 dell'API, quindi sono sempre allineate al codice. Il documento è scaricabile da [`/openapi.json`](https://docs.getbeel.com/openapi.json) per generare client e SDK. Le descrizioni degli endpoint sono in inglese, come i nomi dei campi. ## Playground [#playground] Ogni pagina ha un playground per provare la richiesta dal browser. Le richieste passano da un proxy di questo sito, che inoltra solo all'API di Getbeel e non registra i corpi. Nel campo `Authorization` scrivi `Bearer gb_test_…`. Il playground gira nel tuo browser: non incollarci una chiave live. ## Convenzioni [#convenzioni] - URL di base: `https://www.getbeel.com/api/v1`. - Autenticazione: [chiave API](/it/api/authentication) nell'header `Authorization`. - Errori: [forma comune](/it/api/errors) `{ "error": { type, code, message, param } }`. - Elenchi: [paginazione a cursore](/it/api/pagination). - `POST` che creano o inviano: header [`Idempotency-Key`](/it/api/idempotency). # Report ed export per il commercialista (https://docs.getbeel.com/it/api/reports) Conto economico, flussi di cassa e crediti per scadenza dai dati in Getbeel, e lo ZIP con XML, prima nota IVA e registri da dare al commercialista. Getbeel calcola tre **report gestionali** dalle fatture e dai movimenti bancari che ha già, e prepara uno **ZIP per il commercialista** con le fatture elettroniche XML, la prima nota IVA e i registri. Sono le stesse sezioni dell'app **Tasse → IVA e report**. Scope: `taxes:read`. L'export contiene tutte le fatture e i movimenti bancari del periodo, quindi chiede anche `invoices:read`, `received_invoices:read` e `bank:read`. I report non sono il bilancio d'esercizio (artt. 2423 e seguenti c.c.): importi al netto dell'IVA, senza ratei e risconti, ammortamenti, personale, magazzino e imposte. `management_figures` è sempre `true` e `reliable` sempre `false`: mostrali come dati da verificare con il commercialista. ## Report [#report] ```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` è `profit-and-loss`, `cash-flow` o `aging`. `period` è un anno (`2026`), un trimestre (`2026-Q3`) o un mese (`2026-10`); in alternativa `from` e `to` (al massimo due anni). Senza nulla, l'anno in corso. La risposta ha `object: "report"`, `type`, `period`, `start`, `end`, `currency: "EUR"`, una `note` e uno fra `profit_and_loss`, `cash_flow` e `aging`. Gli importi sono stringhe decimali (`"1234.50"`). ### Conto economico (`profit-and-loss`) [#conto-economico-profit-and-loss] - **Ricavi**: fatture emesse accettate dallo SDI (consegnate o non consegnate), per data del documento. L'importo è l'imponibile del `DatiRiepilogo` (cassa previdenziale compresa, IVA e bollo esclusi), come nei [registri IVA](/it/api/vat-registers). Le note di credito (TD04, TD08) sottraggono. - **Costi**: fatture fornitore verificate, per data del documento, al netto dell'IVA (in euro, o al cambio per le altre valute), divise per `category`. Le note di credito sottraggono. - **Competenza**: art. 2423-bis, c. 1, n. 3 c.c. ("si deve tener conto dei proventi e degli oneri di competenza dell'esercizio, indipendentemente dalla data dell'incasso o del pagamento"). La data del documento fa da data di competenza: è la data dell'operazione per la fattura immediata (art. 21, c. 4 DPR 633/1972) e la fine del mese per la differita (TD24, TD25). Un servizio a cavallo di due periodi non viene ripartito. - **Non sono ricavi**: TD16–TD19 e TD28 (integrazioni in reverse charge: solo IVA, il costo è la fattura del fornitore), TD20 (autofattura di regolarizzazione: è un costo), TD21–TD23 (splafonamento, deposito IVA: solo IVA), TD26 (cessione di beni ammortizzabili: è ricavo la plusvalenza, che richiede il valore contabile), TD27 (autoconsumo e cessioni gratuite), TD29. - `not_included` elenca quello che resta fuori: fatture ancora allo SDI, fatture fornitore da verificare, cessioni TD26, documenti in valuta senza cambio. - `by_month` dà ricavi, costi e risultato di ogni mese. L'IVA indetraibile, che in contabilità è un costo, non è nota a Getbeel e non viene aggiunta. ### Flussi di cassa (`cash-flow`) [#flussi-di-cassa-cash-flow] Entrate e uscite dei conti in Getbeel (estratti conto caricati e banche collegate) per data contabile, mese per mese. Le uscite abbinate a una fattura fornitore (abbinamento approvato) sono raggruppate per la sua categoria, le altre in `unmatched`. `invoice_payments_recorded` riporta gli incassi registrati sulle fatture emesse (app, Stripe, API): sono mostrati a parte, mai sommati ai movimenti bancari. ### Crediti per scadenza (`aging`) [#crediti-per-scadenza-aging] Quanto devono ancora i clienti **oggi** sulle fatture emesse, per giorni di ritardo: `not_due`, `overdue_1_30`, `overdue_31_60`, `overdue_61_90`, `overdue_over_90`. `period`, `from` e `to` non si usano. - Residuo = totale del documento meno la ritenuta trattenuta dal cliente e le note di credito emesse (l'`ImportoPagamento`), meno l'IVA delle fatture in split payment, che la versa l'ente pubblico (art. 17-ter DPR 633/1972), meno gli incassi registrati. - Senza scadenza in fattura: 30 giorni dalla data della fattura (art. 4, c. 2, lett. a, D.Lgs. 231/2002, "trenta giorni dalla data di ricevimento da parte del debitore della fattura"; la data della fattura sta per quella di ricevimento). Queste righe hanno `due_date_assumed: true`. - `customers` somma per cliente; `invoices` elenca le fatture, le più in ritardo prima (al massimo 1.000, poi `has_more`). ## Export per il commercialista [#export-per-il-commercialista] ```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` è un anno, un trimestre o un mese. Solo aziende italiane. Lo ZIP contiene: | Cartella o file | Contenuto | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `fatture-emesse/` | Gli XML FatturaPA delle fatture emesse accettate o in attesa dello SDI, come trasmessi (nome file SDI) | | `fatture-ricevute/` | Gli XML delle fatture fornitore del periodo (per data del documento o di ricezione), come ricevuti dallo SDI o allegati; PDF e immagini in `altri-documenti/` | | `autofatture/` | Gli XML delle autofatture TD16–TD19 inviate da Getbeel | | `prima-nota-iva.csv` | Una riga per documento e aliquota o natura: registro, date, numero, tipo documento, controparte, `AliquotaIVA`, `Natura`, `ImponibileImporto`, `Imposta`, totale, stato, nome del file XML | | `registri-iva/` | Registri IVA vendite e acquisti di ogni periodo di liquidazione (CSV), se l'azienda applica l'IVA | | `banca/movimenti-bancari.csv` | I movimenti bancari del periodo con la fattura abbinata | | `LEGGIMI.txt` | Cosa c'è dentro e i file che non è stato possibile leggere | I CSV usano il punto e virgola, la virgola per i decimali e UTF-8 con BOM, così Excel li apre direttamente. **Formati dei gestionali.** I gestionali dei commercialisti (TeamSystem, Zucchetti, Profis di Sistemi e gli altri) importano le fatture elettroniche dai file XML FatturaPA (Specifiche tecniche, Allegato A v1.9.1): è il formato che hanno tutti in comune. Nessuno dei tre pubblica il tracciato del proprio import di prima nota, quindi Getbeel non produce un formato proprietario e non lo inventa. Un periodo con più di 3.000 file o 250 MB risponde `422 too_many_documents`: chiedi un trimestre o un mese. ## MCP e SDK [#mcp-e-sdk] - MCP: `get_report` con `type` e `period` (o `from`/`to`). L'export ZIP non è uno strumento MCP: è un file binario. - SDK TypeScript: `getbeel.taxes.report('profit-and-loss', { period: '2026' })`, `getbeel.taxes.accountantExport('2026-Q3')` (un `Blob`). - SDK Python: `client.taxes.report("aging")`, `client.taxes.accountant_export("2026-Q3")` (byte). - CLI: `getbeel taxes report --type cash-flow --period 2026-Q3`. # Sandbox (https://docs.getbeel.com/it/api/sandbox) Le chiavi di test inviano a uno SDI simulato da getbeel. Ecco come ottenere ogni esito. Con una chiave di test (`gb_test_…`), `POST /invoices/{id}/send` non contatta lo SDI né il canale di trasmissione: getbeel genera e valida l'XML come per un invio vero, gli assegna un identificativo SDI simulato di 12 cifre e un nome file, e qualche secondo dopo applica un esito con i relativi [webhook](/it/api/webhooks). La sandbox è gratuita e non consuma la quota SDI; vale solo il [limite di richieste](/it/api/rate-limits). ## Come ottenere ogni esito [#come-ottenere-ogni-esito] L'esito dipende dai dati del cliente, controllati in quest'ordine: | Esito | Come ottenerlo | Stato | `sdi` | Webhook | | -------------- | -------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------ | ----------------------- | | Scartata | Partita IVA del cliente `00000000000` (con o senza `IT` davanti, spazi ignorati) | `rejected` | `error_codes: ["00305"]`, `errors: [{ "code": "00305", "description": null }]` | `invoice.rejected` | | Non consegnata | Codice destinatario `MC00000` (maiuscole o minuscole) e un'altra partita IVA | `not_delivered` | `available_since: null` | `invoice.not_delivered` | | Consegnata | Qualsiasi altra fattura valida | `delivered` | — | `invoice.delivered` | - La risposta all'invio è `200` con `status: "sent"` e il webhook `invoice.sent`. L'esito arriva circa 3 secondi dopo; se per qualche motivo non arriva, un processo periodico lo applica entro qualche minuto. Rileggi la fattura con `GET /invoices/{id}`. - **Lo scarto simulato usa il codice `00305`** (IdCodice del cessionario non valido), con il messaggio `00305 1.4.1.1.2 non valido (sandbox: partita IVA 00000000000 is always rejected)`, e la fattura va a `rejected` come uno scarto reale. Il `00404` non è simulato: su una fattura già inviata significa che è **già emessa**, vedi [ciclo di vita SDI](/it/api/sdi-lifecycle#duplicato-di-una-fattura-emessa-00404-su-una-fattura-inviata). - **La non consegna simulata non ha data**: `sdi.available_since` è `null`. Nella realtà una MC porta la data di messa a disposizione nel cassetto fiscale; il tuo codice deve gestire entrambi i casi. - Una fattura che non passa la validazione locale non viene inviata: la richiesta risponde `422 invoice_invalid` e la fattura resta in bozza. - Una fattura di test scartata si riapre come una live: `POST /invoices/{id}/reopen`, correggila con `PATCH /invoices/{id}` (per esempio una partita IVA vera al posto di `00000000000`) e inviala di nuovo. ## Test e live a confronto [#test-e-live-a-confronto] | | Test (`gb_test_`) | Live (`gb_live_`) | | -------------- | --------------------------- | ---------------------------------------------------------- | | Endpoint | Gli stessi | Gli stessi | | Invio | SDI simulato da getbeel | SDI reale, tramite un provider di trasmissione accreditato | | Risposta | `200`, `sent` | `202`, `sending` | | Esito | Deciso dai dati del cliente | Deciso dallo SDI, da pochi minuti a 5 giorni | | Valore fiscale | Nessuno | La fattura è emessa (se consegnata o non consegnata) | | Costo | Gratis, nessuna quota | Secondo il [listino](/it/api/pricing) | ## La sandbox del canale di trasmissione [#la-sandbox-del-canale-di-trasmissione] È una cosa diversa: è l'ambiente di prova del provider di trasmissione (openapi.com) che getbeel usa al suo interno per collaudare il canale. **Una chiave di test di getbeel non lo raggiunge mai.** Lo descriviamo perché spiega quali esiti getbeel ha potuto provare contro un canale vero (prova del 9 novembre 2026): - le fatture e le autofatture in uscita passano a SENT e poi a DONE/DELIVERED a distanza di qualche minuto, anche con codice destinatario `0000000`; - non produce mai una MC: openapi.com documenta una simulazione solo per le fatture in arrivo (`POST /IT-invoices_supplier_simulate`, Invoice API 1.8.7); - non controlla i duplicati: lo stesso file inviato due volte viene consegnato due volte, quindi il `00404` non arriva mai da lì. Per questo MC e `00404` sono collaudati riproducendo nel webhook di getbeel ricevute registrate. ## Fatture ricevute di prova [#fatture-ricevute-di-prova] `POST /sandbox/inbound-invoices` riceve una fattura come se arrivasse dallo SDI (il tuo XML o una fattura di esempio intestata alla tua azienda): compare in `GET /received-invoices` con la chiave di test (`source: "sdi"`) e invia `received_invoice.created` agli endpoint di test. Vedi [Ricezione da SDI](/it/api/sdi-receiving#sandbox). # Ciclo di vita SDI (https://docs.getbeel.com/it/api/sdi-lifecycle) Gli stati di una fattura emessa, cosa significa ogni esito dello SDI e cosa fare. Una fattura emessa passa per pochi stati, sempre in avanti. Lo stato dice se la fattura **è emessa**: una cosa da sapere prima di inviarla di nuovo, perché una fattura emessa non si reinvia mai. ## Stati [#stati] | `status` | Significato | Emessa? | | --------------- | ------------------------------------------------------------------------------ | -------------- | | `draft` | Bozza, modificabile | No | | `sending` | L'XML è in preparazione e l'invio è in coda (solo chiavi live) | No, non ancora | | `sent` | Trasmessa allo SDI, in attesa dell'esito (da pochi minuti fino a 5 giorni) | In attesa | | `delivered` | Ricevuta di consegna (RC) | **Sì** | | `not_delivered` | Ricevuta di impossibilità di recapito (MC): è nel cassetto fiscale del cliente | **Sì** | | `rejected` | Ricevuta di scarto (NS) | **No**, mai | ```text draft → sending → sent → not_delivered → delivered → rejected ``` Le transizioni vanno solo in avanti, in quest'ordine. Una ricevuta che arriva in ritardo o due volte non riporta mai indietro una fattura: un `sent` arrivato dopo un `delivered` viene ignorato. `not_delivered` può ancora diventare `delivered`, e una fattura consegnata può ancora diventare `rejected` quando una Pubblica Amministrazione la rifiuta. Le date dello SDI senza fuso orario vengono lette come ora italiana (Europe/Rome). Con una chiave di test, `POST /invoices/{id}/send` risponde subito con `sent` e l'esito arriva qualche secondo dopo dalla [sandbox](/it/api/sandbox). Con una chiave live risponde `202` con `sending`. ## Ogni esito [#ogni-esito] ### Consegnata (RC) → `delivered` [#consegnata-rc--delivered] Lo SDI ha recapitato la fattura all'indirizzo telematico del cliente. La fattura è emessa e la data di esigibilità dell'IVA è quella della fattura. ### Non consegnata (MC) → `not_delivered` [#non-consegnata-mc--not_delivered] Lo SDI ha fatto i controlli ma non ha potuto recapitare il file: il canale del cliente non era attivo, oppure il codice destinatario era `0000000` senza un indirizzo registrato. Ha messo la fattura nell'area riservata del cliente in "Fatture e Corrispettivi" (il cassetto fiscale), dalla data che trovi in `sdi.available_since`. ![Una fattura non consegnata (MC): risulta emessa, è nel cassetto fiscale dalla data indicata e non va inviata di nuovo.](/screenshots/invoice-not-delivered.it.webp) - **La fattura è emessa.** Non inviarla di nuovo: lo SDI scarterebbe la copia come duplicato (`00404`). - Avvisa il cliente per un'altra via (email, telefono) che la trova nella sua area riservata; per lui l'IVA è detraibile dalla presa visione. Una copia di cortesia via email ([`POST /invoices/{id}/email`](/it/api/invoice-collection)) aiuta. - Per le prossime fatture chiedigli il codice destinatario o la PEC. - Per un'autofattura (TD16–TD19) il destinatario è la tua azienda: la trovi nel tuo cassetto fiscale. Per riceverle direttamente, registra un indirizzo telematico in "Fatture e Corrispettivi" (vedi [codice destinatario](/it/guide/codice-destinatario)). ### Scartata (NS) → `rejected` [#scartata-ns--rejected] Uno o più controlli dello SDI non sono passati. **La fattura si considera mai emessa.** ![Una fattura scartata dallo SDI: il codice di errore, la sua descrizione, la regola per reinviarla e il pulsante Correggi e reinvia.](/screenshots/invoice-rejected.it.webp) - `sdi.errors` elenca i codici con la descrizione dello SDI; `sdi.error_codes` solo i codici. Cosa significa ogni codice e come correggerlo: [Codici di scarto SDI](/it/api/reference-data/sdi-errors). - Correggi e inviala di nuovo **con lo stesso numero e la stessa data**, preferibilmente entro 5 giorni dalla notifica di scarto. Il nuovo invio ha un nuovo nome file, e lo SDI non lo considera un duplicato perché il primo era stato scartato. - Riapri, correggi, reinvia: 1. `POST /invoices/{id}/reopen` la riporta in `draft` con lo stesso numero e la stessa data (nell'app: **Correggi e reinvia**; in MCP: `reopen_rejected_invoice`). `sdi.errors` resta visibile finché non viene reinviata. 2. `PATCH /invoices/{id}` corregge quanto indicato in `sdi.errors` ([Fatturazione](/it/api/invoicing#modificare-una-bozza); MCP `update_invoice_draft`). 3. `POST /invoices/{id}/send` la invia di nuovo, con un `Idempotency-Key` così un nuovo tentativo non conta due volte. Con qualsiasi altro stato la risposta è `409 invoice_not_rejected`. Con le chiavi di test si riaprono allo stesso modo gli scarti della sandbox. ```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)" ``` - Il rifiuto di una Pubblica Amministrazione dopo la consegna (notifica di esito) compare oggi anche come `rejected`, ma non è uno scarto dello SDI: la fattura era stata consegnata. In quel caso non applicare la regola del reinvio e chiedi al commercialista come rettificarla. - Per le fatture live, getbeel può tentare da solo una correzione dell'XML e reinviarlo (al massimo 3 volte): la fattura torna `sent` con un nuovo invio, oppure torna in bozza da correggere a mano. ### Duplicato di una fattura emessa (`00404` su una fattura inviata) [#duplicato-di-una-fattura-emessa-00404-su-una-fattura-inviata] Lo SDI scarta con `00404` ("Fattura duplicata") un file con lo stesso cedente, lo stesso anno e lo stesso numero di un documento che ha già accettato. Se capita a una fattura che era stata inviata, vuol dire che lo SDI ha **già accettato una copia precedente: la fattura è emessa**. ![Una fattura scartata come duplicato (00404) di una copia già accettata: risulta già emessa e resta bloccata.](/screenshots/invoice-duplicate.it.webp) - getbeel non la porta a `rejected`: resta `sent` (o lo stato che aveva), con `00404` in `sdi.error_codes` e `sdi.errors`. Nessun evento webhook. - **Non rigenerarla e non reinviarla**: ogni nuovo invio verrebbe di nuovo scartato con `00404`. - L'assistenza collega l'invio accettato. Nei registri IVA il documento conta come emesso, segnato da verificare (`needs_review`). Per le autofatture TD16–TD20, TD22, TD23, TD28 e TD29 il controllo di unicità si fa sul cessionario (la tua azienda). ### In attesa → `sent` [#in-attesa--sent] Lo SDI ha il file e non ha ancora risposto. I controlli e la consegna richiedono da pochi minuti fino a 5 giorni quando lo SDI è molto carico. Non reinviare una fattura `sent`: aspetta l'esito. ## Cosa mostrano web, API e MCP [#cosa-mostrano-web-api-e-mcp] | Esito | Web (badge) | API `status` e `sdi` | MCP (`get_invoice`, `list_invoices`) | Webhook | | -------------------------- | ------------------------------------ | --------------------------------------- | ------------------------------------------- | ----------------------- | | In preparazione | Invio al SDI... | `sending` | Lo stesso JSON dell'API | — | | In attesa | Inviata al SDI | `sent` | Come l'API | `invoice.sent` | | RC | Consegnata | `delivered` | Come l'API | `invoice.delivered` | | MC | Emessa · nel cassetto fiscale | `not_delivered`, `sdi.available_since` | Come l'API: "issued, never resend" | `invoice.not_delivered` | | NS | Scartata, con **Correggi e reinvia** | `rejected`, `sdi.errors` | Come l'API: "fix sdi.errors and resend" | `invoice.rejected` | | `00404` su fattura inviata | Già emessa · duplicato (bloccata) | `sent` con `00404` in `sdi.error_codes` | Come l'API: "already issued, do not resend" | — | ![L'elenco delle fatture emesse con lo stato SDI di ciascuna: bozza, inviata, consegnata, emessa nel cassetto fiscale, scartata, già emessa (duplicato).](/screenshots/issued-invoices.it.webp) - **Web.** Il dettaglio della fattura spiega l'esito con le fonti ufficiali: per MC la data di messa a disposizione e "Non va inviata di nuovo"; per NS i codici con la descrizione e la regola del reinvio; per `00404` "Già emessa: lo SDI ha una copia accettata". - **API.** `GET /invoices/{id}` e `GET /invoices?status=…` (vedi il [riferimento](/it/api/reference)). - **MCP.** Gli strumenti `list_invoices` e `get_invoice` restituiscono lo stesso JSON, e la loro descrizione spiega all'assistente ogni stato, così non propone mai di reinviare una fattura emessa. Esempio: [Server MCP](/it/api/mcp#esempi). ## Webhook [#webhook] Ogni cambio di stato invia un [evento](/it/api/webhooks) con la fattura completa in `data.object`: | Evento | Nuovo stato | | ----------------------- | --------------- | | `invoice.sent` | `sent` | | `invoice.delivered` | `delivered` | | `invoice.not_delivered` | `not_delivered` | | `invoice.rejected` | `rejected` | Un evento per transizione: una ricevuta duplicata o in ritardo non ne genera un altro. Il `00404` di una fattura già emessa non cambia stato e non invia eventi. Rileggi sempre lo stato con `GET /invoices/{id}` se ti serve quello attuale. ## Inviare due volte non crea un duplicato [#inviare-due-volte-non-crea-un-duplicato] - **`Idempotency-Key`.** Ripetere `POST /invoices/{id}/send` con la stessa chiave restituisce la prima risposta senza un secondo invio ([Idempotenza](/it/api/idempotency)). - **Un solo invio per bozza.** L'invio prende la bozza in modo atomico: una seconda richiesta, anche senza chiave, riceve `409 invoice_send_in_progress` o `409 invoice_not_draft` prima di qualsiasi chiamata allo SDI. - **Esiti incerti.** Se un invio finisce senza risposta certa (timeout, errore 5xx, rete), getbeel cerca il documento presso il canale di trasmissione prima di riprovare: se lo SDI l'ha già ricevuto ne registra l'identificativo invece di inviarlo di nuovo. - Le autofatture seguono la stessa regola: l'invio prende il documento in modo atomico e il canale viene interrogato solo dopo un esito incerto. ## Fonti [#fonti] - Agenzia delle Entrate, [La fattura elettronica e i servizi gratuiti](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guida_fattura_elettronica_dicembre_2025), dicembre 2025: p. 16 (controlli dello SDI, duplicati, tempi fino a 5 giorni), p. 17 (ricevuta di scarto, reinvio con stessa data e numero e nuovo nome file; ricevuta di consegna), p. 18 (impossibilità di recapito, data di messa a disposizione, fattura emessa per il fornitore, scarto = fattura mai emessa), pp. 19–20 (registrazione dell'indirizzo telematico). - Agenzia delle Entrate, [circolare 13/E del 2 luglio 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: la fattura scartata va preferibilmente reinviata entro cinque giorni dalla notifica di scarto con la data e il numero del documento originario. - Agenzia delle Entrate, [Allegato A, Specifiche tecniche versione 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) (31 marzo 2026), Appendice 1, "Verifiche di unicità della fattura", pp. 122–123: codici `00404` e `00409`, controllo sul cessionario per TD16–TD20, TD22, TD23, TD28, TD29. - [fatturapa.gov.it, documentazione SDI](https://www.fatturapa.gov.it/it/norme-e-regole/DocumentazioneSDI/): specifiche tecniche ed elenco dei controlli. # Ricezione da SDI (https://docs.getbeel.com/it/api/sdi-receiving) Ricevi le fatture dei fornitori dal Sistema di Interscambio, con codice destinatario, checklist e sandbox. Getbeel riceve dal Sistema di Interscambio (SDI) le fatture che i fornitori mandano alla tua azienda e le mette tra le fatture ricevute, già lette dall'XML (anche se firmato `.p7m`). Le trovi con `GET /received-invoices` e `source: "sdi"`, accanto a quelle raccolte da email, inoltro o caricamento. Scope: `received_invoices:read` per leggere lo stato, `received_invoices:write` per attivare la ricezione e per la sandbox. ## Come funziona [#come-funziona] 1. **Attiva la ricezione** con `POST /sdi-receiving` (o dall'app, in Impostazioni → Ricezione SDI). Servono i dati dell'azienda completi (`422 company_not_ready`) e l'add-on SDI (`402 sdi_addon_required`). Solo chiavi live (`403 livemode_required`). 2. La risposta contiene il **codice destinatario** da dare ai fornitori. 3. **Registra il codice come indirizzo telematico** nell'area riservata dell'Agenzia delle Entrate (Fatture e Corrispettivi). Lo fa l'azienda, una volta: vedi la [guida](/it/guide/codice-destinatario). Da quel momento ogni fattura arriva a Getbeel, qualunque codice abbia scritto il fornitore. 4. Ogni fattura ricevuta crea una fattura ricevuta (`status: "pending_review"`, `source: "sdi"`) e invia il webhook `received_invoice.created`. Se lo stesso documento era già stato raccolto dalla email (stesso fornitore, numero e data), Getbeel lo collega a quello esistente invece di crearne un secondo, e non invia un nuovo webhook. ```bash curl -X POST https://getbeel.com/api/v1/sdi-receiving \ -H "Authorization: Bearer $GETBEEL_LIVE_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` ## Stato e checklist [#stato-e-checklist] `GET /sdi-receiving` restituisce: | Campo | Significato | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `status` | `not_enabled`, `pending`, `active` o `error` (`last_error` dice perché) | | `codice_destinatario` | Il codice da dare ai fornitori e registrare come indirizzo telematico | | `fiscal_id` | La P.IVA (o il codice fiscale) per cui ricevi | | `indirizzo_telematico.confirmed` | Un membro ha confermato nell'app di averlo registrato (Getbeel non può verificarlo) | | `conservazione` | Lo stato della [conservazione gratuita AdE](/it/guide/conservazione): `not_activated`, `active`, `expired`, con le date | | `readiness.steps` | `company_data`, `sdi_addon`, `receiving_enabled`, `indirizzo_telematico`, `conservazione` (consigliato), ognuno con `done` | | `links` | Il portale Fatture e Corrispettivi e la pagina informativa dell'Agenzia | Una P.IVA può ricevere in un solo workspace Getbeel: un secondo tentativo risponde `409 fiscal_id_taken`. ## Costo [#costo] Ogni fattura ricevuta dallo SDI costa 0,18 € sul listino ([prezzi](/it/api/pricing)). Una fattura raccolta dalle email si paga come estrazione email, non come ricezione dallo SDI; se la stessa fattura arriva anche dallo SDI, conta la ricezione SDI. ## Sandbox [#sandbox] Con una chiave di test, `POST /sandbox/inbound-invoices` riceve una fattura come se arrivasse dallo SDI: passa il tuo XML (o un `.p7m` in base64) in `xml`, oppure manda un corpo vuoto per ricevere una fattura di esempio intestata alla tua azienda. MCP: `create_sandbox_inbound_invoice`. ```bash curl -X POST https://getbeel.com/api/v1/sandbox/inbound-invoices \ -H "Authorization: Bearer $GETBEEL_TEST_KEY" ``` La fattura compare in `GET /received-invoices` con la stessa chiave di test (`source: "sdi"`) e il webhook `received_invoice.created` va agli endpoint di test. Nell'app non compare nulla. Un XML illeggibile risponde `422 invoice_unreadable`. ## MCP [#mcp] Il tool `get_sdi_receiving_status` legge lo stato e la checklist; `list_received_invoices` accetta `source: "sdi"`. L'attivazione resta nell'app o nell'API: la registrazione presso l'Agenzia delle Entrate la fa l'azienda. Oggi la ricezione passa da un provider di trasmissione accreditato (openapi.com): il codice destinatario è il suo. Le fatture che non si riescono ad abbinare a un'azienda restano in quarantena e le controlliamo a mano. # SDK Python (https://docs.getbeel.com/it/api/sdk-python) Il client Python ufficiale, tipizzato, con una sola dipendenza (httpx). `getbeel` copre tutta l'[API](/it/api/reference). Aggiunge un `Idempotency-Key` a ogni `POST` che lo supporta, riprova i limiti di frequenza e gli errori del server, lancia errori tipizzati, scorre le liste e verifica le firme dei webhook. Python 3.9+. ```bash pip install getbeel ``` ## Crea e invia una fattura [#crea-e-invia-una-fattura] ```python from getbeel import Getbeel client = Getbeel() # legge GETBEEL_API_KEY; oppure Getbeel(api_key="gb_test_...") bozza = client.invoices.create( tipo_documento="TD01", currency="EUR", customer={ "denominazione": "Bianchi S.p.A.", "partita_iva": "01234567890", "country": "IT", "codice_destinatario": "ABCDE12", }, lines=[{"description": "Consulenza, ottobre", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00"}], ) inviata = client.invoices.send(bozza["id"]) # mostra la bozza e chiedi l'OK prima ``` Le risposte sono dizionari con i campi del [riferimento API](/it/api/reference). I corpi si passano come dizionario, come argomenti con nome o in entrambi i modi. Il parametro `from` si scrive `from_`. Opzioni: `Getbeel(api_key=None, base_url=None, company=None, timeout=60.0, max_retries=2, http_client=None)`; `base_url` predefinito: `GETBEEL_BASE_URL`, poi `https://www.getbeel.com/api/v1`. ## Risorse [#risorse] `me()`, `invoices`, `recurring_invoices`, `received_invoices`, `bank_statements` (`upload` accetta un percorso, dei byte o un 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`). I nomi dei metodi sono quelli dell'[SDK TypeScript](/it/api/sdk-typescript) in snake_case. ## Idempotenza ed errori [#idempotenza-ed-errori] ```python from getbeel import GetbeelError, NotFoundError client.invoices.send(bozza["id"], idempotency_key=f"send-{bozza['id']}") try: client.invoices.get("inesistente") 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) ``` Ogni `POST` che supporta l'idempotenza riceve un `Idempotency-Key` casuale, lo stesso nei nuovi tentativi automatici e riportato in `e.idempotency_key` se fallisce. Quei `POST` e le letture vengono riprovati `max_retries` volte su `408`, `429` (dopo `Retry-After`), `5xx`, errori di rete e `409 idempotency_key_in_use`; gli altri `POST` solo su `429`. Sottoclassi: `InvalidRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `APIError`, `APIConnectionError`. ## Paginazione e aziende clienti [#paginazione-e-aziende-clienti] ```python for fattura in client.invoices.iter_all(status="delivered"): print(fattura["number"]) bianchi = client.with_company("COMPANY_ID") # header Getbeel-Company bianchi.invoices.list() ``` ## Webhook [#webhook] ```python from getbeel import webhooks, WebhookSignatureError try: event = webhooks.construct_event(corpo_grezzo, headers["Getbeel-Signature"], os.environ["GETBEEL_WEBHOOK_SECRET"]) except WebhookSignatureError: ... # rispondi 400 ``` `webhooks.verify(payload, header, secret)` restituisce `True` o `False`; le firme più vecchie di 5 minuti sono rifiutate. Vedi [Webhook](/it/api/webhooks). # SDK TypeScript (https://docs.getbeel.com/it/api/sdk-typescript) Il client ufficiale per Node.js e TypeScript, generato dalla specifica OpenAPI. `@getbeel/sdk` copre tutta l'[API](/it/api/reference) con i tipi generati dalla specifica OpenAPI. Aggiunge un `Idempotency-Key` a ogni `POST` che lo supporta, riprova i limiti di frequenza e gli errori del server, lancia errori tipizzati, scorre le liste e verifica le firme dei webhook. ESM, nessuna dipendenza: Node.js 20.19+, Deno, Bun, Cloudflare Workers e Vercel Edge. ```bash npm install @getbeel/sdk ``` ## Crea e invia una fattura [#crea-e-invia-una-fattura] ```ts import { Getbeel } from '@getbeel/sdk'; const getbeel = new Getbeel({ apiKey: process.env.GETBEEL_API_KEY }); // gb_test_… nella sandbox const bozza = 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: 'Consulenza, ottobre', quantity: '1', unit_price: '1000.00', vat_rate: '22.00', }, ], }); const inviata = await getbeel.invoices.send(bozza.id); // mostra la bozza e chiedi l'OK prima ``` Opzioni: `apiKey` (predefinita `GETBEEL_API_KEY`), `baseUrl` (predefinito `https://www.getbeel.com/api/v1`), `company`, `maxRetries` (2), `timeoutMs` (60 000), `fetch`. ## Risorse [#risorse] | Proprietà | Metodi | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `me()` | Account, azienda, modalità della chiave e scope | | `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` | I tipi delle richieste e delle risposte sono esportati (`Invoice`, `CreateInvoiceRequest`, `Filing`…), e tutti sotto `types`. ## Idempotenza e nuovi tentativi [#idempotenza-e-nuovi-tentativi] Ogni `POST` che supporta l'[idempotenza](/it/api/idempotency) (creazioni, invii, pagamenti, caricamenti, sincronizzazioni) riceve un `Idempotency-Key` casuale, lo stesso a ogni nuovo tentativo automatico: un create ripetuto non crea mai due fatture. Una chiamata fallita lo riporta in `error.idempotencyKey`: riprova con quella chiave, mai con una nuova. Per sceglierla tu: ```ts await getbeel.invoices.send(bozza.id, { idempotencyKey: `send-${bozza.id}` }); ``` Le letture e quei `POST` vengono riprovati due volte con attesa crescente su `408`, `429` (dopo `Retry-After`), `5xx`, errori di rete e `409 idempotency_key_in_use`. Gli altri `POST` (approva, rifiuta, sospendi, caricamento della quietanza) solo su `429`, così non agiscono mai due volte. ## Errori [#errori] ```ts import { GetbeelError } from '@getbeel/sdk'; try { await getbeel.invoices.get('inesistente'); } catch (error) { if (error instanceof GetbeelError) { console.log( error.status, error.type, error.code, error.param, error.requestId, ); } } ``` `code` è il [codice d'errore](/it/api/errors) dell'API. Gli errori di rete hanno `status: 0` e codice `connection_error` o `timeout`. ## Paginazione [#paginazione] ```ts const pagina = await getbeel.invoices.list({ status: 'delivered', limit: 50 }); // pagina.data, pagina.has_more, pagina.next_cursor for await (const fattura of getbeel.invoices.listAll({ status: 'delivered' })) { console.log(fattura.number); } ``` ## Aziende clienti [#aziende-clienti] ```ts const cliente = getbeel.withCompany('COMPANY_ID'); // oppure new Getbeel({ company: 'COMPANY_ID' }) await cliente.invoices.list(); ``` Ogni chiamata porta l'header `Getbeel-Company`. Vedi [Aziende](/it/api/companies). ## File [#file] ```ts import { readFile } from 'node:fs/promises'; await getbeel.bankStatements.upload({ file: await readFile('ottobre.csv'), filename: 'ottobre.csv', }); await getbeel.bankStatements.uploadFromUrl({ file_url: 'https://…/estratto.pdf', }); // oltre 4,5 MB const pdf = await getbeel.filings.file('FILING_ID'); // Blob (l'XML per una 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 ``` ## Webhook [#webhook] Verifica la firma sul corpo grezzo, prima di leggerlo come JSON: ```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('firma non valida', { status: 400 }); if (event.type === 'invoice.delivered') { // … } return new Response('ok'); } ``` `webhooks.verify(body, header, secret)` restituisce `true` o `false`. Le firme più vecchie di 5 minuti sono rifiutate (`toleranceSeconds`). Vedi [Webhook](/it/api/webhooks). # Regole fiscali (https://docs.getbeel.com/it/api/tax-rules) I valori e le proroghe dietro lo scadenzario e le stime, con le fonti ufficiali; per gli amministratori di getbeel, le proposte del controllo settimanale delle fonti. Lo scadenzario e le stime seguono regole che cambiano ogni anno o per legge. getbeel le tiene **versionate per data**, ognuna con la sua fonte ufficiale: - **valori**: numeri come il minimale e le aliquote INPS dell'anno, le soglie del forfettario o le quote degli impatriati (chiave, valore, `valid_from`, `valid_to`); - **proroghe**: un decreto o un comunicato dell'Agenzia delle Entrate che sposta una scadenza (`deadline_kind`, le date di legge che sposta, `new_due_date`). Un valore mancante non viene mai sostituito da quello dell'anno prima: la stima dice che manca. Ogni settimana un **controllo delle fonti** legge le fonti ufficiali (news e prassi dell'Agenzia delle Entrate, MEF Dipartimento delle Finanze, Gazzetta Ufficiale, circolari e messaggi INPS) e propone le modifiche, ognuna con il link e la frase che la stabilisce. Nulla cambia finché un amministratore di getbeel non la approva. Quando si approva una proroga, i team di cui sposta le scadenze ricevono un avviso nell'app e gli F24 preparati e non ancora pagati prendono la nuova data. Scope: `taxes:read` per leggere. **Solo gli amministratori di getbeel** modificano le regole, con una **chiave live** che ha lo scope riservato `tax_rules:admin`. Questa chiave si crea nella pagina di amministrazione di getbeel e non viene mai proposta in Impostazioni → Chiavi API né all'accesso MCP (`403 insufficient_scope` senza, `403 live_key_required` con una chiave di test, `403 super_admin_required` se chi l'ha creata non è più amministratore). Ogni modifica è nel registro di audit. ## Leggere le regole in vigore [#leggere-le-regole-in-vigore] ```bash curl https://www.getbeel.com/api/v1/tax-rules \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `GET /v1/tax-rules` restituisce ogni valore per data (`origin: "code"` incluso in getbeel, `"db"` aggiunto dopo), `coverage` (i valori che mancano nei prossimi 13 mesi e se sono in ritardo) e `overrides` (le proroghe in vigore). `pending` e `watch_runs` sono `null` se la chiave non è di un amministratore di getbeel. ## Aggiungere un valore [#aggiungere-un-valore] ```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` risponde `201`. Con `status: "active"` il valore è subito in vigore, solo con una fonte ufficiale (`agenziaentrate.gov.it`, `mef.gov.it`, `finanze.gov.it`, `gazzettaufficiale.it`, `inps.it`, `normattiva.it`, `fatturapa.gov.it`; altrimenti `400 official_source_required`). Due valori attivi della stessa chiave non si sovrappongono mai (`409 rule_value_overlap`). Una chiave nuova richiede un rilascio di getbeel. ## Aggiungere una proroga [#aggiungere-una-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` risponde `201`. Con `deadline_kind: "all"` sposta ogni scadenza fiscale di quelle date (mai la dichiarazione OSS né il deposito del bilancio, che una proroga deve nominare). Una proroga non anticipa mai una scadenza. ## Approvare, rifiutare o ritirare [#approvare-rifiutare-o-ritirare] ```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` mette in vigore una proposta (`approve`) o la scarta (`reject`); `withdraw` ritira una regola in vigore (un valore inserito male: ritiralo, poi aggiungi quello corretto; l'`id` di un valore aggiunto senza rilascio è in `GET /v1/tax-rules`). Ritirare una proroga riporta gli F24 preparati alla data di legge. Via API si approvano solo proposte con una fonte ufficiale e, per quelle del controllo delle fonti, solo se la citazione è stata trovata parola per parola nella fonte (`400 quote_not_verified` per un PDF: leggilo e approvalo dalla pagina di amministrazione). `404 proposal_not_found` se è già stata decisa. Gli stessi strumenti sono in [MCP](/api/mcp): `get_tax_rules`, `add_tax_rule_value`, `add_tax_calendar_override`, `decide_tax_rule`. # Cespiti, stime e POS–RT (https://docs.getbeel.com/it/api/tax-tools) Cespiti e ammortamenti con il libro cespiti, la stima delle imposte (IRES, IRAP, IRPEF, forfettario, minimi, INPS) e i collegamenti POS–RT con il file CSV dell'Agenzia delle Entrate. Le stesse funzioni di **Tasse → Cespiti**, **Tasse → Stima imposte** e **Tasse → POS e RT**. Scope `taxes:read` per leggere, `taxes:write` per scrivere; le scritture richiedono una chiave live (`403 livemode_required`) e sono gratis. Solo aziende italiane (`400 taxes_not_available`). Le regole e le fonti sono nelle guide: [Cespiti](/it/guide/cespiti), [Stima imposte](/it/guide/stima-imposte), [POS e RT](/it/guide/collegamento-pos-rt). ## Cespiti [#cespiti] ```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` sceglie il coefficiente del DM 31/12/1988 (`GET /v1/fixed-asset-categories`); senza, passa `category_label` e `coefficient`. Un coefficiente superiore a quello della categoria risponde `400 coefficient_above_maximum`. - `received_invoice_id` compila data, fornitore e numero dalla fattura ricevuta; nella stima delle imposte il costo del cespite esce dai costi dell'anno. - `expense_in_full: true` deduce per intero un bene materiale fino a 516,46 € (`400 not_a_small_asset` altrimenti). - La risposta ha `schedule` (anno, `max_amount`, `amount`, fondo, residuo), `status`, `accumulated_depreciation` e `residual_value` a fine `as_of_year`. - `PATCH /v1/fixed-assets/{id}` con `disposal_date` e `disposal_amount` registra la cessione: `disposal.gain` positivo è una plusvalenza, negativo una minusvalenza. `depreciation_overrides` (`{"2027": "100.00"}`) registra quote dedotte minori del massimo. - `GET /v1/companies/me/fixed-assets-register?year=2026` è il libro cespiti dell'anno con `totals`, `by_category` e `closing_entries` (riepilogo delle scritture di chiusura); `&format=csv` o `xlsx` restituisce il file. ## Stima delle imposte [#stima-delle-imposte] ```bash curl "https://www.getbeel.com/api/v1/companies/me/tax-estimate?year=2026" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `reliable` è sempre `false` e `label` è "Stima, da verificare con il commercialista". `figures` mostra cosa viene da Getbeel (fatture emesse e ricevute, pagamenti, ammortamenti); `ires`/`irap` (società), `forfettario`, `irpef` (persone fisiche in regime ordinario) o `minimi` (regime di vantaggio, righi del quadro LM), e `inps`; `installments` gli acconti e il saldo con codice tributo F24, `due_date` e `confirmed` (`false` per le date non ancora confermate da una fonte in vigore); `warnings` cosa manca. `PUT /v1/companies/me/tax-estimate` salva per l'anno quello che Getbeel non sa (`entity`, `ateco_code` o `forfettario_group`, `inps_scheme`, `personnel_costs`, `permanent_staff_costs`, `irap_rate`, `prior_year_ires`…) e restituisce la stima ricalcolata. I campi non inviati restano com'erano; l'anno successivo parte dalle stesse risposte. Gli importi sono stringhe decimali (`"12000.00"`) come in tutta l'API; sono accettati anche numeri semplici. ## Collegamenti POS–RT [#collegamenti-posrt] ```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` è un POS fisico e richiede il suo `terminal_id` (senza, `400 terminal_id_required`); per `01`, un POS virtuale, `terminal_id` è ignorato e salvato vuoto. - Ogni collegamento ha `status` (`to_file`, `filed`, `end_to_file`, `ended`) e `pending`: l'operazione da comunicare (`I` o `C`) con la finestra `from`–`due` del provvedimento AdE 424470/2025. - Dopo la comunicazione un collegamento non si modifica (`409 link_already_filed`): `PATCH` con `ended_on` lo chiude e la chiusura diventa la prossima cosa da comunicare. - `GET /v1/pos-rt-links/export?part=1` restituisce il CSV (`csv`, al massimo 1.000 righe per parte), le stesse righe separate da tabulazioni (`tsv`) da incollare nel modello AdE, `links` (id e operazione di ogni riga), cosa è ufficiale e cosa no del formato (`layout`) e i passaggi nel portale (`next_steps`). `&format=csv` restituisce il file. - Dopo il caricamento in Fatture e Corrispettivi, `POST /v1/pos-rt-links/mark-filed` con quei `links` le segna come comunicate; un collegamento la cui operazione da comunicare è cambiata nel frattempo resta com'è. - `GET /v1/pos-rt-links/{id}` legge un collegamento. `PATCH /v1/pos-rt-links/{id}` lo modifica; dopo la comunicazione, solo `label` ed `ended_on` (l'ultimo giorno di utilizzo, che rende la cessazione la prossima cosa da comunicare). `DELETE /v1/pos-rt-links/{id}` elimina un collegamento non ancora comunicato; uno già comunicato risponde `409 link_already_filed`: va cessato. Getbeel non carica il file né accede al portale per te. ## 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`. # Tasse e scadenze (https://docs.getbeel.com/it/api/taxes) Lo scadenzario fiscale della tua azienda italiana, come JSON o come calendario .ics, e la stima della posizione IVA. Getbeel calcola le scadenze fiscali dell'azienda a partire dal profilo (paese, regime fiscale) e da due impostazioni che scegli una volta, nell'app (**Tasse**) o con `PATCH /companies/me/tax-settings`: IVA mensile o trimestrale (`vat_periodicity`), se l'azienda paga compensi a professionisti con ritenuta (`withholding_agent`) e, per chi è iscritto all'OSS (IVA sulle vendite B2C a consumatori di altri Paesi UE), le date dell'iscrizione (`oss_from`, `oss_until`; `null` le cancella). È la stessa lista della pagina **Tasse → Scadenze**. Scope: `taxes:read`. Disponibile solo per aziende italiane. ```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" }' ``` Per cambiarle servono `taxes:write` e una chiave live; un `PATCH` cambia solo quello che invia, e `GET /companies/me/tax-settings` le legge (`null` = non ancora impostata). Imposta la periodicità come l'azienda liquida davvero l'IVA: decide i periodi IVA dei registri, delle liquidazioni e degli F24. Strumenti MCP: `get_tax_settings`, `update_tax_settings`. Getbeel non accede mai alla tua area riservata dell'Agenzia delle Entrate e non paga per te. Prepara gli importi e l'F24 (vedi [Adempimenti](/it/api/filings)); il pagamento lo fai tu, in F24 web o dalla tua banca. ## Profilo fiscale [#profilo-fiscale] Ogni azienda paga tasse diverse. Il profilo fiscale dice quali si applicano e perché: forma giuridica, regime fiscale, periodicità IVA, sostituto d'imposta, dipendenti, fornitori esteri (reverse charge), Intrastat, OSS, liquidazione, primo anno d'imposta e, per le persone fisiche, previdenza e regimi speciali (forfettario, impatriati, rientro docenti, neo-residenti). È la stessa scheda di **Tasse → Il tuo profilo fiscale** nell'app. Gratuito con ogni piano. ```bash curl https://www.getbeel.com/api/v1/companies/me/tax-profile \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Getbeel rileva quello che può dai dati che ha già, e mostra la prova in `detection.fields.` (`value`, `confidence`, `evidence.key` ed `evidence.params`): | Campo | Rilevato da | | -------------------------- | ---------------------------------------------------------------------------------------- | | `legal_form` | La ragione sociale (S.r.l., S.p.A., …); un codice fiscale personale è solo un indizio | | `regime_fiscale` | Il profilo aziendale (il codice RF di ogni fattura emessa) | | `vat_periodicity` | Il volume d'affari dell'anno prima: oltre 800.000 € è mensile (art. 7 DPR 542/1999) | | `withholding_agent` | Ritenute registrate negli ultimi 12 mesi | | `reverse_charge_suppliers` | Fatture ricevute da fornitori fuori Italia | | `intrastat` | Vendite a imprese di altri Paesi UE | | `oss_suggested` | Vendite a consumatori di altri Paesi UE oltre 10.000 € l'anno (art. 7-octies DPR 633/72) | | `in_liquidation` | "in liquidazione" nella ragione sociale | Mai un'ipotesi silenziosa: un valore che imposti tu vince sempre (`sources.` = `user`); una rilevazione ad alta confidenza viene usata (`detected`); tutto il resto resta `null` ed è elencato in `questions`, ciascuno con una domanda semplice da fare una volta all'utente. Dipendenti, iscrizione all'OSS, previdenza e regimi speciali non vengono mai presi da una rilevazione: si chiedono sempre. ```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"] }' ``` Un `PATCH` cambia solo quello che invia e lo segna come confermato; `null` riporta un valore alla rilevazione; `confirm` conferma i valori rilevati così come sono; `regimes` sostituisce i regimi speciali (`[]`: nessuno). `POST /companies/me/tax-profile/detect` ripete subito la rilevazione. Ogni mese (il giorno 2) getbeel ripete la rilevazione per ogni azienda che l'ha già fatta. Un nuovo obbligo (ritenute, fornitori esteri, Intrastat) viene applicato e segnalato nell'app ("Nuovo obbligo: …"). Una modifica che toglierebbe o cambierebbe una scadenza (per esempio nessuna ritenuta negli ultimi 12 mesi, IVA mensile invece che trimestrale, o una forma giuridica diversa) **non viene mai applicata da una rilevazione**, mensile o `POST …/detect`: resta il valore precedente e il campo riporta `held` (`value`, `confidence`, `evidence`, `since`: cosa dicono i nuovi dati). Il titolare riceve un avviso nella sua lingua e l'app mostra il campo come "Da verificare". Solo la tua risposta lo cambia: un `PATCH` con il valore, o `confirm` per tenere quello precedente. Per cambiare il profilo e ripetere la rilevazione servono `taxes:write` e una chiave live; ogni modifica va nel registro attività con la chiave e il canale (API o MCP). Strumenti MCP: `get_tax_profile`, `update_tax_profile`, `detect_tax_profile`. Quando un regime speciale finisce entro un anno (l'ultimo giorno è `effect.ends_year` di ogni regime, o il suo `valid_until` se prima), i titolari e i commercialisti ricevono un'email e l'app mostra un avviso ("Impatriati (regime precedente al 2024): finisce il 31 dicembre 2027, dal 2028 non si applica più"): una volta circa un anno prima e una volta un mese prima. La fine dell'aliquota ridotta del forfettario è annunciata allo stesso modo, con le due aliquote dai valori delle regole (oggi 5% e poi 15%). Il profilo cambia lo scadenzario: le scadenze che non si applicano non compaiono, e ognuna dice perché si applica in `applies_because`. ## Lo scadenzario [#lo-scadenzario] ```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" ``` Senza `from` e `to`: da 90 giorni fa a un anno da oggi (al massimo tre anni). | Tipo (`kind`) | Cosa | Codici tributo | Fonte | | -------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | `bollo` | Imposta di bollo sulle fatture elettroniche, trimestre | 2521–2524 | Art. 6 DM 17/06/2014; Ris. AdE 42/E/2019 | | `withholdings` | Ritenute sui compensi ai professionisti e, con dipendenti, sugli stipendi, mese | 1040; 1001 | Artt. 23, 25 DPR 600/1973; art. 18 D.Lgs. 241/97 | | `vat_payment` | Versamento IVA mensile o trimestrale | 6001–6012, 6031–6033 | DPR 100/1998; art. 7 DPR 542/1999 | | `vat_advance` | Acconto IVA (27 dicembre) | 6013, 6035 | Art. 6 L. 405/1990 | | `vat_annual_balance` | Saldo IVA annuale (16 marzo) | 6099 | Art. 6 DPR 542/1999 | | `lipe` | Comunicazione liquidazioni periodiche IVA | – | Art. 21-bis DL 78/2010 | | `vat_return` | Dichiarazione IVA annuale (30 aprile) | – | Art. 8 DPR 322/1998 | | `pf_tax_return` | Dichiarazione Redditi PF di una persona fisica (31 ottobre; 2 novembre 2026) | – | Art. 2 c. 1 DPR 322/1998 | | `pf_tax_balance` | Persona fisica: saldo + primo acconto (30 giugno; 20 luglio 2026 per 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` | Persona fisica: secondo acconto (30 novembre) | 4034 / 1791 / 1794 | Art. 17 c. 3 DPR 435/2001 | | `oss_return` | Dichiarazione e versamento OSS, per trimestre (solo OSS) | – (Portale OSS) | Artt. 369f, 369i Dir. 2006/112/CE; art. 74-sexies DPR 633/72 | Ogni scadenza ha: - `due_date`: la data vera. Sabato, domenica e festivi slittano al primo giorno lavorativo; dal 1° al 20 agosto si paga entro il 20 agosto. `nominal_due_date` è la data indicata dalla legge. Quando una proroga pubblicata sposta la scadenza, `due_date` è la nuova data ed `extension` riporta la fonte ufficiale (`source_title`, `source_url`); altrimenti `extension` è `null`. - `amount` e `amount_status`: l'imposta di bollo è calcolata dalle fatture emesse (`provisional` finché il trimestre non è chiuso). Gli importi IVA sono `null` finché non salvi la liquidazione; una liquidazione salvata senza niente da pagare rende la scadenza `not_due`. - `status`: `to_prepare`, `ready` (F24 preparato), `paid`, `filed` o `not_due` (nessun bollo dovuto nel trimestre, o niente IVA da versare). - `can_prepare` e `filing_type`: se Getbeel può preparare l'adempimento: F24 di bollo, ritenute e IVA (`vat_payment`, a periodo chiuso) e il file LIPE (`lipe`). - `needs_review`: per i regimi IVA speciali la regola generale potrebbe non valere. Controllala ("da verificare"). - `source`: la norma da cui viene la scadenza. - `applies_because`: perché si applica a questa azienda, dal profilo fiscale, come chiavi con parametri: `issues_e_invoices`, `vat_monthly`, `vat_quarterly`, `vat_payer` (`regime`), `withholding_agent`, `has_employees`, `oss_registered`, `oss_sales` (`countries`). - `review_key`: `in_liquidation` quando l'azienda è in liquidazione e la scadenza cade da quella data: verificala con il liquidatore ("da verificare"). - La dichiarazione OSS mantiene la data anche di sabato o domenica (regola UE) e in quel caso è segnata `needs_review`; si paga dal Portale OSS, non con F24. `missing_settings` elenca le impostazioni ancora da scegliere nell'app: finché mancano, le scadenze che ne dipendono non compaiono. Forfettari (RF19) e minimi (RF02) non hanno scadenze IVA. ### OSS (vendite B2C nell'UE) [#oss-vendite-b2c-nellue] Con `oss_from` impostato, lo scadenzario aggiunge `oss_return` per ogni trimestre dell'iscrizione: la dichiarazione OSS trimestrale e il relativo versamento, entro l'**ultimo giorno del mese successivo al trimestre** (30 aprile, 31 luglio, 31 ottobre, 31 gennaio), anche senza vendite (dichiarazione a zero). Fonti: Direttiva 2006/112/CE artt. 369f e 369i, Regolamento (UE) 282/2011 art. 59a, DPR 633/72 artt. 74-quinquies e 74-sexies. - La data **non slitta** nei fine settimana o festivi: lo dice la pagina OSS della Commissione europea. L'Agenzia non dice altro, quindi quando cade in un giorno non lavorativo la scadenza ha `needs_review: true` ("da verificare"). - Si paga dal Portale OSS dell'Agenzia con addebito diretto o bonifico con riferimento `IT//Qn.AAAA`, **non con l'F24**, e non si può compensare con crediti. - Dal 2027 le regole passano al Testo unico IVA (D.Lgs. 10/2026, artt. 149–153); le date dovrebbero restare le stesse (da verificare). ### Imposte sui redditi (società) [#imposte-sui-redditi-società] Per una società che paga l'IRES (SRL, SpA), con esercizio coincidente con l'anno solare e bilancio approvato entro 120 giorni, lo scadenzario elenca anche: | `kind` | Scadenza | Codici F24 | Fonte | | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------- | | `income_tax_balance` | Saldo IRES e IRAP + primo acconto: 30 giugno (soggetti ISA, solo 2026: 20 luglio, DL 89/2026 art. 6) | 2003, 2001, 3800, 3812 | art. 17 c. 1-2 DPR 435/2001 | | `chamber_fee` | Diritto annuale camerale, con il primo acconto | 3850 | art. 6 DM 21/04/2011 | | `income_tax_advance` | Secondo acconto: 30 novembre (60%, oppure 50% per i soggetti ISA) | 2002, 3813 | art. 17 c. 3 DPR 435/2001; art. 58 DL 124/2019 | | `income_tax_return` | Dichiarazioni Redditi SC e IRAP: 31 ottobre (2 novembre nel 2026) | — | art. 2 c. 2 DPR 322/1998 | | `financial_statements` | Deposito del bilancio: 30 maggio (non slitta: è un termine civilistico) | — | artt. 2435 e 2478-bis c.c. | Se la società paga l'IRES e applica gli ISA lo dice **Tasse → Stima imposte**, per anno d'imposta (`settings.income_tax`). Finché non è salvato lì non si indovina nulla: le scadenze non compaiono e `missing_settings` contiene `income_tax`. I soggetti ISA pagano entro il 21 luglio nel 2025 (DL 84/2025 art. 13) e il 20 luglio nel 2026. Le scadenze sono `needs_review` dal 2027, perché le regole dei versamenti passano al Testo unico versamenti (D.Lgs. 33/2025) e si assumono le stesse date. Il codice 3813 (secondo acconto IRAP) è nella tabella dei codici tributo dell'Agenzia (11 novembre 2026), e la dichiarazione IRAP scade lo stesso giorno di Redditi SC (DM 11 settembre 2008, art. 2 DPR 322/1998). Gli importi qui non sono ancora calcolati: vedi la stima delle imposte. ### Contributi INPS (persone fisiche con partita IVA) [#contributi-inps-persone-fisiche-con-partita-iva] Per una persona fisica il calendario aggiunge le scadenze INPS della gestione indicata nel profilo fiscale (`social_security`): | `kind` | Scadenza | Causale F24 | Fonte | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------- | | `inps_fixed` | Artigiani / commercianti, contributi fissi sul minimale: 16 maggio, 16 agosto (pagabile entro il 20 agosto), 16 novembre, 16 febbraio dell'anno dopo. `period` è `YYYY-Qn` | AF / CF | art. 18 c. 1-2 D.Lgs. 241/1997; circ. INPS 14/2026 §9 | | `inps_balance` | Saldo dell'anno precedente + primo acconto: 30 giugno (30 luglio con lo 0,40%) | AP / CP; PXX o P10 (gestione separata) | art. 18 c. 4 D.Lgs. 241/1997; circ. INPS 62/2026 §3 | | `inps_advance` | Secondo acconto: 30 novembre | AP / CP; PXX o P10 | art. 18 c. 4 D.Lgs. 241/1997; circ. INPS 62/2026 §3 | | `inps_reduction_request` | Forfettari artigiani / commercianti: domanda di riduzione del 35% entro il 28 febbraio (non slitta; `needs_review` se non è un giorno lavorativo) | — | art. 1 c. 83 L. 190/2014; circ. INPS 14/2026 §8 | - Una **cassa professionale** ha un proprio calendario: non viene elencato nulla. Senza gestione nel profilo non si indovina nulla. - Nel primo anno di attività non ci sono il saldo dell'anno prima, il secondo acconto e la domanda del 28 febbraio (una nuova attività chiede il 35% all'iscrizione). Le quattro rate fisse sono elencate: se inizi durante l'anno sono dovuti solo i mesi dall'iscrizione (circ. INPS 14/2026 §2), e il calendario, che conosce solo l'anno, non può dire quali. - Gli importi sono nel Cassetto previdenziale INPS (rate fisse, codeline). Sopra il minimale dipendono dal reddito: vedi la stima imposte. - PXX è l'aliquota del 26,07%, P10 quella del 24% per pensionati e iscritti ad altra forma obbligatoria. Soggetti ISA e forfettari: che la proroga 2026 al 20 luglio (DL 89/2026 art. 6) valga anche per i contributi non è confermato dall'INPS, quindi si mostra il 30 giugno. - Dal 2027 si assumono le stesse date, segnalate (`needs_review`): le regole di versamento passano al D.Lgs. 33/2025 e i commi della L. 190/2014 sul regime del 35% sono abrogati dal D.Lgs. 117/2026. ### Preparazione automatica [#preparazione-automatica] Attiva per impostazione predefinita (`auto_prepare: true` nelle impostazioni fiscali): ogni mattina getbeel prepara l'F24 di bollo, ritenute e IVA periodica in scadenza entro `auto_prepare_days` giorni (5 di default), quando il periodo è chiuso e l'importo è noto. È come premere **Prepara** (stessi controlli, stesso webhook `filing.ready`), più una notifica nell'app. Tu controlli l'F24 e lo paghi, e puoi sempre ricalcolarlo, prepararlo a mano o caricare la quietanza. La LIPE e la dichiarazione IVA annuale richiedono chi firma e le tue risposte, quindi non vengono mai preparate in automatico; nemmeno le scadenze con `needs_review` e l'IVA di dicembre dei mensili finché l'acconto IVA non è salvato nella liquidazione. L'IVA si prepara con i dati salvati nella liquidazione (crediti riportati, acconto). Per disattivarla: `PATCH /companies/me/tax-settings` con `{"auto_prepare": false}` (oppure in **Tasse → Impostazioni**, o con lo strumento MCP `update_tax_settings`): ricevi solo i promemoria. ## Nel calendario (.ics) [#nel-calendario-ics] Nell'app, **Tasse → Aggiungi al calendario** mostra un indirizzo privato da aggiungere a Google Calendar, Outlook o Apple Calendar: ``` https://www.getbeel.com/api/v1/companies/me/tax-calendar.ics?token=… ``` Il token sostituisce la chiave API (i calendari non possono inviare header). Chi ha l'indirizzo vede le scadenze: se lo hai condiviso per errore, rigeneralo nell'app e il vecchio smette di funzionare. ## Posizione IVA (stima) [#posizione-iva-stima] ```bash curl "https://www.getbeel.com/api/v1/companies/me/vat-position?period=2026-Q3" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `period` è un mese (`2026-10`) o un trimestre (`2026-Q3`). - `sales_vat`: IVA delle fatture emesse accettate dallo SDI nel periodo. Le note di credito sottraggono; lo split payment è escluso (`split_payment_invoices`); l'IVA a esigibilità differita è a parte (`deferred_sales_vat`). - `purchase_vat_estimate`: IVA delle fatture fornitore verificate, in euro. - `balance_estimate`: positivo da versare, negativo a credito. `reliable` è sempre `false`: Getbeel non conosce la detraibilità, il mese di ricezione delle fatture d'acquisto né le autofatture in reverse charge. Usala per farti un'idea e verificala con il commercialista. Getbeel non prepara un F24 IVA da questa stima. Per la liquidazione vera, con il suo F24 e la LIPE, usa i [registri IVA e le liquidazioni](/it/api/vat-registers). Conto economico, flussi di cassa, crediti per scadenza e lo ZIP per il commercialista: [Report ed export](/it/api/reports). ## Dichiarazione OSS (bozza) [#dichiarazione-oss-bozza] Per un'azienda iscritta all'OSS, regime dell'Unione (impostazioni `oss_from` / `oss_until`), la bozza della dichiarazione trimestrale, da riportare nel Portale OSS dell'Agenzia delle Entrate: ```bash curl "https://www.getbeel.com/api/v1/companies/me/oss-return?period=2026-Q3" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` - **Cosa conta:** le fatture emesse nel trimestre a un consumatore (senza partita IVA) di un altro paese UE, righe con Natura N7 ("IVA assolta in altro stato UE"). - **`countries`:** per paese e aliquota, imponibile e IVA all'aliquota ordinaria di quel paese alla data della fattura (banca dati TEDB della Commissione europea). L'IVA si calcola riga per riga, arrotondata al centesimo, poi si somma; `vat_country_level` è la stessa IVA calcolata una volta sul totale del paese, come può fare il portale, e `rounding_gap` è true quando differiscono di più di €0,01. - **`corrections`:** note di credito (TD04, TD08) su vendite di un trimestre precedente, come rettifiche di quel trimestre (entro tre anni). `balances` per paese; un saldo negativo lo rimborsa quel paese (`refunds`), non si compensa con gli altri; `total_due` non è mai negativo. - **`deadline`:** l'ultimo giorno del mese dopo il trimestre, come dicono le regole UE. Getbeel non la sposta per sabati o festivi: verifica eventuali proroghe. - **`reference`:** il riferimento del versamento `IT/IT{partita IVA}/Q{n}.{YYYY}`. Si paga dal portale (addebito SEPA) o con bonifico alla Banca d'Italia, mai con F24 né in compensazione. - **`nil_return`:** nessuna vendita OSS e nessuna rettifica: la dichiarazione va presentata comunque, a zero. - **`doubtful`:** le fatture su cui decidere, con il motivo (`reason`): `n7_not_eu_consumer`, `italian_vat_to_eu_consumer`, `outside_registration`, `foreign_currency` (serve il cambio BCE dell'ultimo giorno del trimestre), `rate_unknown`, `credit_note_unlinked`, `credit_note_before_sale`, `correction_too_old`. Restano fuori dai totali. `reliable` è sempre `false`: aliquote ridotte e beni non sono ancora gestiti (ogni vendita conta come servizio all'aliquota ordinaria). Getbeel non invia né paga la dichiarazione: la presenti tu nel Portale OSS con le tue credenziali (non sono ammessi intermediari). Gratuito. MCP: `get_oss_return`. ## Webhook [#webhook] `tax_deadline.upcoming` arriva 7 giorni e 1 giorno prima di ogni scadenza non ancora pagata, una volta per ciascuna, solo agli endpoint live. `data.object` è la scadenza con `reminder_days_before`. Vedi [Webhook](/it/api/webhooks). `tax_deadline.insufficient_funds` arriva una volta per data di scadenza, da 5 giorni lavorativi prima, quando gli F24 in scadenza quel giorno (compresi gli importi ancora stimati dai registri) superano il saldo di ogni conto bancario collegato in euro, con saldi aggiornati da non più di 3 giorni. Le scadenze si contano in ordine e gli F24 di ognuna escono dal saldo, quindi due date vicine che insieme lo superano vengono segnalate; il bollo dei trimestri piccoli conta nel giorno in cui si paga davvero (con il secondo o il terzo trimestre). Arriva un nuovo avviso quando cambia l'importo in scadenza quel giorno. `data.object` è un `f24_funds_alert` con `due_date`, `amount_due`, `available_balance`, `shortfall`, `deadline_ids` e `bank_account_id`. I titolari del team ricevono anche un'email e una notifica nell'app. Un F24 che la banca non riesce ad addebitare viene respinto e risulta pagato in ritardo (sanzioni, art. 13 D.Lgs. 471/1997). # Registri IVA e liquidazioni (https://docs.getbeel.com/it/api/vat-registers) I registri IVA vendite e acquisti, la liquidazione IVA mensile o trimestrale con il suo F24 e il file della LIPE, preparati dai documenti in Getbeel. Getbeel costruisce i **registri IVA** (vendite e acquisti) di un mese o di un trimestre dalle fatture emesse, dalle fatture fornitore e dalle autofatture che ha già, calcola la **liquidazione IVA** del periodo nelle righe della LIPE (VP2–VP14) e, da lì, prepara l'**F24** e il file della **LIPE**. Sono le stesse pagine dell'app **Tasse → Registri IVA** e **Tasse → Liquidazioni**. Scope: `taxes:read` per leggere, `taxes:write` per salvare una liquidazione o preparare la LIPE (con [Adempimenti](/it/api/filings)). Solo aziende italiane con IVA: forfettari e minimi ricevono `400 vat_not_applicable`. Registri e liquidazioni contano solo i documenti presenti in Getbeel. `reliable` è sempre `false`: Getbeel non conosce la detraibilità (art. 19-bis.1), il pro-rata, i documenti tenuti fuori, i versamenti VP10 e i crediti d'imposta VP11. Controlla con il commercialista prima di pagare o inviare. Getbeel non firma, non paga e non invia nulla. Prima di tutto scegli nell'app (**Tasse → Impostazioni**) se l'azienda liquida l'IVA **mensilmente** o **trimestralmente**: senza questa scelta la liquidazione risponde `400 settings_missing`, e un periodo nel formato sbagliato (un mese per un trimestrale) risponde `400 parameter_invalid`. ## I registri IVA [#i-registri-iva] ```bash curl "https://www.getbeel.com/api/v1/companies/me/vat-registers?period=2026-Q3" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `period` è un mese (`2026-10`) o un trimestre (`2026-Q3`). **Registro vendite** (art. 23 DPR 633/1972): - Fatture emesse in Getbeel e accettate dallo SDI (consegnate o non consegnate), per data del documento. Imponibile e IVA per aliquota e natura sono quelli del `DatiRiepilogo` dell'XML. Conta come emesso anche un documento il cui invio lo SDI ha scartato con `00404` perché ne aveva già accettato una copia: la riga è segnalata `needs_review` finché l'assistenza non collega l'invio accettato ([ciclo di vita SDI](/it/api/sdi-lifecycle)). - Le note di credito (TD04, TD08) sono negative. - Split payment (art. 17-ter): registrata ma non dovuta (`vat_counted` 0, flag `split_payment`). - IVA a esigibilità differita (`EsigibilitaIVA` D): dovuta all'incasso (art. 6, c. 5 DPR 633/1972) e, con l'IVA per cassa, comunque dopo un anno dall'operazione (art. 32-bis DL 83/2012); la riga conta in quel periodo (`deferred_vat_collected`). Una riga che arriva al limite di un anno senza incasso è segnalata `needs_review`: il limite non vale per le cessioni dell'art. 6, c. 5, e la fattura elettronica non dice di quale caso si tratta. - Autofatture in reverse charge TD16–TD19 e TD28 (art. 17 DPR 633/1972; artt. 46–47 DL 331/1993): l'IVA è a debito qui e, di norma, in detrazione negli acquisti, quindi compaiono in **entrambi** i registri (flag `reverse_charge`). **Registro acquisti** (art. 25 DPR 633/1972): - Fatture fornitore appena l'AI le ha lette, comprese quelle ricevute dallo SDI. Contano anche quelle che non hai ancora verificato, con il flag `unreviewed` sulla riga; `totals.to_review` conta le righe da controllare. I documenti rifiutati non contano mai. - Periodo: quello di ricezione. Una fattura ricevuta entro il 15 del mese dopo l'operazione conta nel periodo dell'operazione, ma mai a cavallo d'anno (art. 1, c. 1, DPR 100/1998). La data di ricezione è nota per le fatture arrivate dallo SDI; per le altre si usa la data del documento (`late_receipt` segnala le fatture ricevute dopo). - L'IVA addebitata da fornitori esteri non è IVA italiana: conta 0 (`foreign_vat`); la porta l'autofattura. Un fornitore di cui non si capisce il paese (nessun paese, un identificativo né italiano né con il prefisso di un paese noto) non è considerato italiano: la sua IVA conta 0, flag `country_unknown`. - Le autofatture in reverse charge, come sopra. Ogni riga ha `breakdown` (per aliquota e natura), `taxable`, `vat`, `vat_counted` (l'IVA che entra nella liquidazione), `counted`, `flags` e `adjustment`. I totali di ciascun registro sono in `totals` (anche per aliquota, `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` elenca i documenti del periodo non ancora nei registri: `processing` (l'AI la sta ancora leggendo; entra da sola), `no_vat_data` (importi in valuta senza controvalore in euro), `pending_sdi` (fattura emessa ancora in attesa di esito), `autofattura_pending`, `autofattura_unreadable`, `autofattura_missing` (acquisto estero il cui TD17/TD18/TD19 non è ancora stato inviato allo SDI: entro il 15 del mese successivo; solo acquisti ricevuti da quando esistono le proposte automatiche, e non quando un TD17/TD18/TD19 inviato per lo stesso fornitore ha lo stesso numero di fattura o un importo vicino nello stesso mese o in quello adiacente). ### Escludere o correggere una riga [#escludere-o-correggere-una-riga] Getbeel non può sapere se un acquisto è detraibile solo in parte (auto aziendali, telefonia, pro-rata) o se vuoi detrarlo più avanti. Nell'app (**Tasse → Registri IVA → Modifica**) puoi escludere una riga dalla liquidazione o indicare l'IVA che conta, sempre con un motivo. La riga mostra `adjustment` e `vat_counted` cambia di conseguenza. Per un acquisto con IVA indetraibile indica IVA 0 invece di escluderlo: le istruzioni LIPE contano gli acquisti con IVA indetraibile tra le operazioni passive (VP3). Escludi solo i documenti che non riguardano il periodo o l'azienda. Una riga a esigibilità differita non ancora dovuta non si modifica: si modifica nel periodo in cui è dovuta. La stessa correzione dall'API, sulla `key` della riga (`register:source:document_id`). Servono `taxes:write` e una chiave live: ```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` è `exclude` o `adjust` (con `vat_amount`, l'IVA che conta); `reason` è obbligatorio. `DELETE /companies/me/vat-adjustments/{key}` toglie la correzione. Una riga che non è di questa azienda risponde `404`, una fonte nel registro sbagliato `400`. Una liquidazione già salvata mantiene i suoi numeri finché non la prepari di nuovo. Strumenti MCP: `set_vat_adjustment`, `remove_vat_adjustment`. ### Esportare [#esportare] Dall'app ogni registro si scarica in CSV, Excel (XLSX) o PDF, per te o per il commercialista. ## La liquidazione IVA [#la-liquidazione-iva] ```bash curl "https://www.getbeel.com/api/v1/companies/me/vat-settlements?period=2026-10" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` `period` è un mese per chi liquida mensilmente, un trimestre per chi liquida trimestralmente. La liquidazione è calcolata al momento dai registri, nelle righe della LIPE (`lipe`): | Campo | Rigo LIPE | Cosa | | ------------------------------------------ | --------- | --------------------------------------------------------------------------- | | `operations_active` / `operations_passive` | VP2 / VP3 | Imponibile delle vendite e degli acquisti (senza le esclusioni art. 15, N1) | | `vat_due` / `vat_deducted` | VP4 / VP5 | IVA esigibile e IVA detratta (`vat_counted` dei registri) | | `vat_balance_debit` / `vat_balance_credit` | VP6 | Differenza a debito o a credito | | `previous_debt` | VP7 | Debito fino a 100 € del periodo precedente, non versato | | `previous_credit` | VP8 | Credito del periodo precedente (non nel primo periodo dell'anno) | | `annual_credit` | VP9 | Credito dell'anno precedente usato in questa liquidazione | | `car_payments` / `tax_credits` | VP10/VP11 | Non noti a Getbeel: sempre `0.00` | | `interest` | VP12 | Interessi dell'1% per i trimestrali (1°–3° trimestre) | | `advance`, `advance_method` | VP13 | Acconto IVA, solo a dicembre o nel 4° trimestre | | `amount_due` / `amount_credit` | VP14 | Importo da versare o a credito (`null` nel 4° trimestre dei trimestrali) | Le regole che Getbeel applica: - **Minimo di versamento**: fino a 100 € non si versa e passa al periodo dopo (`carried_debt`, nota `below_minimum_carried`), ma va comunque pagato entro il 16 dicembre (mensili) o il 16 novembre (trimestrali): l'IVA di novembre, di dicembre e del 3° e 4° trimestre non si rinvia mai (art. 1, c. 4, DPR 100/1998; art. 7 DPR 542/1999, come modificati dal D.Lgs. 1/2024). - **Credito**: un risultato negativo passa al periodo dopo (`carried_credit`, VP8 della liquidazione successiva) all'interno dello stesso anno. - **Periodo precedente**: VP7 e VP8 vengono dal periodo precedente dello stesso anno: la sua liquidazione salvata oppure, se non è salvata, quella che Getbeel calcola dai suoi registri, risalendo l'anno. `previous` dice quale (`source`: `saved`, `computed` o `input`). Solo quando Getbeel non ha dati precedenti in quell'anno li passi tu (`previous_debt`, `previous_credit`) e trovi la nota `previous_missing`. Gli importi che passi sostituiscono quelli calcolati. - **Interessi trimestrali**: 1% sull'importo dovuto del 1°, 2° e 3° trimestre (art. 7 DPR 542/1999), nota `interest_added`. - **4° trimestre dei trimestrali**: si versa con il saldo annuale (cod. 6099, entro il 16 marzo, con l'1%): `amount_to_pay` è `0.00` e la nota è `paid_with_annual_balance`. - **Acconto** (art. 6 L. 405/1990): a dicembre o nel 4° trimestre indica l'acconto versato (`advance`, almeno 103,29 €) e il metodo (`advance_method`: 1 storico, 2 previsionale, 3 analitico, 4 settori speciali). `amount_to_pay` è quello che paga l'F24 adesso; `tax_code` e `due_date` sono il codice tributo (6001–6012 per i mesi, 6031–6033 per i trimestri) e la scadenza. `saved` è la versione salvata, con `outdated: true` se i registri sono cambiati da allora. ```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): …" } ``` ## Salvare la liquidazione e preparare l'F24 [#salvare-la-liquidazione-e-preparare-lf24] Quando il periodo è chiuso, salva la liquidazione con [`POST /v1/filings`](/it/api/filings) e `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" }' ``` Facoltativi: `previous_credit`, `previous_debt` (per sostituire il riporto calcolato, o quando Getbeel non ha dati precedenti in quell'anno), `annual_credit_used`, `advance` e `advance_method` (dicembre o 4° trimestre). La risposta è l'adempimento con la riga F24 e `details.settlement` (le righe LIPE). Se non c'è niente da pagare (credito, importo fino a 100 € rinviato, 4° trimestre dei trimestrali) la liquidazione viene **comunque salvata**, l'F24 preparato prima per il periodo e non pagato viene eliminato, e la risposta è `422 nothing_due`. Finché l'F24 non è pagato puoi ricalcolarla; dopo risponde `409 filing_completed`, così come quando la LIPE del trimestre è già inviata (una modifica va allora in una LIPE correttiva). `previous_debt` (VP7) è al massimo 100,00. ## La LIPE [#la-lipe] La Comunicazione delle liquidazioni periodiche IVA (art. 21-bis DL 78/2010) si invia ogni trimestre: entro il 31 maggio, il 30 settembre, il 30 novembre e la fine di febbraio dell'anno dopo. Getbeel prepara il file XML dalle liquidazioni **salvate** del trimestre (i tre mesi, o il trimestre): ```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 }' ``` - Le società indicano chi firma: `declarant_fiscal_code` (codice fiscale di 16 caratteri) e `declarant_role` (codice carica, 1 = rappresentante legale). - Se manca una liquidazione del trimestre risponde `400 settlements_missing`; codice fiscale o partita IVA dell'azienda non validi: `fiscal_code_invalid`, `vat_number_invalid`. - Il file segue le specifiche tecniche dell'Agenzia (fornitura `IVP18`): un modulo per mese o uno per il trimestre; il 4° trimestre dei trimestrali è indicato come trimestre `5`, senza interessi né VP14. Nome del file: `IT{codice fiscale}_LI_{5 caratteri}.xml`, diverso per ogni file. Le specifiche chiedono il codice fiscale di chi trasmette: Getbeel usa quello dell'azienda, perché lo carichi dall'area dell'azienda; il commercialista che lo invia lo rinomina con il proprio. `GET /filings/{id}/file` restituisce l'XML (`application/xml`). Poi tu lo controlli con il software di controllo dell'Agenzia, lo firmi e lo invii da "Fatture e corrispettivi" (o lo dai al commercialista). Quando carichi la ricevuta con `POST /filings/{id}/receipt` la LIPE risulta `filed` (webhook `filing.filed`). ## SDK, CLI e MCP [#sdk-cli-e-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 ``` Con un assistente AI: `get_vat_registers`, `get_vat_settlement` e `prepare_filing` (tipi `vat_payment` e `lipe`). L'assistente mostra la liquidazione e chiede conferma prima di salvarla. Vedi [Server MCP](/it/api/mcp). ## Fonti [#fonti] Le regole qui sopra seguono i testi ufficiali, letti il 2 novembre 2026. Verificale con il tuo commercialista: Getbeel prepara, tu invii. - LIPE: specifiche tecniche `SpecificheIVP18_2024.pdf`, XSD `Specifiche IVP2018_SchemaIV18.zip` (versione 1.0) e istruzioni `IVA period_2024.pdf`, approvate con provvedimento dell'Agenzia delle Entrate prot. 125654 del 14 marzo 2024, su [agenziaentrate.gov.it](https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/liquidazioni-periodiche-iva). L'XSD e il software di controllo chiamano ancora VP10 `VersamentiAutoUE`; Getbeel non lo compila mai. - Liquidazione mensile e soglia di 100 €: [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) (come modificato dal D.Lgs. 1/2024). - Liquidazione trimestrale e interessi dell'1%: [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). L'1% è "calcolat[o] sugli importi da versare … relativamente alla liquidazione del trimestre" (istruzioni LIPE, rigo VP12): Getbeel lo applica all'importo del trimestre (VP6 − VP8 − VP9). Il debito riportato in VP7 resta fuori perché comprende già i suoi interessi: la soglia di 100 euro si verifica "comprensivo degli interessi dovuti dai contribuenti trimestrali" ([Istruzioni IVA 2026](https://www.agenziaentrate.gov.it/portale/iva-2026/modello-e-istruzioni), quadro VH). - Acconto: art. 6 L. 405/1990 (entro il 27 dicembre); il minimo di 103,29 € è nelle istruzioni e nelle specifiche LIPE. - Scadenze LIPE: art. 21-bis DL 78/2010. - Registri e detrazione: artt. 19, 23 e 25 DPR 633/1972 (artt. 19 e 25 come modificati dal D.Lgs. 148/2026 dal 12 agosto 2026: detrazione al più tardi con la dichiarazione del secondo anno successivo); split payment art. 17-ter; esigibilità differita art. 6, c. 5 e [art. 32-bis DL 83/2012](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legge:2012-06-22;83~art32bis). - Dal 1° gennaio 2027 gran parte di questi articoli passa al Testo unico IVA (D.Lgs. 10/2026) e al Testo unico adempimenti (D.Lgs. 141/2026); DPR 100/1998 e DPR 542/1999 restano. Non da un testo ufficiale (da confermare con il commercialista): lasciare fuori da VP2 gli importi esclusi ex art. 15 (natura N1), e contare una vendita a esigibilità differita nel VP2 del solo periodo di emissione. # Webhook (https://docs.getbeel.com/it/api/webhooks) Ricevi un evento per ogni ricevuta SDI e verifica la firma Getbeel-Signature. Invece di interrogare l'API, registra un endpoint HTTPS: Getbeel gli invia un `POST` JSON firmato per ogni evento che scegli, sulle tue fatture, riconciliazioni e tasse. | Parte | Regola | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Richiesta | `POST`, corpo JSON, header `Content-Type: application/json`, `User-Agent: getbeel-webhooks/1.0` e [`Getbeel-Signature`](#verificare-la-firma) | | La tua risposta | Un `2xx` qualsiasi entro 10 secondi. I redirect non vengono seguiti: un `3xx` conta come errore | | Nuovi tentativi | Dopo un non-`2xx`, un timeout o un errore di rete: di nuovo dopo 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h e 24 h. Fino a 9 tentativi in circa 3 giorni, poi l'invio è `failed` | | Duplicati | L'invio è almeno una volta: deduplica sull'`id` dell'evento | | Ordine | Non garantito: rileggi la fattura quando l'ordine conta | | Modalità | Un endpoint **test** riceve gli eventi delle chiavi di test (la sandbox); un endpoint **live** quelli reali | ## Aggiungere un endpoint [#aggiungere-un-endpoint] Nell'app apri **Impostazioni → Chiavi API e MCP → Webhook**, scegli **Aggiungi endpoint**, poi l'URL, la modalità e gli eventi. Il segreto di firma si vede una volta sola: conservalo sul tuo server. - L'URL deve essere `https` su un host pubblico. Host privati e interni sono rifiutati, anche quando un nome pubblico punta a uno di essi. - **Invia evento di prova** manda subito un evento di prova all'endpoint. Ogni invio è in **Invii recenti**, con lo stato, e **Reinvia** lo manda di nuovo. - Un endpoint funziona finché il membro che l'ha aggiunto può gestire le impostazioni del team. Se perde quel permesso, gli invii si fermano. ## Eventi [#eventi] | Evento | Quando | Stato della fattura | | ----------------------- | ----------------------------------------- | ------------------- | | `invoice.sent` | Trasmessa allo SDI, in attesa dell'esito | `sent` | | `invoice.delivered` | Ricevuta di consegna (RC) | `delivered` | | `invoice.not_delivered` | Mancata consegna (MC) | `not_delivered` | | `invoice.rejected` | Notifica di scarto (NS), con i codici SDI | `rejected` | Con una chiave di test gli eventi arrivano dalla [sandbox](/it/api/sandbox), quindi puoi collaudare ogni caso. Gli eventi su banca e documenti raccolti riguardano dati reali, quindi li ricevono solo gli endpoint **live**: | Evento | Quando | `data.object` | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `bank_statement.parsed` | Un [estratto conto](/it/api/bank-reconciliation) è stato letto | `bank_statement` | | `reconciliation.completed` | L'abbinamento AI è terminato: gli abbinamenti si possono verificare | `reconciliation` | | `received_invoice.created` | È arrivata una fattura fornitore dallo SDI (`source: "sdi"`) o è stata raccolta (scansione della casella, inoltro o caricamento) | `received_invoice` | | `invoice.emailed` | È stata inviata al cliente un email con la fattura o un sollecito | `invoice_email` | | `invoice.email_failed` | L'email al cliente non è partita (`error` dice perché) | `invoice_email` | | `invoice.paid` | I pagamenti registrati coprono l'importo dovuto | `invoice` | | `invoice.overdue` | Il giorno dopo la scadenza, una volta, se la fattura non è pagata | `invoice` | | `filing.ready` | È stato preparato (o ricalcolato) un [adempimento](/it/api/filings) | `filing` | | `filing.filed` | È stata caricata la quietanza: l'adempimento è pagato | `filing` | | `filing.needs_review` | Un adempimento preparato aspetta la revisione del commercialista | `filing` | | `filing.changes_requested` | Il commercialista l'ha rimandato indietro con un commento | `filing` | | `filing.approved` | Approvato: si può pagare o inviare | `filing` | | `filing.skipped` | Segnato da non fare, con il motivo | `filing` | | `filing.approval_due` | Con l'approvazione del commercialista obbligatoria, scade entro 5 giorni lavorativi e non è ancora approvato (una volta per scadenza) | `filing` | | `tax_deadline.upcoming` | Una [scadenza fiscale](/it/api/taxes) è tra 7 giorni o domani e non è pagata | `tax_deadline` | | `tax_deadline.insufficient_funds` | Un F24 in scadenza entro 5 giorni lavorativi supera il saldo di ogni conto bancario collegato | `f24_funds_alert` | | `bank_connection.expiring` | Il consenso di una [banca collegata](/it/api/bank-connections) scade entro 7 giorni | `bank_connection` | | `bank_connection.expired` | Il consenso è scaduto o revocato: gli aggiornamenti sono fermi finché non ricolleghi | `bank_connection` | `invoice.accepted` e `invoice.refused` (esito della PA), `invoice.terms_expired` (decorrenza termini). ## Il payload [#il-payload] Ogni evento è un oggetto `event`; per gli eventi delle fatture `data.object` è la fattura completa, la stessa di `GET /invoices/{id}` (senza le righe). ```json title="POST al tuo 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" }, "…": "…" } } } ``` Usa `type` per decidere cosa fare. Un evento può arrivare più di una volta o in ritardo: deduplica su `id` e, se ti serve lo stato attuale, rileggi la fattura con `GET /invoices/{id}`. Cosa significa ogni stato: [ciclo di vita SDI](/it/api/sdi-lifecycle). ## Verificare la firma [#verificare-la-firma] Ogni richiesta ha un header `Getbeel-Signature`: ```text Getbeel-Signature: t=1761742800,v1=5f2b9c… ``` - `t` è il timestamp Unix (secondi) dell'invio. - `v1` è l'HMAC-SHA256, in esadecimale, della stringa `t` + `.` + corpo grezzo della richiesta, calcolato con il segreto del tuo endpoint. Per verificarla: ricalcola l'HMAC sul corpo **grezzo** (prima di fare il parsing del JSON), confrontalo in tempo costante con `v1` e rifiuta i timestamp troppo vecchi (consigliamo 5 minuti) per evitare replay. ```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: leggi il corpo grezzo, non il JSON già interpretato 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); // gestisci 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() restituisce il corpo grezzo @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() # gestisci event["type"] … return "", 200 ``` ## Se qualcosa non va [#se-qualcosa-non-va] Cosa mostra **Invii recenti**, e cosa fare: | Errore di invio | Causa | Soluzione | | ------------------------------------------------------------------ | ------------------------------------------- | --------------------------------------------------------------------- | | `HTTP 4xx` o `5xx` | Il tuo endpoint ha risposto con un errore | Correggi il gestore; Getbeel riprova secondo lo schema sopra | | `Timed out after 10 seconds` | Nessuna risposta in 10 secondi | Rispondi subito `2xx`, poi fai il lavoro in una coda | | `Could not connect to the endpoint` | Errore DNS, TLS o di rete | Controlla che l'URL sia raggiungibile da internet | | `Endpoint URL not allowed` | Non è `https`, o è un host privato | Usa un URL `https` pubblico (per le prove va bene webhook.site) | | `The member who added this endpoint can no longer manage webhooks` | Quel membro è uscito o ha perso il permesso | Aggiungi di nuovo l'endpoint come membro che gestisce le impostazioni | Gli errori che non possono risolversi da soli (URL non ammesso, endpoint disattivato, permesso del membro) non vengono ritentati. ## Buone pratiche [#buone-pratiche] - Rispondi subito con un `2xx` e fai il lavoro pesante dopo, in una coda. - Lo stesso evento può arrivare più di una volta: rendi la gestione idempotente (per esempio non inviare due volte la stessa email al cliente). - Gli eventi possono arrivare in ordine diverso da quello in cui sono avvenuti: se l'ordine conta, rileggi lo stato con `GET /invoices/{id}`. - Tieni il segreto del webhook sul server, come la chiave API. I webhook sono appena usciti. Eventi, header e algoritmo di firma sono quelli indicati qui; i campi di `data` sono descritti nel riferimento API e possono crescere con nuovi campi. # Ritenute d'acconto (https://docs.getbeel.com/it/api/withholdings) Fatture con ritenuta e cassa previdenziale, ritenute dovute come sostituto d'imposta, F24 codice 1040 e dati per la Certificazione Unica e il 770. Due lati della stessa ritenuta: - **Emetti** una fattura da professionista: `POST /v1/invoices` con `withholding` (blocco `DatiRitenuta`) e, se serve, `cassa_previdenziale`. Il cliente paga `amount_due`, cioè il totale meno le ritenute. - **Paghi** un professionista o un agente: sei sostituto d'imposta, trattieni la ritenuta e la versi tu con l'F24 (codice tributo 1040) entro il 16 del mese dopo il pagamento. `/v1/withholdings` tiene un compenso per riga; a fine anno `/v1/withholdings/cu` dà i dati per la CU e il 770. Scope: `taxes:read` per leggere, `taxes:write` per scrivere (chiave live, come gli [adempimenti](/it/api/filings)). Registrare le ritenute è gratis. ## Emettere una fattura con ritenuta [#emettere-una-fattura-con-ritenuta] ```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": "Consulenza ottobre", "unit_price": "1000.00", "vat_rate": "22" }, { "description": "Spese anticipate", "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` si può omettere: Getbeel calcola `rate` × (righe soggette + contributo cassa se soggetto). Le righe con natura N1 (spese anticipate in nome e per conto, art. 15 DPR 633/72) non sono soggette se non indichi `subject_to_withholding: true`. Sulle righe soggette scrive `SI`. - Per le provvigioni (`reason` da Q a V) l'aliquota si applica solo a una parte dell'importo (art. 25-bis DPR 600/1973): `amount` è obbligatorio. - `withholding.contributions`: altri blocchi `DatiRitenuta` per i contributi trattenuti dal cliente (RT03 INPS, RT04 ENASARCO, RT05 ENPAM, RT06 altro). Anche questi riducono `amount_due` e `ImportoPagamento`. - `cassa_previdenziale.amount` si può omettere: `rate` × compensi (righe tranne N1); Getbeel scrive anche `ImponibileCassa`. `subject_to_withholding` vale per la rivalsa che fa parte del compenso; il contributo integrativo delle casse professionali non ne fa parte (istruzioni CU 2026, punto 4). - `reason` è la causale della CU: i codici accettati sono quelli dello schema FatturaPA che sono anche causali della CU 2026 (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). La fattura restituita ha `withholdings` (tipo, aliquota, importo e causale di ogni blocco) e `amount_due` al netto di tutti. ## Ritenute che devi versare [#ritenute-che-devi-versare] ```bash curl https://www.getbeel.com/api/v1/withholdings?paid_in=2026-10 \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Le fatture ricevute dallo SDI con `DatiRitenuta` RT01 o RT02 diventano una ritenuta da sole all'arrivo (`source: sdi`). `POST /v1/withholdings/sync` rilegge quelle arrivate prima (100 per chiamata, `has_more`). Getbeel ricava gli importi come li vuole la CU: | Campo | CU | Come | | -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | | `gross_amount` | punto 4 | Righe senza IVA + contributo cassa soggetto a ritenuta. Il contributo integrativo (cassa senza `Ritenuta` SI) è escluso | | `not_subject_amount` | punto 7 | Il resto: spese anticipate, quota non soggetta delle provvigioni (50% o 80%) | | `taxable_amount` | punto 8 | La base a cui l'emittente ha applicato l'aliquota: le righe con `Ritenuta` SI, o la parte che corrisponde a `ImportoRitenuta` | | `withheld_amount` | punto 9 | Somma di `ImportoRitenuta` dei blocchi RT01/RT02 | Quando i numeri non tornano, manca il codice fiscale del professionista (serve per la CU) o la fattura ha uno sconto sul totale, la ritenuta ha `needs_review: true` e `notes` spiega perché. `status`: - `unpaid`: non hai ancora pagato il compenso, quindi non hai ancora trattenuto nulla. Quando paghi: `PATCH /v1/withholdings/{id}` con `paid_on`. - `withheld`: compenso pagato, ritenuta da versare entro `due_date` (16 del mese dopo, spostato al primo giorno lavorativo). `overdue` dopo. - `remitted`: versata con un F24 registrato in Getbeel. Non si modifica più (`409 withholding_remitted`). - Se il compenso cambia dopo aver preparato l'F24, l'F24 va ricalcolato: pagato così com'è, versa solo i compensi rimasti uguali; gli altri restano da versare. - Un compenso registrato dopo l'F24 del mese già pagato, o un F24 preparato con `amount`: se quella ritenuta era compresa nell'F24 pagato, `PATCH` con `{ "remitted": true }` la collega e la blocca (`409 no_paid_filing` se per il mese non c'è un F24 pagato). - Le chiavi di test non vedono le ritenute (sono dati reali dei professionisti, come le fatture ricevute). Un compenso non arrivato dallo SDI (fattura cartacea, ricevuta per prestazione occasionale): ```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` si calcola se lo ometti: (`gross_amount` − `not_subject_amount`) × `rate`. ## L'F24 del mese [#lf24-del-mese] `POST /v1/filings` con `{ "type": "withholdings", "period": "2026-10" }` somma le ritenute con `paid_on` nel mese e prepara l'F24 (sezione Erario, codice 1040, mese `10`, anno `2026`). Vedi [Adempimenti](/it/api/filings). Caricata la quietanza, quelle ritenute diventano `remitted`. ## Certificazione Unica e 770 [#certificazione-unica-e-770] ```bash curl "https://www.getbeel.com/api/v1/withholdings/cu?year=2026" \ -H "Authorization: Bearer $GETBEEL_API_KEY" ``` Per percipiente e causale, i compensi **pagati** nell'anno (conta la data di pagamento): lordo (punto 4), somme non soggette (7), imponibile (8), ritenute (9), e quanto è stato versato con F24 registrati in Getbeel. `form_770` elenca per mese le ritenute operate, l'importo versato e la data (quadro ST, sezione I: punti 1, 2, 7, 11, 14). `format=csv` restituisce un foglio (punto e virgola, decimali con la virgola). Scadenze (istruzioni CU 2026, periodo d'imposta 2025; per i compensi del 2026 valgono le istruzioni CU 2027 di gennaio 2027): CU al percipiente entro il 16 marzo; all'Agenzia entro il 16 marzo, o entro il 30 aprile per lavoro autonomo abituale (causale A) e provvigioni non occasionali; 770 entro il 31 ottobre. Getbeel non prepara il file da inviare all'Agenzia né firma la CU: questi sono i dati da controllare e dare a chi la presenta (spesso il commercialista), o da riportare nel software dell'Agenzia. ## Fonti [#fonti] - [Specifiche tecniche FatturaPA, Allegato A, versione 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) e [schema 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` su righe e cassa, controlli 00411 e 00415. - Art. 25 e 25-bis DPR 600/1973 (ritenuta del 20% all'atto del pagamento; provvigioni) e art. 18 D.Lgs. 241/1997 (versamento entro il 16). - [Codice tributo 1040](https://www1.agenziaentrate.gov.it/servizi/codici/ricerca/SezioneErario.php?CT=1040) e [Risoluzione 13/E del 17 marzo 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) (dal 2017 il codice 1038 delle provvigioni confluisce nel 1040). - [Istruzioni Certificazione Unica 2026](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"; istruzioni del Modello 770/2026, quadro ST. # Panoramica (https://docs.getbeel.com/it/guide/analytics/dashboard) La prima pagina dell'app: l'attività del mese, l'elenco Per iniziare e le prossime scadenze fiscali. **Panoramica** è la pagina che si apre dopo l'accesso. Ti dice cosa è successo questo mese e cosa resta da fare. ## Prima di iniziare [#prima-di-iniziare] - **Un team** con il ruolo **Proprietario** o **Membro**. Il **Commercialista** non vede la Panoramica. - **Non serve** configurare nulla: la pagina si riempie man mano che usi Getbeel. - **Costo:** la pagina è gratuita ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Leggi l'attività del mese [#leggi-lattività-del-mese] Apri **Panoramica** nella barra laterale. Sotto il titolo trovi, per esempio, "Questo mese: 42 fatture raccolte · 8 emesse · 8 invii SDI". ### Completa l'elenco Per iniziare [#completa-lelenco-per-iniziare] **Per iniziare** mostra i passi che mancano, in ordine. Scegli il percorso in **Configura per**: **Azienda**, **Sviluppatore** o **Commercialista**. Per cambiarlo usa **Cambia percorso**. Fai clic su un passo per aprire la pagina giusta. Quando hai finito, scegli **Nascondi**. ### Controlla le scadenze fiscali [#controlla-le-scadenze-fiscali] Per le aziende italiane, **Prossime scadenze fiscali** elenca i prossimi versamenti. Scegli **Tutte le scadenze** per aprire **Tasse**. ### Vai dove serve [#vai-dove-serve] Nella colonna **Vai a** trovi **Fatture ricevute**, **Fatture emesse**, **Tasse**, **Riconciliazione**, **Impostazioni** e **Chiavi API e MCP**. ## Cosa è successo [#cosa-è-successo] - **Conosci i numeri del mese**: fatture raccolte, emesse e inviate allo SDI. - **I passi di configurazione sono fatti**, e l'elenco si spunta da solo. - **Sai cosa scade**, con un collegamento a ogni scadenza. - **Le pagine principali** sono a un clic. ## I passi di Per iniziare [#i-passi-di-per-iniziare] | Percorso | Passi | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Azienda** | Completa i dati aziendali, Collega una casella email, Collega la banca, Emetti la prima fattura elettronica, Collega Stripe, Crea una chiave API | | **Sviluppatore** | Completa i dati aziendali, Crea una chiave di test, Invia una fattura di prova, Collega Claude o Cursor, Collega una casella email, Collega la banca | | **Commercialista** | Completa i dati aziendali, Aggiungi un'azienda cliente, Collega una casella email, Collega la banca, Emetti la prima fattura elettronica, Crea una chiave API | Emettere fatture e collegare Stripe compaiono solo per le aziende italiane. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ----------------------------------------------------- | --------------------------------------------------------- | -------------------------------------- | | "Non siamo riusciti ad aggiornare la lista. Riprova." | La modifica dell'elenco non è stata salvata | Ricarica la pagina e riprova | | "Non siamo riusciti a salvare la scelta. Riprova." | Il percorso scelto non è stato salvato | Scegli di nuovo il percorso | | "Nessuna scadenza nei prossimi mesi." | Non ci sono versamenti, o mancano le impostazioni fiscali | Controlla le impostazioni in **Tasse** | | L'elenco **Per iniziare** è sparito | L'hai nascosto | Scegli **Mostra «Per iniziare»** | ## Prossimi passi [#prossimi-passi] I passi di Per iniziare, spiegati uno per uno. Le scadenze della Panoramica, con importi e F24. Spese ed entrate dai movimenti bancari. # Analisi e dashboard (https://docs.getbeel.com/it/guide/analytics) Dove vedere i numeri dell'azienda: la Panoramica, l'elenco delle fatture ricevute e l'Analisi dei movimenti bancari. Getbeel mostra i numeri dell'azienda in tre pagine. Ognuna parte da dati diversi: sapere quali evita di confrontare cifre che non si sommano. ## Le tre pagine [#le-tre-pagine] | Pagina | Da quali dati | A cosa serve | | -------------------- | ------------------------------------------ | ------------------------------------------------------- | | **Panoramica** | Attività del mese e scadenze | Vedere cosa manca da configurare e le prossime scadenze | | **Fatture ricevute** | Le fatture dei fornitori | Cercare, filtrare ed esportare le fatture | | **Analisi** | I movimenti bancari in **Riconciliazione** | Spese, entrate, fornitori e conto economico per periodo | ## Panoramica [#panoramica] È la prima pagina dopo l'accesso. Mostra le fatture raccolte, emesse e inviate allo SDI nel mese, l'elenco **Per iniziare** e le **Prossime scadenze fiscali**. Vedi [Panoramica](/it/guide/analytics/dashboard). ## Fatture ricevute [#fatture-ricevute] L'elenco delle fatture dei fornitori, da email, SDI e caricamenti. Cerchi per fornitore o numero, filtri per categoria, fonte e date, ed esporti in CSV, Excel o ZIP. Vedi [Lista fatture e ricerca](/it/guide/analytics/invoice-list). ## Analisi [#analisi] L'Analisi conta i **movimenti bancari**, non le fatture. Senza estratti caricati o banca collegata è vuota. Vedi [Analisi di spesa](/it/guide/analytics/spending-analytics). Per i numeri calcolati dalle fatture (conto economico per competenza, crediti per scadenza) usa i [report gestionali](/it/guide/report-e-commercialista) in **Tasse**. ## Chi le vede [#chi-le-vede] **Proprietario** e **Membro** vedono tutte e tre le pagine. Il **Commercialista** non vede **Panoramica** e **Analisi**; vede le fatture dei clienti dalla sua barra laterale. ## Pagine correlate [#pagine-correlate] Il riepilogo del mese e i passi da completare. Trova ed esporta le fatture ricevute. Spese ed entrate dai movimenti bancari. Report dalle fatture e l'export per il commercialista. # Lista fatture e ricerca (https://docs.getbeel.com/it/guide/analytics/invoice-list) Trova una fattura ricevuta, filtra per periodo, categoria e fonte, ed esporta l'elenco in CSV, Excel o ZIP. **Fatture ricevute** è l'elenco delle fatture dei fornitori, da email, SDI e caricamenti. Qui cerchi una fattura, filtri l'elenco e lo esporti. ## Prima di iniziare [#prima-di-iniziare] - **Fatture in Getbeel**: da una [casella collegata](/it/guide/invoice-management/gmail-integration), dallo SDI o caricate a mano. - **Un ruolo qualsiasi.** Tutti cercano ed esportano; il **Commercialista** non elimina e non cambia categoria. - **Costo:** cercare ed esportare è gratuito ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Apri l'elenco [#apri-lelenco] Apri **Fatture ricevute** nella barra laterale. La scheda **Tutte** mostra ogni fattura; **PDF mancante** solo quelle senza documento. ### Cerca una fattura [#cerca-una-fattura] Scrivi in **Cerca fornitore o n. fattura...**. L'elenco si aggiorna mentre scrivi. ### Filtra l'elenco [#filtra-lelenco] Restringi con i filtri: - **Stato**: **Tutti gli stati** o **Fattura PDF mancante**. - **Categoria**: **Tutte le categorie** o una sola. - **Fonte**: **Tutte le fonti**, **SDI** o **Email e caricamenti**. - **Intervallo date**: **Tutto il periodo**, **Questo mese**, **Mese scorso**, **Ultimi 3 mesi**, **Quest'anno** o **Seleziona date**. Fai clic sull'intestazione di una colonna per ordinare per fornitore, numero, data, importo o categoria. ### Apri il dettaglio [#apri-il-dettaglio] Fai clic su una riga, o scegli **Vedi dettagli** dal menu della riga. Il pannello mostra **Informazioni fornitore**, **Dettagli fattura** (numero, tipo, data, scadenza, categoria), le **Voci** e **Subtotale**, **IVA** e **Totale**, accanto al documento. ### Esporta [#esporta] Seleziona le righe, o **Seleziona tutte le fatture** del filtro, e scegli **Esporta**. Scegli il formato e poi **Scarica**: - **CSV**: valori separati da virgola. - **Excel**: foglio formattato (.xlsx). - **ZIP**: il file dei dati con gli allegati PDF. ## Cosa è successo [#cosa-è-successo] - **Vedi le fatture** della scheda che ti serve. - **La ricerca** ha trovato la fattura per fornitore o numero. - **I filtri** restano nell'indirizzo della pagina: puoi condividerlo con il team. - **Il dettaglio** mostra i dati letti dall'AI accanto al documento. - **L'esportazione** è scaricata nel formato scelto. ## Altre azioni [#altre-azioni] - **Scarica** (menu della riga): il documento originale. - **Elimina** (riga o selezione): rimuove le fatture. Non si annulla. - **Categoria**: cambiala dalla riga; vedi [Categorie e regole](/it/guide/invoice-management/categories-rules). - **Righe** (per pagina): 25, 50, 100 o 250. Gli stati e la verifica delle fatture sono in [Flusso delle fatture](/it/guide/invoice-management/invoice-workflow). ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ----------------------------------- | ------------------------------------------- | ------------------------------------------------ | | "Nessuna fattura trovata" | Nessuna fattura soddisfa ricerca e filtri | Usa **Cancella** sui filtri o allarga il periodo | | "Nessun allegato PDF trovato" | Le fatture scelte non hanno un documento | Esporta in CSV o Excel, o carica il PDF mancante | | "Esportazione non riuscita" | Il file non si è potuto creare | Riprova con meno fatture | | "Eliminazione fatture non riuscita" | Non hai i permessi o la richiesta è fallita | Controlla il tuo ruolo e riprova | ## Prossimi passi [#prossimi-passi] Stati delle fatture e come verificarle. Ordina le fatture per categoria, anche in automatico. L'export completo del periodo per il commercialista. # Analisi di spesa (https://docs.getbeel.com/it/guide/analytics/spending-analytics) La pagina Analisi: spese, entrate, fornitori e conto economico per periodo, calcolati dai movimenti bancari in Riconciliazione. **Analisi** mostra l'andamento delle transazioni in **Riconciliazione**: quanto è uscito, quanto è entrato e a chi hai pagato. I numeri vengono dai movimenti bancari, non dalle fatture. ## Prima di iniziare [#prima-di-iniziare] - **Movimenti bancari in Getbeel**: [carica un estratto conto](/it/guide/bank-reconciliation/statement-upload) o [collega la banca](/it/guide/collega-la-banca). Senza movimenti la pagina è vuota. - **Il ruolo Proprietario o Membro.** Il **Commercialista** non vede l'Analisi. - **Non serve** che i movimenti siano già abbinati alle fatture. - **Costo:** la pagina è gratuita ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Apri l'Analisi [#apri-lanalisi] Apri **Analisi** nella barra laterale. All'apertura vedi **Questo mese**. ### Scegli il periodo [#scegli-il-periodo] Scegli **Questo mese**, **Mese scorso**, **Questo trimestre**, **Quest'anno** o **Tutto il periodo**. Per altre date scegli un intervallo nel calendario. ### Leggi i totali [#leggi-i-totali] In alto trovi **Totale speso**, **Totale incassato**, **Transazioni totali** e **Fornitori unici**. Speso e incassato mostrano la variazione in percentuale rispetto al periodo precedente. ### Guarda spese e conto economico [#guarda-spese-e-conto-economico] **Spesa mensile** divide le uscite di ogni mese per fornitore. **Conto economico** mette a confronto **Ricavi** e **Spese**, con **Utile / perdita netta**. Apri una voce di spesa per vedere i fornitori. ### Confronta i fornitori [#confronta-i-fornitori] **Tutti i fornitori** elenca a chi hai pagato, con **Totale speso**, **Transazione media**, **Conteggio** e **Ultima transazione**. ## Cosa è successo [#cosa-è-successo] - **Hai aperto la pagina** sui movimenti del mese in corso. - **Il periodo scelto** vale per tutti i totali, i grafici e l'elenco. - **I totali** mostrano se spendi o incassi più del periodo precedente. - **Il conto economico** mostra il saldo tra entrate e uscite del conto. - **L'elenco fornitori** mostra dove va la spesa. ## Come conta Getbeel [#come-conta-getbeel] - **Uscita**: ogni movimento con importo negativo. **Entrata**: ogni movimento positivo. - **Ricavi** sono raggruppati per controparte. **Spese** per tipo di movimento della banca, non per categoria di fattura. - **Periodo precedente**: il mese prima, il trimestre prima o l'anno prima. **Tutto il periodo** e le date scelte a mano non hanno confronto. - **Valuta**: gli importi sono sommati così come sono, senza conversione. Questi numeri sono movimenti di cassa, IVA compresa. Per il conto economico per competenza, dalle fatture e al netto dell'IVA, usa i [report gestionali](/it/guide/report-e-commercialista). ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ---------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------- | | "Carica un estratto conto per generare il conto economico" | Non ci sono movimenti bancari | Carica un estratto o collega la banca | | "Nessun dato disponibile" | Nessun movimento nel periodo scelto | Scegli **Tutto il periodo** o un altro intervallo | | "Nessun ricavo registrato" | Nel periodo non ci sono entrate | Controlla che l'estratto contenga anche le entrate | | Un mese manca | L'estratto di quel mese non è stato caricato | Carica l'estratto mancante in **Riconciliazione** | ## Prossimi passi [#prossimi-passi] Conto economico e flussi di cassa dalle fatture. Da dove arrivano i movimenti dell'Analisi. Le fatture dei fornitori, una per una. # Autofatture (https://docs.getbeel.com/it/guide/autofatture) Gli acquisti da fornitori esteri, dall'estratto conto all'autofattura inviata allo SDI. *Video tutorial in arrivo.* Quando compri da un fornitore estero, per esempio un abbonamento software, integri l'IVA con un'**autofattura** e la invii allo SDI. Getbeel trova questi acquisti nei movimenti bancari e prepara l'XML. ![L'elenco delle autofatture con lo stato SDI: consegnata, emessa nel cassetto fiscale, già emessa (duplicato).](/screenshots/autofatture.it.webp) ## Quale tipo documento [#quale-tipo-documento] Getbeel propone il tipo documento per ogni acquisto. Tu lo controlli prima di inviare. | Codice | Descrizione ufficiale | Esempio | | ------ | ------------------------------------------------------------------------ | ------------------------------------------------- | | `TD17` | Integrazione/autofattura per acquisto servizi dall'estero | Abbonamento SaaS, pubblicità online | | `TD18` | Integrazione per acquisto di beni intracomunitari | Merce comprata da un fornitore UE | | `TD19` | Integrazione/autofattura per acquisto di beni ex art. 17 c. 2 DPR 633/72 | Beni già in Italia venduti da un fornitore estero | Fonte: Agenzia delle Entrate, [Specifiche tecniche FatturaPA, Allegato A, versione 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1), e [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), versione 1.10 (aprile 2025). Tutti i codici: [Tipo documento](/it/api/reference-data/tipo-documento). ## Le fatture estere ricevute diventano proposte [#le-fatture-estere-ricevute-diventano-proposte] Quando una fattura di un fornitore estero arriva in Getbeel dalla scansione email, dall'indirizzo di inoltro o da un caricamento, Getbeel propone da solo l'autofattura. Vale per le aziende italiane e solo per fatture che non arrivano dallo SDI. - **Il tipo documento lo decide la regola, non l'AI.** Servizi da un fornitore estero (per esempio Vercel, Cloudflare, OpenRouter, Supabase, Resend negli Stati Uniti, Trigger.dev nel Regno Unito): `TD17`. Beni spediti da un altro paese UE: `TD18`. Beni già in Italia: `TD19`. Beni importati da fuori UE passano dalla dogana: nessun TD, nessuna proposta. - **L'XML è generato come bozza.** L'invio allo SDI resta una tua azione. - **Una sola autofattura per acquisto.** Se lo stesso acquisto ha già un'autofattura da un movimento bancario abbinato alla fattura, o la stessa fattura (fornitore e numero) è già stata proposta o importata, Getbeel non ne crea un'altra. Anche l'importazione da **Importa fonti** salta una fattura che ne ha già una. - **Le tue modifiche restano.** Se elimini una proposta o la modifichi (per esempio inserisci il paese), Getbeel non la ricrea e non la sovrascrive quando la fattura viene salvata di nuovo. Se elimini la fattura ricevuta, la sua proposta viene eliminata se non è stata inviata allo SDI; una già inviata resta ed è segnalata. - **Il cambio** è quello del giorno della fattura (art. 13, c. 4, DPR 633/72). - **La data di effettuazione** (fornitori extra UE) è presa dalla data della fattura. Per legge un servizio è effettuato quando è ultimato o, se periodico, quando matura il corrispettivo, oppure prima se lo paghi prima (art. 6, c. 6, DPR 633/72): se è diversa, correggi la **Data** nel dettaglio. Alcune proposte compaiono nell'elenco **da verificare** e non sono generate da sole: paese del fornitore sconosciuto (**Paese mancante**: inseriscilo in **IdPaese**), beni o servizi non chiari, IVA addebitata dal fornitore, solo un avviso di pagamento, scadenza già passata, possibile doppione di un pagamento in banca, data di ricezione sconosciuta (fornitori UE: la scadenza è allora contata dalla data della fattura), fornitore dell'Irlanda del Nord. Se manca l'identificativo fiscale del fornitore l'XML usa `OO99999999999`: è una convenzione diffusa ma non è scritta nella guida né nelle specifiche dell'Agenzia, quindi la riga è segnalata da verificare. ### Entro quando inviarla [#entro-quando-inviarla] Entro il **15 del mese successivo** (art. 1, c. 3-bis, lett. b, d.lgs. 127/2015): | Fornitore | Il mese che conta | Data dell'autofattura (`Data`) | | --------------------------------------------- | ----------------------------- | ----------------------------------------------- | | UE (integrazione), beni dall'Irlanda del Nord | ricezione della fattura | data di ricezione, o una data dello stesso mese | | Extra UE, San Marino (servizi), Vaticano | effettuazione dell'operazione | data di effettuazione | La data di ricezione è la data dell'email per la scansione email e l'indirizzo di inoltro, e la data della fattura per un caricamento (la prima possibile). **Irlanda del Nord (`XI`).** Con il Windsor Framework le regole IVA UE continuano a valere per i beni in Irlanda del Nord: i beni da un fornitore `XI` sono un acquisto intra UE (`TD18`), i servizi seguono il Regno Unito (`TD17`). Non è confermato che lo SDI accetti `XI` come **IdPaese**, quindi queste proposte sono sempre da verificare. Getbeel mostra la scadenza nell'elenco (**Entro il …**), sempre il 15, senza spostarla se cade di sabato o in un giorno festivo. Nei [registri IVA](/it/guide/tasse) un acquisto estero ricevuto da quando esistono queste proposte, senza autofattura inviata, compare tra i documenti mancanti. Conta come coperto da qualsiasi autofattura inviata per lo stesso fornitore con lo stesso numero di fattura, o con un importo vicino nello stesso mese o in quello successivo, anche se non è abbinata alla fattura. Gli acquisti precedenti non compaiono mai, così i periodi chiusi non cambiano. e una fattura estera di cui non si conosce il paese non conta come italiana: la sua IVA non viene detratta. Fonti: Guida AdE alla compilazione delle fatture elettroniche e dell'esterometro v1.10 (1 aprile 2025), paragrafi TD17, TD18, TD19; Specifiche tecniche Allegato A v1.9.1 (controlli 00473 e 00475); DPR 633/72 artt. 7-ter, 13, 17 c. 2, 21 c. 4 lett. d, 6 c. 6; DL 331/93 artt. 46 e 47; Ris. 89/E/2010; Circ. 26/E/2022; Irlanda del Nord: Windsor Framework (Protocollo su Irlanda/Irlanda del Nord, art. 8) e la guida della Commissione europea sui codici GB e XI. Dal 1° gennaio 2027 il Testo unico IVA (D.Lgs. 10/2026) rinumera gli articoli: 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. ## Prima di iniziare [#prima-di-iniziare] - **Un'azienda italiana**: **Autofatture** compare nella barra laterale solo per le aziende italiane. - **I dati fiscali completi** in **Impostazioni → Azienda**: l'autofattura porta i tuoi dati come cessionario. - **I movimenti bancari** in **Riconciliazione**, da estratto conto o da [banca collegata](/it/guide/collega-la-banca). In alternativa importi fatture o un CSV dei fornitori esteri. - **L'add-on SDI attivo.** Ogni autofattura inviata conta come un invio SDI ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Porta i pagamenti esteri in Autofatture [#porta-i-pagamenti-esteri-in-autofatture] I movimenti degli estratti in **Riconciliazione** arrivano da soli. Per altre fonti premi **Importa fonti** e scegli **Estratto conto**, **Fattura singola** o **CSV provider esteri**. ### Genera le autofatture [#genera-le-autofatture] Seleziona le righe e premi **Genera**, oppure **Crea** su una riga. Getbeel compila fornitore, paese, importo e tipo documento. ### Controlla i dati [#controlla-i-dati] Apri la riga con **Dettagli**. Correggi con **Modifica dettagli**, poi premi **Rigenera XML** per applicare le modifiche. ### Invia allo SDI [#invia-allo-sdi] Nel dettaglio premi **Invia allo SDI**, o seleziona più righe e premi **Invia allo SDI**. Segui lo stato come per le [fatture emesse](/it/guide/emettere-fatture). ## Cosa è successo [#cosa-è-successo] - **I pagamenti esteri sono diventati righe da autofatturare**, uno per movimento. - **L'XML è stato generato** con tipo documento, natura e riferimento normativo. - **I tuoi controlli sono nell'XML**: ogni modifica vale dopo **Rigenera XML**. - **L'autofattura è allo SDI.** Lo stato si aggiorna da solo: **Consegnata**, **Emessa · nel cassetto fiscale**, **Scartata** o **Già emessa · duplicato**. Un'autofattura già inviata allo SDI non si elimina: **Elimina** la salta. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | "Nessuna transazione estera da generare per questo estratto conto." | L'estratto non ha pagamenti a fornitori esteri | Scegli un altro estratto o importa le fatture | | **Add-on SDI richiesto** | L'account non ha l'add-on SDI | Apri **Impostazioni → Utilizzo e fatturazione** | | "Lo SDI rifiuterebbe questo XML: non è stato inviato nulla. …" | Un campo non passa i controlli dello SDI | Correggi con **Modifica dettagli** o rigenera l'XML, poi invia di nuovo | | "IdDocumento deve essere un riferimento del fornitore di 1-20 caratteri, non un ID di transazione." | Il riferimento alla fattura del fornitore non è valido | Scrivi il numero della fattura del fornitore | | **Emessa · nel cassetto fiscale** | Lo SDI non ha potuto recapitarla a te | È emessa: non reinviarla. Registra il tuo [codice destinatario](/it/guide/codice-destinatario) | | **Paese mancante** | Non si sa in che paese è il fornitore | Apri **Dettagli**, inserisci il codice paese in **IdPaese** (es. `US`, `IE`) e premi **Crea** | | "Il TD18 vale solo per beni da un altro paese UE. …" | TD18 scelto per un fornitore extra UE | Usa `TD17` (servizi) o `TD19` (beni già in Italia); i beni importati non richiedono autofattura | ## Prossimi passi [#prossimi-passi] Carica gli estratti da cui nascono le autofatture. Le autofatture entrano nei registri IVA e nella liquidazione. Ricevi le autofatture anche come destinatario. # Corrispondenza transazioni con IA (https://docs.getbeel.com/it/guide/bank-reconciliation/ai-matching) Le regole con cui Getbeel abbina ogni uscita del conto a una fattura ricevuta, e quando conferma da solo. Getbeel abbina ogni uscita del conto a una fattura ricevuta solo se importo, data e fornitore tornano. Una proposta dubbia non viene confermata da sola: la decidi tu. ## Le regole [#le-regole] | Regola | Cosa controlla Getbeel | | ----------------- | --------------------------------------------------------------------------------- | | Direzione | Solo le uscite. Le entrate non vengono abbinate a fatture | | Importo | Uguale alla fattura, con al massimo 1 centesimo di differenza | | Importo in valuta | Fattura in un'altra valuta: confronto con l'importo convertito, tolleranza del 5% | | Data | Entro 7 giorni dalla data della fattura o dalla sua scadenza | | Fornitore | Il nome sul movimento deve corrispondere al fornitore della fattura | | Uno a uno | Ogni movimento va con una sola fattura, e ogni fattura con un solo movimento | L'AI propone le coppie. Getbeel ricontrolla importo e data prima di salvare e scarta le proposte che non tornano. ## Quali fatture considera [#quali-fatture-considera] Getbeel guarda le fatture ricevute con data nel periodo dell'estratto, allargato di 30 giorni prima e dopo. Senza un periodo nel file, guarda gli ultimi 90 giorni. Restano fuori le fatture con stato **Documento mancante**. Per la banca collegata restano fuori anche le fatture già abbinate a un altro pagamento. ## I nomi dei fornitori [#i-nomi-dei-fornitori] La banca spesso abbrevia o usa un nome commerciale. Getbeel riconosce, per esempio, "Bunnycdn" come "BUNNYWAY" o "Google Workspace" come "Google Cloud Italy". Prima del confronto toglie le forme societarie (S.r.l., Inc., GmbH, Ltd) e la punteggiatura. ## Cosa diventa ogni movimento [#cosa-diventa-ogni-movimento] Ogni proposta ha un grado di fiducia da 0 a 1. Il grado decide se serve il tuo controllo. - **Riconciliato** subito: fiducia 0,9 o più. Importo e fornitore coincidono e non c'erano altre fatture plausibili. - **Da confermare**: fiducia sotto 0,9. Succede quando più fatture erano plausibili o l'importo non è identico al centesimo. - **Fattura mancante**: nessuna fattura soddisfa le regole. Le entrate restano senza fattura e non contano nell'avanzamento dell'estratto. ## Valute diverse [#valute-diverse] Se la fattura è in dollari e il conto in euro, Getbeel usa l'importo della fattura convertito nella valuta dell'azienda. La tolleranza del 5% copre le differenze di cambio e le commissioni. Senza un importo convertito, la fattura non viene proposta. ## Se qualcosa non va [#se-qualcosa-non-va] | Problema | Causa | Cosa fare | | ------------------------------------------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Un'uscita resta **Fattura mancante** ma la fattura c'è | Importo diverso (pagamento parziale) o data oltre 7 giorni | Collegala a mano con **Aggiungi fattura** ([Flusso di revisione](/it/guide/bank-reconciliation/review-workflow)) | | La fattura non viene mai proposta | È **Documento mancante**, o la data è fuori dal periodo | Carica il PDF in **Fatture ricevute**, poi **Rifai abbinamento** | | Abbinata alla fattura sbagliata | Due fatture con stesso importo e fornitore | **Non è questa fattura**, poi collega quella giusta | | Le entrate non hanno fattura | Getbeel abbina solo le uscite | Nessuna azione: le entrate non contano nell'avanzamento | ## Prossimi passi [#prossimi-passi] Conferma le proposte e risolvi le fatture mancanti. Più movimenti leggibili, più abbinamenti esatti. Le fatture tra cui Getbeel cerca l'abbinamento. # Riconciliazione bancaria (https://docs.getbeel.com/it/guide/bank-reconciliation) Carica un estratto conto o collega la banca: Getbeel abbina ogni uscita alla fattura del fornitore e tu confermi. *Video tutorial in arrivo.* **Riconciliazione** abbina ogni uscita del conto alla fattura del fornitore che la giustifica. Getbeel propone gli abbinamenti; tu confermi quelli giusti e segni cosa manca. ![La pagina Riconciliazione: gli estratti conto caricati o scaricati dalla banca, con stato, periodo, movimenti e quota abbinata.](/screenshots/reconciliation.it.webp) ## In breve [#in-breve] | Cosa | Come funziona | | ---------------------------- | -------------------------------------------------------------------------------------------------- | | Da dove arrivano i movimenti | Da un estratto conto che carichi, o dalla [banca collegata](/it/guide/collega-la-banca) ogni 6 ore | | Cosa viene abbinato | Solo le uscite, alle fatture ricevute | | Chi decide | Tu: confermi, scarti o colleghi a mano | | Quando è finita | Quando scegli **Completa riconciliazione** | ## Da dove arrivano i movimenti [#da-dove-arrivano-i-movimenti] Hai due strade, anche insieme. - **Carichi un estratto conto.** CSV, PDF, Excel, testo o un file bancario CBI, CAMT.053 o MT940, fino a 50 MB. Vedi [Caricamento estratti conto](/it/guide/bank-reconciliation/statement-upload). - **Colleghi la banca.** I movimenti arrivano da soli ogni 6 ore. Getbeel crea un estratto per ogni conto e ogni mese. Vedi [Collega la banca](/it/guide/collega-la-banca). ## Come Getbeel abbina [#come-getbeel-abbina] Getbeel cerca, per ogni uscita, una fattura ricevuta con lo stesso importo, una data vicina e lo stesso fornitore. Ogni fattura va con un solo movimento. Le entrate non vengono abbinate. Le regole esatte sono in [Corrispondenza transazioni con IA](/it/guide/bank-reconciliation/ai-matching). ## Lo stato di ogni movimento [#lo-stato-di-ogni-movimento] Ogni riga dell'estratto ha uno stato. Lo stato ti dice la prossima azione. | Stato | Cosa significa | Cosa fai | | -------------------------- | ------------------------------------------------------- | ------------------------------------------------------- | | **Da confermare** | Getbeel ha trovato una fattura | **Conferma abbinamento** o **Non è questa fattura** | | **Riconciliato** | L'abbinamento è confermato | Niente | | **Fattura mancante** | Uscita senza fattura | **Aggiungi fattura**, oppure **Fattura non necessaria** | | **Fattura non necessaria** | Hai segnato che non serve una fattura (es. commissioni) | Niente | | **Rifiutato** | L'abbinamento è stato scartato | Collega la fattura giusta | Come si lavora su questi stati è spiegato in [Flusso di revisione](/it/guide/bank-reconciliation/review-workflow). ## Lo stato di un estratto conto [#lo-stato-di-un-estratto-conto] | Stato | Cosa significa | | ------------------------ | ------------------------------------------------------ | | **In attesa** | Il file è caricato e sta per essere letto | | **In elaborazione** | Getbeel legge i movimenti del file | | **Abbinamento in corso** | Getbeel cerca la fattura di ogni uscita | | **Da verificare** | Gli abbinamenti sono pronti per te | | **Completato** | Hai completato la riconciliazione: non si modifica più | | **Non riuscito** | Il file non si è potuto leggere: usa **Riprova** | La pagina si aggiorna da sola mentre un estratto è in elaborazione. ## La pagina Riconciliazione [#la-pagina-riconciliazione] L'elenco mostra ogni estratto con **File**, **Stato**, **Periodo**, **Movimenti**, **Abbinati** e **Caricato**. Filtra per mese con **Tutti i mesi**. In alto vedi quanti **Estratti conto** hai, quanti sono **Da verificare** e il **Totale abbinato**. Dal menu **Altre azioni** (⋯) apri **Collega la banca**. ## Chi può fare cosa [#chi-può-fare-cosa] - **Proprietario** e **Membro** caricano estratti, collegano la banca e verificano gli abbinamenti. - **Commercialista** vede estratti e abbinamenti e li esporta, ma non modifica nulla. Vedi [Ruoli e permessi](/it/guide/team-collaboration/roles-permissions). ## Dall'API e dall'assistente AI [#dallapi-e-dallassistente-ai] Le stesse operazioni sono disponibili con l'[API](/it/api/bank-reconciliation) e con gli strumenti MCP: `upload_bank_statement`, `list_bank_statements`, `get_bank_statement`, `get_reconciliation`, `list_unmatched`, `approve_match`, `match_manually` e `start_reconciliation`. ## Pagine correlate [#pagine-correlate] I formati accettati e cosa succede dopo il caricamento. I movimenti arrivano da soli, senza caricare file. Le regole con cui Getbeel propone una fattura. Conferma, correggi e completa un estratto. # Flusso di revisione (https://docs.getbeel.com/it/guide/bank-reconciliation/review-workflow) Conferma gli abbinamenti proposti, risolvi le fatture mancanti e completa la riconciliazione di un estratto conto. Getbeel propone gli abbinamenti; tu decidi. Un estratto è finito quando ogni uscita è **Riconciliato** o **Fattura non necessaria** e scegli **Completa riconciliazione**. ## Prima di iniziare [#prima-di-iniziare] - **Un estratto in stato Da verificare.** Caricalo ([Caricamento estratti conto](/it/guide/bank-reconciliation/statement-upload)) o [collega la banca](/it/guide/collega-la-banca). - **Il ruolo Proprietario o Membro.** Il ruolo **Commercialista** vede ed esporta, ma non modifica. - **Non serve** controllare le righe già **Riconciliato**: Getbeel le ha confermate perché era sicuro. - **Costo:** confermare è gratuito. Caricare una fattura mancante usa un credito fattura ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Apri l'estratto [#apri-lestratto] Apri **Riconciliazione** e fai clic sull'estratto. In alto vedi l'avanzamento, per esempio "12 di 40 uscite completate". ### Mostra solo cosa serve [#mostra-solo-cosa-serve] Usa i filtri sopra la tabella: - **Tutte**, **Da confermare**, **Fattura mancante** o **Completate**. - **Uscite**, **Entrate** o **Entrate e uscite**. All'apertura vedi solo le **Uscite**. - **Cerca movimenti** per nome o descrizione. ### Conferma le proposte [#conferma-le-proposte] Sulle righe **Da confermare** controlla movimento e fattura. Fai clic sulla fattura per aprirne i dettagli. Poi scegli **Conferma abbinamento** (✓) o **Non è questa fattura** (✕). Per confermarne molte insieme, selezionale e scegli **Conferma abbinamenti** nella barra in basso. ### Risolvi le fatture mancanti [#risolvi-le-fatture-mancanti] Su una riga **Fattura mancante** scegli **Aggiungi fattura**. In **Collega fattura** cerca una fattura esistente, o trascina il PDF o l'immagine (fino a 10 MB). Se il movimento non ha fattura, come una commissione bancaria, apri il menu della riga e scegli **Fattura non necessaria**. ### Aggiungi un movimento che manca [#aggiungi-un-movimento-che-manca] Se il file non conteneva un movimento, scegli **Aggiungi movimento**. Inserisci data, controparte, descrizione, importo e tipo (**Debito** o **Credito**). ### Completa la riconciliazione [#completa-la-riconciliazione] Quando hai finito, scegli **Completa riconciliazione** e poi **Completa**. Dopo non potrai più modificare l'estratto. ## Cosa è successo [#cosa-è-successo] - **Hai aperto l'estratto** e visto quante uscite restano da decidere. - **Hai filtrato** le righe che chiedono un'azione. - **Le proposte giuste sono Riconciliato.** Quelle sbagliate sono tornate **Fattura mancante**. - **Ogni uscita ha la sua fattura**, o è segnata **Fattura non necessaria**. - **Il movimento aggiunto** compare nell'estratto come gli altri. - **L'estratto è Completato** e resta in sola lettura. ## Correggere una decisione [#correggere-una-decisione] - **Rimuovi abbinamento** (menu della riga): la riga torna **Fattura mancante**. - **Serve una fattura**: annulla una **Fattura non necessaria**. - **Elimina transazione**: toglie il movimento e il suo abbinamento dall'estratto. - **Rifai abbinamento** (in alto): cancella movimenti e abbinamenti e rilegge il file da capo. Per la banca collegata rifà solo gli abbinamenti. ## Esportare [#esportare] Seleziona le righe, anche **Seleziona tutte le corrispondenze** del filtro, e scegli **Esporta**. I formati sono: - **CSV**, apribile nei fogli di calcolo. - **Excel**, con colonne formattate. - **Archivio ZIP**, con il file dei dati e i PDF delle fatture abbinate. - **Autofattura XML**, per le righe che hanno un'autofattura. Le colonne includono data, movimento, controparte, importo, fattura abbinata, tipo di abbinamento e stato. Su un estratto caricato, conferme e collegamenti a mano vengono eliminati e rifatti dal file originale. Usalo solo se il file è stato letto male. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | "Impossibile salvare la modifica" | La modifica non è arrivata al server | Ricarica la pagina e riprova | | "Nessun abbinamento da confermare nella selezione" | Le righe scelte non sono **Da confermare** | Filtra **Da confermare** e seleziona di nuovo | | "Nessuna fattura mancante nella selezione" | Le righe scelte hanno già una fattura | Filtra **Fattura mancante** e seleziona di nuovo | | "Crediti fatture esauriti. Passa a un piano superiore o acquista altre fatture." | Il caricamento di una fattura usa un credito | Aggiungi crediti in **Impostazioni → Utilizzo e fatturazione**, o collega una fattura esistente | | "Impossibile riavviare l'abbinamento. Riprova o contatta l'assistenza." | Troppi riavvii oggi, o un'autofattura del file è già allo SDI | Riprova domani; se l'estratto ha autofatture inviate, correggi a mano | | "Impossibile completare la riconciliazione" | Il salvataggio non è riuscito, o l'estratto non è più **Da verificare** | Ricarica la pagina, controlla lo stato e riprova | ## Dall'assistente AI [#dallassistente-ai] Con MCP, `get_reconciliation` legge le righe e `list_unmatched` le uscite senza fattura. `approve_match` conferma una riga, o la scarta con `decision: "reject"`. `match_manually` collega una fattura a mano. Vedi [Collega l'AI](/it/guide/connect-ai). ## Prossimi passi [#prossimi-passi] I pagamenti a fornitori esteri diventano autofatture. I flussi di cassa e l'export usano i movimenti abbinati. Perché una riga è Da confermare o Fattura mancante. # Caricamento estratti conto (https://docs.getbeel.com/it/guide/bank-reconciliation/statement-upload) Carica un estratto conto (CSV, PDF, Excel, testo, CBI, CAMT.053 o MT940): Getbeel legge i movimenti e li abbina alle fatture. Carica l'estratto conto della banca e Getbeel ne legge i movimenti, poi li abbina alle fatture ricevute. I file bancari CBI, CAMT.053 e MT940 sono letti esattamente, senza AI. ## Prima di iniziare [#prima-di-iniziare] - **Il file dell'estratto**, scaricato dall'home banking. Formati accettati: - **CBI** (Rendicontazione movimenti), **CAMT.053** (XML) e **MT940**: letti campo per campo, senza AI. - **CSV**, **PDF** e **testo**: letti con l'AI. - **Fogli di calcolo** (XLS, XLSX, ODS): non letti. Esporta il foglio in CSV e carica il CSV. - **Un file fino a 50 MB.** Puoi caricarne più di uno insieme. - **Il ruolo Proprietario o Membro.** Il **Commercialista** non carica estratti. - **Un piano attivo.** Lettura e abbinamento usano l'AI ([Prezzi](/it/api/pricing)). - **Non serve** se hai [collegato la banca](/it/guide/collega-la-banca): i movimenti arrivano da soli. ## Passi [#passi] ### Apri il caricamento [#apri-il-caricamento] Apri **Riconciliazione** e scegli **Carica estratto conto**. ### Scegli i file [#scegli-i-file] Trascina i file nel riquadro o scegli **sfoglia**. Puoi aggiungerne altri prima di caricare; ogni file diventa un estratto. ### Indica la valuta [#indica-la-valuta] In **Valuta dell'estratto conto** scegli la valuta del conto (euro di default). I file CBI, CAMT.053 e MT940 dichiarano già la loro valuta. ### Carica [#carica] Scegli **Carica ed elabora**. L'estratto passa da **In elaborazione** ad **Abbinamento in corso**, poi a **Da verificare**. La pagina si aggiorna da sola. ## Cosa è successo [#cosa-è-successo] - **Hai aperto il caricamento** nella pagina Riconciliazione. - **Ogni file è un estratto** nell'elenco, con nome, periodo e numero di movimenti. - **La valuta** vale per i movimenti dei file che non la indicano. - **Getbeel ha letto i movimenti** e cercato la fattura di ogni uscita. Ora puoi [verificare gli abbinamenti](/it/guide/bank-reconciliation/review-workflow). ## Come legge i file bancari [#come-legge-i-file-bancari] Getbeel riconosce il formato dal contenuto, non dal nome del file. - **CAMT.053**: XML ISO 20022 `BankToCustomerStatement`, versioni da 001.02 a 001.13. - **CBI**: record da 120 caratteri, flusso RH (movimenti) o EC (estratto conto). - **MT940**: messaggio SWIFT con i tag `:20:`, `:25:`, `:60F:`, `:61:`, `:86:`, `:62F:`. Il saldo iniziale più i movimenti deve dare il saldo finale del file. Se non torna, un movimento è stato letto male: Getbeel rilegge il file con l'AI. Un file con più di 50.000 movimenti non viene importato. Dividilo per periodo. ## Gestire gli estratti [#gestire-gli-estratti] Dal menu di ogni riga puoi: - **Vedi estratto conto** e **Scarica file**: il file originale. - **Rinomina**: cambia il nome mostrato. - **Rifai abbinamento** o, se è **Non riuscito**, **Riprova**: rilegge il file da capo. - **Elimina**: toglie l'estratto con i suoi movimenti e abbinamenti. Non si annulla. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------- | | "“estratto.xls” è un foglio di calcolo: Getbeel non legge i file Excel o ODS. Esporta il foglio in CSV e carica il CSV." | Il file è un foglio di calcolo (anche se rinominato) | Esporta il foglio in CSV e carica il CSV | | "“estratto.zip” non è un file supportato. Usa CSV, PDF o testo." | Estensione non accettata | Esporta dalla banca in CSV, PDF o in un formato bancario | | "“estratto.pdf” supera 50MB." | Il file è più grande di 50 MB | Scarica un periodo più breve | | "Impossibile elaborare “estratto.csv”. Riprova o contatta l'assistenza." | Il caricamento non è partito | Riprova; se si ripete, contatta l'assistenza | | Stato **Non riuscito** | File illeggibile, o più di 50.000 movimenti | Dividi il file, poi **Riprova** dal menu della riga | | Il caricamento chiede un piano | Lettura e abbinamento richiedono un piano attivo | Scegli un piano in **Impostazioni → Utilizzo e fatturazione** | | "Impossibile riavviare l'abbinamento. Riprova o contatta l'assistenza." | Troppi riavvii oggi | Riprova domani | ## Fonti [#fonti] I lettori esatti seguono le specifiche ufficiali, citate nel codice (`apps/web/lib/bank-statements/parsers`): - **CBI**: Consorzio CBI, "CBI-RND-001 Rendicontazioni – Standard tecnici" v6.05 (05-03-2013), §2.1–2.8. La distribuzione ufficiale è riservata ai soci CBI; il testo è stato letto da una copia pubblica. - **CAMT.053**: schemi ufficiali camt.053.001.02–.13 (iso20022.org, Message Definitions) e 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. Il manuale SWIFT è ad accesso riservato e non è stato letto direttamente: le regole dei campi vengono da DK "DFÜ-Abkommen" Anlage 3 v3.7 (05.04.2023) §8, verificate sulla descrizione MT940/MT942 di ING (2016). ## Prossimi passi [#prossimi-passi] Conferma gli abbinamenti dell'estratto appena caricato. Smetti di caricare file: i movimenti arrivano ogni 6 ore. Carica estratti da codice o con `upload_bank_statement`. # Cespiti e ammortamenti (https://docs.getbeel.com/it/guide/cespiti) Registra i beni strumentali, anche da una fattura ricevuta: Getbeel calcola l'ammortamento fiscale, la cessione e il libro cespiti dell'anno. In **Tasse → Cespiti** tieni i beni strumentali: computer, macchinari, arredi, automezzi, software. Getbeel calcola ogni anno quota, fondo e residuo, la plus o minusvalenza alla vendita e il **libro cespiti**. Getbeel calcola gli ammortamenti **fiscali** con i dati che inserisci. Il commercialista verifica categorie, ammortamenti civilistici e scritture di bilancio: Getbeel non tiene la contabilità generale. ## Prima di iniziare [#prima-di-iniziare] - **I dati del bene**: costo, data di acquisto e data di entrata in funzione. Se il bene è in una fattura ricevuta in Getbeel, il resto lo prende da lì. - **Non serve** conoscere il coefficiente: lo scegli con la categoria. - **Costo**: salvare i cespiti è gratis ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Apri il modulo [#apri-il-modulo] Apri **Tasse → Cespiti** e scegli **Aggiungi cespite**. ### Parti dalla fattura ricevuta [#parti-dalla-fattura-ricevuta] In **Fattura ricevuta** scegli la fattura del bene: data, fornitore e numero si compilano da soli. In **Riga della fattura** scegli la riga del bene per riprendere descrizione e costo. Senza fattura scegli **Nessuna (inserisci a mano)**. ### Scegli la categoria [#scegli-la-categoria] In **Categoria (coefficiente ministeriale)** scegli la voce del bene: ognuna ha il suo coefficiente. Se non c'è, scegli **Altra categoria: inserisco io il coefficiente**. ### Indica costo e date [#indica-costo-e-date] Inserisci **Costo (€)**, al netto dell'IVA detraibile e con gli oneri accessori. Poi **Data di acquisto** ed **Entrata in funzione**. Lascia vuota l'entrata in funzione se il bene non è ancora in uso. ### Salva [#salva] Scegli **Salva**. Il bene compare nel **Libro cespiti** con la quota dell'anno. ## Cosa è successo [#cosa-è-successo] - **Il bene è nel libro cespiti** con costo, coefficiente, fondo e residuo dell'anno scelto. - **L'ammortamento sostituisce il costo**: nella [stima delle imposte](/it/guide/stima-imposte) la fattura del bene non conta più tra i costi, al suo posto conta la quota. ## Come calcola l'ammortamento [#come-calcola-lammortamento] - L'ammortamento parte dall'**anno di entrata in funzione**, non da quello di acquisto (art. 102 c. 1 TUIR). - Ogni anno si deduce al massimo **costo × coefficiente ministeriale**, ridotto **alla metà nel primo anno** (art. 102 c. 2). La metà vale qualunque sia la data: Getbeel non calcola i giorni. - Il coefficiente è un tetto: puoi dedurre meno, e il piano dura più anni. Le quote dedotte negli anni passati si registrano via API (`depreciation_overrides`). - I beni materiali di **costo unitario fino a 516,46 €** si possono dedurre per intero nell'anno (art. 102 c. 5). Per i lavoratori autonomi la soglia è 516,40 € (art. 54-quinquies). Attiva **Deduci per intero nell'anno**. - **Software, brevetti e know-how**: fino al 50% l'anno. **Marchi e avviamento**: fino a 1/18 l'anno (art. 103). Per i beni immateriali niente metà nel primo anno. - Gli importi sono arrotondati per difetto al centesimo, per non superare mai la quota massima. ### Coefficienti [#coefficienti] Le categorie vengono dal **DM 31 dicembre 1988**, nella tabella in vigore dal 16 maggio 1996 (DM 28 marzo 1996). Ecco i gruppi più usati da piccole imprese e professionisti: | Bene ("Attività non precedentemente specificate – Altre attività") | Coefficiente | | ---------------------------------------------------------------------------------------------- | ------------ | | Edifici | 3% | | Fabbricati destinati alla grande distribuzione | 6% | | Costruzioni leggere | 10% | | Impianti e mezzi di sollevamento, carico, scarico, pesatura | 7,5% | | Macchinari, apparecchi e attrezzature varie | 15% | | Arredamento | 15% | | Mobili e macchine ordinarie d'ufficio | 12% | | Macchine d'ufficio elettromeccaniche ed elettroniche, computer, sistemi telefonici elettronici | 20% | | Impianti di allarme e di ripresa | 30% | | Autoveicoli da trasporto | 20% | | Autovetture, motoveicoli e simili | 25% | Ci sono anche le voci del Gruppo 19 (alberghi, ristoranti, bar) e del Gruppo XXII specie I (servizi alla persona). I professionisti usano il coefficiente dello stesso bene nell'attività d'impresa corrispondente (art. 2 del DM). Alcuni limiti non sono calcolati. Getbeel li segnala accanto alla categoria: - **auto**: deducibili al 20% (80% per gli agenti), con costo massimo di 18.075,99 € (art. 164 TUIR); - **telefonia**: quote deducibili all'80% (art. 102 c. 9); - **fabbricati**: la parte del costo riferita al terreno non si ammortizza. ## Vendere o eliminare un bene [#vendere-o-eliminare-un-bene] ### Registra la cessione [#registra-la-cessione] Sulla riga del bene scegli **Cessione**. Inserisci **Data di cessione** e **Prezzo (€)**: 0 se il bene è stato eliminato. Scegli **Salva**. Getbeel calcola: - **plusvalenza** = prezzo − costo non ancora ammortizzato (art. 86 c. 2 TUIR); - **minusvalenza** se il prezzo è più basso (art. 101 c. 1). Nell'anno della cessione Getbeel non calcola la quota: tutto il residuo entra nella plus o minusvalenza. Dal 2026 la plusvalenza su un singolo bene è tassata tutta nell'anno. La rateizzazione in cinque anni resta solo per la cessione dell'azienda (art. 86 c. 4, come sostituito dalla L. 199/2025 art. 1 c. 42). Un cespite inserito per errore non è una cessione. Sceglilo, poi **Elimina**: esce dal libro cespiti di ogni anno. ## Libro cespiti e scritture di chiusura [#libro-cespiti-e-scritture-di-chiusura] Scegli l'anno e scarica il **Libro cespiti** con **CSV** o **Excel**. Per ogni bene ci sono costo, coefficiente, fondo al 1° gennaio, quota dell'anno, fondo al 31 dicembre, residuo ed eventuale cessione. Sotto trovi **Scritture di chiusura (riepilogo)**: le quote di ammortamento per categoria, i beni dedotti per intero e le plus o minusvalenze. Passalo al commercialista, che le registra in contabilità. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- | | "Il coefficiente supera quello ministeriale della categoria (art. 102 c. 2 TUIR)." | Il coefficiente inserito è più alto del massimo | Usa un coefficiente uguale o più basso | | "La deduzione integrale vale solo per beni materiali di costo unitario fino a 516,46 €." | Il bene costa di più, o è immateriale | Disattiva **Deduci per intero nell'anno** | | "L'entrata in funzione non può precedere l'acquisto." | Le date sono invertite | Correggi **Data di acquisto** o **Entrata in funzione** | | "Indica sia la data sia il prezzo di cessione." | Nella cessione manca un dato | Inserisci entrambi; 0 se il bene è eliminato | | "La fattura ricevuta scelta non esiste più." | La fattura è stata eliminata | Scegli **Nessuna (inserisci a mano)** | | "Serve un piano attivo per salvare: scegli un piano in Impostazioni → Utilizzo e fatturazione." | L'account non ha un piano | Scegli un piano in **Impostazioni → Utilizzo e fatturazione** | ## Fonti [#fonti] - TUIR (DPR 917/1986), artt. 86, 101, 102, 103, 164, 54-quinquies, testo in vigore al 31 dicembre 2026 ([Normattiva](https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.presidente.repubblica:1986-12-22;917~art102!vig=2026-10-01)). Dal 1° gennaio 2027 il TUIR è sostituito dal Testo unico D.Lgs. 117/2026. - DM 31 dicembre 1988, coefficienti di ammortamento ([copia dell'Agenzia delle Entrate](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)). Non confermato in una fonte ufficiale: che nell'anno della cessione non si deduca la quota. È la prassi seguita da Getbeel. ## Prossimi passi [#prossimi-passi] Gli ammortamenti entrano nella stima di IRES, IRAP o forfettario. Consegna libro cespiti e dati al commercialista. Registra i cespiti dal tuo codice o dall'assistente AI. # Codice destinatario (https://docs.getbeel.com/it/guide/codice-destinatario) Cos'è il codice destinatario, come si registra presso l'Agenzia delle Entrate e cosa cambia con Getbeel. Il **codice destinatario** è il codice di 7 caratteri che dice allo SDI dove recapitare le fatture destinate a te. Se lo registri come indirizzo telematico, vale per tutte le tue fatture, qualunque codice scriva il fornitore. ![Una fattura non consegnata (MC): risulta emessa, è nel cassetto fiscale dalla data indicata e non va inviata di nuovo.](/screenshots/invoice-not-delivered.it.webp) ## Le regole in breve [#le-regole-in-breve] | | Come funziona | | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Chi lo assegna | Il canale che riceve le fatture per te: un software o un intermediario. In alternativa si usa una PEC. | | Indirizzo telematico | Il codice (o la PEC) che registri nel portale **Fatture e Corrispettivi**. Prevale su quello scritto in fattura. | | Senza indirizzo registrato | Lo SDI usa il codice o la PEC scritti dal fornitore. | | Fatture non recapitabili | Restano nella tua area riservata di Fatture e Corrispettivi. | | Invio di fatture | Non serve registrare nulla: il codice riguarda solo la ricezione. | Fonte: Agenzia delle Entrate, [La fattura elettronica e i servizi gratuiti](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guida_fattura_elettronica_dicembre_2025) (dicembre 2025), pp. 18–20 e 25. ## Il codice destinatario di Getbeel [#il-codice-destinatario-di-getbeel] Getbeel può ricevere le fatture dei fornitori direttamente dallo SDI. Arrivano in **Fatture ricevute** con il badge **SDI**, già lette dall'XML, accanto a quelle raccolte dalle email. Se la stessa fattura arriva sia dalla email sia dallo SDI, Getbeel la tiene una volta sola. ### Prima di iniziare [#prima-di-iniziare] - **Un'azienda italiana** con P.IVA (o codice fiscale), regime fiscale e indirizzo in **Impostazioni → Azienda**. - **L'add-on SDI attivo**, da **Impostazioni → Utilizzo e fatturazione**. Ogni fattura ricevuta dallo SDI si paga ([Prezzi](/it/api/pricing)). - **L'accesso a Fatture e Corrispettivi** con SPID, CIE o CNS, come legale rappresentante o con delega. - **Il ruolo giusto**: solo chi gestisce le impostazioni del team può attivare la ricezione. ### Passi [#passi] ### Controlla cosa manca [#controlla-cosa-manca] Apri **Impostazioni → Ricezione SDI**. La lista **Cosa manca** mostra i passi da completare, ognuno con il suo link. ### Attiva la ricezione [#attiva-la-ricezione] Premi **Attiva la ricezione**. Getbeel mostra **Il tuo codice destinatario**, con il pulsante **Copia**. ### Registra il codice come indirizzo telematico [#registra-il-codice-come-indirizzo-telematico] Premi **Apri Fatture e Corrispettivi** e accedi. Apri **Fatturazione elettronica e Conservazione**, poi **Registrazione dell'indirizzo telematico**. In alcune versioni si chiama **Registrazione delle modalità di ricezione**. Scegli **Codice destinatario**, incolla il codice e conferma. L'Agenzia ti mostra la ricevuta di registrazione. ### Conferma in Getbeel [#conferma-in-getbeel] Torna in **Impostazioni → Ricezione SDI** e premi **Ho registrato il codice**. ### Cosa è successo [#cosa-è-successo] - **Getbeel riceve per la tua P.IVA.** Lo stato della ricezione è **Attiva**. - **Lo SDI recapita tutto a Getbeel.** L'indirizzo registrato prevale sul codice scritto dai fornitori. - **L'indirizzo precedente è sostituito.** Se avevi un altro software o una PEC, da ora le fatture arrivano solo in Getbeel. - **Le fatture compaiono in Fatture ricevute** con il badge **SDI**. Le filtri con **Vedi le fatture SDI**. Se non registri il codice, in Getbeel arrivano solo le fatture dei fornitori che lo scrivono in fattura. ### Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | --------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------- | | "Completa prima i dati dell'azienda (P.IVA, regime fiscale, indirizzo)." | Mancano dati aziendali | Completa **Impostazioni → Azienda** | | "La ricezione via SDI richiede l'add-on SDI. Attivalo in Fatturazione." | Manca l'add-on SDI | Apri **Impostazioni → Utilizzo e fatturazione** | | "Un altro workspace Getbeel riceve già le fatture per questa P.IVA. Scrivici se è tua." | La P.IVA è attiva in un altro team | Contatta il supporto | | "Il canale SDI non ha risposto. Riprova tra qualche minuto." | Il canale di ricezione non ha risposto | Premi **Riprova l'attivazione** | | "Solo chi gestisce le impostazioni del workspace può attivare la ricezione." | Il tuo ruolo non può farlo | Chiedi a un Proprietario | Con **Disattiva la ricezione** Getbeel smette di ricevere per questa P.IVA. Cambia l'indirizzo telematico nel portale, altrimenti le nuove fatture arrivano solo nel cassetto fiscale. ## Domande frequenti [#domande-frequenti] **Se non registro nulla perdo le fatture?** No. Le fatture non recapitabili restano nella tua area riservata di Fatture e Corrispettivi. Però le devi andare a prendere tu. **Devo comunque dare il codice ai fornitori?** Conta l'indirizzo registrato. Comunicare il codice giusto ai fornitori evita confusione. **Posso usare anche le email?** Sì. Caselle collegate e inoltro continuano a portare fatture in Getbeel, senza doppioni. ## Correlati [#correlati] Il passo consigliato dopo la ricezione, nella stessa pagina. Dove arrivano le fatture dello SDI e delle email. Stato e checklist con `GET /sdi-receiving` e gli strumenti MCP. # Collega la banca (https://docs.getbeel.com/it/guide/collega-la-banca) I movimenti del conto arrivano da soli in Getbeel, senza caricare estratti conto. Guida passo per passo. Con la banca collegata, Getbeel scarica i movimenti dei tuoi conti ogni 6 ore e li abbina alle fatture. Non devi più caricare estratti conto. Il collegamento passa da **Enable Banking**, un servizio europeo autorizzato a leggere i conti con il tuo consenso. Usi un'applicazione Enable Banking **intestata alla tua azienda**: Getbeel legge i movimenti con la tua chiave, e solo dei conti che autorizzi. ## Prima di iniziare [#prima-di-iniziare] - **L'accesso all'home banking** dell'azienda. - **Credito sul saldo prepagato.** Ogni conto collegato costa 2 € al mese e ogni movimento importato 0,02 € ([Prezzi](/it/api/pricing)). Enable Banking è gratuito. Se ti sei registrato prima del 13 novembre 2026, i conti collegati sono inclusi nel tuo piano a pagamento attivo: non serve il saldo. - **Il ruolo Proprietario o Membro.** Il **Commercialista** vede le banche collegate ma non le gestisce. - **Circa 10 minuti**, una volta sola, sullo **stesso browser** dall'inizio alla fine. - **Non serve** caricare estratti conto: i movimenti arrivano da soli. ## Passi [#passi] ### Crea un account Enable Banking [#crea-un-account-enable-banking] Vai su [enablebanking.com](https://enablebanking.com/sign-in/) e registrati con l'email aziendale. ### Crea un'applicazione [#crea-unapplicazione] Nel [pannello di controllo](https://enablebanking.com/cp/applications) apri **Applications → Register new application**: - Ambiente: **Production**. - Nome: per esempio "Getbeel - Rossi S.r.l.". - Chiave: scegli **Generate in the browser** ed esporta la chiave privata. Salva il file `.pem`: ti serve al passo 5. - Se chiede gli indirizzi di privacy e termini, usa quelli del sito della tua azienda. Annota l'**Application ID** che compare sotto il nome. ### Aggiungi l'indirizzo di ritorno di Getbeel [#aggiungi-lindirizzo-di-ritorno-di-getbeel] Nella stessa applicazione, in **Allowed redirect URLs**, incolla esattamente: ```text https://getbeel.com/api/open-banking/callback ``` In Getbeel lo trovi anche nella pagina della banca, con il pulsante **Copia**. ### Attiva l'applicazione collegando i tuoi conti [#attiva-lapplicazione-collegando-i-tuoi-conti] Scegli **Activate by linking accounts** e accedi alla tua banca. L'applicazione si attiva in **modalità limitata**: leggerà solo i conti che colleghi qui. Collega tutti i conti che vuoi vedere in Getbeel. ### Carica ID e chiave in Getbeel [#carica-id-e-chiave-in-getbeel] In Getbeel apri **Riconciliazione**, poi **Altre azioni** (⋯) → **Collega la banca**. Inserisci: - l'**ID dell'applicazione**; - la **Chiave privata (.pem)**, con **Scegli il file .pem**; - il **Tipo di conto**: **Conto aziendale** (S.r.l. e partite IVA con home banking business) o **Conto personale**; - il **Paese della banca**. Scegli **Verifica e continua**. ### Scegli la banca e accedi [#scegli-la-banca-e-accedi] Cerca la tua banca in **Cerca la tua banca** e scegli **Vai alla banca**. Accedi come fai di solito e autorizza la lettura dei conti. Hai 30 minuti, nello stesso browser. ## Cosa è successo [#cosa-è-successo] - **Hai un account Enable Banking** a nome dell'azienda. - **L'applicazione è tua**, con la tua chiave privata. - **Getbeel può ricevere il ritorno** dalla banca all'indirizzo autorizzato. - **L'applicazione è attiva** e vede solo i conti che hai collegato. - **Getbeel ha verificato la chiave** con Enable Banking e l'ha salvata cifrata (AES-256): non è più visibile a nessuno, nemmeno a te. - **La banca è collegata.** I movimenti degli ultimi 90 giorni arrivano in **Riconciliazione** in pochi minuti, un estratto per conto e per mese, già abbinati alle fatture. ## Dopo il collegamento [#dopo-il-collegamento] - **Aggiornamenti**: ogni 6 ore. Con **Sincronizza ora** aggiorni subito. - **Consenso**: la banca lo concede per un massimo di 180 giorni (alcune banche meno). Sette giorni prima della scadenza, e di nuovo se scade, Getbeel manda un'email ai proprietari del team e mostra un avviso in Riconciliazione. Scegli **Ricollega** e rifai l'accesso alla banca. I movimenti già scaricati restano. - **Movimenti in attesa**: quelli che la banca non ha ancora contabilizzato compaiono sotto il conto come **In attesa di contabilizzazione**. Non vengono abbinati; quando la banca li contabilizza diventano movimenti normali. - **Fornitori esteri**: come per gli estratti caricati, l'AI riconosce i pagamenti a fornitori esteri e li propone in **Autofatture**. - **Più banche**: con **Collega un'altra banca** ne colleghi fino a 10. - **Scollega**: chiude il consenso presso la banca e cancella la chiave. Estratti e abbinamenti restano. Getbeel usa la chiave solo per leggere i movimenti dei conti autorizzati. Non può disporre pagamenti. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ------------------------------------------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | "Questo non è il file della chiave privata" | Hai caricato un file diverso dalla chiave | Carica il file `.pem` esportato al passo 2 (inizia con `-----BEGIN PRIVATE KEY-----`), non il certificato | | "Enable Banking non riconosce l'ID dell'applicazione o la chiave" | ID e chiave di applicazioni diverse, o applicazione non attiva | Controlla che siano della stessa applicazione e rifai il passo 4 | | "La tua applicazione Enable Banking non consente l'indirizzo di ritorno di Getbeel" | Manca l'indirizzo tra gli Allowed redirect URLs | Rifai il passo 3: l'indirizzo deve essere identico | | "La banca non ha condiviso nessun conto" | L'applicazione è in modalità limitata senza conti | Collega i conti in Enable Banking (passo 4), poi **Ricollega** | | "Completa l'accesso alla banca nello stesso browser in cui l'hai avviato su Getbeel" | Hai finito l'accesso su un altro browser o dispositivo | Ricomincia da Getbeel con **Ricollega** e completa l'accesso alla banca in quel browser, non su un altro dispositivo | | "Il collegamento è scaduto (hai 30 minuti per completare l'accesso alla banca)" | Sono passati più di 30 minuti | Riprova dal passo 6 | | "L'accesso è stato annullato o rifiutato dalla banca" | Hai annullato, o la banca ha rifiutato | Riprova quando vuoi | | "Hai già collegato 10 banche" | Hai raggiunto il limite | Scollega una banca per aggiungerne un'altra | | "Il consenso della banca è scaduto: ricollega la banca." | Sono passati i giorni del consenso, o l'hai revocato | Scegli **Ricollega** | ## Prossimi passi [#prossimi-passi] Conferma gli abbinamenti dei movimenti appena arrivati. I pagamenti a fornitori esteri, pronti come autofatture. Collega la banca da codice o dall'assistente AI. # Collegare i POS ai registratori telematici (https://docs.getbeel.com/it/guide/collegamento-pos-rt) Dal 2026 ogni POS va collegato all'RT nel portale dell'Agenzia delle Entrate. Getbeel tiene i collegamenti, ti dice entro quando comunicarli e prepara il file CSV per il caricamento massivo. Dal 1° gennaio 2026 chi certifica i corrispettivi con un **registratore telematico** (RT) deve collegare all'RT ogni **POS** con cui incassa. Il collegamento si comunica nell'area **Fatture e Corrispettivi** dell'Agenzia delle Entrate (L. 207/2024, art. 1 c. 74 e 77; provv. AdE prot. 424470 del 31 ottobre 2025). In **Tasse → POS e RT** inserisci i collegamenti. Getbeel ti dice **entro quando** comunicarli e prepara il **file CSV** per il caricamento massivo. Il caricamento sul portale lo fai tu. ## Prima di iniziare [#prima-di-iniziare] - **La matricola dell'RT** (o del Server RT). - **I dati del POS**, dal contratto con la banca o il gestore: acquirer, tipo di POS, Terminal ID, numero di convenzione. - **L'accesso all'area riservata** dell'Agenzia con SPID, CIE, CNS, Fisconline o Entratel. Getbeel non ti chiede mai queste credenziali. - **Costo**: salvare i collegamenti è gratis ([Prezzi](/it/api/pricing)). ## Entro quando [#entro-quando] - **POS già attivi a gennaio 2026**: entro 45 giorni dall'apertura del servizio (5 marzo 2026), cioè entro il **20 aprile 2026**. - **Nuovi POS e modifiche** (POS spostato su un altro RT, nuovo RT, POS o RT dismesso): dal **6° giorno** all'**ultimo giorno lavorativo del secondo mese successivo** al collegamento. - Esempio: un POS attivato il 1° febbraio si comunica tra il 6 e il 30 aprile. - Il sabato non è lavorativo. Una comunicazione entro l'ultimo giorno del mese non è comunque tardiva. ## Passi [#passi] ### Aggiungi il collegamento [#aggiungi-il-collegamento] Apri **Tasse → POS e RT** e scegli **Aggiungi collegamento**. Compila i campi descritti in [Cosa inserire](#cosa-inserire) e scegli **Salva**. ### Scarica il file [#scarica-il-file] Scegli **Scarica il CSV**. Ogni file ha al massimo 1.000 righe: se sono di più, Getbeel le divide in parti. ### Accedi al portale [#accedi-al-portale] Scegli **Apri Fatture e Corrispettivi** e accedi. Scegli l'utenza di lavoro: la tua azienda, o la delega diretta se sei un intermediario con la delega "Accreditamento e censimento dispositivi". ### Apri il collegamento massivo [#apri-il-collegamento-massivo] Nel riquadro **Corrispettivi** scegli **vai a Corrispettivi**, poi **Accedi ai servizi** in **Gestore ed Esercente**. Nel menu **Collegamento dispositivi – POS** apri **Gestione collegamenti → Collegamento massivo**. ### Carica il file [#carica-il-file] Scegli **Scegli il file**, seleziona il CSV di Getbeel e scegli **Invia**. ### Controlla l'esito [#controlla-lesito] Apri **Storico richieste massive** sul portale. Se è tutto elaborato, torna su Getbeel e scegli **Ho caricato il file: segna come comunicati**. ## Cosa è successo [#cosa-è-successo] - **I collegamenti sono registrati** in Getbeel, con la data entro cui comunicarli. - **Il file è caricato** sul portale dell'Agenzia, che collega i POS ai tuoi RT. - **I collegamenti risultano Comunicato** in Getbeel e non si modificano più. ## Cosa inserire [#cosa-inserire] Per ogni POS usato con un RT: - **Matricola RT**: la matricola del registratore o del Server RT; - **Acquirer**: la banca o il gestore che ti ha dato il POS, italiano o estero, con codice fiscale e denominazione (11 cifre per gli italiani, es. 04107060966 per Nexi); - **Tipo di POS**: fisico (anche SoftPOS) con il suo **ID terminale**, o virtuale (pagamenti online); - **Numero di convenzione**: il contratto con l'acquirer; - **Indirizzo dell'esercizio** (indirizzo, civico, comune, provincia, CAP), oppure **RT ambulante** se l'RT è sempre usato in forma itinerante; - **Usato con questo RT dal**: la data da cui dipende la scadenza. Un RT può avere più POS. Un POS fisico può andare su più RT solo allo stesso indirizzo. Un collegamento già comunicato non si modifica. Scegli **Chiudi**, indica la **Data di fine** e aggiungine uno nuovo. ## Il formato del file [#il-formato-del-file] Colonne e valori seguono il Manuale operativo dell'Agenzia (aprile 2026): - `TipoAcquirer`, `IdentificativoAcquirer`, `DenominazioneAcquirer`; - `TipoPos` (00 fisico, 01 virtuale) e `TerminalId` (solo POS fisici); - `Convenzione`, `Matricola`, `Operazione` (I associa, C chiude); - `Ambulante` (1 o 0), `UbicazioneProv`, `UbicazioneComune`, `UbicazioneIndirizzo`, `UbicazioneCivico`, `UbicazioneCap`; - `DataFine` (MMAAAA, solo per C). Gli zeri iniziali sono mantenuti. Separatore, codifica e nomi esatti delle intestazioni non sono in nessun documento ufficiale. Getbeel usa punto e virgola e UTF-8. Se il portale rifiuta il file, scarica il modello dal portale, scegli **Copia le righe per il modello AdE** e incollale lì. Il caricamento massivo collega solo i POS che l'acquirer ha già comunicato all'Agenzia. Un POS che non compare va aggiunto con la procedura puntuale del portale ("Aggiungi nuovo POS"). Per il **Documento Commerciale online** il collegamento si fa dentro quella procedura web, non con il file. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | | "Il collegamento è già stato comunicato: chiudilo con una data di fine e aggiungine uno nuovo." | Hai provato a modificare un collegamento comunicato | Scegli **Chiudi** e aggiungi un nuovo collegamento | | "Questo POS è già collegato a questo RT." | Il collegamento esiste già | Usa quello esistente | | "Per un POS fisico serve il Terminal ID." | Manca l'ID terminale | Copialo dallo scontrino del POS o dal contratto | | "Il codice fiscale di un acquirer italiano ha 11 cifre." | Il codice dell'acquirer è incompleto | Inseriscilo con gli zeri iniziali | | "Non usare punto e virgola, virgolette o a capo: romperebbero il file CSV." | Un campo contiene caratteri non ammessi | Toglili dal campo | | Il portale rifiuta il file | Il modello del portale usa un formato diverso | Scegli **Copia le righe per il modello AdE** e incollale nel modello | ## Fonti [#fonti] - [Collegamento POS-RT](https://www.agenziaentrate.gov.it/portale/collegamento-pos-rt), Agenzia delle Entrate. - [Provvedimento prot. 424470 del 31 ottobre 2025](https://www.agenziaentrate.gov.it/portale/documents/d/guest/decreto-legislativo-del-05_08_2015-n-127_), punti 2 e 3. - [Manuale operativo](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-2_-manuale-operativo2026-04-29) (29 aprile 2026), "Procedura di collegamento massivo", pp. 15–17. - [Guida operativa POS-RT](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guidaoperativa_pos-rt) (febbraio 2026) e [FAQ](https://www.agenziaentrate.gov.it/portale/documents/d/guest/faq_collegamento_pos_rt_2503) (25 marzo 2026). ## Prossimi passi [#prossimi-passi] Le altre scadenze fiscali dell'azienda. Gestisci i collegamenti POS–RT dal tuo codice. # Collega Claude, ChatGPT o Cursor (https://docs.getbeel.com/it/guide/connect-ai) Come collegare il tuo assistente AI a Getbeel, passo per passo. *Video tutorial in arrivo.* Getbeel si collega agli assistenti AI con MCP, lo standard che permette a un assistente di usare strumenti esterni. Aggiungi un indirizzo e accedi con il tuo account Getbeel: nessuna chiave da copiare. ![La pagina Chiavi API e MCP: chiavi di test e live, permessi e indirizzo del server MCP.](/screenshots/api-keys-mcp.it.webp) ## Prima di iniziare [#prima-di-iniziare] - **Un account Getbeel** con un team in cui puoi gestire le impostazioni. - **Un assistente** che accetta connettori MCP remoti: Claude (web, desktop o Claude Code), ChatGPT, Cursor. - **L'indirizzo del server**: `https://www.getbeel.com/api/mcp`. Lo trovi anche in **Impostazioni → Chiavi API e MCP**. - **Non serve** una chiave API: accedi con il tuo account. - **Costo**: il server MCP non si paga a parte. Le fatture inviate in live allo SDI seguono il listino ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Aggiungi Getbeel all'assistente [#aggiungi-getbeel-allassistente] Su claude.ai o in Claude Desktop apri **Impostazioni → Connettori** e scegli **Aggiungi connettore personalizzato**. Nome `Getbeel`, URL `https://www.getbeel.com/api/mcp`. Poi scegli **Connetti**. In ChatGPT apri **Impostazioni → App e connettori** e attiva la modalità sviluppatore. Crea un connettore con URL `https://www.getbeel.com/api/mcp` e autenticazione **OAuth**. Poi scegli **Connetti**. In **Settings → MCP** aggiungi un server, oppure crea il file `.cursor/mcp.json`: ```json title=".cursor/mcp.json" { "mcpServers": { "getbeel": { "url": "https://www.getbeel.com/api/mcp" } } } ``` Poi clicca **Needs login** accanto al server. Nel terminale: ```bash claude mcp add --transport http getbeel https://www.getbeel.com/api/mcp ``` Poi esegui `/mcp` in Claude Code e scegli **Authenticate**. ### Accedi a Getbeel [#accedi-a-getbeel] Si apre una pagina di Getbeel: **Collega … a Getbeel**, con il nome dell'app. Accedi, o crea un account. ### Controlla dove torni [#controlla-dove-torni] La pagina mostra dove ti porta **Consenti**: l'host completo, come `claude.ai`, o un'app sul tuo dispositivo. Solo Claude (`claude.ai`) e ChatGPT (`chatgpt.com`) risultano verificate. Per ogni altra app, Cursor e Claude Code compresi, vedi **Getbeel non ha verificato questa app**. Autorizzala solo se hai avviato tu il collegamento e riconosci la destinazione. ### Scegli team, modalità e permessi [#scegli-team-modalità-e-permessi] - **Team**: l'azienda su cui lavora l'assistente. - **Modalità**: **Test** per provare, nulla arriva allo SDI; **Live** per le fatture vere. - **Permessi**: cosa può leggere e fare. Per iniziare vanno bene quelli predefiniti. ### Consenti l'accesso [#consenti-laccesso] Scegli **Consenti**. Torni all'assistente, già collegato. ### Prova il collegamento [#prova-il-collegamento] Chiedi: **"Con Getbeel, chi sono?"**. L'assistente usa lo strumento `whoami` e risponde con il nome della tua azienda e la modalità. ## Cosa è successo [#cosa-è-successo] - **L'assistente agisce come te** su quel team, con i permessi che hai scelto. - **In modalità Test** lavora nella sandbox: nessuna fattura arriva allo SDI. - **Il collegamento compare** in **Impostazioni → Chiavi API e MCP → App collegate**, con l'ultimo utilizzo. ## Sicurezza [#sicurezza] - **Parti da Test.** Ricollega in **Live** solo quando ti fidi del flusso. - **Chiedi conferma prima di inviare.** Lascia attiva l'approvazione degli strumenti nell'assistente, almeno per `send_invoice`. - **Revoca in un attimo.** In **App collegate** scegli **Revoca**: l'assistente perde subito l'accesso. In **Live** `send_invoice` emette una fattura vera, con valore fiscale, e non si annulla. Controlla cliente, importi e IVA prima di confermare. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ---------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------- | | "Questo link non è valido" | La richiesta di collegamento è scaduta o non è valida | Torna all'assistente e collegalo di nuovo | | "Per collegare un'app ti serve un team in cui puoi gestire le impostazioni." | Non hai un team, o il tuo ruolo non gestisce le impostazioni | Crea un team o chiedi l'accesso a un proprietario | | "Getbeel non ha verificato questa app" | L'app non è Claude o ChatGPT | Continua solo se hai avviato tu il collegamento e riconosci la destinazione | | "Impossibile collegare l'app" | Il collegamento non è riuscito | Riprova dall'assistente | | L'assistente non trova Getbeel | Il connettore non è attivo nella conversazione | Attivalo e inizia la richiesta con "Con Getbeel…" | I client che accettano solo un header possono usare una chiave API: vedi il [riferimento del server MCP](/it/api/mcp#con-una-chiave-api). ## Prossimi passi [#prossimi-passi] Cosa chiedere all'assistente, con gli strumenti che usa. Tutti i 128 strumenti, con scope e argomenti. Come ottenere ogni esito SDI senza inviare nulla. # Conservazione gratuita dell'Agenzia delle Entrate (https://docs.getbeel.com/it/guide/conservazione) Le fatture elettroniche vanno conservate a norma. L'Agenzia delle Entrate offre un servizio gratuito: ecco come attivarlo. Le fatture elettroniche, emesse e ricevute, vanno conservate a norma: una copia in una cartella o in un software non basta. L'Agenzia delle Entrate conserva gratis le fatture passate dallo SDI, se aderisci al suo servizio. ## Le regole in breve [#le-regole-in-breve] | | Servizio di conservazione dell'Agenzia | | ------------------- | -------------------------------------------------------------------------- | | Costo | Gratuito | | Cosa conserva | Le fatture emesse e ricevute tramite lo SDI, dalla data di adesione in poi | | Chi aderisce | L'azienda, o un intermediario con la sua delega | | Durata dell'accordo | Tre anni, poi va rinnovato | | Dove | Portale **Fatture e Corrispettivi** | Fonte: 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). ## Cosa fa Getbeel e cosa no [#cosa-fa-getbeel-e-cosa-no] - **Archivia** XML, PDF e ricevute SDI di ogni fattura nel tuo account, consultabili dall'app. - **Non è un conservatore.** L'archivio di Getbeel non sostituisce la conservazione a norma. - **Non può aderire per te.** L'adesione la fa l'azienda o un intermediario con delega, per esempio il commercialista. - **Trasmette dallo SDI.** Le fatture inviate e ricevute con Getbeel passano dallo SDI, quindi rientrano nel servizio. ## Aderire e segnarlo in Getbeel [#aderire-e-segnarlo-in-getbeel] ### Accedi a Fatture e Corrispettivi [#accedi-a-fatture-e-corrispettivi] Accedi a [Fatture e Corrispettivi](https://ivaservizi.agenziaentrate.gov.it/portale/) con SPID, CIE o CNS. ### Aderisci al servizio [#aderisci-al-servizio] Apri **Fatturazione elettronica e Conservazione**, poi **Conservazione** e **Adesione al servizio di conservazione**. Accetta l'accordo di servizio. ### Scrivi la data in Getbeel [#scrivi-la-data-in-getbeel] Apri **Impostazioni → Ricezione SDI**, riquadro **Conservazione a norma**. Inserisci la **Data di adesione** e premi **Salva**. ## Cosa è successo [#cosa-è-successo] - **Le fatture passate dallo SDI sono conservate** dall'Agenzia, dalla data di adesione. - **Getbeel calcola la scadenza** a tre anni e mostra **Adesione del …, scadenza …**. - **Lo stato compare nella lista Cosa manca**: **Attiva**, **Scaduta** o **Non attiva**. Via API è il campo `conservazione` di `GET /sdi-receiving`. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ----------------------------------------------- | ----------------------------------- | ---------------------------------------------------- | | "Controlla la data: non può essere nel futuro." | La data di adesione è dopo oggi | Scrivi la data della ricevuta di adesione | | **Scaduta** | Sono passati tre anni dall'adesione | Rinnova l'accordo nel portale e scrivi la nuova data | ## Cosa resta fuori [#cosa-resta-fuori] Il servizio conserva solo le fatture passate dallo SDI. Altri documenti vanno conservati in altro modo: fatture estere in PDF o cartacee, contratti, documenti contabili. Chiedi al tuo commercialista o a un conservatore. Questa pagina è informativa e non sostituisce la consulenza del tuo commercialista. Fa fede quanto pubblicato dall'Agenzia delle Entrate. ## Correlati [#correlati] Ricevi le fatture dallo SDI nella stessa pagina delle impostazioni. Lo stato della conservazione in `GET /sdi-receiving`. # Dichiarazione IVA annuale (https://docs.getbeel.com/it/guide/dichiarazione-iva) I dati della dichiarazione IVA dai registri IVA di Getbeel, la LIPE controllata con lo schema ufficiale, e cosa resta da fare a te o al commercialista. Getbeel prepara i **dati** della dichiarazione IVA annuale dai registri IVA e dalle liquidazioni salvate durante l'anno. Non prepara il file da inviare: tu o il commercialista copiate i righi, controllate e inviate. ![La sezione Tasse: scadenze, liquidazione IVA, F24 e dichiarazioni da preparare.](/screenshots/taxes.it.webp) ## Prima di iniziare [#prima-di-iniziare] - **Le liquidazioni dell'anno salvate** in **Tasse → Liquidazioni**. Il rigo VL30 conta solo quelle e gli F24 IVA segnati come pagati in Getbeel ([Tasse](/it/guide/tasse)). - **Il credito IVA dell'anno scorso**, se c'è: il credito della dichiarazione precedente (VX5) meno quanto hai già compensato con F24. - **Non serve** il software dell'Agenzia per preparare i dati: ti servirà dopo, per compilare e inviare. - **Costo**: preparare i dati è gratis; si pagano una volta, quando registri l'invio ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Apri la scadenza [#apri-la-scadenza] Dal 1° gennaio apri **Tasse → Scadenze** e trova **Dichiarazione IVA annuale**. Scegli **Prepara i dati**. ### Indica il credito dell'anno precedente [#indica-il-credito-dellanno-precedente] Nel campo **Credito IVA dell'anno precedente ancora disponibile (facoltativo)** inserisci il credito, oppure lascialo vuoto. Va nel rigo VL25. Poi scegli **Prepara i dati**. ### Controlla i punti segnalati [#controlla-i-punti-segnalati] In cima trovi i **punti da controllare**. Per esempio: documenti non ancora nei registri, operazioni senza un rigo chiaro, reverse charge interno (TD16), fornitori esteri senza autofattura, IVA indetraibile, liquidazioni non salvate. ### Rivedi i righi [#rivedi-i-righi] Sotto trovi i righi dei quadri VE, VF, VJ, VL e VX, in unità di euro. Ogni rigo ha il codice del campo delle specifiche tecniche. Più in basso vedi le liquidazioni dell'anno: quanto era dovuto e quanto è stato versato. ### Scarica i dati [#scarica-i-dati] Scegli **Scarica Excel**, **Scarica CSV** o **Scarica JSON**. Manda il file al commercialista, oppure copia i righi nel "Software di compilazione Iva" gratuito dell'Agenzia. ### Carica la ricevuta [#carica-la-ricevuta] Dopo l'invio, carica la ricevuta dell'Agenzia in **Hai presentato la dichiarazione IVA?**. La scadenza risulta presentata. ## Cosa è successo [#cosa-è-successo] - **I dati sono pronti** dai registri IVA e dalle liquidazioni salvate, non da un inserimento a mano. - **I punti da controllare** ti dicono cosa Getbeel non poteva sapere. - **Il file scaricato** è un prospetto da copiare, non il file telematico. - **La scadenza è chiusa** con la ricevuta conservata in Getbeel. ## Cosa resta da fare fuori da Getbeel [#cosa-resta-da-fare-fuori-da-getbeel] - **Compila le parti che Getbeel non conosce**: frontespizio, firme, quadri VA, VC, VO, VT e gli altri. - **Controlla e invia** con la procedura di controllo dell'Agenzia, da Fisconline, Entratel o un intermediario. La finestra va dal **1° febbraio al 30 aprile** (art. 8, c. 1, DPR 322/1998). - **Versa l'eventuale saldo** (VX1) con F24, codice tributo **6099**, entro il **16 marzo** (istruzioni IVA 2026). - **Per compensare un credito sopra 5.000 €** in F24 serve il **visto di conformità** di un professionista (art. 10, c. 1, lett. a), n. 7, DL 78/2009). ## Quale modello [#quale-modello] I righi seguono l'ultimo modello pubblicato: **IVA 2026**, anno d'imposta 2025, approvato con provv. AdE prot. 51732 del 15 gennaio 2026. Il modello per l'anno d'imposta 2026 non è ancora uscito. Getbeel lo segnala nel prospetto: ricontrollalo quando esce quello nuovo. ## La LIPE [#la-lipe] Getbeel controlla il file LIPE trimestrale con lo schema ufficiale (IVP18) appena lo crea. Il software di controllo dell'Agenzia è un programma desktop: lo usi tu, Getbeel non può eseguirlo. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------ | | "Liquidazione non salvata" accanto a un periodo | Quel mese o trimestre non è salvato, quindi VL30 non lo conta | Salvalo in **Tasse → Liquidazioni**, poi scegli **Ricalcola** | | "Sono cambiate fatture o liquidazioni? Prepara di nuovo i dati." | Un documento o una liquidazione è cambiato dopo la preparazione | Scegli **Ricalcola** | | "Il modello di dichiarazione per il … non è ancora pubblicato" | L'Agenzia non ha ancora pubblicato il modello nuovo | Usa i dati e ricontrollali quando esce il modello | | "Alcuni controlli delle specifiche tecniche non tornano" | Un controllo interno di Getbeel non torna | Segnala il caso all'assistenza di Getbeel e non copiare quei righi | | "Per preparare gli F24 serve un piano attivo. Sceglilo in Fatturazione." | L'account non ha un piano | Scegli un piano in **Impostazioni → Utilizzo e fatturazione** | ## Fonti [#fonti] - Modello e istruzioni [IVA 2026](https://www.agenziaentrate.gov.it/portale/iva-2026/modello-e-istruzioni), provv. AdE prot. 51732 del 15 gennaio 2026; specifiche tecniche, provv. prot. 50925 dell'11 febbraio 2026. - Termini di presentazione: art. 8, c. 1, DPR 322/1998. - Visto di conformità: art. 10, c. 1, lett. a), n. 7, DL 78/2009, come modificato dall'art. 3 DL 50/2017. ## Prossimi passi [#prossimi-passi] Registri, liquidazioni, F24 e LIPE durante l'anno. Esportazioni e accesso in sola lettura per il commercialista. Chiedi all'assistente quanta IVA devi versare, dai tuoi dati. # Emettere e inviare una fattura (https://docs.getbeel.com/it/guide/emettere-fatture) Dalla bozza allo SDI in un minuto, e come leggere l'esito. *Video tutorial in arrivo.* In **Fatture emesse** crei le fatture elettroniche (FatturaPA), le invii allo SDI e ne segui l'esito. Lo SDI è il Sistema di Interscambio dell'Agenzia delle Entrate. ![L'elenco delle fatture emesse con lo stato SDI di ciascuna: bozza, consegnata, scartata, emessa nel cassetto fiscale.](/screenshots/issued-invoices.it.webp) ## Prima di iniziare [#prima-di-iniziare] - **Un'azienda italiana** con i dati completi in **Impostazioni → Azienda**: partita IVA o codice fiscale, indirizzo e regime fiscale. - **I dati del cliente**: nome, indirizzo, partita IVA o codice fiscale. Per la consegna, il suo [codice destinatario](/it/guide/codice-destinatario) o la PEC. - **Non serve** registrare nulla presso l'Agenzia delle Entrate per inviare: Getbeel trasmette dal suo canale. - **Costo.** Gli invii reali allo SDI seguono il listino ([Prezzi](/it/api/pricing)). Bozze e controlli non si pagano. ## Passi [#passi] ### Crea la bozza [#crea-la-bozza] In **Fatture emesse** premi **Nuova fattura** e scegli **Nuova fattura**. Compila la sezione **Cliente**. Getbeel verifica la partita IVA su VIES e mostra **Partita IVA verificata**. Il numero segue la [numerazione](/it/guide/numerazione-fatture): viene assegnato al salvataggio, il prossimo dell'anno. ### Aggiungi le righe [#aggiungi-le-righe] In **Linee** inserisci descrizione, **Qtà**, **Prezzo unitario** e **Aliquota IVA %**. Per una riga senza IVA scegli la natura (per esempio N2.2). Premi **Aggiungi linea** per altre righe. I totali si calcolano da soli. ### Salva la bozza [#salva-la-bozza] Premi **Salva bozza**. Finché è una bozza puoi modificarla o eliminarla. ### Invia allo SDI [#invia-allo-sdi] Apri il menu della fattura nell'elenco, o il suo dettaglio, e scegli **Invia al SDI**. Getbeel mostra **Inviare la fattura allo SDI?**: conferma. Prima di trasmetterla, Getbeel controlla l'XML con lo schema ufficiale e i controlli dello SDI. Se un controllo non passa, non invia nulla e mostra l'errore. ### Segui l'esito [#segui-lesito] Lo stato si aggiorna da solo con la ricevuta dello SDI. Il significato di ogni stato è sotto. ## Cosa è successo [#cosa-è-successo] - **La bozza ha preso il suo numero** dalla numerazione scelta. - **L'XML è passato i controlli** prima dell'invio, con le regole dello SDI. - **La fattura è un documento fiscale.** Non si modifica né si elimina più: si corregge con una nota di credito (TD04). - **L'esito arriva da solo** e si legge nella colonna **Stato**. | Stato | Cosa significa | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Inviata al SDI** | Lo SDI l'ha ricevuta e non ha ancora risposto. | | **Consegnata** | Il cliente l'ha ricevuta. | | **Emessa · nel cassetto fiscale** | Lo SDI non è riuscito a recapitarla, ma la fattura si considera emessa. È nell'area riservata del cliente: non va reinviata. | | **Scartata** | Un controllo dello SDI non è passato e la fattura si considera non emessa. Il dettaglio mostra il codice. | | **Già emessa · duplicato** | Lo SDI ha già accettato lo stesso documento (`00404`): è emessa, non va inviata di nuovo. | Una fattura scartata va corretta e inviata di nuovo con lo stesso numero e la stessa data. Una fattura non recapitata (MC) è emessa dalla data di messa a disposizione. Fonte: Agenzia delle Entrate, [La fattura elettronica e i servizi gratuiti](https://www.agenziaentrate.gov.it/portale/documents/d/guest/guida_fattura_elettronica_dicembre_2025) (dicembre 2025), pp. 17–18, e circolare 13/E del 2 luglio 2018. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | "Con IVA 0% indica la natura (N1–N7): senza, lo SDI scarterebbe la fattura." | Una riga al 0% non ha la natura | Scegli la natura della riga | | "Questo numero di fattura è già usato." | Il numero scritto a mano esiste già | Lascia il numero automatico o scegline uno libero | | "La quota SDI del mese è esaurita." | Gli invii del piano sono finiti | Apri **Impostazioni → Utilizzo e fatturazione** | | "Hai bisogno di un abbonamento SDI attivo per utilizzare le fatture emesse. Aggiorna il tuo piano." | L'account non ha l'add-on SDI | Premi **Vedi i piani** | | "Non siamo riusciti a inviare la fattura allo SDI per un problema del nostro fornitore di trasmissione. …" | Il canale di trasmissione non ha risposto | Non è stato inviato nulla: riprova più tardi | | **Scartata** | Lo SDI ha trovato un errore; codice e motivo sono nel dettaglio | Premi **Correggi e reinvia**: la fattura torna bozza con lo stesso numero e la stessa data. Correggila e inviala | Ogni codice di scarto è spiegato in [Codici di scarto SDI](/it/api/reference-data/sdi-errors). Gli stati in dettaglio sono nel [ciclo di vita SDI](/it/api/sdi-lifecycle). L'invio allo SDI non si annulla. Controlla cliente, righe e totale prima di confermare. ## Prossimi passi [#prossimi-passi] Come Getbeel numera le fatture e come creare un sezionale. Cosa chiedere al cliente perché riceva la fattura. Conserva a norma le fatture passate dallo SDI, gratis. # Esempi di richieste (https://docs.getbeel.com/it/guide/example-prompts) Cosa chiedere al tuo assistente collegato a Getbeel. Scrivi all'assistente come scriveresti a un collaboratore. Accanto a ogni richiesta trovi lo strumento MCP che l'assistente usa. ## Prima di iniziare [#prima-di-iniziare] - **Un assistente collegato** a Getbeel: vedi [Collega Claude, ChatGPT o Cursor](/it/guide/connect-ai). - **Con più strumenti collegati**, inizia con "Con Getbeel…": l'assistente sceglie quello giusto. - **Modalità Test** per provare. Gli strumenti che cambiano dati fiscali (cespiti, ritenute, adempimenti) e i dati aziendali funzionano solo in **Live**. - **Costo**: le richieste non si pagano a parte. Gli invii live allo SDI seguono il listino ([Prezzi](/it/api/pricing)). ## Controllare la situazione [#controllare-la-situazione] | Richiesta | Strumento | | -------------------------------------------------------------------------------------------------------- | ------------------------------ | | "Con Getbeel, quali fatture emesse a ottobre sono state scartate dallo SDI? Spiegami perché." | `list_invoices`, `get_invoice` | | "Elenca le fatture emesse ma finite nel cassetto fiscale negli ultimi 30 giorni, con cliente e importo." | `list_invoices` | | "Quanto ho fatturato in totale a Rossi S.r.l. quest'anno?" | `list_invoices` | | "Quali fatture sono scadute e non ancora pagate?" | `list_overdue_invoices` | | "Elenca le note di credito della fattura 12." | `list_credit_notes` | ## Fatture dei fornitori [#fatture-dei-fornitori] | Richiesta | Strumento | | ------------------------------------------------------------------------------------ | -------------------------------- | | "Quali fatture ricevute a settembre arrivano dall'email? Raggruppale per fornitore." | `list_received_invoices` | | "Quanto ho speso in software negli ultimi tre mesi?" | `list_received_invoices` | | "Ricevi una fattura di prova nella sandbox e mostramela." (solo in Test) | `create_sandbox_inbound_invoice` | ## Prima di inviare [#prima-di-inviare] | Richiesta | Strumento | | ------------------------------------------------------------------------------------ | ------------------ | | "Controlla questo XML FatturaPA e dimmi cosa correggere." (allega o incolla il file) | `validate_invoice` | | "Questa fattura è a IVA zero per un cliente tedesco: quale natura devo usare?" | nessuno | Per l'ultima domanda l'assistente può leggere questa documentazione. Per i casi dubbi chiedi al commercialista. ## Preparare e inviare [#preparare-e-inviare] | Richiesta | Strumento | | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | "Prepara una bozza per Bianchi S.p.A., P.IVA 01234567890, codice destinatario M5UXCR1: consulenza di ottobre, 1.000 euro più IVA al 22%. Non inviarla." | `create_invoice_draft` | | "Mostrami la bozza e, se è tutto corretto, inviala." | `get_invoice`, `send_invoice` | | "Fai una nota di credito che annulla la fattura 12." | `create_credit_note` | Prima di `send_invoice` l'assistente deve mostrarti la fattura e chiederti conferma. In **Live** l'invio emette una fattura vera e non si annulla. Controlla cliente, importi e IVA nella bozza prima di confermare. ## Banca [#banca] | Richiesta | Strumento | | ------------------------------------------------------------------------------------ | -------------------------------------------- | | "Mostrami l'ultimo estratto conto: periodo, saldi e quanti movimenti sono abbinati." | `list_bank_statements`, `get_bank_statement` | | "Quali movimenti non sono ancora abbinati a una fattura?" | `list_unmatched` | ## Tasse [#tasse] | Richiesta | Strumento | | ---------------------------------------------------------------- | ------------------------- | | "Quali scadenze fiscali ho nei prossimi 30 giorni?" | `get_tax_calendar` | | "Quanta IVA devo versare per ottobre?" | `get_vat_settlement` | | "Posso compensare il credito IVA?" | `ask_accountant_question` | | "Quanto devo mettere da parte per le imposte di quest'anno?" | `get_tax_estimate` | | "Prepara i dati della CU 2026 dei professionisti che ho pagato." | `get_withholdings_cu` | ## Correggere dati [#correggere-dati] | Richiesta | Strumento | | -------------------------------------------------------------------- | ----------------------------------------- | | "Elimina il cespite registrato per errore." | `list_fixed_assets`, `delete_fixed_asset` | | "Elimina la ritenuta registrata due volte per la parcella di Verdi." | `list_withholdings`, `delete_withholding` | | "Aggiorna l'indirizzo della sede: Via Roma 10, 20121 Milano." | `list_companies`, `update_company` | L'assistente deve chiederti conferma prima di eliminare o cambiare dati. Una ritenuta già versata con un F24 non si elimina. I dati aziendali finiscono in ogni fattura che emetti. ## Cosa significano gli stati delle fatture [#cosa-significano-gli-stati-delle-fatture] L'assistente usa gli stessi stati che vedi in **Fatture emesse**. Quello che conta è se la fattura è emessa: | In Getbeel | Cosa significa | Cosa fare | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | **Inviata al SDI** | Lo SDI sta facendo i controlli (da pochi minuti fino a 5 giorni) | Aspetta l'esito, non inviarla di nuovo | | **Consegnata** | Recapitata al cliente: è emessa | Niente | | **Emessa · nel cassetto fiscale** | Lo SDI non ha potuto recapitarla, ma è **emessa**: il cliente la trova nella sua area riservata di Fatture e Corrispettivi | Avvisa il cliente. **Non inviarla di nuovo**: sarebbe un duplicato | | **Scartata** | Lo SDI l'ha rifiutata: si considera **mai emessa**. Il dettaglio mostra il codice e il motivo | Scegli **Correggi e reinvia**: torna in bozza con lo stesso numero e la stessa data; correggila e inviala | | **Già emessa · duplicato** | Lo SDI ha scartato un secondo invio con il codice 00404 perché ha già accettato la stessa fattura: è **emessa** | Niente: non va reinviata. L'assistenza collega l'invio accettato | Per i dettagli e le fonti ufficiali: [ciclo di vita SDI](/it/api/sdi-lifecycle) e [codici di scarto](/it/api/reference-data/sdi-errors). ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio dell'assistente | Causa | Cosa fare | | ------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `livemode_required` | Lo strumento cambia dati reali e il collegamento è in Test | Ricollega l'assistente in **Live** | | `test_mode_required` | La sandbox funziona solo in Test | Usa un collegamento in **Test** | | `subscription_required` | Lo strumento richiede un piano attivo | Scegli un piano in **Impostazioni → Utilizzo e fatturazione** | | `withholding_remitted` | La ritenuta è già in un F24 pagato | Lasciala com'è e senti il commercialista | | `insufficient_scope` | Il collegamento non ha quel permesso | Revoca l'app in **App collegate** e ricollegala con il permesso giusto | Puoi anche chiedere direttamente: - "La fattura 118 è stata scartata con il codice 00305. Cosa significa e come la correggo?" - "La fattura per Verdi risulta Emessa · nel cassetto fiscale. Cosa devo fare?" - "Perché la fattura 121 dice Già emessa · duplicato?" ## Prossimi passi [#prossimi-passi] L'elenco completo degli strumenti, con scope e argomenti. Prova ogni esito SDI e le fatture ricevute senza inviare nulla. Cosa calcola Getbeel da solo e cosa prepari tu. # Per iniziare (https://docs.getbeel.com/it/guide/getting-started) Cosa fa Getbeel e da dove partire: dati aziendali, caselle email, banca e prima fattura elettronica. *Video tutorial in arrivo.* Getbeel raccoglie le fatture dei fornitori, emette le tue fatture elettroniche e le abbina ai movimenti della banca. Questa sezione ti porta dalla registrazione alla prima fattura inviata allo SDI. ![La Panoramica di Getbeel: l'elenco "Per iniziare", il collegamento dell'assistente AI tramite MCP e l'attività recente.](/screenshots/overview.it.webp) ## Da dove partire [#da-dove-partire] Dopo la registrazione apri **Panoramica**. L'elenco **Per iniziare** mostra i passi che mancano, nell'ordine giusto. La [guida rapida](/it/guide/getting-started/quick-start) li spiega uno per uno. ## Cosa trovi nell'app [#cosa-trovi-nellapp] Ogni voce è una pagina della barra laterale. - **Fatture ricevute.** Le fatture dei fornitori dalle caselle email, dall'inoltro, dai caricamenti e dallo SDI. L'AI le legge e le classifica. - **Autofatture.** Gli acquisti da fornitori esteri diventano autofatture da inviare allo SDI. Solo per aziende italiane. - **Fatture emesse.** Crei le fatture elettroniche (FatturaPA), le invii allo SDI e ne segui l'esito. Solo per aziende italiane. - **Tasse.** Scadenze, registri IVA, liquidazioni e F24 preparati dalle tue fatture. Solo per aziende italiane. - **Riconciliazione.** I movimenti bancari, da estratto conto o dalla [banca collegata](/it/guide/collega-la-banca), abbinati alle fatture. - **Analisi.** I movimenti bancari di Riconciliazione per periodo: spesa mensile, conto economico di cassa e fornitori. Vedi [Analisi della spesa](/it/guide/analytics/spending-analytics). - **Drive.** Fatture, file bancari e documenti condivisi, in cartelle. - **Aziende clienti.** Per i commercialisti: ogni azienda cliente ha i suoi dati e le sue fatture, da un solo account. In **Impostazioni** trovi i dati dell'azienda, i membri, le caselle email, le categorie, le regole AI e la fatturazione. ## Prima di iniziare [#prima-di-iniziare] - **Ruoli.** Invita il team o il commercialista come **Proprietario**, **Membro** o **Commercialista** (sola lettura). - **Costo.** Le scansioni usano i crediti fattura; invii e ricezioni SDI hanno un listino ([Prezzi](/it/api/pricing)). ## Prossimi passi [#prossimi-passi] I cinque passi dell'elenco "Per iniziare", in dieci minuti. Come arrivano e come le legge l'AI. Dalla bozza allo SDI, e come leggere l'esito. Abbina ogni movimento alla sua fattura. # Guida rapida (https://docs.getbeel.com/it/guide/getting-started/quick-start) Configura l'azienda, collega una casella ed emetti la prima fattura elettronica, nell'ordine dell'elenco "Per iniziare" della Panoramica. Configura Getbeel in circa dieci minuti: dati aziendali, una casella per le fatture dei fornitori, la banca e la prima fattura allo SDI. L'elenco **Per iniziare** in **Panoramica** segue gli stessi passi. ![La Panoramica: l'elenco "Per iniziare" con i passi da completare e le prossime scadenze fiscali.](/screenshots/overview.it.webp) ## Prima di iniziare [#prima-di-iniziare] - **Un account.** Registrati su [getbeel.com](https://www.getbeel.com) con Google o con l'email. Crea un team con il nome della tua azienda. - **I dati dell'azienda**: ragione sociale, partita IVA o codice fiscale, sede legale e regime fiscale. - **Non serve** installare nulla né configurare lo SDI: Getbeel trasmette dal suo canale. - **Costo.** Collegare caselle nell'app richiede un piano con crediti fattura. Gli invii allo SDI seguono il listino ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Completa i dati aziendali [#completa-i-dati-aziendali] Apri **Impostazioni → Azienda**. Compila ragione sociale, paese, partita IVA o codice fiscale, indirizzo e **Regime Fiscale**. Premi **Salva profilo aziendale**. ### Collega una casella email [#collega-una-casella-email] Apri **Impostazioni → Email** e scegli la scheda **Gmail**, **Outlook** o **Altra email** (IMAP). Premi il pulsante di collegamento e autorizza la lettura. Getbeel chiede accesso in sola lettura. Per cercare subito le fatture degli ultimi mesi, apri **Fatture ricevute** e premi **Scansiona ora**. ### Collega la banca [#collega-la-banca] Apri **Riconciliazione → Collega la banca**, oppure carica un estratto conto. Getbeel abbina ogni movimento alla sua fattura. ### Emetti la prima fattura elettronica [#emetti-la-prima-fattura-elettronica] Apri **Fatture emesse**, premi **Nuova fattura** e scegli **Nuova fattura**. Compila cliente e righe, poi **Salva bozza**. Dal menu della fattura scegli **Invia al SDI** e conferma. ### Invita il tuo team [#invita-il-tuo-team] Apri **Impostazioni → Membri** e premi **Invita membri**. Scegli un ruolo per ogni persona: - **Proprietario**: accesso completo, compresi fatturazione, membri e impostazioni. - **Membro**: scansiona le email, gestisce le fatture e vede le analisi. - **Commercialista**: sola lettura; vede ed esporta fatture, tasse e banca, ma non modifica, approva o elimina nulla. ## Cosa è successo [#cosa-è-successo] - **L'azienda è configurata.** Ogni fattura che emetti porta questi dati, e i controlli prima dell'invio li usano. - **Le fatture dei fornitori arrivano da sole.** Getbeel controlla la casella una volta al giorno e l'AI le legge in **Fatture ricevute**. - **I movimenti bancari sono abbinati** alle fatture in **Riconciliazione**. - **La prima fattura è allo SDI.** Lo stato si aggiorna da solo con la ricevuta. - **Il team lavora in Getbeel** con gli accessi del suo ruolo. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | --------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------- | | "Il profilo aziendale non è salvato: completa prima Impostazioni → Azienda." | Mancano i dati aziendali | Completa il passo 1 | | "Hai bisogno di un abbonamento SDI attivo per utilizzare le fatture emesse. Aggiorna il tuo piano." | L'account non ha l'add-on SDI | Apri **Impostazioni → Utilizzo e fatturazione** | | "Hai raggiunto il limite di collegamenti email." | Il piano consente meno caselle | Scollega una casella o cambia piano | | **Crediti esauriti** nella cronologia scansioni | I crediti fattura sono finiti | Aggiungi crediti in **Impostazioni → Utilizzo e fatturazione** | | **Scartata** sulla fattura | Un controllo dello SDI non è passato | Premi **Correggi e reinvia** ([Emettere fatture](/it/guide/emettere-fatture)) | ## Prossimi passi [#prossimi-passi] Ricevi le fatture dei fornitori direttamente dallo SDI. Spiega all'AI come leggere e classificare i tuoi costi. Lavora in Getbeel da Claude, ChatGPT o Cursor. # Getbeel nel tuo assistente AI (https://docs.getbeel.com/it/guide) Consulta e prepara le fatture elettroniche da Claude, ChatGPT o Cursor, senza scrivere codice. Collega Claude, ChatGPT o Cursor a Getbeel e chiedi in italiano quello che oggi cerchi a mano. Per esempio: "quali fatture sono state scartate questo mese?" o "questo XML è corretto?". L'assistente usa gli strumenti MCP di Getbeel. MCP è lo standard che permette a un assistente di usare servizi esterni. ## Cosa può fare l'assistente [#cosa-può-fare-lassistente] | Richiesta | Strumento MCP | | -------------------------------------------------- | ------------------------------------------------------------------ | | Leggere le fatture emesse e il loro stato SDI | `list_invoices`, `get_invoice` | | Leggere le fatture ricevute dai fornitori | `list_received_invoices` | | Controllare un XML FatturaPA prima dell'invio | `validate_invoice` | | Preparare una bozza di fattura | `create_invoice_draft` | | Inviare una fattura allo SDI, dopo la tua conferma | `send_invoice` | | Approvare o rifiutare una fattura ricevuta | `approve_collected_document` | | Ricevere le fatture dei fornitori dallo SDI | `get_sdi_receiving_status`, `enable_sdi_receiving` | | Leggere estratti conto e riconciliazione | `list_bank_statements`, `get_bank_statement`, `get_reconciliation` | L'elenco completo, con i permessi di ogni strumento, è nel [riferimento MCP](/it/api/mcp). ## Prima di iniziare [#prima-di-iniziare] - **Un account Getbeel** con un team e i dati della tua azienda in **Impostazioni → Azienda**. - **Un assistente che supporta MCP**: Claude, ChatGPT, Cursor o Claude Code. - **Non serve** copiare una chiave API: accedi con il tuo account Getbeel quando colleghi l'assistente. - **Costo**: il collegamento MCP non si paga. Si pagano gli invii e le ricezioni SDI reali, come nell'app ([Prezzi](/it/api/pricing)). Quando colleghi l'assistente scegli il team e la modalità. In modalità **Test** nessuna fattura arriva allo SDI. L'assistente vede solo il team scelto e fa solo ciò che i permessi consentono. ## Prossimi passi [#prossimi-passi] Claude, ChatGPT, Cursor e Claude Code, passo per passo. Cosa chiedere, dalla prima domanda all'invio. Ricevi le fatture dei fornitori in Getbeel dallo SDI. Il servizio gratuito dell'Agenzia delle Entrate e come segnarlo. ## Guide all'app [#guide-allapp] Configura l'azienda e raccogli le prime fatture. Caselle email, lettura con l'AI, categorie e regole. Abbina i movimenti bancari alle fatture. Ruoli e inviti per il tuo team e il commercialista. # Estrazione dati con IA (https://docs.getbeel.com/it/guide/invoice-management/ai-extraction) Cosa legge l'AI di Getbeel da ogni fattura, e come caricare i file a mano. L'AI di Getbeel legge ogni fattura che arriva da email, inoltro o caricamento e ne estrae i dati. Le fatture dallo SDI non passano dall'AI: Getbeel le legge dall'XML. ## Cosa estrae [#cosa-estrae] - **Fornitore**: nome, email, indirizzo, partita IVA, paese e città. - **Documento**: numero, data, scadenza, valuta e tipo. - **Importi**: imponibile, IVA e totale, nella valuta originale. - **Righe**: descrizione, quantità, prezzo unitario e importo. - **Altro**: categoria, stato del pagamento, se è ricorrente e se è una nota di credito. Il tipo è uno di questi: **Fattura**, **Ricevuta**, **Abbonamento**, **Rimborso** o **Bolletta**. Se l'AI non è sicura che la fattura sia indirizzata alla tua azienda, il dettaglio mostra **Corrispondenza azienda incerta**. Controlla i dati del destinatario. ## Carica le fatture a mano [#carica-le-fatture-a-mano] ### Prima di iniziare [#prima-di-iniziare] - **Formati**: PDF, JPG, PNG o WebP, al massimo 10 MB ciascuno, fino a 20 file per volta. - **Un piano con crediti fattura**: senza, il pulsante **Carica** è disattivato. - **Costo**: ogni file letto usa un credito fattura ([Prezzi](/it/api/pricing)). ### Passi [#passi] ### Apri il caricamento [#apri-il-caricamento] In **Fatture ricevute** premi **Carica**. Si apre **Carica fatture**. ### Scegli i file [#scegli-i-file] Trascina i file nel riquadro o fai clic per sfogliare. ### Avvia la lettura [#avvia-la-lettura] Premi **Carica e elabora**. ### Cosa è successo [#cosa-è-successo] - **I file sono caricati.** Getbeel mostra, per esempio, "3 file caricati. L'elaborazione inizierà a breve." - **L'AI li legge.** Durante la lettura l'elenco mostra **Elaborazione fatture...** e si aggiorna da solo. - **Le fatture compaiono in Fatture ricevute** con i dati estratti e la categoria. ## Quando manca il PDF [#quando-manca-il-pdf] A volte l'email conferma un pagamento ma non allega la fattura. Getbeel la mette nella scheda **PDF mancante** con il badge **Fattura PDF mancante**. 1. Apri la fattura. Il riquadro **Conferma di pagamento** mostra il link del fornitore, se c'è. 2. Premi **Scarica la fattura**. Il link può scadere: scaricala subito. 3. Trascina il file nel riquadro. Getbeel lo legge e completa la fattura. ## Leggere meglio [#leggere-meglio] - **Regole AI**: istruzioni in italiano che l'AI segue per le fatture nuove ([Categorie e regole AI](/it/guide/invoice-management/categories-rules)). - **Profilo aziendale**: ragione sociale e partita IVA in **Impostazioni → Azienda** aiutano l'AI a riconoscere le fatture per te. - **Categorie**: categorie precise danno una classificazione migliore. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ---------------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------- | | "fattura.docx: Tipo di file non supportato. Usa PDF, JPG, PNG o WebP." | Formato non ammesso | Converti il file in PDF o immagine | | "fattura.pdf: File troppo grande. Massimo 10MB." | Il file supera 10 MB | Comprimi il PDF o dividilo | | "Massimo 20 file consentiti" | Più di 20 file | Carica in più volte | | "Elaborazione non riuscita" | L'AI non ha potuto leggere il documento | Ricarica il file o un'immagine più nitida | | **Corrispondenza azienda incerta** | Il destinatario non coincide con i tuoi dati | Controlla la fattura; completa **Impostazioni → Azienda** | ## Prossimi passi [#prossimi-passi] Controlla, approva ed esporta le fatture lette. Dai all'AI le tue istruzioni. # Categorie e regole IA (https://docs.getbeel.com/it/guide/invoice-management/categories-rules) Organizza le spese con le categorie e dai all'AI istruzioni in linguaggio naturale per leggere le fatture. Le **categorie** raggruppano le fatture ricevute per tipo di spesa. Le **regole AI** sono istruzioni in italiano che l'AI segue quando legge una fattura nuova. ## Categorie predefinite [#categorie-predefinite] Ogni team parte con 10 categorie, segnate **Predefinita**: | Categoria | Per esempio | | ------------------------- | --------------------------------- | | **Software & SaaS** | Abbonamenti, licenze, API | | **Cloud Infrastructure** | Hosting e servizi cloud | | **Utilities** | Internet, telefono, energia | | **Travel** | Voli, hotel, trasporti | | **Food & Dining** | Pranzi e cene di lavoro | | **Hardware** | Computer, monitor, attrezzature | | **Professional Services** | Consulenza legale e contabile | | **Marketing** | Pubblicità, strumenti, agenzie | | **Office Supplies** | Cancelleria e materiale d'ufficio | | **Other** | Tutto il resto | Le categorie predefinite non si possono eliminare. ## Crea una categoria [#crea-una-categoria] ### Apri le categorie [#apri-le-categorie] Apri **Impostazioni → Categorie** e premi **Aggiungi categoria**. ### Dai nome e colore [#dai-nome-e-colore] Scrivi l'**Etichetta**, per esempio "Spese legali", e scegli un **Colore**. Premi **Crea**. Puoi anche creare una categoria dall'elenco: nella colonna **Categoria** di una fattura scrivi un nome nuovo e scegli **Crea "…"**. Eliminando una categoria tua, le sue fatture passano ad **Other**. L'operazione non si annulla. ## Aggiungi una regola AI [#aggiungi-una-regola-ai] ### Apri le regole [#apri-le-regole] Apri **Impostazioni → Regole AI** e premi **Aggiungi regola**. ### Scrivi la regola [#scrivi-la-regola] Scrivila come la diresti a un collega, al massimo 500 caratteri. Per esempio: - _"Escludi le fatture da billing@shopify.com"_ - _"Per le fatture Cloudflare, imposta la scadenza a 30 giorni netti"_ - _"Le fatture Google Workspace vanno in Software & SaaS"_ ### Salva e attivala [#salva-e-attivala] Lascia acceso **Attiva** e salva. ## Cosa è successo [#cosa-è-successo] - **La categoria è disponibile** nei filtri, nell'elenco e per l'AI. - **La regola vale per le fatture nuove.** L'AI la segue quando legge le prossime fatture, non quelle già lette. - **Le regole si applicano in ordine**, dalla prima all'ultima. L'AI segue solo quelle attive. Per provare l'effetto di una regola, spegnila con l'interruttore invece di eliminarla. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------- | | "L’etichetta è obbligatoria" | Il nome è vuoto | Scrivi un'etichetta | | "L’etichetta deve avere al massimo 100 caratteri" | Il nome è troppo lungo | Accorcialo | | "Il testo della regola è obbligatorio" | La regola è vuota | Scrivi la regola | | Una fattura già letta ha la categoria sbagliata | Le regole valgono solo per le fatture nuove | Cambia la categoria dalla colonna **Categoria** dell'elenco | ## Prossimi passi [#prossimi-passi] Controlla ed esporta le fatture classificate. La spesa per categoria nel tempo. # Connessioni email (https://docs.getbeel.com/it/guide/invoice-management/gmail-integration) Collega Gmail, Outlook, IMAP o l’inoltro email: Getbeel trova le fatture dei fornitori nella casella. Getbeel legge le caselle che colleghi e importa le email con fatture. Puoi collegare più caselle per team, per esempio amministrazione@ e fatture@. ## Prima di iniziare [#prima-di-iniziare] - **Un piano con crediti fattura.** Senza piano i pulsanti di collegamento sono disattivati. - **Il limite del piano.** **Impostazioni → Email** mostra quante connessioni email usi sul totale. - **Non serve** dare a Getbeel la password di Gmail o Outlook: l'accesso passa da Google o Microsoft, in sola lettura. - **Costo.** Ogni fattura letta usa un credito; l'inoltro email è un servizio aggiuntivo a pagamento ([Prezzi](/it/api/pricing)). ## Collega una casella [#collega-una-casella] ### Apri le impostazioni email [#apri-le-impostazioni-email] Apri **Impostazioni → Email**. Le schede sono **Gmail**, **Outlook**, **Altra email** e **Inoltro e-mail**. ### Scegli il provider e autorizza [#scegli-il-provider-e-autorizza] - **Gmail**: premi **Collega Gmail** e autorizza la lettura delle email nella schermata di Google. - **Outlook**: premi **Collega Outlook** e accedi con l'account Microsoft (Outlook.com o Microsoft 365). - **Altra email** (IMAP): premi **Collega IMAP**. Scegli il **Provider email**, poi inserisci indirizzo e una password per le app. Per IMAP Getbeel usa SSL/TLS sulla porta 993. I server con solo altre porte o STARTTLS non sono supportati. ### Cerca le fatture passate [#cerca-le-fatture-passate] Apri **Fatture ricevute** e premi **Scansiona ora**. Scegli un periodo, per esempio **Ultimi 3 mesi**, e premi **Avvia scansione**. ## Cosa è successo [#cosa-è-successo] - **La casella è collegata.** Dopo il primo accesso riuscito il suo stato è **Accesso email verificato**. - **Getbeel la controlla una volta al giorno** e importa le nuove fatture da solo. - **La scansione del periodo è partita.** **Fatture ricevute** mostra l'avanzamento e si aggiorna da sola. - **L'AI legge ogni fattura trovata** e la mette in **Fatture ricevute**. ## Inoltra le fatture [#inoltra-le-fatture] L'inoltro serve quando non vuoi collegare tutta la casella. È un servizio aggiuntivo a pagamento. 1. Apri **Impostazioni → Email → Inoltro e-mail** e premi **Configura inoltro**. 2. Copia l'**Indirizzo di inoltro**. 3. Inoltra le fatture a quell'indirizzo, a mano o con una regola del tuo programma di posta. Getbeel elabora ogni email appena arriva. ## Gestisci le connessioni [#gestisci-le-connessioni] Ogni casella mostra indirizzo e stato. Dal menu della riga: - **Ricollega** (Gmail): rinnova l'autorizzazione se Google l'ha revocata. - **Scollega**: Getbeel smette di leggere la casella. Le fatture già importate restano. **Cronologia scansioni**, nella stessa pagina, elenca ogni scansione con tipo, stato, fatture trovate ed elaborate. Apri una riga per l'esito di ogni email: | Esito | Cosa significa | | ------------------------------------ | ------------------------------------------------------------ | | **Fattura creata** | La fattura è in **Fatture ricevute** | | **Manca il documento della fattura** | L'email parla di una fattura ma non ha un allegato leggibile | | **Duplicata** | La fattura c'è già | | **Non è una fattura** | Per esempio una newsletter | | **Nessun contenuto di fattura** | L'email o l'allegato non hanno testo leggibile | | **Crediti esauriti** | Saltata: i crediti fattura sono finiti | | **Errore** | Un errore imprevisto; Getbeel riprova da solo | ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ---------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------- | | **Da ricollegare**: "GetBeel non può leggere questa casella. …" | Google ha revocato l'accesso | Dal menu della casella scegli **Ricollega** | | "Scegli lo stesso account Google della casella che stai ricollegando." | Hai scelto un altro account | Ricollega con l'account giusto | | "L’amministratore Google Workspace ha bloccato l’accesso a Gmail. …" | Il tuo dominio blocca le app esterne | Chiedi all'amministratore di autorizzare Getbeel, o carica i file | | "Hai raggiunto il limite di collegamenti email." | Il piano consente meno caselle | Scollega una casella o cambia piano | | "L'inoltro email è un servizio aggiuntivo a pagamento. …" | Manca il servizio di inoltro | Premi **Vai a Utilizzo e fatturazione** | | **Scansioni da controllare** | Le importazioni non riescono | Getbeel riprova da solo; se continua, ricollega la casella | Dopo un ricollegamento, premi **Scansiona ora** sul periodo mancante. ## Prossimi passi [#prossimi-passi] Cosa legge l'AI da ogni fattura. Escludi mittenti o correggi i dati in automatico. Ricevi le fatture elettroniche anche dallo SDI. # Gestione delle fatture (https://docs.getbeel.com/it/guide/invoice-management) Raccogli le fatture dei fornitori da email, caricamenti e SDI: l'AI le legge e le classifica. *Video tutorial in arrivo.* **Fatture ricevute** raccoglie le fatture dei fornitori in un solo elenco. L'AI legge ogni documento e ne estrae fornitore, importi, date e righe. ![L'elenco delle fatture ricevute, con la ricerca, i filtri per categoria e la scheda PDF mancante.](/screenshots/received-invoices.it.webp) ## Da dove arrivano [#da-dove-arrivano] | Fonte | Come | Guida | | ------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- | | Caselle email | Gmail, Outlook o IMAP, controllate ogni giorno | [Connessioni email](/it/guide/invoice-management/gmail-integration) | | Inoltro | Inoltri le email al tuo indirizzo Getbeel | [Connessioni email](/it/guide/invoice-management/gmail-integration#inoltra-le-fatture) | | Caricamento | **Carica** in **Fatture ricevute**: PDF o immagini | [Estrazione con l'AI](/it/guide/invoice-management/ai-extraction) | | SDI | Le fatture elettroniche dei fornitori, con il badge **SDI** | [Codice destinatario](/it/guide/codice-destinatario) | Se la stessa fattura arriva da due fonti, Getbeel la tiene una volta sola. ## Cosa succede a ogni fattura [#cosa-succede-a-ogni-fattura] 1. **Arriva** da una delle fonti sopra. 2. **L'AI la legge**: fornitore, numero, date, importi, IVA e righe. 3. **Prende una categoria**, secondo le tue [categorie e regole AI](/it/guide/invoice-management/categories-rules). 4. **La controlli** nel dettaglio e la esporti per il commercialista. Il percorso completo e gli stati sono in [Flusso delle fatture](/it/guide/invoice-management/invoice-workflow). ## Prima di iniziare [#prima-di-iniziare] - **Un piano attivo.** Collegare caselle e caricare file richiede un piano. - **Costo.** Ogni documento letto dall'AI usa un credito fattura. Le fatture ricevute dallo SDI hanno il loro prezzo ([Prezzi](/it/api/pricing)). - **I dati dell'azienda** in **Impostazioni → Azienda**: aiutano l'AI a riconoscere le fatture indirizzate a te. ## Prossimi passi [#prossimi-passi] Collega Gmail, Outlook, IMAP o l'inoltro. Cosa legge l'AI e come caricare i file a mano. Controlla, approva ed esporta. Organizza le spese a modo tuo. # Flusso delle fatture (https://docs.getbeel.com/it/guide/invoice-management/invoice-workflow) Dalla fattura letta dall'AI all'export per il commercialista: controlla, approva ed esporta le fatture ricevute. Ogni fattura ricevuta passa per gli stessi stati, dalla lettura dell'AI all'export. In **Fatture ricevute** la controlli e la esporti; l'approvazione si fa con l'assistente AI o l'API. ## Gli stati [#gli-stati] | Stato | Valore API | Cosa significa | | -------------------------- | ------------------ | ---------------------------------------------- | | **In elaborazione** | `processing` | L'AI sta leggendo il documento. | | **In attesa di revisione** | `pending_review` | Letta, da controllare. | | **Approvata** | `verified` | Hai confermato che i dati sono corretti. | | **Rifiutata** | `rejected` | Non è una fattura valida per te. | | **Esportata** | `exported` | Già consegnata alla contabilità. | | **Documento mancante** | `missing_document` | L'email conferma un pagamento ma manca il PDF. | Una fattura si approva da **In attesa di revisione** o **Rifiutata**, e si rifiuta da **In attesa di revisione** o **Approvata**. In **Tasse** una fattura non ancora approvata entra nei registri IVA, segnata **Non ancora verificata**. ## Prima di iniziare [#prima-di-iniziare] - **Fatture in Getbeel**, da email, inoltro, caricamento o SDI ([Gestione delle fatture](/it/guide/invoice-management)). - **Il ruolo giusto**: **Proprietario** o **Membro** gestiscono le fatture; **Commercialista** ha sola lettura e può esportare. - **Per approvare**: un [assistente AI collegato](/it/guide/connect-ai). L'app non ha un pulsante di approvazione. ## Passi [#passi] ### Trova la fattura [#trova-la-fattura] In **Fatture ricevute** cerca per fornitore o numero. Filtra per **Categoria**, per periodo o per fonte: **SDI** oppure **Email e caricamenti**. ### Controlla i dati [#controlla-i-dati] Apri la fattura. **Dettagli fattura** mostra fornitore, numero, date, importi e **Voci**, accanto all'anteprima del documento. Correggi la categoria dalla colonna **Categoria** dell'elenco. ### Completa le fatture senza PDF [#completa-le-fatture-senza-pdf] Apri la scheda **PDF mancante**. Per ogni fattura scarica il documento dal fornitore e caricalo nel riquadro ([Quando manca il PDF](/it/guide/invoice-management/ai-extraction#quando-manca-il-pdf)). ### Approva o rifiuta [#approva-o-rifiuta] Chiedi all'assistente, per esempio: _"Mostrami le fatture ricevute in attesa di revisione e approva quelle di Aruba."_ L'assistente usa `list_received_invoices` e `approve_collected_document`, con `decision: "reject"` per rifiutare. Ti chiede conferma prima di ogni modifica. ### Esporta per il commercialista [#esporta-per-il-commercialista] Seleziona le fatture e premi **Esporta**. In **Esporta fatture** scegli **CSV**, **Excel** o **ZIP** (dati e allegati PDF), poi premi **Scarica**. ## Cosa è successo [#cosa-è-successo] - **Hai trovato le fatture** con ricerca e filtri, senza aprirle una per una. - **I dati sono controllati** contro il documento originale. - **Nessuna fattura resta senza documento**: la scheda **PDF mancante** è vuota. - **Le fatture approvate sono Approvata**, e in **Tasse** perdono il segno **Non ancora verificata**. - **Il commercialista ha il file** con i dati e, nello ZIP, i PDF. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | --------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------- | | "Esportazione non riuscita" | Il file non è stato creato | Riprova con meno fatture | | "Nessun allegato PDF trovato" | Le fatture scelte non hanno PDF | Esporta in **CSV** o **Excel** | | "Eliminazione fatture non riuscita" | Le fatture non sono state eliminate | Riprova; controlla il tuo ruolo | | L'assistente risponde che la fattura non si può approvare | È ancora **In elaborazione**, **Documento mancante** o **Esportata** | Aspetta la lettura o carica il PDF | Eliminare una fattura non si annulla. ## Prossimi passi [#prossimi-passi] Abbina le fatture ai pagamenti in banca. Esportazioni e accesso in sola lettura per il commercialista. Altre domande da fare all'assistente sulle fatture. # Numerazione delle fatture (https://docs.getbeel.com/it/guide/numerazione-fatture) Come Getbeel numera le fatture emesse: 1, 2, 3… che ripartono da 1 ogni anno, come consente l'Agenzia delle Entrate. Ogni fattura ha un numero progressivo che la identifica in modo univoco (art. 21, comma 2, lettera b, DPR 633/1972). Getbeel lo assegna da solo e lo scrive nel campo `Numero` della FatturaPA. ![L'elenco delle fatture emesse con numero, data e stato SDI di ciascuna.](/screenshots/issued-invoices.it.webp) ## La regola in breve [#la-regola-in-breve] | | Numerazione Standard | | --------------------- | ------------------------------------------------------------------- | | Formato | `1`, `2`, `3`… con la data della fattura accanto | | 1° gennaio | Riparte da 1, se non scegli altrimenti | | Numero scritto a mano | Può essere il prossimo o colmare un buco, mai saltare avanti | | Cosa va allo SDI | Esattamente il numero che vedi in Getbeel, senza anno o altro testo | | Limiti dello SDI | Al massimo 20 caratteri, almeno una cifra (errore `00425`) | ## Ripartire da 1 ogni anno [#ripartire-da-1-ogni-anno] La prima fattura del 2027 è la numero 1. Il numero segue la data: con una data del 2027 la fattura prende il prossimo numero del 2027. È ammesso. La [Risoluzione n. 1/E del 10 gennaio 2013](https://www.agenziaentrate.gov.it/portale/documents/20143/304338/Risoluzione+1++10012013a_risoluzione+1e.pdf/71b92d56-5b2e-6e70-a1c1-47cf4d365a29) dell'Agenzia delle Entrate accetta "qualsiasi tipologia di numerazione progressiva che garantisca l'identificazione univoca della fattura, se del caso, anche mediante riferimento alla data". Accetta anche una sequenza unica negli anni, e formati come `1/2013` o `2013/1`. Lo SDI riconosce una fattura doppia (errore `00404`) da cedente, anno della data e numero. La fattura 1 del 2026 e la fattura 1 del 2027 non sono un doppione. Fonte: [Specifiche tecniche FatturaPA, Allegato A, versione 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1). ## Continuare la numerazione negli anni [#continuare-la-numerazione-negli-anni] Per una sola sequenza che non riparte mai, apri **Fatture emesse**. Nel menu **Altre azioni** scegli **Preventivi**, poi la scheda **Numerazione**. Sulla riga **Standard** spegni l'interruttore nella colonna **Riparte ogni anno**. Puoi cambiarlo quando vuoi. Ogni numero nuovo è più alto dell'ultimo dello stesso anno, quindi la numerazione resta progressiva e senza doppioni. ## Le fatture emesse prima di novembre 2026 [#le-fatture-emesse-prima-di-novembre-2026] Fino a novembre 2026 la numerazione Standard aggiungeva una barra finale, per esempio `45/`. Quelle fatture restano così: è il numero già inviato allo SDI. La fattura successiva prosegue la stessa sequenza senza barra. | Data | Numero | | ---------------------------- | ------ | | 28 ottobre 2026 (già emessa) | `45/` | | 20 novembre 2026 | `46` | | 10 gennaio 2027 | `1` | ## Sezionali (serie separate) [#sezionali-serie-separate] Un sezionale tiene separate alcune fatture, per esempio le vendite online. Ha un prefisso o un suffisso (`FT-12`, `12/A`) e la sua sequenza. Prefisso e suffisso fanno parte del numero inviato allo SDI. Per crearne uno apri la scheda **Numerazione** e premi **Nuova numerazione**. Scegli **Prefisso** o **Suffisso**, **Riparte da 1 ogni anno** e se usarla per le nuove fatture o per le note di credito. Prefisso, suffisso e azzeramento annuale non si possono cambiare dopo la prima fattura. Per cambiarli crea una nuova numerazione. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------------- | | "Questo numero di fattura è già usato." | Il numero esiste già in quell'anno | Lascia vuoto il numero: Getbeel assegna il prossimo | | "Esiste già una numerazione con questo prefisso e suffisso." | Un sezionale uguale esiste già | Usa quello, o cambia prefisso o suffisso | | "Prefisso e suffisso: massimo 10 tra lettere, cifre e / \_ . -, e diversi dalla numerazione Standard (aggiungi ad esempio /A)." | Formato non ammesso | Correggi prefisso o suffisso | | "Ci sono già fatture con questa numerazione: prefisso, suffisso e azzeramento non si possono più cambiare. Crea una nuova numerazione." | La numerazione è già in uso | Premi **Nuova numerazione** | ## Correlati [#correlati] Dove il numero viene assegnato, dalla bozza all'invio. Leggere e creare sezionali con l'API o l'MCP. Cosa significano `00404` e `00425`. # Report e commercialista (https://docs.getbeel.com/it/guide/report-e-commercialista) Conto economico, flussi di cassa e crediti per scadenza; l'export per il commercialista e come invitarlo in sola lettura. In **Tasse → IVA e report** trovi, sotto la posizione IVA, i **Report gestionali** dell'azienda e la sezione **Per il commercialista**. Da qui consegni i dati al commercialista, o gli dai accesso diretto in sola lettura. ![Il Drive: documenti, fatture ed estratti conto ordinati per mese, pronti per il commercialista.](/screenshots/drive.it.webp) I report servono a seguire l'andamento dell'azienda. Non sono il bilancio d'esercizio: sono al netto dell'IVA e non tengono conto di ratei e risconti, ammortamenti, personale, magazzino e imposte. Le cifre del commercialista prevalgono. ## Prima di iniziare [#prima-di-iniziare] - **Un'azienda italiana.** **Tasse** compare solo per le aziende con paese Italia. - **Fatture e movimenti in Getbeel.** Verifica le fatture fornitore in **Fatture ricevute**, e collega la banca o carica gli estratti in **Riconciliazione**. - **Per invitare il commercialista**: il ruolo **Proprietario** o **Membro**, e la sua email. - **Non serve** che il commercialista usi Getbeel: l'export si apre nel suo gestionale. - **Costo:** i report sono gratuiti; per i piani vedi [Prezzi](/it/api/pricing). ## Passi [#passi] ### Apri i report [#apri-i-report] Apri **Tasse** e la scheda **IVA e report**. Scorri fino a **Report gestionali**. ### Scegli report e periodo [#scegli-report-e-periodo] Scegli **Conto economico**, **Flussi di cassa** o **Crediti per scadenza**. Poi scegli il periodo: anno in corso, anno scorso o uno degli ultimi quattro trimestri. ### Scarica l'export per il commercialista [#scarica-lexport-per-il-commercialista] In **Esporta per il commercialista** scegli il **Periodo** e poi **Scarica ZIP**. ### Invita il commercialista [#invita-il-commercialista] In **Invita il tuo commercialista** scegli **Invita il commercialista**. Scrivi l'**Email del commercialista** e scegli **Invia invito**. ## Cosa è successo [#cosa-è-successo] - **Hai aperto i report** calcolati dalle tue fatture e dai movimenti bancari. - **Il report del periodo** è pronto, con il dettaglio mese per mese. - **Hai lo ZIP** con quello che serve per la contabilità del periodo. - **Il commercialista ha ricevuto un'email** con il link. Entra con il suo account e vede l'azienda in sola lettura. Finché non accetta, risulta **Invito inviato**. ## I report [#i-report] - **Conto economico**: i ricavi dalle fatture emesse accettate dallo SDI e i costi dalle fatture fornitore che hai verificato. Per data del documento, IVA esclusa, mese per mese. I costi sono divisi per categoria. Le note di credito sottraggono; le autofatture e gli altri documenti solo IVA (TD16–TD23, TD27) non sono ricavi. Sotto trovi cosa è rimasto fuori: fatture ancora allo SDI e fatture fornitore da verificare. - **Flussi di cassa**: entrate e uscite dei conti collegati e degli estratti caricati, mese per mese, per data contabile. Le uscite abbinate a una fattura fornitore sono raggruppate per la sua categoria. Gli incassi che segni a mano sulle fatture emesse sono indicati a parte. - **Crediti per scadenza**: quanto ti devono ancora i clienti oggi. È diviso in non scaduto, scaduto da 1–30, 31–60, 61–90 e oltre 90 giorni, per cliente e per fattura. Il residuo toglie ritenuta, note di credito, IVA in split payment (la versa l'ente pubblico) e incassi registrati. Se una fattura non ha scadenza, Getbeel conta 30 giorni dalla sua data: è il termine di legge per le transazioni commerciali (art. 4 D.Lgs. 231/2002). La competenza per data del documento segue l'art. 2423-bis c.c. ## Cosa c'è nello ZIP [#cosa-cè-nello-zip] - le fatture elettroniche **XML** emesse e ricevute e le autofatture, così come sono passate dallo SDI; - la **prima nota IVA** in CSV, una riga per documento e aliquota, con il nome del file XML; - i **registri IVA** vendite e acquisti di ogni periodo di liquidazione; - i **movimenti bancari** del periodo; - un file `LEGGIMI.txt` che spiega il contenuto ed elenca i documenti che mancano. TeamSystem, Zucchetti, Profis e gli altri gestionali importano direttamente gli XML delle fatture. I CSV si aprono in Excel. ## Cosa vede il commercialista [#cosa-vede-il-commercialista] Il ruolo **Commercialista** è in sola lettura. Vede fatture emesse e ricevute, autofatture, riconciliazione, Drive e la sezione **Tasse** (scadenze, registri, liquidazioni, report) e può esportare. Non può modificare nulla. Se segue più aziende su Getbeel, le trova tutte nella sua barra laterale, sotto **Clienti**. Togli l'accesso quando vuoi da **Impostazioni → Membri**, o con **Gestisci accessi**. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | --------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------- | | "Troppi documenti per questo periodo: scegli un trimestre o un mese." | Il periodo ha troppi documenti per un report | Scegli un trimestre | | "Troppi documenti per un solo file: scegli un trimestre." | Lo ZIP dell'anno sarebbe troppo grande | Scarica un trimestre alla volta | | "Disponibile solo per le aziende italiane." | Il paese dell'azienda non è l'Italia | Imposta l'Italia in **Impostazioni → Azienda** | | "Esportazione non riuscita. Riprova." | Il file non si è potuto creare | Riprova tra qualche minuto | | "Invito non riuscito. Riprova." | L'invito non è partito | Controlla l'email e riprova | | Il conto economico ha pochi costi | Le fatture fornitore non sono verificate | Verificale in **Fatture ricevute** | ## Dall'API e dall'assistente AI [#dallapi-e-dallassistente-ai] Gli stessi dati sono disponibili con l'API (`GET /v1/companies/me/reports/{type}`, `GET /v1/companies/me/accountant-export`) e con gli strumenti MCP `get_report` e `get_accountant_export`: vedi [Report ed export](/it/api/reports). Per invitare o rimuovere il commercialista da codice usa `invite_advisor` e `remove_advisor`: vedi [Commercialista (advisors)](/it/api/advisors). ## Prossimi passi [#prossimi-passi] Registri, liquidazioni e F24 accanto ai report. Cosa può fare ogni ruolo, commercialista compreso. Flussi di cassa completi senza caricare estratti. # Ritenute d'acconto (https://docs.getbeel.com/it/guide/ritenute) Fatture con ritenuta e cassa previdenziale, ritenute da versare quando paghi un professionista, F24 codice 1040 e dati per la Certificazione Unica. La ritenuta d'acconto riguarda Getbeel in due casi: quando **emetti** una fattura da professionista e quando **paghi** un professionista o un agente. ## Prima di iniziare [#prima-di-iniziare] - **Per emettere**: i dati aziendali completi in **Impostazioni → Azienda**. - **Per versare**: in **Tasse → Scadenze** rispondi **Sì** a "Paghi professionisti (avvocati, consulenti, freelance) trattenendo la ritenuta d'acconto?". - **Non serve** nel regime forfettario e dei minimi: non si applicano ritenute sui compensi che paghi (art. 1, c. 69, L. 190/2014). - **Costo**: registrare i compensi e preparare l'F24 è gratis; l'F24 si paga una volta, quando registri la quietanza ([Prezzi](/it/api/pricing)). ## Emettere una fattura con ritenuta [#emettere-una-fattura-con-ritenuta] ### Apri i campi della ritenuta [#apri-i-campi-della-ritenuta] In **Fatture emesse → Nuova fattura** scegli **Mostra altri campi** e attiva **Ritenuta d'acconto**. ### Scegli tipo, aliquota e causale [#scegli-tipo-aliquota-e-causale] Il tipo è RT01 se sei una persona fisica, RT02 se sei una società. Indica l'aliquota (di solito 20%) e la **Causale pagamento**. È il codice che il cliente userà nella Certificazione Unica: A per il lavoro autonomo abituale, M per l'occasionale, R per le provvigioni di un agente plurimandatario. ### Calcola l'importo [#calcola-limporto] Scegli **Usa € …** sotto l'importo. Getbeel calcola la ritenuta sulle righe soggette, più il contributo cassa se è soggetto. Le righe con natura N1 (spese anticipate in nome e per conto del cliente) non sono soggette. Per le provvigioni la ritenuta si applica solo su una quota: 50%, o 20% se l'agente si avvale di dipendenti o terzi (art. 25-bis DPR 600/1973). Inserisci tu l'importo. ### Aggiungi la cassa previdenziale [#aggiungi-la-cassa-previdenziale] Se serve, aggiungi il **Contributo previdenziale** e indica se è soggetto a ritenuta (per esempio la rivalsa INPS del 4%). Il contributo integrativo delle casse professionali non fa parte del compenso. ### Aggiungi i contributi trattenuti [#aggiungi-i-contributi-trattenuti] Se il cliente trattiene anche un contributo, scegli **Aggiungi contributo trattenuto (INPS, ENASARCO…)**. Nei totali vedi **Ritenute trattenute dal cliente** e **Netto a pagare**. Il netto è quello che il cliente ti paga e l'importo del pagamento nella fattura elettronica. Il totale del documento non cambia. ## Versare le ritenute quando paghi un professionista [#versare-le-ritenute-quando-paghi-un-professionista] Se paghi parcelle o provvigioni sei **sostituto d'imposta**. Trattieni la ritenuta e la versi con F24, **codice tributo 1040**, entro il **16 del mese dopo il pagamento** (art. 25 DPR 600/1973; art. 18 D.Lgs. 241/1997). ### Raccogli i compensi [#raccogli-i-compensi] Apri **Tasse → Ritenute**. Le fatture dei professionisti ricevute dallo SDI con la ritenuta compaiono da sole in **Compensi da pagare**. Per quelle arrivate prima scegli **Importa dalle fatture ricevute**. ### Aggiungi i compensi senza fattura SDI [#aggiungi-i-compensi-senza-fattura-sdi] Per una parcella cartacea o una prestazione occasionale scegli **Aggiungi compenso**. Inserisci professionista, codice fiscale, causale, compenso lordo senza IVA e somme non soggette. ### Segna il pagamento [#segna-il-pagamento] Quando paghi, scegli **Segna pagato** e indica la **Data del pagamento**. La ritenuta si fa al pagamento: una fattura di ottobre pagata a novembre si versa entro il 16 dicembre. ### Prepara l'F24 [#prepara-lf24] In **Ritenute da versare** trovi il totale di ogni mese con la sua scadenza. Scegli **Prepara l'F24**: ottieni i valori da copiare in F24 web o nella tua banca (sezione Erario, codice 1040, mese e anno). ### Carica la quietanza [#carica-la-quietanza] Dopo il pagamento scegli **Ho pagato: carica la quietanza** nella pagina dell'F24. Le ritenute diventano **Versata** e non si possono più modificare. Getbeel ricava dalla fattura gli importi della CU: compenso lordo senza IVA, somme non soggette, imponibile e ritenuta. Se qualcosa non torna, il compenso è segnato **Da verificare**: correggilo con **Modifica**. ## Preparare i dati di CU e 770 [#preparare-i-dati-di-cu-e-770] ### Scegli l'anno [#scegli-lanno] In fondo a **Tasse → Ritenute** apri **Certificazione Unica e 770** e scegli l'anno. Conta l'anno in cui hai pagato il compenso, non quello della fattura. ### Scarica il file [#scarica-il-file] Per ogni professionista e causale trovi lordo (punto 4), somme non soggette (punto 7), imponibile (punto 8) e ritenute (punto 9). Per il **770** trovi le ritenute di ogni mese con il loro F24. Scegli **Scarica Excel** o **Scarica CSV** e dai il file a chi presenta CU e 770. Getbeel non prepara il file telematico per l'Agenzia. Le scadenze, secondo le istruzioni della CU 2026: - la CU al professionista entro il **16 marzo**; - la CU all'Agenzia entro il 16 marzo, o entro il **30 aprile** se contiene solo lavoro autonomo abituale o provvigioni non occasionali; - il **770** entro il 31 ottobre. Per i compensi pagati nel 2026 valgono le istruzioni della CU 2027, attese a gennaio 2027: controllale. ## Cosa è successo [#cosa-è-successo] - **La fattura emessa** riporta la ritenuta e il netto a pagare nel tracciato FatturaPA. - **I compensi ricevuti** sono registrati, con la data di pagamento che decide il mese del versamento. - **L'F24 del mese** è pronto e, dopo la quietanza, versato. - **I dati di CU e 770** sono pronti da consegnare. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | -------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- | | "Manca il codice fiscale del professionista: serve per la CU." | La fattura o il compenso non ha il codice fiscale | Scegli **Modifica** e aggiungilo | | "Indica prima il giorno in cui hai pagato il compenso." | Il compenso non è segnato come pagato | Scegli **Segna pagato** | | "Questo F24 non corrisponde ai compensi registrati per il mese" | Hai aggiunto o cambiato compensi dopo aver preparato l'F24 | Scegli **Ricalcola** prima di pagare | | "Questa ritenuta è già stata versata con un F24: non si può più cambiare." | Il compenso è in un F24 pagato | Lascialo com'è; correggi con il commercialista | | "Questa fattura ha già una ritenuta: modifica quella." | La ritenuta di quella fattura è già registrata | Apri la riga esistente e scegli **Modifica** | | Una ritenuta era in un F24 pagato fuori da Getbeel | Getbeel non conosce quel versamento | Scegli **Già versata** sulla riga | ## Fonti [#fonti] - [Specifiche tecniche FatturaPA, Allegato A, versione 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) e [schema XSD 1.2.3](https://www.fatturapa.gov.it/it/norme-e-regole/documentazione-fattura-elettronica/formato-fatturapa/) - Art. 25 e 25-bis DPR 600/1973; art. 18 D.Lgs. 241/1997; art. 1, c. 69, L. 190/2014 - [Codice tributo 1040](https://www1.agenziaentrate.gov.it/servizi/codici/ricerca/SezioneErario.php?CT=1040) e [Risoluzione 13/E del 17 marzo 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) - [Istruzioni Certificazione Unica 2026](https://www.agenziaentrate.gov.it/portale/documents/20143/9602395/CU_istruzioni_2026.pdf/4184818b-05a3-acce-5956-70811c7d2233) e istruzioni del Modello 770/2026 ## Prossimi passi [#prossimi-passi] Tutte le scadenze, con l'F24 delle ritenute del mese. Il resto della fattura, fino all'esito dello SDI. Registra compensi e leggi i dati della CU dal tuo codice. # Stima delle imposte (https://docs.getbeel.com/it/guide/stima-imposte) Quanto mettere da parte per IRES e IRAP (società), IRPEF e addizionali (persone fisiche in regime ordinario), imposta sostitutiva del forfettario o dei minimi e INPS, con le date di acconti e saldo. Una stima da verificare con il commercialista. In **Tasse → Stima imposte** Getbeel stima le imposte dell'anno dalle tue fatture e dai cespiti. Ti mostra anche quando pagare acconti e saldo, per pianificare la liquidità. Non è l'importo da versare. Le imposte definitive le calcola il commercialista con la dichiarazione dei redditi. ## Prima di iniziare [#prima-di-iniziare] - **Le fatture dell'anno in Getbeel**: emesse e accettate dallo SDI, ricevute e già verificate. - **I [cespiti](/it/guide/cespiti)** registrati, se ne hai: al posto del loro costo conta l'ammortamento. - **I dati che Getbeel non conosce**: costo del personale, altri costi e ricavi, aliquota IRAP della regione, imposte dell'anno scorso. - **Non serve** nessun collegamento all'Agenzia: la stima usa solo i dati in Getbeel. - **Non disponibile** per le società di persone e gli altri regimi speciali. - **Costo**: salvare i tuoi dati è gratis ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Apri la stima [#apri-la-stima] Apri **Tasse → Stima imposte**. Senza dati salvati vedi i valori predefiniti. ### Scegli forma giuridica e regime [#scegli-forma-giuridica-e-regime] In **Forma giuridica e regime** scegli **Società di capitali (IRES + IRAP)**, **Regime forfettario**, **Persona fisica, regime ordinario (IRPEF)** o **Regime dei minimi**. ### Completa i tuoi dati [#completa-i-tuoi-dati] Inserisci quello che Getbeel non può sapere. Per una società: personale, variazioni fiscali IRES, aliquota IRAP, imposte dell'anno scorso. Per il forfettario: codice ATECO, gestione previdenziale, contributi versati, imposta sostitutiva dell'anno scorso. ### Salva [#salva] Scegli **Salva e ricalcola**. Getbeel salva i dati per quest'anno e aggiorna la stima. ### Controlla gli avvisi [#controlla-gli-avvisi] Leggi **Cosa manca o va controllato**: per esempio fatture ricevute ancora da revisionare o documenti in valuta estera non conteggiati. ### Leggi le scadenze [#leggi-le-scadenze] In **Acconti e saldo** trovi date, codici tributo F24 e importi stimati. Le date segnate **Da confermare** seguono le regole di oggi ma non sono ancora confermate. ## Cosa è successo [#cosa-è-successo] - **La stima usa i tuoi documenti**: ricavi, costi, ammortamenti e plusvalenze dell'anno. - **I tuoi dati sono salvati** per l'anno: cambiali quando servono, la stima si aggiorna. - **Hai le date** di acconti e saldo con i codici tributo, da verificare con il commercialista. ## Da dove vengono i numeri [#da-dove-vengono-i-numeri] - **Ricavi**: le fatture emesse dell'anno accettate dallo SDI, al netto dell'IVA. Le note di credito sottraggono; le autofatture non sono ricavi. Per il forfettario contano gli **incassi** registrati sulle fatture (principio di cassa), oppure le fatture se scegli **Fatturati nell'anno**. - **Costi**: le fatture ricevute dell'anno già revisionate, al netto dell'IVA, senza i beni registrati come cespiti. Al loro posto contano **ammortamenti** e beni dedotti per intero. - **Plus e minusvalenze** dei cespiti venduti. Le fatture ricevute ancora da revisionare e i documenti in valuta estera non sono conteggiati: Getbeel lo segnala. ## Società di capitali: IRES e IRAP [#società-di-capitali-ires-e-irap] - **IRES 24%** sull'utile più le variazioni fiscali che indichi (art. 77 TUIR). L'IRES ridotta al 20% della L. 207/2024 valeva solo per il 2025. - **IRAP 3,9%** (art. 16 D.Lgs. 446/1997) sul valore della produzione: ricavi meno costi, **senza** il costo del personale. Fanno eccezione i dipendenti a tempo indeterminato, che sono deducibili (art. 5 e art. 11 c. 4-octies). - Le regioni possono variare l'aliquota IRAP di 0,92 punti: inserisci quella della tua. Getbeel non calcola le perdite degli anni precedenti, i limiti agli interessi passivi e le deduzioni IRAP per le basi piccole. ## Regime forfettario [#regime-forfettario] Il reddito è ricavi × **coefficiente di redditività** del gruppo ATECO (Allegato 4 L. 190/2014): | Gruppo | ATECO | Coefficiente | | -------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------ | | Industrie alimentari e delle bevande | 10–11 | 40% | | Commercio all'ingrosso e al dettaglio | 45; 46.2–46.9; 47.1–47.7; 47.9 | 40% | | Commercio ambulante di alimentari e bevande | 47.81 | 40% | | Commercio ambulante di altri prodotti | 47.82–47.89 | 54% | | Costruzioni e attività immobiliari | 41–43; 68 | 86% | | Intermediari del commercio | 46.1 | 62% | | Alloggio e ristorazione | 55–56 | 40% | | Attività professionali, scientifiche, tecniche, sanitarie, istruzione, servizi finanziari e assicurativi | 64–66; 69–75; 85; 86–88 | 78% | | Altre attività economiche | le altre | 67% | - Dal reddito si sottraggono i **contributi previdenziali versati** nell'anno (c. 64). - **Imposta sostitutiva 15%**, oppure **5%** per i primi cinque anni di una nuova attività (c. 65). - Oltre **85.000 €** di ricavi si esce dal regime l'anno dopo; oltre **100.000 €** si esce subito (c. 54 e 71). I codici ATECO 2025 usano il coefficiente del codice ATECO 2007 corrispondente (D.Lgs. 81/2025). Se il gruppo ricavato dal codice non è giusto, sceglilo a mano in **Gruppo di attività (Allegato 4)**. ### Contributi INPS 2026 [#contributi-inps-2026] - **Gestione separata** (professionisti senza cassa): 26,07% del reddito, fino a 122.295 € (circolare INPS n. 8 del 3 febbraio 2026). - **Artigiani e commercianti**: contributi fissi sul minimale di 18.808 €, cioè 4.521,36 € per gli artigiani e 4.611,64 € per i commercianti, maternità compresa. Sul reddito oltre il minimale si aggiunge il 24% (artigiani) o il 24,48% (commercianti), più un punto oltre 56.224 € (circolare INPS n. 14 del 9 febbraio 2026). - I forfettari artigiani e commercianti che l'hanno chiesto pagano il 35% in meno (c. 77). - **Casse professionali**: inserisci tu l'importo in **Contributi dell'anno (€)**. ## Persone fisiche in regime ordinario (IRPEF) [#persone-fisiche-in-regime-ordinario-irpef] - Il reddito è ricavi meno costi dell'anno; la riduzione impatriati del profilo fiscale si applica al reddito professionale. - Con il **rientro di docenti e ricercatori** nel profilo fiscale, è tassato solo il 10% del reddito professionale (art. 44 DL 78/2010). Con l'opzione **neo-residenti**, l'imposta forfettaria annua sui redditi esteri (art. 24-bis TUIR) è aggiunta come voce a parte, da versare in un'unica soluzione con F24 ELIDE (codice NRPP) entro il saldo. - Si sottraggono i contributi INPS, poi l'IRPEF per scaglioni: 23% fino a 28.000 €, 33% (35% nel 2025) fino a 50.000 €, 43% oltre (art. 11 TUIR). - La detrazione per lavoro autonomo (art. 13 c. 5 TUIR) si calcola sul reddito prima dei contributi; si sottraggono le ritenute d'acconto subite. - Addizionale regionale (1,23% di base) e comunale sono dovute solo se è dovuta l'IRPEF netta (art. 50 D.Lgs. 446/1997). ## Regime dei minimi (regime di vantaggio) [#regime-dei-minimi-regime-di-vantaggio] Per chi è ancora nel regime (entrato entro il 2015, per cinque anni e fino all'anno in cui compie 35 anni: art. 27 DL 98/2011): - Il reddito è l'**incassato** meno le spese dell'anno; i beni strumentali si deducono **per intero** nell'anno in cui li compri (c. 104 L. 244/2007). - Si sottraggono i contributi INPS fino al reddito, poi le perdite degli anni precedenti (**Perdite degli anni precedenti (€)**). - **Imposta sostitutiva del 5%**, al posto di IRPEF e addizionali. - Oltre **30.000 €** di ricavi il regime cessa dall'anno dopo; oltre **45.000 €** cessa già quest'anno (c. 111). - Se vendi un bene, tutto il prezzo di vendita è reddito: aggiungilo agli **Altri ricavi**. ## Acconti e saldo [#acconti-e-saldo] Getbeel elenca le scadenze con i codici tributo F24: | Imposta | Primo acconto | Secondo acconto | Saldo | | ------------------------------- | ------------- | --------------- | ----- | | IRES | 2001 | 2002 | 2003 | | IRAP | 3812 | 3813 | 3800 | | Imposta sostitutiva forfettario | 1790 | 1791 | 1792 | | IRPEF | 4033 | 4034 | 4001 | | Addizionale regionale | — | — | 3801 | | Addizionale comunale | 3843 (30%) | — | 3844 | | Imposta sostitutiva minimi | 1793 | 1794 | 1795 | - **Saldo e primo acconto** entro il 30 giugno, o nei 30 giorni successivi con lo 0,40% in più. **Secondo acconto** entro il 30 novembre (art. 17 DPR 435/2001). - Nel 2026 soggetti ISA e forfettari hanno pagato entro il 20 luglio (DL 89/2026). - L'acconto è il 100% dell'imposta dell'anno prima: 40% e 60%, oppure 50% e 50% per soggetti ISA e forfettari (art. 58 DL 124/2019; ris. AdE 93/E/2019). - Se il primo acconto è fino a 103 €, si paga tutto a novembre. - L'acconto non è dovuto se l'imposta dell'anno prima è fino a 20,66 € (IRES e IRAP) o sotto 52 € (IRPEF e imposte sostitutive). - Senza l'imposta dell'anno scorso, gli acconti sono calcolati sulla stima di quest'anno (metodo previsionale). Le date del 2027 sono segnate **Da confermare**: dal 2027 i versamenti passano al Testo unico D.Lgs. 33/2025. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ----------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------- | | "… fatture ricevute dell'anno sono ancora da revisionare: i loro costi non sono conteggiati." | Ci sono fatture fornitore non verificate | Verificale in **Fatture ricevute** | | "Indica il codice ATECO o il gruppo: senza coefficiente di redditività il reddito non è calcolabile." | Manca il codice ATECO | Inserisci **Codice ATECO** o scegli il **Gruppo di attività (Allegato 4)** | | "Contributi dedotti stimati pari a quelli dell'anno: inserisci quelli versati nell'anno." | **Contributi versati nell'anno (€)** è vuoto | Inserisci i contributi versati e scegli **Salva e ricalcola** | | "Ammortamenti di auto o telefoni contati per intero: la parte deducibile è minore …" | Hai cespiti con deducibilità limitata | Correggi la stima con il commercialista | | "Per questa forma giuridica la stima non è disponibile." | Società di persone o altro regime speciale | Chiedi la stima al commercialista | | "Serve un piano attivo per salvare …" | L'account non ha un piano | Scegli un piano in **Impostazioni → Utilizzo e fatturazione** | ## Fonti [#fonti] - TUIR (DPR 917/1986) art. 77, testo in vigore al 31 dicembre 2026. - D.Lgs. 446/1997 artt. 5, 11, 16 e istruzioni IRAP 2026. - L. 190/2014 art. 1 c. 54–89 e Allegato 4; circolare AdE 9/E del 10 aprile 2019; D.Lgs. 81/2025 art. 1. - Circolari INPS [n. 8 del 3 febbraio 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) e [n. 14 del 9 febbraio 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; istruzioni Redditi 2026. Non confermati in una fonte ufficiale: - le date e la ripartizione degli acconti dal 2027 (Testo unico versamenti); - se i contributi INPS dei forfettari si calcolano sul reddito prima della deduzione dei contributi (Getbeel fa così); - gli acconti dei contributi INPS, che Getbeel non calcola. ## Prossimi passi [#prossimi-passi] Registra i beni strumentali: la stima usa i loro ammortamenti. Le scadenze IVA, bollo e ritenute dell'anno. Leggi la stima dal tuo codice o dall'assistente AI. # Tasse (https://docs.getbeel.com/it/guide/tasse) Scadenze, registri IVA e liquidazioni aggiornati dalle tue fatture. Getbeel prepara l'F24; tu controlli e paghi. *Video tutorial in arrivo.* **Tasse** tiene aggiornati scadenze, registri IVA e liquidazioni IVA a partire dai documenti in Getbeel. Tu controlli le righe segnalate, prepari l'F24 quando sei pronto e lo paghi tu. ![La pagina Tasse: le scadenze del mese con importo, stato e azione di ciascuna.](/screenshots/taxes.it.webp) ## Prima di iniziare [#prima-di-iniziare] - **Le impostazioni fiscali**, una volta sola. In **Tasse → Scadenze** rispondi a **Come versi l'IVA?** e alla domanda sui professionisti pagati con ritenuta. Getbeel costruisce le scadenze da qui. - **I documenti in Getbeel**: fatture emesse, fatture dei fornitori (dallo SDI, dalle email o caricate) e autofatture. Getbeel conta solo quello che è in Getbeel. - **Non serve** compilare i registri a mano. Getbeel non ti chiede le credenziali dell'Agenzia delle Entrate e non paga al posto tuo. - **Costo**: preparare F24 e LIPE è gratis; ogni adempimento si paga una volta, quando è pagato o inviato ([Prezzi](/it/api/pricing)). ## Cosa aggiorna Getbeel da solo [#cosa-aggiorna-getbeel-da-solo] - **Registri IVA.** Getbeel li calcola dai documenti ogni volta che li apri. Una fattura fornitore letta dall'AI ma non ancora verificata entra subito, con la nota **Non ancora verificata**. - **Liquidazioni IVA.** Anche loro si ricalcolano dai registri a ogni apertura: IVA a debito, IVA detraibile e risultato. - **Riporto dal periodo precedente.** Il credito (rigo VP8) o il debito fino a 100 € (rigo VP7) viene dalla liquidazione salvata. Se non l'hai salvata, Getbeel lo calcola dai suoi registri. Un importo che scrivi tu sostituisce quello calcolato. - **Scadenze.** Il versamento IVA mostra l'importo calcolato, seguito da **finora**, finché non salvi la liquidazione. Bollo e ritenute fanno lo stesso finché il periodo non è chiuso. In cima a **Registri IVA** e **Liquidazioni** leggi **Aggiornato alle** con l'ora del calcolo e quante righe sono da verificare. Getbeel non prepara F24 e LIPE da solo: restano **Da preparare** finché non li prepari tu. ## Passi [#passi] ### Controlla le righe da verificare [#controlla-le-righe-da-verificare] Apri **Tasse → Registri IVA** e scegli il periodo. Le righe **Non ancora verificata** escono da questo stato quando verifichi la fattura in **Fatture ricevute**. Se un acquisto non è detraibile, o lo è in parte, scegli **Modifica** sulla riga. Poi **Escludi dalla liquidazione** oppure **Indica l'IVA che conta**, sempre con un motivo. Per un acquisto con IVA indetraibile indica 0. ### Controlla la liquidazione [#controlla-la-liquidazione] Apri **Tasse → Liquidazioni** e scegli il periodo. I righi sono gli stessi della LIPE. I campi **Credito del periodo precedente** e **Debito fino a 100 € non versato** sono già compilati da Getbeel. Cambiali solo se il commercialista ti dà un importo diverso. ### Salva la liquidazione [#salva-la-liquidazione] A periodo chiuso scegli **Salva e prepara l'F24**. Se c'è qualcosa da versare, Getbeel prepara l'F24; altrimenti vedi **Liquidazione salvata: niente da versare ora.** ### Paga l'F24 [#paga-lf24] Scegli **Apri l'F24**. Usa **Scarica il promemoria F24 (PDF)** o copia i valori con **Copia**. Paga da F24 web o dalla tua banca. ### Carica la quietanza [#carica-la-quietanza] Nella stessa pagina scegli **Ho pagato: carica la quietanza** (PDF, PNG o JPEG fino a 10 MB). La scadenza diventa **Pagato**. ### Prepara la LIPE del trimestre [#prepara-la-lipe-del-trimestre] A trimestre chiuso, con tutte le liquidazioni salvate, scegli **Prepara il file LIPE** in **Tasse → Liquidazioni**. Per una società indica **Codice fiscale di chi firma** e **Carica** (il ruolo di chi firma, non un caricamento). ### Invia la LIPE [#invia-la-lipe] Scegli **Apri la LIPE** e **Scarica il file LIPE (XML)**. Controllalo con il software dell'Agenzia, poi caricalo su Fatture e Corrispettivi, o dallo al commercialista. Infine carica la ricevuta in **Hai inviato la LIPE?**. ## Cosa è successo [#cosa-è-successo] - **I registri erano già completi**: hai controllato solo le righe su cui Getbeel aveva dubbi. - **La liquidazione è salvata** con i suoi importi, che servono alla liquidazione successiva e alla LIPE. - **L'F24 è pronto**, con i valori da copiare e il promemoria PDF. - **La scadenza è pagata**, con la quietanza conservata in Getbeel. - **La LIPE è pronta** dalle liquidazioni salvate, già controllata con lo schema ufficiale IVP18. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | --------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------- | | "Rispondi a due domande per vedere tutte le tue scadenze." | Le impostazioni fiscali mancano | Rispondi alle due domande in **Tasse → Scadenze** | | "Nessun dato del periodo precedente in Getbeel: indica tu credito o debito riportato." | È il primo periodo dell'anno con dati in Getbeel | Inserisci il credito o il debito della liquidazione precedente | | "I registri sono cambiati da quando hai salvato questa liquidazione: salvala di nuovo." | Un documento del periodo è cambiato dopo il salvataggio | Salva di nuovo la liquidazione prima di pagare | | "In lettura dall'AI" o "Importi in euro mancanti" in **Registri IVA** | Il documento non ha ancora importi, o non li ha in euro | Aspetta la lettura; per la valuta estera completa gli importi in euro | | "Salva prima le liquidazioni del trimestre." | Per la LIPE manca una liquidazione salvata | Salva ogni mese, o il trimestre, in **Tasse → Liquidazioni** | | "Per preparare gli F24 serve un piano attivo. Sceglilo in Fatturazione." | L'account non ha un piano | Scegli un piano in **Impostazioni → Utilizzo e fatturazione** | Getbeel prepara; tu e il commercialista controllate prima di pagare o inviare. ## Fonti [#fonti] - Versamento mensile entro il 16 e debito fino a 100 € riportato: art. 1, c. 1 e 4, DPR 100/1998. - Versamento trimestrale con interessi dell'1%: art. 7 DPR 542/1999. - Righi VP7, VP8 e LIPE: modello e specifiche tecniche IVP18 approvati con provv. AdE prot. 125654 del 14 marzo 2024 ([Liquidazioni periodiche IVA](https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/liquidazioni-periodiche-iva)). ## Prossimi passi [#prossimi-passi] I dati annuali, dai registri e dalle liquidazioni salvate. Ritenute sui compensi ai professionisti, F24 1040 e CU. Esportazioni e accesso in sola lettura per il commercialista. # Collaborazione del team (https://docs.getbeel.com/it/guide/team-collaboration) Ogni azienda è un team con i suoi membri: Proprietario, Membro o Commercialista, ognuno con i suoi permessi. In Getbeel ogni azienda è un **team**: i dati sono separati e ogni persona entra con un ruolo. Il ruolo decide cosa vede e cosa può cambiare. ## In breve [#in-breve] | Cosa | Regola | | ----------- | ------------------------------------------------------------------ | | Un team | Un'azienda, con le sue fatture, banche, impostazioni e abbonamento | | Più aziende | Crei un team per ognuna e passi dall'una all'altra | | Chi entra | Solo chi inviti per email, con un ruolo | | Ruoli | **Proprietario**, **Membro**, **Commercialista** | ## I team [#i-team] Un team tiene separati fatture, caselle email, banche collegate, impostazioni e abbonamento. Le persone di un team non vedono nulla degli altri. Crei un altro team da **Cambia area di lavoro** → **Crea un team**. Chi segue più aziende, come un commercialista, può gestirle da **Aziende clienti**. ## I ruoli [#i-ruoli] - **Proprietario**: accesso completo. Gestisce fatturazione, membri e impostazioni. - **Membro**: lavora su fatture, riconciliazione e analisi, e cambia le impostazioni. Non gestisce l'abbonamento né i ruoli. - **Commercialista**: sola lettura. Vede ed esporta fatture, riconciliazione, Drive e Tasse, ma non modifica nulla. Il dettaglio è in [Ruoli e permessi](/it/guide/team-collaboration/roles-permissions). ## Il proprietario principale [#il-proprietario-principale] Chi crea il team ne è il **Proprietario principale**. Solo lui elimina il team e trasferisce la proprietà a un altro membro. ## Pagine correlate [#pagine-correlate] Cosa può fare ogni ruolo, pagina per pagina. Invita una persona e gestisci gli inviti in sospeso. Invita il commercialista in sola lettura dalla pagina Tasse. # Ruoli e permessi (https://docs.getbeel.com/it/guide/team-collaboration/roles-permissions) Cosa possono fare Proprietario, Membro e Commercialista, e come cambiare il ruolo di una persona. Ogni persona del team ha un ruolo: **Proprietario**, **Membro** o **Commercialista**. Puoi gestire solo le persone con un ruolo più basso del tuo. ## Prima di iniziare [#prima-di-iniziare] - **Per cambiare un ruolo** serve il ruolo **Proprietario**. Il **Membro** invita ma non cambia ruoli. - **La persona deve essere già nel team.** Per aggiungerla vedi [Inviti del team](/it/guide/team-collaboration/team-invitations). - **Costo:** i ruoli non costano nulla ([Prezzi](/it/api/pricing)). ## I ruoli a confronto [#i-ruoli-a-confronto] | Cosa | Proprietario | Membro | Commercialista | | ---------------------------------------------------------- | ------------------------------- | ------ | -------------- | | Vedere fatture ricevute, emesse e autofatture | Sì | Sì | Sì | | Caricare, categorizzare ed eliminare fatture | Sì | Sì | No | | Scansionare le caselle email | Sì | Sì | No | | Vedere Riconciliazione ed esportare | Sì | Sì | Sì | | Caricare estratti, collegare la banca, confermare | Sì | Sì | No | | Vedere Tasse | Sì | Sì | Sì | | Modificare in Tasse | Sì | Sì | No | | Vedere Drive | Sì | Sì | Sì | | Vedere Panoramica e Analisi | Sì | Sì | No | | Aprire Impostazioni (Azienda, Email, Categorie, Regole AI) | Sì | Sì | No | | Creare chiavi API e webhook | Sì | Sì | No | | Invitare persone | Sì | Sì | No | | Cambiare ruoli e rimuovere membri | Sì | No | No | | Cambiare piano e dati di pagamento | Sì | No | No | | Trasferire la proprietà, eliminare il team | Solo il proprietario principale | No | No | Puoi invitare persone con il tuo ruolo o uno più basso. Un **Membro** invita quindi **Membri** e **Commercialisti**. ## Cambiare il ruolo di una persona [#cambiare-il-ruolo-di-una-persona] ### Apri i membri [#apri-i-membri] Apri **Impostazioni → Membri**. In **Membri del team** trovi ogni persona con il suo ruolo. ### Apri il menu della persona [#apri-il-menu-della-persona] Fai clic su ⋯ accanto alla persona e scegli **Aggiorna ruolo**. ### Scegli il ruolo [#scegli-il-ruolo] In **Aggiorna ruolo del membro** scegli il nuovo ruolo e conferma con **Aggiorna ruolo**. ## Cosa è successo [#cosa-è-successo] - **Hai aperto l'elenco** delle persone del team. - **Il menu** mostra solo le azioni che il tuo ruolo permette. - **Il nuovo ruolo vale subito**: alla prossima pagina la persona vede solo quello che il ruolo consente. ## Altre azioni sui membri [#altre-azioni-sui-membri] - **Rimuovi dall'account**: la persona perde l'accesso al team. - **Trasferisci proprietà**: solo il proprietario principale, verso un altro membro. - **Lascia il team**: da **Impostazioni → Zona pericolosa**, scrivendo `LEAVE`. Il proprietario principale non può lasciare il team. Fatture, banca e tasse dell'azienda sono visibili a chi ha questo ruolo. Invitalo solo se deve seguire la contabilità. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | ------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------- | | Manca il menu ⋯ accanto a una persona | La persona ha un ruolo uguale o più alto del tuo, o sei tu | Chiedi a un Proprietario | | "Il ruolo deve essere diverso da quello attuale" | Hai scelto lo stesso ruolo | Scegli un altro ruolo | | "Non è stato possibile aggiornare il ruolo del membro selezionato." | L'aggiornamento non è riuscito | Ricarica la pagina e riprova | | "Non è stato possibile rimuovere il membro selezionato." | La rimozione non è riuscita | Riprova; il proprietario principale non si rimuove | ## Prossimi passi [#prossimi-passi] Aggiungi una persona con il ruolo giusto. Invita il commercialista direttamente da Tasse. Team, aziende e proprietario principale. # Inviti del team (https://docs.getbeel.com/it/guide/team-collaboration/team-invitations) Invita persone nel team via email con un ruolo, e gestisci gli inviti in sospeso: ruolo, rinnovo e rimozione. Invita una persona via email e scegli il suo ruolo. Quando accetta, entra nel team con i permessi di quel ruolo. ## Prima di iniziare [#prima-di-iniziare] - **Il ruolo Proprietario o Membro.** Il **Commercialista** non invita. - **L'email della persona.** Se non ha un account Getbeel, lo crea dal link dell'invito. - **Il ruolo giusto**: puoi assegnare il tuo ruolo o uno più basso. Vedi [Ruoli e permessi](/it/guide/team-collaboration/roles-permissions). - **Per il commercialista** c'è anche **Invita il commercialista** in **Tasse** ([Report e commercialista](/it/guide/report-e-commercialista)). - **Costo:** gli inviti sono gratuiti ([Prezzi](/it/api/pricing)). ## Passi [#passi] ### Apri i membri [#apri-i-membri] Apri **Impostazioni → Membri**. In **Membri del team** scegli **Invita membri** (il pulsante **+**). ### Inserisci email e ruolo [#inserisci-email-e-ruolo] Scrivi l'email e scegli il ruolo: **Proprietario**, **Membro** o **Commercialista**. Per invitare altre persone scegli **Aggiungi un altro**. ### Invia [#invia] Scegli **Invia inviti**. Ogni persona riceve un'email con il link. ### La persona accetta [#la-persona-accetta] Dal link la persona accede o si registra, poi vede **Unisciti a** con il nome del team. Sceglie **Continua come** con la sua email. ## Cosa è successo [#cosa-è-successo] - **Hai aperto l'elenco** dei membri e degli inviti. - **Ogni invito ha un ruolo**, scelto da te. - **L'invito è in Inviti in sospeso**, con "Invitato il … · scade il …". Vale 7 giorni. - **La persona è nel team** e sparisce dagli inviti in sospeso. ## Gestire gli inviti in sospeso [#gestire-gli-inviti-in-sospeso] In **Inviti in sospeso** apri il menu ⋯ di un invito: - **Aggiorna invito**: cambia il ruolo prima che venga accettato. - **Rinnova invito**: per un invito **Scaduto**, lo prolunga di 7 giorni. - **Rimuovi invito**: annulla l'invito; il link non funziona più. Aggiornare, rinnovare e rimuovere inviti richiede il ruolo **Proprietario**. ## Se qualcosa non va [#se-qualcosa-non-va] | Messaggio | Causa | Cosa fare | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- | | "Non è stato possibile invitare i membri. Riprova." | L'invito non è partito, per esempio un'email ripetuta | Controlla le email inserite e riprova | | "Invito non trovato o scaduto" | Sono passati 7 giorni, o l'invito è stato rimosso | Chiedi al proprietario di usare **Rinnova invito** o di invitarti di nuovo | | "Questo link di invito non è valido. Chiedi al proprietario del team di inviarti un nuovo invito." | Il link è incompleto o modificato | Apri il link dall'email, o chiedi un nuovo invito | | Vuoi accettare con un altro account | Sei entrato con l'account sbagliato | Scegli **Accedi con un account diverso** | | Non vedi **Invita membri** | Il tuo ruolo è **Commercialista** | Chiedi a un Proprietario o a un Membro | ## Prossimi passi [#prossimi-passi] Cosa potrà fare la persona che hai invitato. Dai al commercialista l'accesso in sola lettura. Gli altri passi per configurare l'azienda. # The prepaid balance (https://docs.getbeel.com/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/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/it/api/reference/unknown/invoice.sent) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.delivered (https://docs.getbeel.com/it/api/reference/unknown/invoice.delivered) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.not_delivered (https://docs.getbeel.com/it/api/reference/unknown/invoice.not_delivered) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.rejected (https://docs.getbeel.com/it/api/reference/unknown/invoice.rejected) Full OpenAPI document: https://docs.getbeel.com/openapi.json # bank_statement.parsed (https://docs.getbeel.com/it/api/reference/unknown/bank_statement.parsed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # reconciliation.completed (https://docs.getbeel.com/it/api/reference/unknown/reconciliation.completed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # received_invoice.created (https://docs.getbeel.com/it/api/reference/unknown/received_invoice.created) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.emailed (https://docs.getbeel.com/it/api/reference/unknown/invoice.emailed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.email_failed (https://docs.getbeel.com/it/api/reference/unknown/invoice.email_failed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.paid (https://docs.getbeel.com/it/api/reference/unknown/invoice.paid) Full OpenAPI document: https://docs.getbeel.com/openapi.json # invoice.overdue (https://docs.getbeel.com/it/api/reference/unknown/invoice.overdue) Full OpenAPI document: https://docs.getbeel.com/openapi.json # filing.ready (https://docs.getbeel.com/it/api/reference/unknown/filing.ready) Full OpenAPI document: https://docs.getbeel.com/openapi.json # filing.filed (https://docs.getbeel.com/it/api/reference/unknown/filing.filed) Full OpenAPI document: https://docs.getbeel.com/openapi.json # tax_deadline.upcoming (https://docs.getbeel.com/it/api/reference/unknown/tax_deadline.upcoming) Full OpenAPI document: https://docs.getbeel.com/openapi.json # tax_deadline.insufficient_funds (https://docs.getbeel.com/it/api/reference/unknown/tax_deadline.insufficient_funds) Full OpenAPI document: https://docs.getbeel.com/openapi.json # bank_connection.expiring (https://docs.getbeel.com/it/api/reference/unknown/bank_connection.expiring) Full OpenAPI document: https://docs.getbeel.com/openapi.json # bank_connection.expired (https://docs.getbeel.com/it/api/reference/unknown/bank_connection.expired) Full OpenAPI document: https://docs.getbeel.com/openapi.json