{"openapi":"3.1.0","info":{"title":"getbeel API","version":"1.0.0","description":"Italian e-invoicing API (FatturaPA, SDI).\n\nAuthenticate with an API key from Settings → API keys & MCP:\n`Authorization: Bearer gb_live_…` (or `gb_test_…`).\n\nJSON in snake_case, ISO 8601 dates, amounts as decimal strings.\nLists use cursor pagination (`limit`, `cursor`, `has_more`, `next_cursor`).\nRate limit: 120 requests per 60 seconds per key (RateLimit-* headers, 429 with Retry-After).\nEvery response has an `X-Request-Id` header.\n\nTest keys (`gb_test_…`) work on sandbox data: invoices they create are sandbox invoices, `send` goes to a simulated SDI (free, no quota) and lists only show sandbox invoices. Sandbox outcomes: buyer partita IVA `00000000000` → `rejected` (NS, code 00305); codice destinatario `MC00000` → `not_delivered` (MC); anything else → `delivered` (RC) a few seconds after sending.\nLive keys (`gb_live_…`) work on real data and send to the real SDI; they need an SDI plan: the pay-per-use rate card (new accounts) or an SDI add-on.\n\nBank statements, reconciliation, connections (Gmail, Outlook, IMAP, forwarding, Stripe) and collected documents are real data: both key modes can read them, only live keys can change them.\n\nMulti-company: a parent account (software house, marketplace, commercialista) adds client companies with `POST /companies`. To act on one, send its id in the `Getbeel-Company` header on any other endpoint; without it, requests act on the key's own account. A key can only act on client companies of its own account that its member manages; anything else is 404 `company_not_found`.\n\nWebhooks: add endpoints in Settings → API keys & MCP. See the `webhooks` section for the event payloads and the Getbeel-Signature header."},"servers":[{"url":"https://www.getbeel.com/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account"},{"name":"Companies","description":"Client companies of a parent account (software houses, marketplaces, commercialisti)"},{"name":"Invoices","description":"Issued invoices (fatture emesse)"},{"name":"Recurring invoices","description":"Invoices repeated every month, quarter or year"},{"name":"Quotes","description":"Quotes (preventivi): draft, sent, accepted, declined or expired; converted into an invoice draft"},{"name":"Items","description":"Saved items and services (articoli) for invoice lines"},{"name":"Numbering series","description":"Numbering series (sezionali): prefix, suffix, yearly reset, defaults for invoices and credit notes"},{"name":"Received invoices"},{"name":"Bank reconciliation","description":"Bank statements, their transactions and the AI matching to received invoices"},{"name":"Connections","description":"Mailboxes, forwarding address and Stripe"},{"name":"Taxes","description":"Italian tax calendar (scadenzario), VAT registers and liquidazioni, withholdings owed as sostituto d’imposta with CU and 770 data, prepared filings (F24 for bollo, withholdings and VAT; the LIPE file, checked against the official XSD; the data sheet of the annual VAT return), the VAT position estimate, management reports (P&L, cash flow, receivables aging), the export for the accountant, fixed assets and depreciation (libro cespiti), tax estimates (IRES, IRAP, forfettario, INPS) and POS–RT links (the AdE bulk CSV). getbeel prepares; the client pays or files in their own AdE area or bank."},{"name":"Bank connections","description":"Automatic bank feeds through Enable Banking, with your own Enable Banking application"},{"name":"Advisors","description":"The company’s commercialista: a team member with read-only access (role auditor) who reads and exports invoices, received invoices, bank movements and taxes and changes nothing"},{"name":"AI rules","description":"Plain-language instructions the AI follows, in order, when it reads received invoices (invoice_scan) or drafts issued invoices from Stripe payments (fattura_emessa). The same rules as Settings → AI rules."},{"name":"Tax rules","description":"The rules behind the tax calendar and estimates that change by year or by law: versioned rule values (INPS minimale and rates, forfettario thresholds, impatriati shares…) and proroghe (published extensions that move deadlines). Each carries its official source. A weekly watch reads the official sources (Agenzia delle Entrate, MEF Finanze, Gazzetta Ufficiale, INPS) and proposes changes with a quote; getbeel administrators approve them. Customers read the rules in force."},{"name":"Autofatture","description":"Reverse-charge autofatture (TD17, TD18, TD19) of foreign purchases, as on the Autofatture page: read one and send it to SDI."},{"name":"Drive","description":"The company's Drive, as in the app: received invoices' files, uploaded bank statements and uploaded documents, by month and folder."},{"name":"Billing","description":"Pay as you go: the platform, sandbox, API, MCP and webhooks are free; SDI sends, received invoices, AI document reads, bank feeds and prepared filings are paid from one prepaid EUR balance per billing account. A billable call the balance does not cover answers 402 insufficient_balance (application/problem+json, with topup_url). Amounts are EUR cents, net of VAT."}],"paths":{"/billing/balance":{"get":{"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"}}]}},"/billing/usage":{"get":{"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"}}}}}}},"/billing/prices":{"get":{"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"}}]}},"/billing/topups":{"post":{"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"}}}}}}},"/billing/payment-method":{"post":{"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"}}}}}}},"/ai-rules":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/ai-rules/{id}":{"patch":{"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"}}}}}},"delete":{"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"}}}}}}},"/tax-rules":{"get":{"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"}}]}},"/tax-rules/values":{"post":{"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"}}]}},"/tax-rules/overrides":{"post":{"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"}}]}},"/tax-rules/decisions":{"post":{"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"}}]}},"/sdi-receiving":{"get":{"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"}}]},"post":{"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"}}}}}},"delete":{"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"}}]}},"/sandbox/inbound-invoices":{"post":{"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"}}}}}}},"/received-invoices/uploads":{"post":{"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"}}}}}}},"/received-invoices/uploads/{id}":{"get":{"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"}}}}}}},"/categories":{"get":{"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"}}]},"post":{"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"}}}}}}},"/categories/{id}":{"patch":{"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"}}}}}},"delete":{"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"}}}}}}},"/received-invoices/{id}/category":{"post":{"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"}}}}}}},"/companies/me/vat-adjustments/{key}":{"put":{"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"}}}}}},"delete":{"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"}}}}}}},"/autofatture/{id}":{"get":{"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"}}}}}}},"/autofatture/{id}/send":{"post":{"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"}}}}}}},"/drive":{"get":{"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"}}}}}}},"/drive/files":{"post":{"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"}}}}}}},"/drive/files/{id}/download":{"get":{"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"}}}}}}},"/drive/files/{id}":{"delete":{"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"}}}}}}},"/drive/folders":{"post":{"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"}}}}}},"delete":{"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"}}}}}}},"/bank-connections":{"get":{"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"}}]},"post":{"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"}}}}}}},"/bank-connections/{id}":{"get":{"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"}}}}}},"delete":{"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"}}}}}}},"/bank-connections/{id}/reconnect":{"post":{"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"}}}}}}},"/bank-connections/{id}/sync":{"post":{"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"}}}}}}},"/companies":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/companies/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}}},"/me":{"get":{"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"}}]}},"/usage":{"get":{"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"}}}}}}},"/invoices":{"post":{"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"}}}}}},"get":{"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"}}}}}}},"/invoices/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}}},"/invoices/{id}/reopen":{"post":{"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"}}}}}}},"/invoices/{id}/send":{"post":{"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"}}}}}}},"/invoices/{id}/email":{"post":{"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"}}}}}}},"/invoices/{id}/deliveries":{"get":{"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"}}}}}}},"/invoices/{id}/payments":{"post":{"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"}}}}}},"get":{"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"}}}}}}},"/invoices/{id}/payment-link":{"post":{"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"}}}}}}},"/invoices/{id}/reminders":{"post":{"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"}}}}}}},"/recurring-invoices":{"post":{"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"}}}}}},"get":{"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"}}}}}}},"/recurring-invoices/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}},"delete":{"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"}}}}}}},"/recurring-invoices/{id}/pause":{"post":{"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"}}}}}}},"/recurring-invoices/{id}/resume":{"post":{"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"}}}}}}},"/invoices/validate":{"post":{"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"}}]}},"/received-invoices":{"get":{"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"}}}}}}},"/received-invoices/{id}/approve":{"post":{"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"}}}}}}},"/received-invoices/{id}/reject":{"post":{"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"}}}}}}},"/bank-statements":{"post":{"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"}}}}}},"get":{"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"}}}}}}},"/bank-statements/{id}":{"get":{"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"}}}}}}},"/bank-transactions":{"get":{"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"}}}}}}},"/reconciliations":{"post":{"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"}}}}}}},"/reconciliations/{id}":{"get":{"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"}}}}}}},"/reconciliations/{id}/matches":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/reconciliations/{id}/matches/{matchId}/approve":{"post":{"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"}}}}}}},"/reconciliations/{id}/matches/{matchId}/reject":{"post":{"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"}}}}}}},"/unmatched/payments":{"get":{"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"}}}}}}},"/unmatched/invoices":{"get":{"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"}}}}}}},"/connections":{"get":{"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"}}]}},"/connections/email":{"post":{"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"}}]}},"/connections/{id}/scan":{"post":{"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, no company profile, or a mailbox whose authorization expired (code `reconnect_required`: reconnect it in the app first)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; quote X-Request-Id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/forwarding-address":{"get":{"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"}}]}},"/connections/stripe":{"post":{"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"}}]}},"/connections/stripe/sync":{"post":{"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"}}}}}}},"/companies/me/tax-calendar":{"get":{"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"}}}}}}},"/companies/me/tax-calendar.ics":{"get":{"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"}}}},"/companies/me/vat-position":{"get":{"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"}}}}}}},"/companies/me/oss-return":{"get":{"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"}}}}}}},"/companies/me/vat-registers":{"get":{"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"}}}}}}},"/companies/me/vat-settlements":{"get":{"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"}}}}}}},"/companies/me/reports/{type}":{"get":{"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"}}}}}}},"/companies/me/accountant-export":{"get":{"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"}}}}}}},"/filings":{"post":{"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"}}}}}},"get":{"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"}}}}}}},"/filings/{id}":{"get":{"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"}}}}}}},"/filings/{id}/file":{"get":{"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"}}}}}}},"/filings/{id}/receipt":{"post":{"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"}}}}}}},"/filings/{id}/status":{"post":{"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"}}}}}}},"/filings/skip":{"post":{"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"}}]}},"/filings/{id}/events":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/invoices/{id}/credit-notes":{"post":{"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"}}}}}},"get":{"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"}}}}}}},"/quotes":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/quotes/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}},"delete":{"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"}}}}}}},"/quotes/{id}/send":{"post":{"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"}}}}}}},"/quotes/{id}/accept":{"post":{"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"}}}}}}},"/quotes/{id}/decline":{"post":{"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"}}}}}}},"/quotes/{id}/convert":{"post":{"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"}}}}}}},"/quotes/{id}/pdf":{"get":{"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"}}}}}}},"/items":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/items/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}},"delete":{"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"}}}}}}},"/numbering-series":{"get":{"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"}}]},"post":{"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"}}}}}}},"/numbering-series/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}}},"/withholdings":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/withholdings/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}},"delete":{"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"}}}}}}},"/withholdings/sync":{"post":{"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"}}]}},"/withholdings/cu":{"get":{"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"}}}}}}},"/companies/me/tax-settings":{"get":{"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"}}}}}},"patch":{"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"}}}}}}},"/companies/me/reminder-settings":{"get":{"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"}}}}}},"patch":{"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"}}}}}}},"/companies/me/tax-profile":{"get":{"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"}}}}}},"patch":{"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"}}}}}}},"/companies/me/tax-profile/detect":{"post":{"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"}}}}}}},"/fixed-asset-categories":{"get":{"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"}}]}},"/fixed-assets":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/fixed-assets/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}},"delete":{"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"}}}}}}},"/companies/me/fixed-assets-register":{"get":{"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"}}}}}}},"/companies/me/tax-estimate":{"get":{"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"}}}}}},"put":{"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"}}}}}}},"/pos-rt-links":{"get":{"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"}}}}}},"post":{"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"}}}}}}},"/pos-rt-links/{id}":{"get":{"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"}}}}}},"patch":{"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"}}}}}},"delete":{"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"}}}}}}},"/pos-rt-links/export":{"get":{"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"}}}}}}},"/pos-rt-links/mark-filed":{"post":{"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"}}}}}}},"/advisors":{"get":{"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"}}]},"post":{"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"}}}}}}},"/advisors/invitations":{"post":{"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"}}}}}}},"/advisors/{id}":{"delete":{"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"}}}}}}}},"webhooks":{"invoice.sent":{"post":{"summary":"invoice.sent","description":"SDI accepted the invoice (it has an identificativo_sdi). Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"invoice.delivered":{"post":{"summary":"invoice.delivered","description":"SDI delivered the invoice to the customer (RC). Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"invoice.not_delivered":{"post":{"summary":"invoice.not_delivered","description":"SDI could not deliver it (MC): the invoice is issued and waits in the customer's fiscal drawer; tell your customer. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"invoice.rejected":{"post":{"summary":"invoice.rejected","description":"SDI rejected the invoice (NS); sdi.error_codes lists the codes. Fix it and create a new invoice. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"bank_statement.parsed":{"post":{"summary":"bank_statement.parsed","description":"A bank statement was read: its transactions are saved and AI matching starts. data.object is the BankStatement. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"reconciliation.completed":{"post":{"summary":"reconciliation.completed","description":"AI matching of a statement finished (status review): the matches can be reviewed. data.object is the Reconciliation. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"received_invoice.created":{"post":{"summary":"received_invoice.created","description":"A supplier invoice was received through SDI (source sdi) or collected (mailbox scan, forwarding, upload). data.object is the ReceivedInvoice. Live endpoints; test endpoints get the sandbox ones (POST /sandbox/inbound-invoices). Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"invoice.emailed":{"post":{"summary":"invoice.emailed","description":"An invoice or reminder email was sent. data.object is the InvoiceEmail. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"invoice.email_failed":{"post":{"summary":"invoice.email_failed","description":"An invoice or reminder email could not be sent. data.object is the InvoiceEmail (error says why). Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"invoice.paid":{"post":{"summary":"invoice.paid","description":"The payments recorded cover what is due (app, API or Stripe payment link). data.object is the Invoice. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"invoice.overdue":{"post":{"summary":"invoice.overdue","description":"The day after the due date, once per invoice, when it is not paid. data.object is the Invoice. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"filing.ready":{"post":{"summary":"filing.ready","description":"A filing was prepared or recomputed (F24 ready to pay). data.object is the Filing. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"filing.filed":{"post":{"summary":"filing.filed","description":"The receipt of a filing was uploaded: it is paid. data.object is the Filing. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"tax_deadline.upcoming":{"post":{"summary":"tax_deadline.upcoming","description":"A tax deadline is 7 days or 1 day away and not paid yet (once each). data.object is the TaxDeadline with reminder_days_before. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"tax_deadline.insufficient_funds":{"post":{"summary":"tax_deadline.insufficient_funds","description":"Within 5 working days of an F24 due date, the F24 payments due that day are higher than the balance of every connected bank account (once per due date). data.object is the F24FundsAlert. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"bank_connection.expiring":{"post":{"summary":"bank_connection.expiring","description":"The consent of a bank connection ends within 7 days (once per consent): reconnect it with POST /bank-connections/{id}/reconnect. data.object is the BankConnection. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankConnectionWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}},"bank_connection.expired":{"post":{"summary":"bank_connection.expired","description":"The consent of a bank connection ended or was revoked (status requires_reconnect; once per consent): automatic updates stopped until it is reconnected. data.object is the BankConnection. Live endpoints only. Sent as JSON with a Getbeel-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with your endpoint secret>). Answer 2xx; other answers are retried with backoff for about 3 days.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankConnectionWebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key: gb_test_… or gb_live_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","permission_error","invalid_request_error","not_found_error","rate_limit_error","api_error"]},"code":{"type":"string","examples":["invalid_api_key"]},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"Problem":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","permission_error","invalid_request_error","not_found_error","rate_limit_error","api_error"]},"code":{"type":"string","examples":["invalid_api_key"]},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","code","message"],"additionalProperties":false},"type":{"type":"string","description":"URL of the error in the docs","examples":["https://docs.getbeel.com/en/api/errors#no_card"]},"title":{"type":"string","examples":["No card saved"]},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"examples":[409]},"detail":{"type":"string"},"code":{"type":"string","examples":["no_card"]}},"required":["error","type","title","status","detail","code"],"additionalProperties":false},"Company":{"type":"object","properties":{"name":{"type":"string"},"vat_number":{"description":"Partita IVA","type":["string","null"]},"codice_fiscale":{"type":["string","null"]},"regime_fiscale":{"examples":["RF01"],"type":["string","null"]},"country":{"type":["string","null"]},"address":{"type":["string","null"]},"street_number":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"preferred_currency":{"type":"string"},"sdi_configured":{"type":"boolean"}},"required":["name","vat_number","codice_fiscale","regime_fiscale","country","address","street_number","postal_code","city","province","preferred_currency","sdi_configured"],"additionalProperties":false},"Account":{"type":"object","properties":{"object":{"type":"string","const":"account"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"slug":{"type":["string","null"]},"company":{"anyOf":[{"$ref":"#/components/schemas/Company"},{"type":"null"}]},"api_key":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"prefix":{"type":"string","examples":["gb_live_a1B2"]},"mode":{"type":"string","enum":["test","live"]},"scopes":{"type":"array","items":{"type":"string"}}},"required":["id","prefix","mode","scopes"],"additionalProperties":false}},"required":["object","id","name","slug","company","api_key"],"additionalProperties":false},"CompanyAccount":{"type":"object","properties":{"object":{"type":"string","const":"company"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Send it as the Getbeel-Company header (or the MCP company_id argument) to act on this company"},"name":{"type":"string"},"slug":{"type":["string","null"]},"parent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The parent (platform) account, null for the parent itself and for standalone accounts"},"company":{"anyOf":[{"$ref":"#/components/schemas/Company"},{"type":"null"}]},"sdi_readiness":{"type":"object","properties":{"ready":{"type":"boolean","description":"The fiscal data needed to issue invoices through SDI is complete. Live sends also need the SDI add-on."},"missing":{"type":"array","items":{"type":"string","enum":["name","country","vat_number","regime_fiscale","address","postal_code","city","province"]}}},"required":["ready","missing"],"additionalProperties":false}},"required":["object","id","name","slug","parent_id","company","sdi_readiness"],"additionalProperties":false},"CompanyList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyAccount"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateCompanyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Company name (ragione sociale)","examples":["Rossi Srl"]},"country":{"description":"ISO 3166-1 alpha-2 country. Default IT","type":"string","pattern":"^[A-Z]{2}$"},"vat_number":{"description":"Partita IVA (Italy: 11 digits, without the IT prefix)","examples":["01234567890"],"anyOf":[{"type":"string","maxLength":30},{"type":"null"}]},"codice_fiscale":{"description":"Codice fiscale (Italy: 16 characters for a person, or the 11 digits of the P.IVA for most companies)","examples":["01234567890"],"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]},"regime_fiscale":{"description":"Regime fiscale of the CedentePrestatore (FatturaPA 1.2.1.8): RF01 ordinario, RF19 forfettario…","examples":["RF01"],"anyOf":[{"type":"string","pattern":"^RF\\d{2}$"},{"type":"null"}]},"address":{"description":"Street (via, piazza…)","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"street_number":{"description":"Numero civico","examples":["12"],"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"postal_code":{"description":"CAP","examples":["20121"],"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"city":{"description":"Comune","examples":["Milano"],"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"province":{"description":"Provincia (sigla)","examples":["MI"],"anyOf":[{"type":"string","maxLength":2},{"type":"null"}]}},"required":["name"],"additionalProperties":false},"UpdateCompanyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Company name (ragione sociale)","examples":["Rossi Srl"]},"country":{"description":"ISO 3166-1 alpha-2 country. Default IT","type":"string","pattern":"^[A-Z]{2}$"},"vat_number":{"description":"Partita IVA (Italy: 11 digits, without the IT prefix)","examples":["01234567890"],"anyOf":[{"type":"string","maxLength":30},{"type":"null"}]},"codice_fiscale":{"description":"Codice fiscale (Italy: 16 characters for a person, or the 11 digits of the P.IVA for most companies)","examples":["01234567890"],"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]},"regime_fiscale":{"description":"Regime fiscale of the CedentePrestatore (FatturaPA 1.2.1.8): RF01 ordinario, RF19 forfettario…","examples":["RF01"],"anyOf":[{"type":"string","pattern":"^RF\\d{2}$"},{"type":"null"}]},"address":{"description":"Street (via, piazza…)","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"street_number":{"description":"Numero civico","examples":["12"],"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"postal_code":{"description":"CAP","examples":["20121"],"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"city":{"description":"Comune","examples":["Milano"],"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"province":{"description":"Provincia (sigla)","examples":["MI"],"anyOf":[{"type":"string","maxLength":2},{"type":"null"}]}},"additionalProperties":false},"InvoiceLine":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"string","examples":["1"]},"unit_price":{"type":"string","description":"Decimal string, up to 8 decimals","examples":["100.00"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat_rate":{"type":"string","examples":["22.00"]},"natura":{"description":"Natura IVA when the rate is 0","examples":["N2.2"],"type":["string","null"]}},"required":["description","quantity","unit_price","amount","vat_rate","natura"],"additionalProperties":false},"Invoice":{"type":"object","properties":{"object":{"type":"string","const":"invoice"},"id":{"type":"string","examples":["fe_3f1c…"]},"livemode":{"type":"boolean","description":"false for sandbox invoices created with a test key"},"number":{"type":"string","description":"Invoice number with its suffix"},"tipo_documento":{"type":"string","examples":["TD01"]},"invoice_date":{"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"]},"due_date":{"anyOf":[{"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"]},{"type":"null"}]},"status":{"type":"string","enum":["draft","sending","sent","delivered","not_delivered","rejected"],"description":"draft → sending (XML being generated and submitted) → sent (accepted by SDI) → delivered (RC), not_delivered (MC) or rejected (NS)"},"is_proforma":{"type":"boolean"},"currency":{"type":"string"},"amount_subtotal":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount_tax":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount_total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"customer":{"type":"object","properties":{"name":{"type":"string"},"vat_number":{"type":["string","null"]},"codice_fiscale":{"type":["string","null"]},"codice_destinatario":{"type":["string","null"]},"pec":{"type":["string","null"]},"email":{"type":["string","null"]},"country":{"type":["string","null"]},"address":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"city":{"type":["string","null"]},"province":{"type":["string","null"]}},"required":["name","vat_number","codice_fiscale","codice_destinatario","pec","email","country","address","postal_code","city","province"],"additionalProperties":false},"sdi":{"type":"object","properties":{"identificativo_sdi":{"type":["string","null"]},"file_name":{"type":["string","null"]},"error_message":{"type":["string","null"]},"error_codes":{"type":"array","items":{"type":"string"},"description":"SDI error codes (00xxx). On a rejected invoice: what to correct before resending with the same number and date. 00404 (duplicate) on a sent or delivered invoice: SDI already accepted the same document, it is issued; do not resend","examples":[["00404"]]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":["string","null"]}},"required":["code","description"],"additionalProperties":false},"description":"The SDI errors with their description, as in the SDI receipt","examples":[[{"code":"00305","description":"1.4.1.1.2 <IdCodice> non valido"}]]},"available_since":{"anyOf":[{"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"]},{"type":"null"}],"description":"not_delivered (SDI ricevuta di impossibilità di recapito): the day SDI made the invoice available in the customer's reserved area (Fatture e Corrispettivi). The invoice counts as issued; do not send it again.","examples":["2026-10-31"]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["identificativo_sdi","file_name","error_message","error_codes","errors","available_since","updated_at"],"additionalProperties":false},"payment_status":{"type":"string","enum":["unpaid","partially_paid","paid"],"description":"unpaid → partially_paid → paid, from the payments recorded (POST /v1/invoices/{id}/payments, Stripe payment links)"},"amount_due":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"What the customer pays: amount_total less the ritenuta d'acconto and less amount_credited","examples":["122.00"]},"amount_credited":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Total of the credit notes (TD04) on this invoice that SDI accepted; a fully credited invoice counts as paid","examples":["122.00"]},"withholdings":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"TipoRitenuta: RT01/RT02 withholding tax, RT03–RT06 contributions","examples":["RT01"]},"rate":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"reason":{"type":"string","description":"CausalePagamento (CU causale)","examples":["A"]}},"required":["type","rate","amount","reason"],"additionalProperties":false},"description":"DatiRitenuta blocks: what the customer withholds and pays to the State or the fund (amount_due is net of all of them)"},"related_invoice_id":{"description":"Credit notes: the invoice they credit","type":["string","null"]},"series_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Numbering series (GET /numbering-series); null = the default numbering"},"amount_paid":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"paid_at":{"anyOf":[{"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"]},{"type":"null"}],"description":"Date of the payment that settled it"},"overdue":{"type":"boolean","description":"Issued, not paid and due_date before today (Italian time)"},"payment_link_url":{"description":"Stripe payment link (POST /v1/invoices/{id}/payment-link)","type":["string","null"]},"lines":{"description":"Only on GET /v1/invoices/{id}","type":"array","items":{"$ref":"#/components/schemas/InvoiceLine"}},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","livemode","number","tipo_documento","invoice_date","due_date","status","is_proforma","currency","amount_subtotal","amount_tax","amount_total","customer","sdi","payment_status","amount_due","amount_credited","withholdings","related_invoice_id","series_id","amount_paid","paid_at","overdue","payment_link_url","created_at","updated_at"],"additionalProperties":false},"InvoiceList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"ReverseChargeProposal":{"type":"object","properties":{"tipo_documento":{"anyOf":[{"type":"string","enum":["TD17","TD18","TD19"]},{"type":"null"}],"description":"TD17 services from abroad, TD18 goods from another EU state, TD19 goods already in Italy. null when no TD document applies or the supplier country is missing"},"status":{"type":"string","enum":["proposed","needs_review","needs_country","not_required","generated","sent","dismissed"],"description":"Live state of the proposal. proposed: the XML draft is generated automatically; needs_review: listed, check it first (goods vs services unknown, VAT charged, receipt date unknown, deadline passed, possible duplicate, Northern Ireland supplier); needs_country: the supplier country is missing; not_required: goods imported from outside the EU (customs document, no TD to SdI); generated: the XML draft exists, not sent; sent: handed to SdI; dismissed: deleted by the team"},"reason":{"type":"string","description":"Why: eu_services, non_eu_services, eu_goods, goods_in_italy, san_marino_goods, non_eu_goods_import, country_unknown","examples":["non_eu_services"]},"deadline_basis":{"anyOf":[{"type":"string","enum":["receipt","effettuazione"]},{"type":"null"}],"description":"receipt: EU supplier, counted from the month the invoice was received; effettuazione: non-EU supplier, from the month of the purchase"},"deadline":{"anyOf":[{"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"]},{"type":"null"}],"description":"Last day to send the TD document to SdI: the 15th of the following month (d.lgs. 127/2015 art. 1 c.3-bis lett. b)"}},"required":["tipo_documento","status","reason","deadline_basis","deadline"],"additionalProperties":false},"ReceivedInvoice":{"type":"object","properties":{"object":{"type":"string","const":"received_invoice"},"id":{"type":"string"},"source":{"type":"string","description":"How the invoice reached getbeel: sdi (received through SDI on the company codice destinatario), email, forwarded, bank_transaction, manual, …","examples":["email"]},"invoice_number":{"type":["string","null"]},"invoice_type":{"type":"string","examples":["invoice"]},"invoice_date":{"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"]},"due_date":{"anyOf":[{"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"]},{"type":"null"}]},"status":{"type":"string","examples":["verified"]},"payment_status":{"type":"string"},"category":{"type":"string"},"currency":{"type":"string"},"amount_subtotal":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount_tax":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount_total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vendor":{"type":"object","properties":{"name":{"type":"string"},"vat_number":{"type":["string","null"]},"email":{"type":["string","null"]},"country":{"type":["string","null"]},"city":{"type":["string","null"]},"address":{"type":["string","null"]}},"required":["name","vat_number","email","country","city","address"],"additionalProperties":false},"reverse_charge":{"anyOf":[{"$ref":"#/components/schemas/ReverseChargeProposal"},{"type":"null"}],"description":"The reverse-charge autofattura getbeel proposed for this invoice of a foreign supplier (null when none applies). The XML draft is on the Autofatture page; sending it to SdI is always a user action."},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","source","invoice_number","invoice_type","invoice_date","due_date","status","payment_status","category","currency","amount_subtotal","amount_tax","amount_total","vendor","reverse_charge","created_at","updated_at"],"additionalProperties":false},"ReceivedInvoiceList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedInvoice"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"ValidateInvoiceRequest":{"type":"object","properties":{"xml":{"type":"string","minLength":1,"description":"FatturaPA XML document"}},"required":["xml"],"additionalProperties":false},"ValidationResult":{"type":"object","properties":{"object":{"type":"string","const":"validation_result"},"valid":{"type":"boolean"},"tipo_documento":{"type":["string","null"]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"AdE error code as SDI reports it (Allegato A v1.9.1, Appendice 1): 00200 = not conforming to the XSD, 00201 = more than 50 format errors, 00313–00476 = SDI content controls; or `not_fatturapa`","examples":["00200","00421"]},"message":{"type":"string"},"line":{"description":"Line in the XML (XSD errors)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["code","message"],"additionalProperties":false}},"checks":{"type":"array","items":{"type":"string"},"description":"Checks that ran","examples":[["structure","xsd","business_rules"]]}},"required":["object","valid","tipo_documento","errors","checks"],"additionalProperties":false},"CreateInvoiceWithholding":{"type":"object","properties":{"type":{"default":"RT01","description":"TipoRitenuta: RT01 the issuer is a natural person, RT02 a company or other entity","type":"string","enum":["RT01","RT02"]},"rate":{"description":"AliquotaRitenuta in percent","examples":["20"]},"reason":{"default":"A","description":"CausalePagamento: the CU causale (A professional services, M occasional work, R commissions to a multi-firm agent, …)","type":"string","enum":["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"]},"amount":{"description":"ImportoRitenuta. Omit to compute rate × (lines subject to withholding + cassa when subject). Required for commissions (reasons Q–V), where the rate applies to part of the amount (art. 25-bis DPR 600/1973).","examples":["100.00"]},"contributions":{"description":"Further DatiRitenuta blocks for contributions the customer withholds (e.g. the ENASARCO share). Each is withheld from amount_due.","maxItems":4,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["RT03","RT04","RT05","RT06"],"description":"RT03 INPS, RT04 ENASARCO, RT05 ENPAM, RT06 other contribution withheld by the customer"},"rate":{"description":"Decimal string (or number)","examples":["100.00"]},"amount":{"description":"Decimal string (or number)","examples":["100.00"]}},"required":["type","rate","amount"],"additionalProperties":false}}},"required":["type","rate","reason"],"additionalProperties":false},"CreateInvoiceCassa":{"type":"object","properties":{"type":{"type":"string","pattern":"^TC(0[1-9]|1\\d|2[0-2])$","description":"TipoCassa (TC22 INPS)","examples":["TC22"]},"rate":{"description":"AlCassa in percent","examples":["4"]},"amount":{"description":"ImportoContributoCassa. Omit to compute rate × the fees (lines except natura N1).","examples":["100.00"]},"vat_rate":{"description":"IVA on the contribution","examples":["22"]},"natura":{"description":"Natura when vat_rate is 0","type":"string","enum":["N1","N2.1","N2.2","N3.1","N3.2","N3.3","N3.4","N3.5","N3.6","N4","N5","N6.1","N6.2","N6.3","N6.4","N6.5","N6.6","N6.7","N6.8","N6.9","N7"]},"subject_to_withholding":{"default":false,"description":"The contribution is subject to the withholding (Ritenuta = SI), e.g. the 4% INPS rivalsa; the integrative contribution of the professional funds is not","type":"boolean"}},"required":["type","rate","vat_rate","subject_to_withholding"],"additionalProperties":false},"CreateInvoiceRequest":{"type":"object","properties":{"customer":{"type":"object","properties":{"denominazione":{"description":"Company name. Or send nome and cognome for a person.","examples":["Rossi S.r.l."],"type":"string","minLength":1,"maxLength":80},"nome":{"description":"First name of a person customer (with cognome)","examples":["Mario"],"type":"string","minLength":1,"maxLength":60},"cognome":{"description":"Surname of a person customer (with nome)","examples":["Rossi"],"type":"string","minLength":1,"maxLength":60},"partita_iva":{"description":"VAT number, with or without the country prefix. Sandbox: 00000000000 is rejected by SDI (NS, code 00305).","examples":["01234567890"],"type":"string","pattern":"^[A-Z0-9]{2,28}$"},"codice_fiscale":{"description":"Italian tax code: 16 characters for a person, 11 digits for a company","examples":["RSSMRA80A01F205X"],"type":"string","pattern":"^[A-Z0-9]{11,16}$"},"address":{"description":"Street and number","examples":["Via Roma 1"],"type":"string","minLength":1,"maxLength":60},"postal_code":{"description":"CAP (postal code)","examples":["20121"],"type":"string","minLength":1,"maxLength":10},"city":{"description":"City (comune)","examples":["Milano"],"type":"string","minLength":1,"maxLength":60},"province":{"description":"Two-letter Italian province code (sigla)","examples":["MI"],"type":"string","pattern":"^[A-Z]{2}$"},"country":{"default":"IT","description":"ISO 3166-1 alpha-2 country code; default IT","examples":["IT"],"type":"string","pattern":"^[A-Z]{2}$"},"codice_destinatario":{"description":"SDI recipient code. Omit (or 0000000) to deliver by PEC or to the buyer's fiscal drawer. Sandbox: MC00000 is not delivered (MC).","examples":["M5UXCR1"],"type":"string","pattern":"^[A-Z0-9]{7}$"},"pec":{"description":"Certified email (PEC) where SDI delivers the invoice when there is no codice_destinatario","examples":["rossisrl@pec.it"],"type":"string","maxLength":256,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"email":{"description":"For the courtesy copy (not used by SDI)","type":"string","maxLength":256,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["country"],"additionalProperties":false,"description":"The buyer (CessionarioCommittente): denominazione, or nome and cognome; partita_iva or codice_fiscale; address; codice_destinatario or pec for delivery"},"tipo_documento":{"default":"TD01","description":"TD01 invoice, TD04 credit note, …","type":"string","enum":["TD01","TD02","TD04","TD05","TD06","TD24","TD25"]},"number":{"description":"Invoice number. Omit to use the next number (test and live keys have separate sequences).","type":"string","pattern":"^(?=.*\\d)[A-Za-z0-9/._-]{1,20}$"},"date":{"description":"Invoice date (default: today in Italy)","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"]},"series_id":{"description":"Numbering series for the automatic number (GET /numbering-series). Omit for the team's default series; null for the default numbering. Ignored when number is sent.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"related_invoice_id":{"description":"With tipo_documento TD04: the issued invoice this credit note credits (written to DatiFattureCollegate). POST /invoices/{id}/credit-notes copies the invoice for you.","type":"string","minLength":1,"maxLength":100},"currency":{"default":"EUR","description":"ISO 4217 currency code; default EUR","examples":["EUR"],"type":"string","pattern":"^[A-Z]{3}$"},"lines":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":1000,"description":"What is sold, as printed on the line (Descrizione)","examples":["Consulenza ottobre 2026"]},"quantity":{"description":"Default 1","examples":["1"]},"unit_price":{"description":"Decimal string (or number)","examples":["100.00"]},"vat_rate":{"description":"IVA rate in percent","examples":["22"]},"subject_to_withholding":{"description":"With a withholding: whether this line is subject to it (written as Ritenuta = SI). Default true, except natura N1 lines (expenses advanced for the customer).","type":"boolean"},"natura":{"description":"Natura IVA of a 0% line (exempt, reverse charge, …)","type":"string","enum":["N1","N2.1","N2.2","N3.1","N3.2","N3.3","N3.4","N3.5","N3.6","N4","N5","N6.1","N6.2","N6.3","N6.4","N6.5","N6.6","N6.7","N6.8","N6.9","N7"]}},"required":["description","unit_price"],"additionalProperties":false},"description":"Invoice lines (DettaglioLinee), 1–200"},"withholding":{"description":"Ritenuta d'acconto: income tax the customer withholds from the payment and pays to the State on the issuer's behalf (DatiRitenuta). Omit when there is none.","$ref":"#/components/schemas/CreateInvoiceWithholding"},"cassa_previdenziale":{"description":"Cassa previdenziale: the professional's social-security contribution charged to the customer (DatiCassaPrevidenziale), e.g. the 4% INPS rivalsa. Omit when there is none.","$ref":"#/components/schemas/CreateInvoiceCassa"},"payment":{"description":"Payment terms printed on the invoice (DatiPagamento): method, terms, due date and bank details","type":"object","properties":{"method":{"default":"MP05","description":"ModalitaPagamento (MP05 bank transfer)","type":"string","pattern":"^MP(0[1-9]|1\\d|2[0-3])$"},"terms":{"default":"TP02","description":"CondizioniPagamento: TP01 instalments, TP02 full payment, TP03 advance","type":"string","enum":["TP01","TP02","TP03"]},"due_date":{"description":"Payment due date (YYYY-MM-DD)","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"]},"iban":{"description":"IBAN to pay into, without spaces","examples":["IT60X0542811101000000123456"],"type":"string","pattern":"^[A-Z]{2}\\d{2}[A-Z0-9]{11,30}$"},"bank_name":{"description":"Name of the bank (IstitutoFinanziario)","examples":["Intesa Sanpaolo"],"type":"string","minLength":1,"maxLength":80},"beneficiary":{"description":"Payee name, if not the issuer (Beneficiario)","type":"string","minLength":1,"maxLength":200}},"required":["method","terms"],"additionalProperties":false},"notes":{"description":"Printed on the invoice as its Causale","type":"string","minLength":1,"maxLength":1000}},"required":["customer","tipo_documento","currency","lines"],"additionalProperties":false},"UpdateInvoiceRequest":{"type":"object","properties":{"customer":{"description":"The buyer, sent whole (same fields as create): replaces the current customer","type":"object","properties":{"denominazione":{"description":"Company name. Or send nome and cognome for a person.","examples":["Rossi S.r.l."],"type":"string","minLength":1,"maxLength":80},"nome":{"description":"First name of a person customer (with cognome)","examples":["Mario"],"type":"string","minLength":1,"maxLength":60},"cognome":{"description":"Surname of a person customer (with nome)","examples":["Rossi"],"type":"string","minLength":1,"maxLength":60},"partita_iva":{"description":"VAT number, with or without the country prefix. Sandbox: 00000000000 is rejected by SDI (NS, code 00305).","examples":["01234567890"],"type":"string","pattern":"^[A-Z0-9]{2,28}$"},"codice_fiscale":{"description":"Italian tax code: 16 characters for a person, 11 digits for a company","examples":["RSSMRA80A01F205X"],"type":"string","pattern":"^[A-Z0-9]{11,16}$"},"address":{"description":"Street and number","examples":["Via Roma 1"],"type":"string","minLength":1,"maxLength":60},"postal_code":{"description":"CAP (postal code)","examples":["20121"],"type":"string","minLength":1,"maxLength":10},"city":{"description":"City (comune)","examples":["Milano"],"type":"string","minLength":1,"maxLength":60},"province":{"description":"Two-letter Italian province code (sigla)","examples":["MI"],"type":"string","pattern":"^[A-Z]{2}$"},"country":{"default":"IT","description":"ISO 3166-1 alpha-2 country code; default IT","examples":["IT"],"type":"string","pattern":"^[A-Z]{2}$"},"codice_destinatario":{"description":"SDI recipient code. Omit (or 0000000) to deliver by PEC or to the buyer's fiscal drawer. Sandbox: MC00000 is not delivered (MC).","examples":["M5UXCR1"],"type":"string","pattern":"^[A-Z0-9]{7}$"},"pec":{"description":"Certified email (PEC) where SDI delivers the invoice when there is no codice_destinatario","examples":["rossisrl@pec.it"],"type":"string","maxLength":256,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"email":{"description":"For the courtesy copy (not used by SDI)","type":"string","maxLength":256,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["country"],"additionalProperties":false},"tipo_documento":{"description":"TD01 invoice, TD04 credit note, … (a credit note made from an invoice keeps its type)","type":"string","enum":["TD01","TD02","TD04","TD05","TD06","TD24","TD25"]},"number":{"description":"Invoice number. A number from a numbering series cannot change; a typed one must fit the year's sequence.","type":"string","pattern":"^(?=.*\\d)[A-Za-z0-9/._-]{1,20}$"},"date":{"description":"Invoice date (YYYY-MM-DD). A series number cannot move to another year.","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"]},"currency":{"description":"ISO 4217 currency code","examples":["EUR"],"type":"string","pattern":"^[A-Z]{3}$"},"lines":{"description":"All the invoice lines (DettaglioLinee), 1–200: replaces the current lines. With a withholding or cassa on the draft, send those again too.","minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":1000,"description":"What is sold, as printed on the line (Descrizione)","examples":["Consulenza ottobre 2026"]},"quantity":{"description":"Default 1","examples":["1"]},"unit_price":{"description":"Decimal string (or number)","examples":["100.00"]},"vat_rate":{"description":"IVA rate in percent","examples":["22"]},"subject_to_withholding":{"description":"With a withholding: whether this line is subject to it (written as Ritenuta = SI). Default true, except natura N1 lines (expenses advanced for the customer).","type":"boolean"},"natura":{"description":"Natura IVA of a 0% line (exempt, reverse charge, …)","type":"string","enum":["N1","N2.1","N2.2","N3.1","N3.2","N3.3","N3.4","N3.5","N3.6","N4","N5","N6.1","N6.2","N6.3","N6.4","N6.5","N6.6","N6.7","N6.8","N6.9","N7"]}},"required":["description","unit_price"],"additionalProperties":false}},"withholding":{"description":"Ritenuta d'acconto, as in create; null removes it. Its amount is computed from the lines unless you send it.","anyOf":[{"$ref":"#/components/schemas/CreateInvoiceWithholding"},{"type":"null"}]},"cassa_previdenziale":{"description":"Cassa previdenziale, as in create; null removes it.","anyOf":[{"$ref":"#/components/schemas/CreateInvoiceCassa"},{"type":"null"}]},"payment":{"description":"Payment terms (DatiPagamento), sent whole: replaces the current ones","type":"object","properties":{"method":{"default":"MP05","description":"ModalitaPagamento (MP05 bank transfer)","type":"string","pattern":"^MP(0[1-9]|1\\d|2[0-3])$"},"terms":{"default":"TP02","description":"CondizioniPagamento: TP01 instalments, TP02 full payment, TP03 advance","type":"string","enum":["TP01","TP02","TP03"]},"due_date":{"description":"Payment due date (YYYY-MM-DD)","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"]},"iban":{"description":"IBAN to pay into, without spaces","examples":["IT60X0542811101000000123456"],"type":"string","pattern":"^[A-Z]{2}\\d{2}[A-Z0-9]{11,30}$"},"bank_name":{"description":"Name of the bank (IstitutoFinanziario)","examples":["Intesa Sanpaolo"],"type":"string","minLength":1,"maxLength":80},"beneficiary":{"description":"Payee name, if not the issuer (Beneficiario)","type":"string","minLength":1,"maxLength":200}},"required":["method","terms"],"additionalProperties":false},"notes":{"description":"Causale printed on the invoice; null removes it","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},"additionalProperties":false},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","examples":["evt_8a1f…"]},"object":{"type":"string","const":"event"},"type":{"type":"string","enum":["invoice.sent","invoice.delivered","invoice.rejected","invoice.not_delivered"]},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Unix seconds"},"livemode":{"type":"boolean"},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Invoice"}},"required":["object"],"additionalProperties":false}},"required":["id","object","type","created","livemode","data"],"additionalProperties":false},"BankStatement":{"type":"object","properties":{"object":{"type":"string","const":"bank_statement"},"id":{"type":"string","examples":["stmt_1761800000000_ab12cd3"]},"file_name":{"type":"string"},"mime_type":{"type":"string","examples":["text/csv"]},"source":{"type":"string","enum":["upload","open_banking"],"description":"upload: a file you uploaded. open_banking: synced from a bank connection (one statement per bank account and month, no file; new transactions are appended on each sync)."},"file_size":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","parsed","matching","review","completed","failed"],"description":"pending → processing → parsed → matching → review (parsed and matched; matches wait for review) → completed (marked done in the app). failed: see error_message."},"error_message":{"type":["string","null"]},"bank_name":{"type":["string","null"]},"account_number_last4":{"type":["string","null"]},"currency":{"type":"string","examples":["EUR"]},"period_start":{"anyOf":[{"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"]},{"type":"null"}]},"period_end":{"anyOf":[{"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"]},{"type":"null"}]},"transactions":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Movements saved for this statement. An upload saves only movements not imported yet (the same file again or an overlapping period adds none of those)."},"debits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"matched":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unmatched":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["total","debits","matched","unmatched"],"additionalProperties":false},"balances":{"description":"Only on GET /bank-statements/{id}. Derived from the running balances on the statement; null when the statement shows none or they do not add up.","type":"object","properties":{"opening":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"closing":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]}},"required":["opening","closing"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"processed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["object","id","file_name","mime_type","source","file_size","status","error_message","bank_name","account_number_last4","currency","period_start","period_end","transactions","created_at","processed_at","completed_at"],"additionalProperties":false},"BankStatementList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/BankStatement"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"UploadBankStatementFromUrl":{"type":"object","properties":{"file_url":{"type":"string","maxLength":2048,"format":"uri","description":"Public https URL of the statement file (PDF, CSV, TXT, or a CBI, CAMT.053 XML or MT940 bank file; up to 50 MB). getbeel downloads it once; redirects are not followed."},"file_name":{"description":"File name with extension (default: the last part of the URL)","type":"string","minLength":1,"maxLength":255},"currency":{"description":"Account currency (default EUR)","type":"string","pattern":"^[A-Za-z]{3}$"}},"required":["file_url"],"additionalProperties":false},"BankTransaction":{"type":"object","properties":{"object":{"type":"string","const":"bank_transaction"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"statement_id":{"type":"string"},"date":{"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"]},"value_date":{"anyOf":[{"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"]},{"type":"null"}]},"description":{"type":"string"},"reference":{"type":["string","null"]},"counterparty":{"type":"object","properties":{"name":{"type":["string","null"]},"iban":{"type":["string","null"]}},"required":["name","iban"],"additionalProperties":false},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Signed: negative for money out, positive for money in","examples":["-122.00"]},"balance_after":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"currency":{"type":"string"},"type":{"type":"string","description":"debit, credit, transfer, fee, interest or other"},"reconciliation":{"anyOf":[{"type":"object","properties":{"match_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"state":{"type":"string","enum":["to_confirm","reconciled","missing_invoice","no_invoice_needed","rejected"],"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"},"invoice_id":{"type":["string","null"]}},"required":["match_id","state","invoice_id"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","statement_id","date","value_date","description","reference","counterparty","amount","balance_after","currency","type","reconciliation","created_at"],"additionalProperties":false},"BankTransactionList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/BankTransaction"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"Reconciliation":{"type":"object","properties":{"object":{"type":"string","const":"reconciliation"},"id":{"type":"string","description":"Same id as the bank statement: one statement has one reconciliation"},"statement_id":{"type":"string"},"status":{"type":"string","enum":["pending","processing","parsed","matching","review","completed","failed"],"description":"The statement status: review means the AI matching finished and the matches can be reviewed"},"error_message":{"type":["string","null"]},"period_start":{"anyOf":[{"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"]},{"type":"null"}]},"period_end":{"anyOf":[{"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"]},{"type":"null"}]},"summary":{"type":"object","properties":{"transactions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"to_confirm":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reconciled":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"missing_invoice":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"no_invoice_needed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rejected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["transactions","to_confirm","reconciled","missing_invoice","no_invoice_needed","rejected"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"processed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["object","id","statement_id","status","error_message","period_start","period_end","summary","created_at","processed_at"],"additionalProperties":false},"CreateReconciliationRequest":{"type":"object","properties":{"statement_id":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-]+$","description":"Bank statement to reconcile again (status review, completed or failed)"}},"required":["statement_id"],"additionalProperties":false},"ReconciliationMatch":{"type":"object","properties":{"object":{"type":"string","const":"reconciliation_match"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reconciliation_id":{"type":"string"},"match_type":{"type":"string","enum":["exact","fuzzy","manual","unmatched"],"description":"exact and fuzzy: found by the AI (fuzzy needs a closer look); manual: linked by a person; unmatched: no invoice found"},"state":{"type":"string","enum":["to_confirm","reconciled","missing_invoice","no_invoice_needed","rejected"],"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"},"review_status":{"type":"string","enum":["pending","approved","rejected","modified"]},"confidence":{"type":"string","description":"AI confidence from 0.00 to 1.00","examples":["0.95"]},"reasons":{"type":"array","items":{"type":"string"}},"amount_difference":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"transaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"date":{"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"]},"description":{"type":"string"},"counterparty_name":{"type":["string","null"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"currency":{"type":"string"}},"required":["id","date","description","counterparty_name","amount","currency"],"additionalProperties":false},"invoice":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"vendor_name":{"type":"string"},"invoice_number":{"type":["string","null"]},"invoice_date":{"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"]},"amount_total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"currency":{"type":"string"}},"required":["id","vendor_name","invoice_number","invoice_date","amount_total","currency"],"additionalProperties":false},{"type":"null"}],"description":"The received (supplier) invoice matched"},"reviewed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["object","id","reconciliation_id","match_type","state","review_status","confidence","reasons","amount_difference","transaction","invoice","reviewed_at"],"additionalProperties":false},"ReconciliationMatchList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ReconciliationMatch"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateMatchRequest":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Bank transaction of this reconciliation"},"invoice_id":{"type":"string","minLength":1,"maxLength":100,"description":"Received invoice to link (GET /received-invoices)"}},"required":["transaction_id","invoice_id"],"additionalProperties":false},"Connection":{"type":"object","properties":{"object":{"type":"string","const":"connection"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["email","stripe"]},"provider":{"type":"string","enum":["gmail","outlook","imap","forwarding","stripe"]},"name":{"description":"Mailbox address, forwarding address or Stripe business name","type":["string","null"]},"active":{"type":"boolean"},"health":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","reconnect_required","error","unknown"],"description":"reconnect_required: open POST /connections/email again for this mailbox"},"error_code":{"type":["string","null"]},"checked_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["status","error_code","checked_at"],"additionalProperties":false},"last_sync_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"auto_send_sdi":{"description":"Stripe only: synced invoices are sent to SDI automatically","type":["boolean","null"]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","type","provider","name","active","health","last_sync_at","auto_send_sdi","created_at"],"additionalProperties":false},"ConnectionList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateEmailConnectionRequest":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["gmail","outlook"],"description":"Returns a link: the user opens it, signs in to getbeel if needed, approves access and lands back in the app"}},"required":["provider"],"additionalProperties":false},{"type":"object","properties":{"provider":{"type":"string","const":"imap"},"email":{"type":"string","maxLength":320,"examples":["fatture@example.it"]},"password":{"type":"string","minLength":1,"maxLength":1024,"description":"App password; stored encrypted, never returned"},"host":{"type":"string","maxLength":253,"examples":["imap.example.it"]},"port":{"default":993,"description":"Implicit TLS only","type":"number","const":993},"display_name":{"type":"string","maxLength":255}},"required":["provider","email","password","host","port"],"additionalProperties":false}]},"ConnectionLink":{"type":"object","properties":{"object":{"type":"string","const":"connection_link"},"provider":{"type":"string","enum":["gmail","outlook","stripe"]},"url":{"type":"string","format":"uri","description":"Open in a browser signed in to getbeel as a member of this team (it asks to sign in otherwise). After approving, the user lands back in getbeel."}},"required":["object","provider","url"],"additionalProperties":false},"CreateEmailConnectionResponse":{"anyOf":[{"$ref":"#/components/schemas/ConnectionLink"},{"$ref":"#/components/schemas/Connection"}]},"ScanMailboxRequest":{"type":"object","properties":{"from":{"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])))$","description":"First day (YYYY-MM-DD)"},"to":{"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])))$","description":"Last day (YYYY-MM-DD)"}},"required":["from","to"],"additionalProperties":false},"MailboxScan":{"type":"object","properties":{"object":{"type":"string","const":"mailbox_scan"},"id":{"type":"string"},"connection_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","const":"pending"},"scan_type":{"type":"string","enum":["manual","full","daily"]},"from":{"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"]},"to":{"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"]}},"required":["object","id","connection_id","status","scan_type","from","to"],"additionalProperties":false},"ForwardingAddress":{"type":"object","properties":{"object":{"type":"string","const":"forwarding_address"},"address":{"description":"Forward supplier invoices here. null until it is set up in the app (Settings → Email, needs the email routing add-on).","type":["string","null"]},"connection_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"active":{"type":"boolean"}},"required":["object","address","connection_id","active"],"additionalProperties":false},"StripeSyncRequest":{"type":"object","properties":{"from":{"description":"First day (default: 30 days ago)","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])))$"},"to":{"description":"Last day (default: today)","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])))$"}},"additionalProperties":false},"StripeSync":{"type":"object","properties":{"object":{"type":"string","const":"stripe_sync"},"id":{"type":"string"},"status":{"type":"string","const":"pending"},"from":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"to":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"auto_send_sdi":{"type":"boolean","description":"When true the synced invoices are also sent to SDI (connection setting in the app)"}},"required":["object","id","status","from","to","auto_send_sdi"],"additionalProperties":false},"BankWebhookEvent":{"type":"object","properties":{"id":{"type":"string","examples":["evt_8a1f…"]},"object":{"type":"string","const":"event"},"type":{"type":"string","enum":["bank_statement.parsed","reconciliation.completed","received_invoice.created"]},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Unix seconds"},"livemode":{"type":"boolean","const":true,"description":"Always true: bank and collection data is real"},"data":{"type":"object","properties":{"object":{"anyOf":[{"$ref":"#/components/schemas/BankStatement"},{"$ref":"#/components/schemas/Reconciliation"},{"$ref":"#/components/schemas/ReceivedInvoice"}]}},"required":["object"],"additionalProperties":false}},"required":["id","object","type","created","livemode","data"],"additionalProperties":false},"UploadReceivedInvoiceRequest":{"type":"object","properties":{"file_url":{"description":"Public https URL of the file (no redirects)","type":"string","maxLength":2048,"format":"uri"},"file_base64":{"description":"The file, base64-encoded (small files)","type":"string","maxLength":69905071},"file_name":{"description":"File name, e.g. fattura-rossi.pdf (required with file_base64)","type":"string","minLength":1,"maxLength":255}},"additionalProperties":false},"ReceivedInvoiceUpload":{"type":"object","properties":{"object":{"type":"string","const":"received_invoice_upload"},"id":{"type":"string","pattern":"^scan_\\d+_[a-z0-9]+$","description":"Upload id (scan_…), from POST /received-invoices/uploads","examples":["scan_1794408453000_k3j9x2a"]},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"pending and processing: the AI is reading the file; completed: the invoice is in GET /received-invoices (status pending_review); failed: error says why"},"files":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"processed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Files that were not an invoice or a duplicate"},"error":{"type":["string","null"]},"error_code":{"anyOf":[{"type":"string","enum":["ai_out_of_credits","ai_unavailable"]},{"type":"null"}],"description":"Why the AI did not read the file: ai_out_of_credits (the AI provider has no credits) or ai_unavailable (it did not answer). Nothing was saved and no invoice credit was used: upload the file again later. null otherwise."},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"completed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["object","id","status","files","processed","skipped","error","error_code","created_at","completed_at"],"additionalProperties":false},"Usage":{"type":"object","properties":{"object":{"type":"string","const":"usage"},"account_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The account the request acts on (the key's, or the Getbeel-Company)"},"billed_to":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The account that pays: the parent for a client company, else account_id"},"period":{"type":"string","examples":["2026-10"]},"plan":{"type":"string","enum":["rate_card","sdi_addon","none"],"description":"rate_card: pay per live SDI transaction, sent and received priced separately (new accounts). sdi_addon: a fixed monthly SDI tier (existing customers). none: sandbox only; live sends answer 402 until a plan is picked in Settings → Usage & billing"},"rate_card_available":{"type":"boolean","description":"No plan yet, but the pay-per-use rate card (with its free tier) can be picked"},"sdi_transactions":{"type":"object","properties":{"sent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sent","received","total"],"additionalProperties":false,"description":"Live SDI transactions this month: sent (invoices and self-invoices sent to SDI) and received (invoices received from SDI), one per document. The sandbox and documents collected from email are not counted. On a client company: its own only"},"free_allowance":{"anyOf":[{"type":"object","properties":{"included":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["included","used","remaining"],"additionalProperties":false},{"type":"null"}],"description":"Free live SDI sends a month on the rate card; received invoices have no free allowance (null otherwise and on client companies)"},"estimated_amount":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"Rate card cost of the month so far (sent, received and email extraction), ex VAT (null without the rate card and on client companies)"},"email_extractions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Documents the mailbox scan extracted and saved this month at the metered email price (rate card accounts without a plan; plan accounts use invoice credits)"},"estimated_amounts":{"anyOf":[{"type":"object","properties":{"sent":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"received":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"email_extraction":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["sent","received","email_extraction","total"],"additionalProperties":false},{"type":"null"}],"description":"The estimated amount split: sent (graduated tiers), received (flat price) and email extraction (flat price), ex VAT (null like estimated_amount)"},"currency":{"type":"string","const":"EUR"},"rate_card":{"type":"array","items":{"type":"object","properties":{"up_to":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"unit_amount":{"type":"string","pattern":"^\\d+\\.\\d{3}$","description":"EUR per transaction","examples":["0.200","0.140"]}},"required":["up_to","unit_amount"],"additionalProperties":false},"description":"Graduated tiers per SENT transaction and month on the card this account pays (existing rate cards keep their price); up_to is inclusive, null = no limit"},"received_unit_amount":{"type":"string","pattern":"^\\d+\\.\\d{3}$","description":"Flat price per invoice RECEIVED from SDI on the card this account pays (no free allowance, no tiers)","examples":["0.180"]},"email_extraction_unit_amount":{"type":"string","pattern":"^\\d+\\.\\d{3}$","description":"Flat price per document extracted by the mailbox scan on the rate card (no free allowance)","examples":["0.060"]},"quota":{"anyOf":[{"type":"object","properties":{"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["limit","used","remaining"],"additionalProperties":false},{"type":"null"}],"description":"Fixed SDI add-on tier: sends allowed and used this month (shared by the parent and its client companies)"},"companies":{"type":"array","items":{"type":"object","properties":{"sent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"company_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["sent","received","total","company_id"],"additionalProperties":false},"description":"Per client company billed to this account (empty on a client company)"}},"required":["object","account_id","billed_to","period","plan","rate_card_available","sdi_transactions","free_allowance","estimated_amount","email_extractions","estimated_amounts","currency","rate_card","received_unit_amount","email_extraction_unit_amount","quota","companies"],"additionalProperties":false},"SendInvoiceEmailRequest":{"type":"object","properties":{"to":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"description":"Recipients; default: the customer's email on the invoice"},"cc":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"description":"Email addresses copied on the email, up to 10. Ignored with a test key (the email goes only to the team owner).","examples":[["amministrazione@example.com"]]},"language":{"default":"it","type":"string","enum":["it","en"]},"message":{"type":"string","maxLength":2000,"description":"A note shown above the invoice summary"},"attach_xml":{"default":false,"description":"Also attach the FatturaPA XML","type":"boolean"}},"required":["language","attach_xml"],"additionalProperties":false},"SendReminderRequest":{"type":"object","properties":{"to":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"description":"Recipients; default: the customer's email on the invoice"},"cc":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"description":"Email addresses copied on the email, up to 10. Ignored with a test key (the email goes only to the team owner).","examples":[["amministrazione@example.com"]]},"language":{"default":"it","type":"string","enum":["it","en"]},"message":{"type":"string","maxLength":2000,"description":"A note shown above the invoice summary"}},"required":["language"],"additionalProperties":false},"InvoiceEmail":{"type":"object","properties":{"object":{"type":"string","const":"invoice_email"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"invoice_id":{"type":"string"},"kind":{"type":"string","enum":["invoice","reminder"]},"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"sent_to":{"type":"array","items":{"type":"string"},"description":"Where it actually went: `to` for live invoices; for sandbox invoices (test keys) only the team owner, never the customer"},"sandbox":{"type":"boolean"},"language":{"type":"string","enum":["it","en"]},"status":{"type":"string","enum":["sending","sent","failed"]},"reminder_day":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Automatic reminders: days after the due date"},"provider_message_id":{"type":["string","null"]},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","invoice_id","kind","to","cc","sent_to","sandbox","language","status","reminder_day","provider_message_id","error","created_at"],"additionalProperties":false},"InvoiceEmailList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceEmail"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"RecordPaymentRequest":{"type":"object","properties":{"amount":{"description":"Decimal string; default: everything still due (marks the invoice paid)","examples":["122.00"]},"date":{"description":"Payment date (YYYY-MM-DD); default today","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])))$"},"method":{"default":"bank_transfer","type":"string","enum":["bank_transfer","card","cash","stripe","other"]},"note":{"description":"Internal note stored with the payment, up to 500 characters (not sent to the customer)","type":"string","maxLength":500}},"required":["method"],"additionalProperties":false},"InvoicePayment":{"type":"object","properties":{"object":{"type":"string","const":"invoice_payment"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"invoice_id":{"type":"string"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"date":{"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"]},"method":{"type":"string","enum":["bank_transfer","card","cash","stripe","other"]},"source":{"type":"string","enum":["app","api","stripe"]},"note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","invoice_id","amount","date","method","source","note","created_at"],"additionalProperties":false},"InvoicePaymentList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoicePayment"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"RecordPaymentResponse":{"type":"object","properties":{"payment":{"$ref":"#/components/schemas/InvoicePayment"},"invoice":{"$ref":"#/components/schemas/Invoice"}},"required":["payment","invoice"],"additionalProperties":false},"PaymentLink":{"type":"object","properties":{"object":{"type":"string","const":"payment_link"},"id":{"type":"string","examples":["plink_1Q…"]},"invoice_id":{"type":"string"},"url":{"type":"string"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"currency":{"type":"string"},"created":{"type":"boolean","description":"false when the invoice already had a link (returned as is)"}},"required":["object","id","invoice_id","url","amount","currency","created"],"additionalProperties":false},"RecurringInvoice":{"type":"object","properties":{"object":{"type":"string","const":"recurring_invoice"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"invoice_id":{"type":"string","description":"The template invoice"},"interval":{"type":"string","enum":["monthly","quarterly","yearly"]},"next_date":{"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"]},"active":{"type":"boolean"},"auto_send":{"type":"boolean","description":"Send each new invoice to SDI (sandbox for test keys)"},"livemode":{"type":"boolean"},"last_invoice_id":{"type":["string","null"]},"last_run_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"last_error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","invoice_id","interval","next_date","active","auto_send","livemode","last_invoice_id","last_run_at","last_error","created_at","updated_at"],"additionalProperties":false},"RecurringInvoiceList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringInvoice"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateRecurringInvoiceRequest":{"type":"object","properties":{"invoice_id":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9_-]+$","description":"Invoice to copy (fe_…)","examples":["fe_3f1c…"]},"interval":{"type":"string","enum":["monthly","quarterly","yearly"]},"start_date":{"description":"Date of the first new invoice (today or later); default: the first date after today in the series invoice_date + n × interval","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])))$"},"auto_send":{"default":false,"type":"boolean"}},"required":["invoice_id","interval","auto_send"],"additionalProperties":false},"UpdateRecurringInvoiceRequest":{"type":"object","properties":{"interval":{"type":"string","enum":["monthly","quarterly","yearly"]},"next_date":{"description":"Date of the next invoice (YYYY-MM-DD), today or later","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])))$"},"auto_send":{"type":"boolean"},"active":{"type":"boolean"}},"additionalProperties":false},"DeletedRecurringInvoice":{"type":"object","properties":{"object":{"type":"string","const":"recurring_invoice"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"deleted":{"type":"boolean","const":true}},"required":["object","id","deleted"],"additionalProperties":false},"CollectionWebhookEvent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"event"},"type":{"type":"string","enum":["invoice.emailed","invoice.email_failed","invoice.paid","invoice.overdue"]},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Unix seconds"},"livemode":{"type":"boolean"},"data":{"type":"object","properties":{"object":{"anyOf":[{"$ref":"#/components/schemas/Invoice"},{"$ref":"#/components/schemas/InvoiceEmail"}],"description":"invoice.paid and invoice.overdue: the Invoice; invoice.emailed and invoice.email_failed: the InvoiceEmail"}},"required":["object"],"additionalProperties":false}},"required":["id","object","type","created","livemode","data"],"additionalProperties":false},"ProfitAndLossReport":{"type":"object","properties":{"revenue":{"type":"object","properties":{"sales":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"credit_notes":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Negative","examples":["122.00"]},"total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sales","credit_notes","total","documents"],"additionalProperties":false},"costs":{"type":"object","properties":{"purchases":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"credit_notes":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Negative","examples":["122.00"]},"total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"by_category":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"label":{"type":["string","null"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["category","label","amount","documents"],"additionalProperties":false}}},"required":["purchases","credit_notes","total","documents","by_category"],"additionalProperties":false},"result":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"revenue.total − costs.total","examples":["122.00"]},"by_month":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","examples":["2026-10"]},"revenue":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"costs":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"result":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["month","revenue","costs","result"],"additionalProperties":false}},"not_included":{"type":"object","properties":{"pending_sdi":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["documents","amount"],"additionalProperties":false},"unreviewed_purchases":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["documents","amount"],"additionalProperties":false},"asset_sales":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["documents","amount"],"additionalProperties":false,"description":"TD26: sales of fixed assets (price, not gain)"},"foreign_currency":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["documents"],"additionalProperties":false}},"required":["pending_sdi","unreviewed_purchases","asset_sales","foreign_currency"],"additionalProperties":false}},"required":["revenue","costs","result","by_month","not_included"],"additionalProperties":false},"CashFlowReport":{"type":"object","properties":{"inflows":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"outflows":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"net":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"movements":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"outflows_by_category":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","description":"Category of the supplier invoice the movement was matched to, or unmatched"},"label":{"type":["string","null"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"movements":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["category","label","amount","movements"],"additionalProperties":false}},"by_month":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"inflows":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"outflows":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"net":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["month","inflows","outflows","net"],"additionalProperties":false}},"invoice_payments_recorded":{"type":"object","properties":{"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"payments":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["amount","payments"],"additionalProperties":false,"description":"Payments recorded on issued invoices in the period (app, Stripe, API). Shown apart, not added to the bank figures"},"not_included":{"type":"object","properties":{"foreign_currency":{"type":"object","properties":{"movements":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["movements"],"additionalProperties":false}},"required":["foreign_currency"],"additionalProperties":false}},"required":["inflows","outflows","net","movements","outflows_by_category","by_month","invoice_payments_recorded","not_included"],"additionalProperties":false},"AgingReport":{"type":"object","properties":{"as_of":{"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"]},"total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"overdue":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"buckets":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","enum":["not_due","overdue_1_30","overdue_31_60","overdue_61_90","overdue_over_90"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["bucket","amount","documents"],"additionalProperties":false}},"customers":{"type":"array","items":{"type":"object","properties":{"customer_name":{"type":"string"},"customer_vat":{"type":["string","null"]},"total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"overdue":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["customer_name","customer_vat","total","overdue","documents"],"additionalProperties":false}},"invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"date":{"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"]},"due_date":{"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"]},"due_date_assumed":{"type":"boolean","description":"No due date on the invoice: 30 days after its date (art. 4, c. 2, lett. a, D.Lgs. 231/2002)"},"customer_name":{"type":"string"},"customer_vat":{"type":["string","null"]},"outstanding":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"days_overdue":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bucket":{"type":"string","enum":["not_due","overdue_1_30","overdue_31_60","overdue_61_90","overdue_over_90"]}},"required":["id","number","date","due_date","due_date_assumed","customer_name","customer_vat","outstanding","days_overdue","bucket"],"additionalProperties":false}},"has_more":{"type":"boolean"},"not_included":{"type":"object","properties":{"foreign_currency":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["documents"],"additionalProperties":false}},"required":["foreign_currency"],"additionalProperties":false}},"required":["as_of","total","overdue","documents","buckets","customers","invoices","has_more","not_included"],"additionalProperties":false},"Report":{"type":"object","properties":{"object":{"type":"string","const":"report"},"type":{"type":"string","enum":["profit_and_loss","cash_flow","aging"]},"period":{"type":["string","null"]},"start":{"anyOf":[{"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"]},{"type":"null"}]},"end":{"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"]},"currency":{"type":"string","const":"EUR"},"management_figures":{"type":"boolean","const":true},"reliable":{"type":"boolean","const":false},"note":{"type":"string"},"profit_and_loss":{"$ref":"#/components/schemas/ProfitAndLossReport"},"cash_flow":{"$ref":"#/components/schemas/CashFlowReport"},"aging":{"$ref":"#/components/schemas/AgingReport"}},"required":["object","type","period","start","end","currency","management_figures","reliable","note"],"additionalProperties":false},"TaxDeadline":{"type":"object","properties":{"id":{"type":"string","examples":["bollo:2026-Q3"]},"object":{"type":"string","const":"tax_deadline"},"kind":{"type":"string","enum":["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"]},"title":{"type":"string"},"period":{"type":"string","examples":["2026-Q3","2026-10","2026"]},"due_date":{"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"],"description":"The real deadline: Saturdays, Sundays and holidays move to the next working day; 1–20 August to 20 August. Exception: oss_return (EU OSS) never moves; when it falls on a non-working day needs_review is true."},"nominal_due_date":{"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"]},"days_left":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"overdue":{"type":"boolean"},"action":{"type":"string","enum":["payment","filing"]},"tax_codes":{"type":"array","items":{"type":"string"},"description":"F24 codici tributo"},"amount":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"Known amount (bollo, prepared filings); null otherwise"},"amount_status":{"type":"string","enum":["final","provisional","unknown"],"description":"final: prepared (a filing) or the period is over; provisional: still changing, or computed now from the VAT registers for a VAT payment without a saved liquidazione; unknown: not computed"},"status":{"type":"string","enum":["to_prepare","not_due","ready","needs_review","changes_requested","approved","skipped","filed","paid"],"description":"to_prepare: nothing prepared yet; not_due: nothing to pay or file; then the filing status (ready, needs_review, changes_requested, approved, skipped, filed, paid)"},"filing_id":{"type":["string","null"]},"can_prepare":{"type":"boolean"},"filing_type":{"anyOf":[{"type":"string","enum":["bollo","withholdings","vat_payment","lipe","vat_return","redditi_pf"]},{"type":"null"}]},"needs_review":{"type":"boolean","description":"Check it (\"da verificare\"): the rule may not fit this company (special VAT regime), or an OSS deadline falls on a non-working day and is kept"},"note":{"description":"Something to know when paying, e.g. the 1% interest on quarterly VAT","type":["string","null"]},"note_key":{"anyOf":[{"type":"string","enum":["quarterly_interest","oss","income_tax_balance","income_tax_advance","income_tax_advance_isa","financial_statements","inps_fixed","inps_balance","inps_advance","inps_reduction_request","pf_tax_balance","pf_tax_balance_isa","pf_tax_advance"]},{"type":"null"}],"description":"Which note it is (quarterly_interest, oss), to show your own text instead of note"},"source":{"type":"string","description":"Legal source of the deadline"},"extension":{"anyOf":[{"type":"object","properties":{"source_title":{"type":"string"},"source_url":{"type":"string"}},"required":["source_title","source_url"],"additionalProperties":false},{"type":"null"}],"description":"Set when a published extension (proroga) moved due_date: the official source"},"applies_because":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","examples":["vat_quarterly"],"description":"issues_e_invoices, withholding_agent, has_employees, vat_monthly, vat_quarterly, vat_payer (params.regime); more kinds add their own"},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}}},"required":["key"],"additionalProperties":false},"description":"Why it applies to this company (from the tax profile). Deadlines that do not apply are not listed."},"review_key":{"anyOf":[{"type":"string","enum":["in_liquidation"]},{"type":"null"}],"description":"Why needs_review is set beyond the rule itself: in_liquidation (check the deadlines of the liquidation periods with the liquidator)"}},"required":["id","object","kind","title","period","due_date","nominal_due_date","days_left","overdue","action","tax_codes","amount","amount_status","status","filing_id","can_prepare","filing_type","needs_review","note","note_key","source","extension","applies_because","review_key"],"additionalProperties":false},"TaxCalendar":{"type":"object","properties":{"object":{"type":"string","const":"tax_calendar"},"applicable":{"type":"boolean","description":"False when the company is not Italian"},"missing_settings":{"type":"array","items":{"type":"string","enum":["vat_periodicity","withholding_agent","income_tax"]},"description":"Set these in the app (Taxes → Settings; income_tax: Taxes → Tax estimate, whether the company pays IRES and applies ISA); deadlines that depend on them are left out until then"},"settings":{"type":"object","properties":{"vat_periodicity":{"anyOf":[{"type":"string","enum":["monthly","quarterly"]},{"type":"null"}]},"withholding_agent":{"type":["boolean","null"]},"oss_from":{"anyOf":[{"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"]},{"type":"null"}]},"oss_until":{"anyOf":[{"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"]},{"type":"null"}]},"income_tax":{"description":"Per tax year (e.g. \"2026\"), from Taxes → Tax estimate: the entity and whether it applies ISA. null: never answered (see missing_settings).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"entity":{"type":"string","enum":["company","forfettario","irpef","minimi","other"]},"isa":{"type":"boolean"}},"required":["entity","isa"],"additionalProperties":false}},{"type":"null"}]}},"required":["vat_periodicity","withholding_agent"],"additionalProperties":false},"regime_fiscale":{"type":["string","null"]},"from":{"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"]},"to":{"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"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxDeadline"}}},"required":["object","applicable","missing_settings","settings","regime_fiscale","from","to","data"],"additionalProperties":false},"CreateFilingRequest":{"type":"object","properties":{"type":{"type":"string","enum":["bollo","withholdings","vat_payment","lipe","vat_return","redditi_pf"],"description":"bollo: stamp duty on e-invoices for a closed quarter (computed from your issued invoices). withholdings: ritenute on professionals’ fees paid in a month (codice tributo 1040), from the fees recorded in /withholdings, or the amount you send. vat_payment: the periodic VAT liquidazione of a closed month or quarter (matching the VAT periodicity), computed from the VAT registers and saved; the F24 (6001–6012, 6031–6033). lipe: the Comunicazione liquidazioni periodiche IVA of a closed quarter, from the saved liquidazioni (XML checked against the official XSD; check, sign and send it yourself). vat_return: the data sheet of the annual VAT return (Dichiarazione IVA) of a closed year: quadri VE, VF, VJ, VL, VX from the VAT registers and the saved liquidazioni, with the points to check (not the telematic file). redditi_pf: the data sheet of the Redditi PF return of a persona fisica for a closed year: the tax estimate (Tasse → Stima imposte: forfettario, irpef or minimi) placed on the quadri LM, RE, RN, RV and RR, with the saldo/acconti F24 codes (not the telematic file)"},"period":{"description":"bollo, lipe: a quarter (2026-Q3); withholdings: a month (2026-10); vat_payment: a month or a quarter, as the company settles VAT; vat_return, redditi_pf: the tax year (2026)","type":"string","pattern":"^\\d{4}(-(Q[1-4]|0[1-9]|1[0-2]))?$","examples":["2026-Q3","2026-10","2026"]},"amount":{"description":"withholdings only: the total withheld, e.g. \"200.00\", for fees not recorded in getbeel. Omit to add up the recorded fees paid in the month","type":"string","pattern":"^-?\\d+\\.\\d{2}$","examples":["122.00"]},"previous_credit":{"description":"vat_payment: VAT credit of the previous period (LIPE VP8), only when that period was not saved in getbeel","anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"previous_debt":{"description":"vat_payment: VAT up to €100 not paid in the previous period (VP7), only when that period was not saved in getbeel","anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"annual_credit_used":{"description":"vat_payment: credit of the previous year used in this liquidazione (VP9)","anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"advance":{"description":"vat_payment, December or Q4 only: the acconto IVA due (VP13, at least 103.29)","anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"advance_method":{"description":"Acconto method: 1 storico, 2 previsionale, 3 analitico, 4 special sectors","anyOf":[{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":4}]},{"type":"null"}]},"declarant_fiscal_code":{"description":"lipe: codice fiscale of the person who signs; required for companies","anyOf":[{"type":"string","pattern":"^[A-Za-z0-9]{16}$"},{"type":"null"}]},"declarant_role":{"description":"lipe: codice carica of the signer (1 = legal representative, default)","anyOf":[{"type":"integer","minimum":1,"maximum":15},{"type":"null"}]},"previous_year_credit":{"description":"vat_return: the VAT credit of the previous year's return still available (VL8 minus VL9; it goes in VL25)","anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]}},"required":["type","period"],"additionalProperties":false},"LipeValues":{"type":"object","properties":{"operations_active":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP2 operazioni attive","examples":["122.00"]},"operations_passive":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP3 operazioni passive","examples":["122.00"]},"vat_due":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP4 IVA esigibile","examples":["122.00"]},"vat_deducted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP5 IVA detratta","examples":["122.00"]},"vat_balance_debit":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP6 col. 1 IVA dovuta","examples":["122.00"]},"vat_balance_credit":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP6 col. 2 IVA a credito","examples":["122.00"]},"previous_debt":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP7 debito del periodo precedente (up to €100, carried)","examples":["122.00"]},"previous_credit":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP8 credito del periodo precedente","examples":["122.00"]},"annual_credit":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP9 credito anno precedente","examples":["122.00"]},"car_payments":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP10, not known to getbeel (always 0.00)","examples":["122.00"]},"tax_credits":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP11 crediti d’imposta, not known to getbeel (0.00)","examples":["122.00"]},"interest":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP12 1% interest (quarterly Q1–Q3)","examples":["122.00"]},"advance":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP13 acconto (December or Q4)","examples":["122.00"]},"advance_method":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"amount_due":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"VP14 col. 1 importo da versare (null for Q4 quarterly)"},"amount_credit":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"VP14 col. 2 importo a credito (null for Q4 quarterly)"}},"required":["operations_active","operations_passive","vat_due","vat_deducted","vat_balance_debit","vat_balance_credit","previous_debt","previous_credit","annual_credit","car_payments","tax_credits","interest","advance","advance_method","amount_due","amount_credit"],"additionalProperties":false},"Filing":{"type":"object","properties":{"id":{"type":"string","examples":["fil_3f2a…"]},"object":{"type":"string","const":"filing"},"type":{"type":"string","enum":["bollo","withholdings","vat_payment","lipe","vat_return","redditi_pf"]},"period":{"type":"string"},"status":{"type":"string","enum":["ready","needs_review","changes_requested","approved","skipped","filed","paid"],"description":"ready: prepared, no review asked; needs_review: waiting for the commercialista; changes_requested: sent back (see the history); approved: visto bueno (approved_at, approved_by); skipped: not to be done (skip_reason); filed: return sent (receipt or filed_reference); paid: F24 paid (receipt)"},"approved_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"approved_by":{"description":"User id of who approved it","type":["string","null"]},"skip_reason":{"type":["string","null"]},"filed_reference":{"description":"Protocol number of a filed return (evidence without a file)","type":["string","null"]},"extension":{"anyOf":[{"type":"object","properties":{"source_title":{"type":"string"},"source_url":{"type":"string"}},"required":["source_title","source_url"],"additionalProperties":false},{"type":"null"}],"description":"Set when a published extension (proroga) gave the due date: the official source"},"file_spec":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","examples":["lipe:IVP18"]},"file":{"type":"string","enum":["lipe_xml","vat_return_sheet","redditi_pf_sheet","f24_reminder"]},"name":{"type":"string"},"version":{"type":"string","examples":["IVP18 (schema Versione 1.0)"]},"approved_by":{"type":"string","examples":["Provv. AdE prot. 125654 of 14 March 2024"]},"source_url":{"type":"string"},"official_format":{"type":"boolean","description":"true: the file is in the official format (the LIPE XML, valid against the XSD); false: a data sheet or reminder that follows the model, not the file sent to the Agenzia"},"tax_year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The tax year the model is for (returns); null: any"},"other_tax_year":{"type":"boolean","description":"A return on the model of another tax year than the filing's (tax_year): check the rows against that year's model"},"provisional":{"type":"boolean","description":"A return on the model of an earlier tax year because the new model is not published yet: check against it when it is"}},"required":["id","file","name","version","approved_by","source_url","official_format","tax_year","other_tax_year","provisional"],"additionalProperties":false},{"type":"null"}],"description":"The official specification the filing file follows, stored when the filing was prepared (also in the Getbeel-File-Spec header of the file). null: no file (skipped before it was prepared)"},"due_date":{"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"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"currency":{"type":"string","const":"EUR"},"f24_lines":{"type":"array","items":{"type":"object","properties":{"section":{"type":"string","const":"erario"},"tax_code":{"type":"string","examples":["2523","1040"]},"reference_month":{"description":"\"Rateazione/regione/prov./mese rif.\" (two digits) or null","type":["string","null"]},"reference_year":{"type":"string","examples":["2026"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["section","tax_code","reference_month","reference_year","amount"],"additionalProperties":false}},"details":{"type":"object","properties":{"invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"date":{"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"]},"list":{"type":"string","enum":["A","B"],"description":"A: sent with bollo; B: bollo due but missing on the invoice (the AdE adds it; check it)"}},"required":["id","number","date","list"],"additionalProperties":false}},"pending_invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"date":{"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"]}},"required":["id","number","date"],"additionalProperties":false}},"invoices_without_bollo_flag":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bollo_threshold_confirmed":{"type":"boolean","description":"bollo: false when the threshold used for the quarter is not confirmed on its source (\"da verificare\"); the filing is then marked needs_review"},"deferral":{"anyOf":[{"type":"object","properties":{"pay_by":{"type":"string","enum":["september_30","november_30"]}},"required":["pay_by"],"additionalProperties":false},{"type":"null"}],"description":"Small Q1/Q2 bollo amounts may be paid later (art. 17 DL 124/2019)"},"settlement":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"lipe":{"$ref":"#/components/schemas/LipeValues"},"notes":{"type":"array","items":{"type":"string"}}},"required":["id","lipe","notes"],"additionalProperties":false},{"type":"null"}],"description":"vat_payment: the liquidazione behind the F24"},"lipe":{"anyOf":[{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quarter":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"declarant":{"anyOf":[{"type":"object","properties":{"fiscal_code":{"type":"string"},"role":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["fiscal_code","role"],"additionalProperties":false},{"type":"null"}]},"modules":{"type":"array","items":{"type":"object","properties":{"month":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"quarter":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"1–4, or 5 for Q4 of quarterly payers"},"lipe":{"$ref":"#/components/schemas/LipeValues"}},"required":["month","quarter","lipe"],"additionalProperties":false}}},"required":["year","quarter","declarant","modules"],"additionalProperties":false},{"type":"null"}],"description":"lipe: what the XML reports"},"vat_return":{"anyOf":[{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"model":{"type":"object","properties":{"name":{"type":"string","examples":["IVA 2026"]},"tax_year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"approved_by":{"type":"string"},"instructions_url":{"type":"string"},"technical_specs":{"type":"string"}},"required":["name","tax_year","approved_by","instructions_url","technical_specs"],"additionalProperties":false},"lines":{"type":"array","items":{"type":"object","properties":{"quadro":{"type":"string","enum":["VE","VF","VJ","VL","VX"]},"row":{"type":"string","examples":["VE23"]},"field":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string","description":"Field code as in the specifiche tecniche (quadro, rigo, campo)","examples":["VE023001"]},"label":{"type":"string"},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Whole euros, as filed"}},"required":["quadro","row","field","code","label","amount"],"additionalProperties":false}},"balance":{"type":"object","properties":{"to_pay":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"VX1, whole euros"},"credit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"VX2, whole euros"},"tax_code":{"examples":["6099"],"type":["string","null"]}},"required":["to_pay","credit","tax_code"],"additionalProperties":false},"volume_d_affari":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"VE50"},"periods":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"settlement_saved":{"type":"boolean"},"amount_to_pay":{"type":["number","null"]},"advance":{"type":["number","null"]},"paid":{"type":["number","null"]}},"required":["period","settlement_saved","amount_to_pay","advance","paid"],"additionalProperties":false}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"items":{"type":"array","items":{"type":"string"}},"taxable":{"type":"number"},"vat":{"type":"number"}},"required":["code","message","items","taxable","vat"],"additionalProperties":false}},"checks":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"ok":{"type":"boolean"}},"required":["rule","ok"],"additionalProperties":false}}},"required":["year","model","lines","balance","volume_d_affari","periods","issues","checks"],"additionalProperties":false,"description":"vat_return: the data sheet (model IVA 2026 until the 2027 one is published). Not the telematic file"},{"type":"null"}]},"redditi_pf":{"anyOf":[{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"entity":{"type":"string","enum":["forfettario","irpef","minimi"]},"model":{"type":"string","examples":["Redditi PF 2026"]},"lines":{"type":"array","items":{"type":"object","properties":{"quadro":{"type":"string","enum":["LM","RE","RG","RN","RV","RR"]},"rigo":{"description":"The rigo of the model (e.g. LM11); null: not one rigo (artigiani/commercianti INPS over RR2/RR3, an impresa in quadro RG): the amount is shown with its meaning","type":["string","null"]},"key":{"type":"string"},"label":{"type":"string"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Whole euros, as the model takes them","examples":["122.00"]}},"required":["quadro","rigo","key","label","amount"],"additionalProperties":false}},"payments":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Saldo and acconti with F24 codes, from the tax estimate"},"balance_to_pay":{"type":"number"},"warnings":{"type":"array","items":{"type":"string"}},"needs_review":{"type":"boolean","const":true}},"required":["year","entity","model","lines","payments","balance_to_pay","warnings","needs_review"],"additionalProperties":false,"description":"redditi_pf: the tax estimate on the Redditi PF lines (model 2026 until the 2027 one is published). Not the return and not the telematic file"},{"type":"null"}]},"withholdings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"recipient_name":{"type":"string"},"document_number":{"type":["string","null"]},"paid_on":{"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"]},"withheld_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["id","recipient_name","document_number","paid_on","withheld_amount"],"additionalProperties":false},"description":"withholdings: the recorded fees this F24 pays (empty when the amount was typed)"}},"required":["invoices","pending_invoices","invoices_without_bollo_flag","bollo_threshold_confirmed","deferral","settlement","lipe","vat_return","redditi_pf","withholdings"],"additionalProperties":false},"checks":{"type":"object","properties":{"xsd":{"anyOf":[{"type":"object","properties":{"schema":{"type":"string"},"valid":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"line":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["message","line"],"additionalProperties":false}}},"required":["schema","valid","issues"],"additionalProperties":false},{"type":"null"}],"description":"lipe: the file checked against the official IVP18 XSD when prepared"},"ade_control_software":{"type":"string","const":"not_run","description":"The AdE control software is a desktop program: run it yourself before sending"}},"required":["xsd","ade_control_software"],"additionalProperties":false,"description":"Checks getbeel ran on the file"},"needs_review":{"type":"boolean"},"receipt":{"anyOf":[{"type":"object","properties":{"uploaded_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["uploaded_at"],"additionalProperties":false},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"next_steps":{"type":"object","properties":{"file_url":{"type":"string","description":"The F24 reminder PDF, the LIPE XML or the VAT return data sheet (add ?format=xlsx or json)"},"deep_link":{"type":"object","properties":{"url":{"type":"string"},"label":{"type":"string"}},"required":["url","label"],"additionalProperties":false,"description":"The AdE page to open; the client signs in there"},"other_links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"label":{"type":"string"}},"required":["url","label"],"additionalProperties":false}},"copy_values":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["key","label","value"],"additionalProperties":false}},"drafts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["bank","accountant"]},"subject":{"type":"string"},"body":{"type":"string"}},"required":["id","subject","body"],"additionalProperties":false},"description":"Email drafts (Italian) to the bank or the commercialista. getbeel never sends them: the client reviews and sends."},"steps":{"type":"array","items":{"type":"string"}}},"required":["file_url","deep_link","other_links","copy_values","drafts","steps"],"additionalProperties":false}},"required":["id","object","type","period","status","approved_at","approved_by","skip_reason","filed_reference","extension","file_spec","due_date","amount","currency","f24_lines","details","checks","needs_review","receipt","completed_at","created_at","updated_at","next_steps"],"additionalProperties":false},"FilingList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Filing"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"SetFilingStatusRequest":{"type":"object","properties":{"status":{"type":"string","enum":["needs_review","changes_requested","approved","skipped","filed"],"description":"approved (visto bueno), changes_requested (reason required; the commercialista only), skipped (reason required), needs_review (back to review, or reopen a skipped filing), filed (a LIPE or VAT return, with reference)"},"reason":{"description":"Why: required for changes_requested and skipped","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"reference":{"description":"filed only: the protocol number of the sent return","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"expected_updated_at":{"description":"The filing's updated_at as you last read it. When set and the filing changed since (recomputed or reviewed by someone else), the call fails with 409 filing_changed, so an approval never applies to figures you did not see","anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["status"],"additionalProperties":false},"FilingReopened":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"filing"},"status":{"type":"string","const":"to_prepare","description":"The skipped filing was never prepared: it is removed and the deadline is to prepare again"},"deleted":{"type":"boolean","const":true}},"required":["id","object","status","deleted"],"additionalProperties":false},"FilingStatusResult":{"anyOf":[{"$ref":"#/components/schemas/Filing"},{"$ref":"#/components/schemas/FilingReopened"}],"description":"The filing after the change, or FilingReopened when a filing skipped before it was prepared is reopened"},"SkipFilingRequest":{"type":"object","properties":{"type":{"type":"string","enum":["bollo","withholdings","vat_payment","lipe","vat_return","redditi_pf"]},"period":{"type":"string","pattern":"^\\d{4}(-(Q[1-4]|0[1-9]|1[0-2]))?$","description":"The period of the deadline: a quarter (2026-Q3), a month (2026-10) or a year (2026, vat_return)"},"reason":{"type":"string","minLength":3,"maxLength":1000,"description":"Why it is not to be done (shown in the history)"}},"required":["type","period","reason"],"additionalProperties":false},"CommentFilingRequest":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4000,"description":"The comment, in plain text (1-4000 characters)"}},"required":["body"],"additionalProperties":false},"FilingEvent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"filing_event"},"kind":{"type":"string","enum":["comment","status"]},"from_status":{"type":["string","null"]},"to_status":{"type":["string","null"]},"body":{"description":"The comment, the reason, or the protocol number","type":["string","null"]},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key","system"]},"name":{"type":["string","null"]},"role":{"anyOf":[{"type":"string","enum":["accountant","team"]},{"type":"null"}]}},"required":["type","name","role"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","object","kind","from_status","to_status","body","actor","created_at"],"additionalProperties":false},"FilingEventList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/FilingEvent"}}},"required":["object","data"],"additionalProperties":false},"VatPosition":{"type":"object","properties":{"object":{"type":"string","const":"vat_position"},"period":{"type":"string"},"start":{"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"]},"end":{"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"]},"currency":{"type":"string","const":"EUR"},"no_vat_regime":{"type":"boolean"},"vat_periodicity":{"anyOf":[{"type":"string","enum":["monthly","quarterly"]},{"type":"null"}]},"sales_vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"sales_invoices":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"deferred_sales_vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"split_payment_invoices":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"purchase_vat_estimate":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"purchase_invoices":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"purchases_skipped_foreign_currency":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"balance_estimate":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Positive: VAT to pay; negative: credit. An estimate.","examples":["122.00"]},"reliable":{"type":"boolean","const":false},"note":{"type":"string"}},"required":["object","period","start","end","currency","no_vat_regime","vat_periodicity","sales_vat","sales_invoices","deferred_sales_vat","split_payment_invoices","purchase_vat_estimate","purchase_invoices","purchases_skipped_foreign_currency","balance_estimate","reliable","note"],"additionalProperties":false},"OssReturnDraft":{"type":"object","properties":{"object":{"type":"string","const":"oss_return_draft"},"period":{"type":"string","examples":["2026-Q3"]},"registered":{"type":"boolean","description":"Registered in the OSS union scheme (tax settings oss_from / oss_until) for some day of the quarter"},"registration":{"type":"object","properties":{"from":{"anyOf":[{"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"]},{"type":"null"}]},"until":{"anyOf":[{"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"]},{"type":"null"}]}},"required":["from","until"],"additionalProperties":false},"deadline":{"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"],"description":"Last day of the month after the quarter. Not moved for weekends or holidays: verify any extension (proroga)"},"reference":{"description":"The payment reference IT/IT{partita IVA}/Q{n}.{YYYY} (null without a valid partita IVA)","examples":["IT/IT01234567897/Q3.2026"],"type":["string","null"]},"currency":{"type":"string","const":"EUR"},"countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166 (GR for Greece)"},"rate":{"type":"number","description":"The State's standard rate on the invoice date, %"},"supply":{"type":"string","const":"services"},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Sum of the VAT of each line, rounded to the cent","examples":["122.00"]},"vat_country_level":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"The VAT computed once on the country's taxable amount, as the portal may do","examples":["122.00"]},"rounding_gap":{"type":"boolean","description":"vat and vat_country_level differ by more than €0.01: to check"},"invoices":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["country","rate","supply","taxable","vat","vat_country_level","rounding_gap","invoices"],"additionalProperties":false}},"corrections":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"country":{"type":"string"},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["period","country","vat"],"additionalProperties":false}},"balances":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["country","vat"],"additionalProperties":false}},"total_due":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VAT to pay: positive balances only; a State's negative balance is refunded by that State","examples":["122.00"]},"refunds":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["country","vat"],"additionalProperties":false}},"nil_return":{"type":"boolean","description":"Nothing to declare: a nil return is still due"},"doubtful":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string"},"number":{"type":"string"},"date":{"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"]},"reason":{"type":"string","enum":["n7_not_eu_consumer","italian_vat_to_eu_consumer","outside_registration","foreign_currency","rate_unknown","credit_note_unlinked","credit_note_before_sale","correction_too_old"]},"country":{"type":["string","null"]}},"required":["invoice_id","number","date","reason","country"],"additionalProperties":false}},"reliable":{"type":"boolean","const":false}},"required":["object","period","registered","registration","deadline","reference","currency","countries","corrections","balances","total_due","refunds","nil_return","doubtful","reliable"],"additionalProperties":false},"F24FundsAlert":{"type":"object","properties":{"object":{"type":"string","const":"f24_funds_alert"},"id":{"type":"string","description":"f24_funds:<due_date>"},"due_date":{"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"]},"currency":{"type":"string","const":"EUR"},"amount_due":{"type":"string","description":"Total of the F24 payments due that day (may include estimates)"},"available_balance":{"type":"string","description":"Highest balance of a single connected EUR account, minus the F24s due on earlier days of the window"},"shortfall":{"type":"string"},"deadline_ids":{"type":"array","items":{"type":"string"},"description":"The TaxDeadline ids due that day"},"bank_account_id":{"type":"string"}},"required":["object","id","due_date","currency","amount_due","available_balance","shortfall","deadline_ids","bank_account_id"],"additionalProperties":false},"TaxWebhookEvent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"event"},"type":{"type":"string","enum":["filing.ready","filing.filed","filing.needs_review","filing.changes_requested","filing.approved","filing.skipped","filing.approval_due","tax_deadline.upcoming","tax_deadline.insufficient_funds"]},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Unix seconds"},"livemode":{"type":"boolean","const":true},"data":{"type":"object","properties":{"object":{"anyOf":[{"$ref":"#/components/schemas/Filing"},{"type":"object","properties":{"id":{"type":"string","examples":["bollo:2026-Q3"]},"object":{"type":"string","const":"tax_deadline"},"kind":{"type":"string","enum":["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"]},"title":{"type":"string"},"period":{"type":"string","examples":["2026-Q3","2026-10","2026"]},"due_date":{"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"],"description":"The real deadline: Saturdays, Sundays and holidays move to the next working day; 1–20 August to 20 August. Exception: oss_return (EU OSS) never moves; when it falls on a non-working day needs_review is true."},"nominal_due_date":{"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"]},"days_left":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"overdue":{"type":"boolean"},"action":{"type":"string","enum":["payment","filing"]},"tax_codes":{"type":"array","items":{"type":"string"},"description":"F24 codici tributo"},"amount":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"Known amount (bollo, prepared filings); null otherwise"},"amount_status":{"type":"string","enum":["final","provisional","unknown"],"description":"final: prepared (a filing) or the period is over; provisional: still changing, or computed now from the VAT registers for a VAT payment without a saved liquidazione; unknown: not computed"},"status":{"type":"string","enum":["to_prepare","not_due","ready","needs_review","changes_requested","approved","skipped","filed","paid"],"description":"to_prepare: nothing prepared yet; not_due: nothing to pay or file; then the filing status (ready, needs_review, changes_requested, approved, skipped, filed, paid)"},"filing_id":{"type":["string","null"]},"can_prepare":{"type":"boolean"},"filing_type":{"anyOf":[{"type":"string","enum":["bollo","withholdings","vat_payment","lipe","vat_return","redditi_pf"]},{"type":"null"}]},"needs_review":{"type":"boolean","description":"Check it (\"da verificare\"): the rule may not fit this company (special VAT regime), or an OSS deadline falls on a non-working day and is kept"},"note":{"description":"Something to know when paying, e.g. the 1% interest on quarterly VAT","type":["string","null"]},"note_key":{"anyOf":[{"type":"string","enum":["quarterly_interest","oss","income_tax_balance","income_tax_advance","income_tax_advance_isa","financial_statements","inps_fixed","inps_balance","inps_advance","inps_reduction_request","pf_tax_balance","pf_tax_balance_isa","pf_tax_advance"]},{"type":"null"}],"description":"Which note it is (quarterly_interest, oss), to show your own text instead of note"},"source":{"type":"string","description":"Legal source of the deadline"},"extension":{"anyOf":[{"type":"object","properties":{"source_title":{"type":"string"},"source_url":{"type":"string"}},"required":["source_title","source_url"],"additionalProperties":false},{"type":"null"}],"description":"Set when a published extension (proroga) moved due_date: the official source"},"applies_because":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","examples":["vat_quarterly"],"description":"issues_e_invoices, withholding_agent, has_employees, vat_monthly, vat_quarterly, vat_payer (params.regime); more kinds add their own"},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}}},"required":["key"],"additionalProperties":false},"description":"Why it applies to this company (from the tax profile). Deadlines that do not apply are not listed."},"review_key":{"anyOf":[{"type":"string","enum":["in_liquidation"]},{"type":"null"}],"description":"Why needs_review is set beyond the rule itself: in_liquidation (check the deadlines of the liquidation periods with the liquidator)"},"reminder_days_before":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","object","kind","title","period","due_date","nominal_due_date","days_left","overdue","action","tax_codes","amount","amount_status","status","filing_id","can_prepare","filing_type","needs_review","note","note_key","source","extension","applies_because","review_key","reminder_days_before"],"additionalProperties":false},{"$ref":"#/components/schemas/F24FundsAlert"}]}},"required":["object"],"additionalProperties":false}},"required":["id","object","type","created","livemode","data"],"additionalProperties":false},"VatRegisters":{"type":"object","properties":{"object":{"type":"string","const":"vat_registers"},"period":{"type":"string"},"start":{"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"]},"end":{"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"]},"currency":{"type":"string","const":"EUR"},"sales":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"register:source:document_id, what adjustments are keyed by"},"source":{"type":"string","enum":["issued_invoice","received_invoice","autofattura"]},"document_id":{"type":"string"},"number":{"type":"string"},"date":{"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"],"description":"Data documento"},"received_date":{"anyOf":[{"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"]},{"type":"null"}],"description":"Date received through SDI (purchases), else null"},"counterparty_name":{"type":"string"},"counterparty_vat":{"type":["string","null"]},"tipo_documento":{"type":"string"},"breakdown":{"type":"array","items":{"type":"object","properties":{"rate":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"AliquotaIVA; null when it cannot be told from the amounts"},"natura":{"type":["string","null"]},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["rate","natura","taxable","vat"],"additionalProperties":false}},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat_counted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VAT that enters the liquidazione (after split payment, deferred VAT, foreign VAT and adjustments)","examples":["122.00"]},"counted":{"type":"boolean"},"flags":{"type":"array","items":{"type":"string","enum":["credit_note","split_payment","deferred_vat","deferred_vat_collected","reverse_charge","foreign_vat","no_vat","late_receipt","needs_review","unreviewed","country_unknown"]},"description":"unreviewed: a received invoice the team has not reviewed yet, counted as the AI read it (da verificare). needs_review: a rule may not fit (check it). country_unknown: the supplier country cannot be told, its VAT counts 0 until it is set"},"adjustment":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","enum":["exclude","adjust"]},"vat_amount":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"reason":{"type":"string"}},"required":["action","vat_amount","reason"],"additionalProperties":false},{"type":"null"}]}},"required":["key","source","document_id","number","date","received_date","counterparty_name","counterparty_vat","tipo_documento","breakdown","taxable","vat","vat_counted","counted","flags","adjustment"],"additionalProperties":false}},"totals":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat_counted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"excluded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"adjusted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"to_review":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows to check: flagged unreviewed or needs_review"},"by_rate":{"type":"array","items":{"type":"object","properties":{"rate":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"AliquotaIVA; null when it cannot be told from the amounts"},"natura":{"type":["string","null"]},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["rate","natura","taxable","vat"],"additionalProperties":false}}},"required":["documents","taxable","vat","vat_counted","excluded","adjusted","to_review","by_rate"],"additionalProperties":false}},"required":["rows","totals"],"additionalProperties":false},"purchases":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"register:source:document_id, what adjustments are keyed by"},"source":{"type":"string","enum":["issued_invoice","received_invoice","autofattura"]},"document_id":{"type":"string"},"number":{"type":"string"},"date":{"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"],"description":"Data documento"},"received_date":{"anyOf":[{"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"]},{"type":"null"}],"description":"Date received through SDI (purchases), else null"},"counterparty_name":{"type":"string"},"counterparty_vat":{"type":["string","null"]},"tipo_documento":{"type":"string"},"breakdown":{"type":"array","items":{"type":"object","properties":{"rate":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"AliquotaIVA; null when it cannot be told from the amounts"},"natura":{"type":["string","null"]},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["rate","natura","taxable","vat"],"additionalProperties":false}},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat_counted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VAT that enters the liquidazione (after split payment, deferred VAT, foreign VAT and adjustments)","examples":["122.00"]},"counted":{"type":"boolean"},"flags":{"type":"array","items":{"type":"string","enum":["credit_note","split_payment","deferred_vat","deferred_vat_collected","reverse_charge","foreign_vat","no_vat","late_receipt","needs_review","unreviewed","country_unknown"]},"description":"unreviewed: a received invoice the team has not reviewed yet, counted as the AI read it (da verificare). needs_review: a rule may not fit (check it). country_unknown: the supplier country cannot be told, its VAT counts 0 until it is set"},"adjustment":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","enum":["exclude","adjust"]},"vat_amount":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"reason":{"type":"string"}},"required":["action","vat_amount","reason"],"additionalProperties":false},{"type":"null"}]}},"required":["key","source","document_id","number","date","received_date","counterparty_name","counterparty_vat","tipo_documento","breakdown","taxable","vat","vat_counted","counted","flags","adjustment"],"additionalProperties":false}},"totals":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat_counted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"excluded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"adjusted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"to_review":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows to check: flagged unreviewed or needs_review"},"by_rate":{"type":"array","items":{"type":"object","properties":{"rate":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"AliquotaIVA; null when it cannot be told from the amounts"},"natura":{"type":["string","null"]},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["rate","natura","taxable","vat"],"additionalProperties":false}}},"required":["documents","taxable","vat","vat_counted","excluded","adjusted","to_review","by_rate"],"additionalProperties":false}},"required":["rows","totals"],"additionalProperties":false},"missing":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["issued_invoice","received_invoice","autofattura"]},"id":{"type":"string"},"number":{"type":["string","null"]},"date":{"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":{"type":"string"},"reason":{"type":"string","enum":["processing","unreviewed","no_vat_data","pending_sdi","autofattura_pending","autofattura_unreadable","autofattura_missing"]}},"required":["source","id","number","date","name","reason"],"additionalProperties":false},"description":"Documents of the period that are not in the registers yet: purchases the AI is still reading (processing), amounts without euro values, invoices and autofatture waiting for SDI, and foreign purchases whose reverse-charge TD17/TD18/TD19 was not sent to SDI yet (autofattura_missing, due by the 15th of the next month). Unreviewed purchases are in the registers, flagged unreviewed"},"computed_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the registers were computed: they are rebuilt from the documents on every read"},"reliable":{"type":"boolean","const":false},"note":{"type":"string"}},"required":["object","period","start","end","currency","sales","purchases","missing","computed_at","reliable","note"],"additionalProperties":false},"VatSettlement":{"type":"object","properties":{"object":{"type":"string","const":"vat_settlement"},"period":{"type":"string"},"periodicity":{"type":"string","enum":["monthly","quarterly"]},"start":{"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"]},"end":{"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"]},"currency":{"type":"string","const":"EUR"},"lipe":{"$ref":"#/components/schemas/LipeValues"},"result":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"VP14: positive to pay, negative a credit","examples":["122.00"]},"amount_to_pay":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"What the F24 pays now: 0.00 for a credit, for up to €100 carried to the next period, and for Q4 of quarterly payers (paid with the annual balance)","examples":["122.00"]},"carried_debt":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"carried_credit":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"tax_code":{"examples":["6010","6033"],"type":["string","null"]},"due_date":{"anyOf":[{"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"]},{"type":"null"}]},"notes":{"type":"array","items":{"type":"string","enum":["interest_added","below_minimum_carried","paid_with_annual_balance","credit_carried","previous_missing","advance_deducted","missing_documents"]}},"previous":{"anyOf":[{"type":"object","properties":{"period":{"type":"string"},"source":{"type":"string","enum":["saved","computed","input"],"description":"saved: the previous liquidazione saved in Getbeel; computed: Getbeel computed it from its registers (not saved yet); input: the amounts the user gave (previous_credit / previous_debt)"},"carried_credit":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Credit carried here (VP8)","examples":["122.00"]},"carried_debt":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Debt up to €100 carried here (VP7)","examples":["122.00"]}},"required":["period","source","carried_credit","carried_debt"],"additionalProperties":false},{"type":"null"}],"description":"Where VP7 / VP8 come from: the previous period of the same year. null for the first period of the year, or when Getbeel has no earlier data that year (notes: previous_missing; send previous_credit / previous_debt)"},"inputs":{"type":"object","properties":{"previous_credit":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"previous_debt":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"annual_credit_used":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"advance":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"advance_method":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["previous_credit","previous_debt","annual_credit_used","advance","advance_method"],"additionalProperties":false},"registers":{"type":"object","properties":{"sales":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat_counted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"excluded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"adjusted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"to_review":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows to check: flagged unreviewed or needs_review"},"by_rate":{"type":"array","items":{"type":"object","properties":{"rate":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"AliquotaIVA; null when it cannot be told from the amounts"},"natura":{"type":["string","null"]},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["rate","natura","taxable","vat"],"additionalProperties":false}}},"required":["documents","taxable","vat","vat_counted","excluded","adjusted","to_review","by_rate"],"additionalProperties":false},"purchases":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat_counted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"excluded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"adjusted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"to_review":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows to check: flagged unreviewed or needs_review"},"by_rate":{"type":"array","items":{"type":"object","properties":{"rate":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"AliquotaIVA; null when it cannot be told from the amounts"},"natura":{"type":["string","null"]},"taxable":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"vat":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["rate","natura","taxable","vat"],"additionalProperties":false}}},"required":["documents","taxable","vat","vat_counted","excluded","adjusted","to_review","by_rate"],"additionalProperties":false},"missing":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sales","purchases","missing"],"additionalProperties":false},"saved":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount_to_pay":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"outdated":{"type":"boolean","description":"The registers changed since it was saved"}},"required":["id","result","amount_to_pay","updated_at","outdated"],"additionalProperties":false},{"type":"null"}],"description":"The liquidazione as last saved (POST /v1/filings type vat_payment); the LIPE reports saved ones"},"computed_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When these numbers were computed. They are recomputed from the registers on every read, so they include every document in Getbeel up to now"},"reliable":{"type":"boolean","const":false},"note":{"type":"string"}},"required":["object","period","periodicity","start","end","currency","lipe","result","amount_to_pay","carried_debt","carried_credit","tax_code","due_date","notes","previous","inputs","registers","saved","computed_at","reliable","note"],"additionalProperties":false},"CreateAdvisorRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email the invitation is sent to"}},"required":["email"],"additionalProperties":false},"Advisor":{"type":"object","properties":{"id":{"type":"string","examples":["inv_42","mem_6f1c…"]},"object":{"type":"string","const":"advisor"},"email":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string","const":"auditor","description":"Read-only team role (\"Commercialista\" in the app): reads invoices, received invoices, bank movements and taxes, exports them, changes nothing"},"status":{"type":"string","enum":["invited","active"],"description":"invited: the invitation email was sent and not accepted yet; active: a member of the team"},"invited_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}],"description":"When a pending invitation stops working"},"joined_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["id","object","email","name","role","status","invited_at","expires_at","joined_at"],"additionalProperties":false},"AdvisorList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Advisor"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"DeletedAdvisor":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"advisor"},"deleted":{"type":"boolean","const":true}},"required":["id","object","deleted"],"additionalProperties":false},"InviteAdvisorToCompaniesRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email the invitation is sent to"},"company_ids":{"description":"The companies to invite them to (at most 25). Default: the company of the Getbeel-Company header, else this account.","minItems":1,"maxItems":25,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"This account’s id or the id of one of its client companies (GET /v1/companies)"}}},"required":["email"],"additionalProperties":false},"AdvisorInvitations":{"type":"object","properties":{"object":{"type":"string","const":"advisor_invitations"},"email":{"type":"string"},"invited":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"New invitations sent"},"already_invited":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Companies where this address already had a pending advisor invitation (returned, no second email)"},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"data":{"type":"array","items":{"type":"object","properties":{"company_id":{"type":"string"},"company_name":{"type":["string","null"]},"status":{"type":"string","enum":["invited","already_invited","failed"]},"advisor":{"anyOf":[{"$ref":"#/components/schemas/Advisor"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why this company failed: company_not_found, already_member, already_invited (to another role), invite_not_allowed, subscription_required, credits_exhausted, rate_limited, invite_failed"}},"required":["company_id","company_name","status","advisor","error"],"additionalProperties":false},"description":"One result per company, in the order sent"}},"required":["object","email","invited","already_invited","failed","data"],"additionalProperties":false},"AiRule":{"type":"object","properties":{"object":{"type":"string","const":"ai_rule"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["invoice_scan","fattura_emessa"],"description":"invoice_scan: followed when the AI reads received invoices and receipts. fattura_emessa: followed when it drafts issued invoices from Stripe payments."},"text":{"type":"string"},"active":{"type":"boolean","description":"Only active rules are followed"},"sort_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Order in which the AI reads the rules of a type"},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","type","text","active","sort_order","created_at","updated_at"],"additionalProperties":false},"AiRuleList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AiRule"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateAiRuleRequest":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500,"description":"The instruction, in plain language (up to 500 characters)","examples":["Le fatture di Amazon Web Services vanno nella categoria software"]},"type":{"default":"invoice_scan","type":"string","enum":["invoice_scan","fattura_emessa"],"description":"invoice_scan: followed when the AI reads received invoices and receipts. fattura_emessa: followed when it drafts issued invoices from Stripe payments."},"active":{"description":"Default true","type":"boolean"}},"required":["text","type"],"additionalProperties":false},"UpdateAiRuleRequest":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500,"description":"The instruction, in plain language (up to 500 characters)","examples":["Le fatture di Amazon Web Services vanno nella categoria software"]},"active":{"description":"false pauses the rule without deleting it","type":"boolean"}},"additionalProperties":false},"Autofattura":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"autofattura"},"date":{"type":"string","description":"Date of the purchase (bank debit or document)"},"supplier":{"type":["string","null"]},"supplier_country":{"description":"IdPaese of the foreign supplier","type":["string","null"]},"supplier_invoice_number":{"type":["string","null"]},"amount":{"type":"string","description":"Amount of the purchase, as a decimal string"},"currency":{"type":"string"},"tipo_documento":{"description":"TD17, TD18 or TD19 (reverse charge)","type":["string","null"]},"numero":{"description":"Number of the autofattura","type":["string","null"]},"status":{"type":"string","description":"not_created, queued, processing, generated (XML ready), error, needs_country"},"xml_ready":{"type":"boolean"},"sdi":{"type":"object","properties":{"status":{"description":"null until sent; queued, sending, sent_to_sdi, consegnata, non_consegnata, scartata, error","type":["string","null"]},"id":{"description":"IdentificativoSdI once SDI took it","type":["string","null"]},"error":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["status","id","error","updated_at"],"additionalProperties":false}},"required":["id","object","date","supplier","supplier_country","supplier_invoice_number","amount","currency","tipo_documento","numero","status","xml_ready","sdi"],"additionalProperties":false},"CreateTopupRequest":{"type":"object","properties":{"amount_cents":{"type":"integer","minimum":1000,"maximum":1000000,"description":"Credit to add, net of VAT (from 1000 to 1000000)","examples":[2500]}},"required":["amount_cents"],"additionalProperties":false},"Balance":{"type":"object","properties":{"object":{"type":"string","const":"balance"},"currency":{"type":"string","const":"EUR"},"balance_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Spendable balance; below zero only because received SDI invoices are never blocked (down to -1000)"},"expiring_soon_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"},"billed_to_parent":{"type":"boolean"},"pricing":{"type":"string","enum":["pay_as_you_go","legacy_plan"],"description":"pay_as_you_go: signed up on or after 13 November 2026; every billable action is paid from this balance. legacy_plan: signed up before; the account keeps its plan and everything it includes for life (tax filings and connected bank accounts too) and nothing is paid from a balance: the amounts are 0, topup_url is null, and usage, top-ups and card links answer 409 not_pay_as_you_go."},"auto_topup":{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"},"amount_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"}},"required":["enabled","threshold_cents","amount_cents"],"additionalProperties":false},"low_balance_alert":{"type":"object","properties":{"enabled":{"type":"boolean","description":"The email goes out only once the account has paid credit: a top-up not refunded in full (the welcome credit alone does not count)"},"threshold_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"}},"required":["enabled","threshold_cents"],"additionalProperties":false},"welcome_credit":{"type":"object","properties":{"granted":{"type":"boolean"},"not_granted_reason":{"anyOf":[{"type":"string","enum":["card_already_used","legacy_plan","moved_from_plan","no_card"]},{"type":"null"}],"description":"Why there is no welcome credit: card_already_used (the saved card already got it on another team; it applies only once per card), legacy_plan (signed up before 13 November 2026 and keeps its plan: the welcome credit is for new accounts only), moved_from_plan (no longer returned), no_card (no card saved yet: saving one grants it). null when granted, while it is being granted, or when no reason is given."}},"required":["granted","not_granted_reason"],"additionalProperties":false,"description":"The €1 welcome credit of this billing account"},"topup_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"The Billing & usage page to add credits; null on legacy_plan (no balance)"},"note":{"type":"string"}},"required":["object","currency","balance_cents","expiring_soon_cents","billed_to_parent","pricing","auto_topup","low_balance_alert","welcome_credit","topup_url","note"],"additionalProperties":false},"BillingUsage":{"type":"object","properties":{"object":{"type":"string","const":"billing_usage"},"currency":{"type":"string","const":"EUR"},"month":{"type":"string"},"total_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"},"daily_average_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"},"by_meter":{"type":"array","items":{"type":"object","properties":{"meter":{"type":"string","enum":["sdi_send","sdi_receive","ai_document_read","bank_account_month","bank_movement","tax_f24","tax_lipe","tax_oss","tax_vat_return","tax_income","tax_redditi_pf"]},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"},"next_unit_price_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The price of this meter's next unit now: it follows the current month's count (tiers reset each calendar month), also when an earlier month is asked for."}},"required":["meter","quantity","amount_cents","next_unit_price_cents"],"additionalProperties":false}},"by_company":{"type":"array","items":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"}},"required":["company_id","name","quantity","amount_cents"],"additionalProperties":false}}},"required":["object","currency","month","total_cents","daily_average_cents","by_meter","by_company"],"additionalProperties":false},"PriceList":{"type":"object","properties":{"object":{"type":"string","const":"price_list"},"currency":{"type":"string","const":"EUR"},"meters":{"type":"array","items":{"type":"object","properties":{"meter":{"type":"string","enum":["sdi_send","sdi_receive","ai_document_read","bank_account_month","bank_movement","tax_f24","tax_lipe","tax_oss","tax_vat_return","tax_income","tax_redditi_pf"]},"unit":{"type":"string"},"never_blocked":{"type":"boolean"},"tiers":{"type":"array","items":{"type":"object","properties":{"up_to":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Inclusive upper bound per billing account per calendar month; null = no bound"},"unit_amount_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"}},"required":["up_to","unit_amount_cents"],"additionalProperties":false}}},"required":["meter","unit","never_blocked","tiers"],"additionalProperties":false}}},"required":["object","currency","meters"],"additionalProperties":false},"TopupCheckout":{"type":"object","properties":{"object":{"type":"string","const":"topup_checkout"},"currency":{"type":"string","const":"EUR"},"amount_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"EUR cents, net of VAT"},"checkout_url":{"type":"string","format":"uri"},"note":{"type":"string"}},"required":["object","currency","amount_cents","checkout_url","note"],"additionalProperties":false},"CardCheckout":{"type":"object","properties":{"object":{"type":"string","const":"card_checkout"},"checkout_url":{"type":"string","format":"uri"},"note":{"type":"string"}},"required":["object","checkout_url","note"],"additionalProperties":false},"Category":{"type":"object","properties":{"object":{"type":"string","const":"category"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"slug":{"type":"string","description":"Stable key used on received invoices (category field)","examples":["software"]},"label":{"type":"string"},"color":{"type":"string"},"is_default":{"type":"boolean","description":"Default categories cannot be deleted"},"sort_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","id","slug","label","color","is_default","sort_order"],"additionalProperties":false},"CategoryList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateCategoryRequest":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100,"description":"Name shown in the app"},"color":{"type":"string","pattern":"^(#[0-9a-fA-F]{6}|hsl\\(\\s*\\d{1,3}(\\.\\d+)?\\s*,\\s*\\d{1,3}(\\.\\d+)?%\\s*,\\s*\\d{1,3}(\\.\\d+)?%\\s*\\))$","description":"Colour: #rrggbb or hsl(h, s%, l%)"}},"required":["label"],"additionalProperties":false},"UpdateCategoryRequest":{"type":"object","properties":{"label":{"description":"New name shown in the app","type":"string","minLength":1,"maxLength":100},"color":{"type":"string","pattern":"^(#[0-9a-fA-F]{6}|hsl\\(\\s*\\d{1,3}(\\.\\d+)?\\s*,\\s*\\d{1,3}(\\.\\d+)?%\\s*,\\s*\\d{1,3}(\\.\\d+)?%\\s*\\))$","description":"Colour: #rrggbb or hsl(h, s%, l%)"}},"additionalProperties":false},"SetInvoiceCategoryRequest":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":100,"description":"A category slug from GET /categories","examples":["software"]}},"required":["category"],"additionalProperties":false},"DeletedDriveFile":{"type":"object","properties":{"object":{"type":"string","const":"drive_file"},"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["object","id","deleted"],"additionalProperties":false},"DeletedDriveFolder":{"type":"object","properties":{"object":{"type":"string","const":"drive_folder"},"path":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["object","path","deleted"],"additionalProperties":false},"Drive":{"type":"object","properties":{"object":{"type":"string","const":"drive"},"month":{"type":["string","null"]},"folder":{"type":["string","null"]},"folders":{"type":"array","items":{"$ref":"#/components/schemas/DriveFolder"}},"files":{"type":"array","items":{"$ref":"#/components/schemas/DriveFile"}}},"required":["object","month","folder","folders","files"],"additionalProperties":false},"DriveFileDownload":{"type":"object","properties":{"object":{"type":"string","const":"drive_file_download"},"id":{"type":"string"},"name":{"type":"string"},"download_url":{"type":"string","description":"A private link, valid 15 minutes"},"expires_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","name","download_url","expires_at"],"additionalProperties":false},"CreateDriveFolderRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"Folder name; its path comes from it (letters, digits and dashes)","examples":["Contratti"]},"month":{"description":"Create it inside this month’s folder instead of the root","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","examples":["2026-10"]}},"required":["name"],"additionalProperties":false},"DriveFolder":{"type":"object","properties":{"object":{"type":"string","const":"drive_folder"},"path":{"type":"string","description":"invoices and reconciliation (system folders), a month (2026-10), or an uploads folder (documents, contratti, 2026-10/contratti)"},"name":{"type":"string"},"kind":{"type":"string","enum":["system","month","custom"]},"month":{"type":["string","null"]},"file_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total_size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Bytes"},"updated_at":{"type":["string","null"]},"writable":{"type":"boolean","description":"Uploads can go here (not the system folders)"}},"required":["object","path","name","kind","month","file_count","total_size","updated_at","writable"],"additionalProperties":false},"UploadDriveFileRequest":{"type":"object","properties":{"folder":{"type":"string","maxLength":100,"pattern":"^(\\d{4}-(0[1-9]|1[0-2])|(\\d{4}-(0[1-9]|1[0-2])\\/)?[a-z0-9]+(-[a-z0-9]+)*)$","description":"Where it goes: a month (2026-10), documents, or a custom folder path from GET /drive (writable true)","examples":["2026-10"]},"file_url":{"description":"Public https URL of the file (no redirects)","type":"string","maxLength":2048,"format":"uri"},"file_base64":{"description":"The file, base64-encoded","type":"string","maxLength":34952538},"file_name":{"description":"File name, e.g. contratto-affitto.pdf (required with file_base64)","type":"string","minLength":1,"maxLength":255}},"required":["folder"],"additionalProperties":false},"DriveFile":{"type":"object","properties":{"object":{"type":"string","const":"drive_file"},"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["invoice","reconciliation","document"],"description":"invoice: a received invoice’s file; reconciliation: an uploaded bank statement; document: an uploaded document"},"folder":{"type":"string","description":"The path of its folder"},"mime_type":{"type":["string","null"]},"size":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"created_at":{"type":["string","null"]},"document_date":{"description":"Invoice date for invoice files, else the upload date","type":["string","null"]},"month":{"type":["string","null"]},"vendor_name":{"type":["string","null"]}},"required":["object","id","name","kind","folder","mime_type","size","created_at","document_date","month","vendor_name"],"additionalProperties":false},"CreateCreditNoteRequest":{"type":"object","properties":{"lines":{"description":"Lines to credit. Omit to credit the whole invoice (ritenuta, cassa and discounts included); a partial credit leaves those out.","minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":199,"description":"Position of the line on the invoice (0-based)"},"quantity":{"description":"Default: the line's whole quantity","examples":["100.00"]}},"required":["index"],"additionalProperties":false}},"series_id":{"description":"Numbering series. Omit for the team's credit-note series, else the invoice's series; null for the default numbering.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"date":{"description":"Credit note date (default: today in Italy)","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"]},"reason":{"description":"Printed as the Causale (default: \"Nota di credito per fattura n. … del …\")","type":"string","minLength":1,"maxLength":1000}},"additionalProperties":false},"Quote":{"type":"object","properties":{"object":{"type":"string","const":"quote"},"id":{"type":"string","examples":["qt_5b0e…"]},"livemode":{"type":"boolean"},"number":{"type":"string","description":"Number and year, one sequence per year","examples":["12/2026"]},"status":{"type":"string","enum":["draft","sent","accepted","declined","expired"],"description":"draft → sent (emailed) → accepted or declined; a draft or sent quote past valid_until reads as expired"},"date":{"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"]},"valid_until":{"anyOf":[{"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"]},{"type":"null"}]},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":["string","null"]},"partita_iva":{"type":["string","null"]},"codice_fiscale":{"type":["string","null"]},"country":{"type":"string"},"address":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"codice_destinatario":{"type":["string","null"]},"pec":{"type":["string","null"]}},"required":["name","email","partita_iva","codice_fiscale","country","address","postal_code","city","province","codice_destinatario","pec"],"additionalProperties":false},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"number"},"unit":{"type":["string","null"]},"vat_rate":{"type":"number"},"natura":{"type":["string","null"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["description","quantity","unit_price","unit","vat_rate","natura","amount"],"additionalProperties":false}},"notes":{"type":["string","null"]},"currency":{"type":"string"},"amount_subtotal":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount_tax":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount_total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"invoice_id":{"description":"The invoice draft created by POST /quotes/{id}/convert","type":["string","null"]},"sent_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"accepted_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"declined_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"converted_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","livemode","number","status","date","valid_until","customer","lines","notes","currency","amount_subtotal","amount_tax","amount_total","invoice_id","sent_at","accepted_at","declined_at","converted_at","created_at","updated_at"],"additionalProperties":false},"QuoteList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateQuoteRequest":{"type":"object","properties":{"customer":{"type":"object","properties":{"denominazione":{"description":"Company name. Or send nome and cognome for a person.","examples":["Rossi S.r.l."],"type":"string","minLength":1,"maxLength":80},"nome":{"description":"First name of a person customer (with cognome)","examples":["Mario"],"type":"string","minLength":1,"maxLength":60},"cognome":{"description":"Surname of a person customer (with nome)","examples":["Rossi"],"type":"string","minLength":1,"maxLength":60},"partita_iva":{"description":"VAT number, with or without the country prefix. Sandbox: 00000000000 is rejected by SDI (NS, code 00305).","examples":["01234567890"],"type":"string","pattern":"^[A-Z0-9]{2,28}$"},"codice_fiscale":{"description":"Italian tax code: 16 characters for a person, 11 digits for a company","examples":["RSSMRA80A01F205X"],"type":"string","pattern":"^[A-Z0-9]{11,16}$"},"address":{"description":"Street and number","examples":["Via Roma 1"],"type":"string","minLength":1,"maxLength":60},"postal_code":{"description":"CAP (postal code)","examples":["20121"],"type":"string","minLength":1,"maxLength":10},"city":{"description":"City (comune)","examples":["Milano"],"type":"string","minLength":1,"maxLength":60},"province":{"description":"Two-letter Italian province code (sigla)","examples":["MI"],"type":"string","pattern":"^[A-Z]{2}$"},"country":{"default":"IT","description":"ISO 3166-1 alpha-2 country code; default IT","examples":["IT"],"type":"string","pattern":"^[A-Z]{2}$"},"codice_destinatario":{"description":"SDI recipient code. Omit (or 0000000) to deliver by PEC or to the buyer's fiscal drawer. Sandbox: MC00000 is not delivered (MC).","examples":["M5UXCR1"],"type":"string","pattern":"^[A-Z0-9]{7}$"},"pec":{"description":"Certified email (PEC) where SDI delivers the invoice when there is no codice_destinatario","examples":["rossisrl@pec.it"],"type":"string","maxLength":256,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"email":{"description":"For the courtesy copy (not used by SDI)","type":"string","maxLength":256,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["country"],"additionalProperties":false,"description":"The buyer (CessionarioCommittente): denominazione, or nome and cognome; partita_iva or codice_fiscale; address; codice_destinatario or pec for delivery"},"date":{"description":"Quote date (default: today in Italy)","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"]},"currency":{"default":"EUR","description":"ISO 4217 currency code; default EUR","examples":["EUR"],"type":"string","pattern":"^[A-Z]{3}$"},"lines":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":1000,"description":"What is sold, as printed on the line (Descrizione)","examples":["Consulenza ottobre 2026"]},"quantity":{"description":"Default 1","examples":["1"]},"unit_price":{"description":"Decimal string (or number)","examples":["100.00"]},"vat_rate":{"description":"IVA rate in percent","examples":["22"]},"subject_to_withholding":{"description":"With a withholding: whether this line is subject to it (written as Ritenuta = SI). Default true, except natura N1 lines (expenses advanced for the customer).","type":"boolean"},"natura":{"description":"Natura IVA of a 0% line (exempt, reverse charge, …)","type":"string","enum":["N1","N2.1","N2.2","N3.1","N3.2","N3.3","N3.4","N3.5","N3.6","N4","N5","N6.1","N6.2","N6.3","N6.4","N6.5","N6.6","N6.7","N6.8","N6.9","N7"]}},"required":["description","unit_price"],"additionalProperties":false},"description":"Invoice lines (DettaglioLinee), 1–200"},"withholding":{"description":"Ritenuta d'acconto: income tax the customer withholds from the payment and pays to the State on the issuer's behalf (DatiRitenuta). Omit when there is none.","$ref":"#/components/schemas/CreateInvoiceWithholding"},"cassa_previdenziale":{"description":"Cassa previdenziale: the professional's social-security contribution charged to the customer (DatiCassaPrevidenziale), e.g. the 4% INPS rivalsa. Omit when there is none.","$ref":"#/components/schemas/CreateInvoiceCassa"},"payment":{"description":"Payment terms printed on the invoice (DatiPagamento): method, terms, due date and bank details","type":"object","properties":{"method":{"default":"MP05","description":"ModalitaPagamento (MP05 bank transfer)","type":"string","pattern":"^MP(0[1-9]|1\\d|2[0-3])$"},"terms":{"default":"TP02","description":"CondizioniPagamento: TP01 instalments, TP02 full payment, TP03 advance","type":"string","enum":["TP01","TP02","TP03"]},"due_date":{"description":"Payment due date (YYYY-MM-DD)","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"]},"iban":{"description":"IBAN to pay into, without spaces","examples":["IT60X0542811101000000123456"],"type":"string","pattern":"^[A-Z]{2}\\d{2}[A-Z0-9]{11,30}$"},"bank_name":{"description":"Name of the bank (IstitutoFinanziario)","examples":["Intesa Sanpaolo"],"type":"string","minLength":1,"maxLength":80},"beneficiary":{"description":"Payee name, if not the issuer (Beneficiario)","type":"string","minLength":1,"maxLength":200}},"required":["method","terms"],"additionalProperties":false},"notes":{"description":"Printed on the invoice as its Causale","type":"string","minLength":1,"maxLength":1000},"valid_until":{"description":"Last day the offer holds","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"]}},"required":["customer","currency","lines"],"additionalProperties":false},"UpdateQuoteRequest":{"type":"object","properties":{"customer":{"type":"object","properties":{"denominazione":{"description":"Company name. Or send nome and cognome for a person.","examples":["Rossi S.r.l."],"type":"string","minLength":1,"maxLength":80},"nome":{"description":"First name of a person customer (with cognome)","examples":["Mario"],"type":"string","minLength":1,"maxLength":60},"cognome":{"description":"Surname of a person customer (with nome)","examples":["Rossi"],"type":"string","minLength":1,"maxLength":60},"partita_iva":{"description":"VAT number, with or without the country prefix. Sandbox: 00000000000 is rejected by SDI (NS, code 00305).","examples":["01234567890"],"type":"string","pattern":"^[A-Z0-9]{2,28}$"},"codice_fiscale":{"description":"Italian tax code: 16 characters for a person, 11 digits for a company","examples":["RSSMRA80A01F205X"],"type":"string","pattern":"^[A-Z0-9]{11,16}$"},"address":{"description":"Street and number","examples":["Via Roma 1"],"type":"string","minLength":1,"maxLength":60},"postal_code":{"description":"CAP (postal code)","examples":["20121"],"type":"string","minLength":1,"maxLength":10},"city":{"description":"City (comune)","examples":["Milano"],"type":"string","minLength":1,"maxLength":60},"province":{"description":"Two-letter Italian province code (sigla)","examples":["MI"],"type":"string","pattern":"^[A-Z]{2}$"},"country":{"default":"IT","description":"ISO 3166-1 alpha-2 country code; default IT","examples":["IT"],"type":"string","pattern":"^[A-Z]{2}$"},"codice_destinatario":{"description":"SDI recipient code. Omit (or 0000000) to deliver by PEC or to the buyer's fiscal drawer. Sandbox: MC00000 is not delivered (MC).","examples":["M5UXCR1"],"type":"string","pattern":"^[A-Z0-9]{7}$"},"pec":{"description":"Certified email (PEC) where SDI delivers the invoice when there is no codice_destinatario","examples":["rossisrl@pec.it"],"type":"string","maxLength":256,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"email":{"description":"For the courtesy copy (not used by SDI)","type":"string","maxLength":256,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["country"],"additionalProperties":false,"description":"The buyer (CessionarioCommittente): denominazione, or nome and cognome; partita_iva or codice_fiscale; address; codice_destinatario or pec for delivery"},"currency":{"default":"EUR","description":"ISO 4217 currency code; default EUR","examples":["EUR"],"type":"string","pattern":"^[A-Z]{3}$"},"lines":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":1000,"description":"What is sold, as printed on the line (Descrizione)","examples":["Consulenza ottobre 2026"]},"quantity":{"description":"Default 1","examples":["1"]},"unit_price":{"description":"Decimal string (or number)","examples":["100.00"]},"vat_rate":{"description":"IVA rate in percent","examples":["22"]},"subject_to_withholding":{"description":"With a withholding: whether this line is subject to it (written as Ritenuta = SI). Default true, except natura N1 lines (expenses advanced for the customer).","type":"boolean"},"natura":{"description":"Natura IVA of a 0% line (exempt, reverse charge, …)","type":"string","enum":["N1","N2.1","N2.2","N3.1","N3.2","N3.3","N3.4","N3.5","N3.6","N4","N5","N6.1","N6.2","N6.3","N6.4","N6.5","N6.6","N6.7","N6.8","N6.9","N7"]}},"required":["description","unit_price"],"additionalProperties":false},"description":"Invoice lines (DettaglioLinee), 1–200"},"withholding":{"description":"Ritenuta d'acconto: income tax the customer withholds from the payment and pays to the State on the issuer's behalf (DatiRitenuta). Omit when there is none.","$ref":"#/components/schemas/CreateInvoiceWithholding"},"cassa_previdenziale":{"description":"Cassa previdenziale: the professional's social-security contribution charged to the customer (DatiCassaPrevidenziale), e.g. the 4% INPS rivalsa. Omit when there is none.","$ref":"#/components/schemas/CreateInvoiceCassa"},"payment":{"description":"Payment terms printed on the invoice (DatiPagamento): method, terms, due date and bank details","type":"object","properties":{"method":{"default":"MP05","description":"ModalitaPagamento (MP05 bank transfer)","type":"string","pattern":"^MP(0[1-9]|1\\d|2[0-3])$"},"terms":{"default":"TP02","description":"CondizioniPagamento: TP01 instalments, TP02 full payment, TP03 advance","type":"string","enum":["TP01","TP02","TP03"]},"due_date":{"description":"Payment due date (YYYY-MM-DD)","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"]},"iban":{"description":"IBAN to pay into, without spaces","examples":["IT60X0542811101000000123456"],"type":"string","pattern":"^[A-Z]{2}\\d{2}[A-Z0-9]{11,30}$"},"bank_name":{"description":"Name of the bank (IstitutoFinanziario)","examples":["Intesa Sanpaolo"],"type":"string","minLength":1,"maxLength":80},"beneficiary":{"description":"Payee name, if not the issuer (Beneficiario)","type":"string","minLength":1,"maxLength":200}},"required":["method","terms"],"additionalProperties":false},"notes":{"description":"Printed on the invoice as its Causale","type":"string","minLength":1,"maxLength":1000},"valid_until":{"description":"Last day the quote is valid (YYYY-MM-DD); null removes it","anyOf":[{"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"]},{"type":"null"}]}},"additionalProperties":false},"SendQuoteRequest":{"type":"object","properties":{"to":{"description":"Recipient email addresses, up to 10; default: the customer's email on the quote","examples":[["cliente@example.com"]],"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"cc":{"description":"Email addresses copied on the email, up to 10. Ignored with a test key (the email goes only to the team owner).","maxItems":10,"type":"array","items":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"language":{"default":"it","type":"string","enum":["it","en"]},"message":{"description":"A personal note added to the email body, up to 2000 characters","type":"string","maxLength":2000}},"required":["language"],"additionalProperties":false},"SendQuoteResponse":{"type":"object","properties":{"quote":{"$ref":"#/components/schemas/Quote"},"sent_to":{"type":"array","items":{"type":"string"},"description":"Where it went: the recipients for live quotes; the team owner only for sandbox quotes"}},"required":["quote","sent_to"],"additionalProperties":false},"ConvertQuoteRequest":{"type":"object","properties":{"series_id":{"description":"Numbering series (a UUID) for the invoice number. Omit for the team's default series; null for the default numbering.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"date":{"description":"Invoice date (default: today in Italy)","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"]}},"additionalProperties":false},"DeletedQuote":{"type":"object","properties":{"object":{"type":"string","const":"quote"},"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["object","id","deleted"],"additionalProperties":false},"Item":{"type":"object","properties":{"object":{"type":"string","const":"item"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"livemode":{"type":"boolean"},"name":{"type":"string"},"description":{"type":["string","null"]},"code":{"type":["string","null"]},"unit_price":{"type":"number"},"unit":{"examples":["ore"],"type":["string","null"]},"vat_rate":{"type":"number"},"natura":{"type":["string","null"]},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","livemode","name","description","code","unit_price","unit","vat_rate","natura","archived","created_at","updated_at"],"additionalProperties":false},"ItemList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateItemRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Name shown in the item list and invoice lines"},"description":{"description":"Line description copied into invoices and quotes","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"code":{"description":"Your product or service code (CodiceArticolo), up to 35","anyOf":[{"type":"string","maxLength":35},{"type":"null"}]},"unit_price":{"description":"Decimal string (or number)","examples":["100.00"]},"unit":{"description":"Unit of measure, e.g. \"ore\", \"pz\" (UnitaMisura)","anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"vat_rate":{"description":"Default 22; ignored with natura","examples":["100.00"]},"natura":{"description":"Natura code for a 0% VAT line (e.g. N2.2); omit for VAT","anyOf":[{"type":"string","pattern":"^N[1-7](\\.[1-6])?$"},{"type":"null"}]}},"required":["name","unit_price"],"additionalProperties":false},"UpdateItemRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Name shown in the item list and invoice lines"},"description":{"description":"Line description copied into invoices and quotes","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"code":{"description":"Your product or service code (CodiceArticolo), up to 35","anyOf":[{"type":"string","maxLength":35},{"type":"null"}]},"unit_price":{"description":"Decimal string (or number)","examples":["100.00"]},"unit":{"description":"Unit of measure, e.g. \"ore\", \"pz\" (UnitaMisura)","anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"vat_rate":{"description":"Default 22; ignored with natura","examples":["100.00"]},"natura":{"description":"Natura code for a 0% VAT line (e.g. N2.2); omit for VAT","anyOf":[{"type":"string","pattern":"^N[1-7](\\.[1-6])?$"},{"type":"null"}]},"archived":{"type":"boolean"}},"additionalProperties":false},"DeletedItem":{"type":"object","properties":{"object":{"type":"string","const":"item"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"deleted":{"type":"boolean","const":true}},"required":["object","id","deleted"],"additionalProperties":false},"NumberingSeries":{"type":"object","properties":{"object":{"type":"string","const":"numbering_series"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"prefix":{"type":"string","examples":["FT-"]},"suffix":{"type":"string","examples":["/A"]},"yearly_reset":{"type":"boolean","description":"Numbers start again from 1 every year"},"default_for_invoices":{"type":"boolean"},"default_for_credit_notes":{"type":"boolean"},"archived":{"type":"boolean"},"next_number":{"type":"string","description":"Next number in the key's mode for today","examples":["FT-13/A"]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","name","prefix","suffix","yearly_reset","default_for_invoices","default_for_credit_notes","archived","next_number","created_at"],"additionalProperties":false},"NumberingSeriesList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/NumberingSeries"}},"default_numbering":{"type":"object","properties":{"next_number":{"type":"string","description":"The Numero the next invoice without a series gets today (no suffix). Invoices numbered before the yearly restart keep the \"/\" they were filed with, e.g. \"45/\".","examples":["46"]},"yearly_reset":{"type":"boolean","description":"true: restarts at 1 every calendar year (default); false: one sequence across years. Set in the app (Invoices > Numbering)."},"used_for_invoices":{"type":"boolean","description":"No series is the default for invoices"}},"required":["next_number","yearly_reset","used_for_invoices"],"additionalProperties":false},"has_more":{"type":"boolean","const":false},"next_cursor":{"type":"null"}},"required":["object","data","default_numbering","has_more","next_cursor"],"additionalProperties":false},"CreateNumberingSeriesRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Name of the series, e.g. \"Estero\""},"prefix":{"default":"","description":"Text before the number (e.g. \"E\"); empty for none","type":"string","pattern":"^([A-Za-z0-9/_.-]{0,9}[A-Za-z/_.-])?$"},"suffix":{"default":"","description":"Text after the number (e.g. \"/A\"); empty for none","type":"string","pattern":"^([A-Za-z/_.-][A-Za-z0-9/_.-]{0,9})?$"},"yearly_reset":{"default":true,"type":"boolean"},"default_for_invoices":{"default":false,"type":"boolean"},"default_for_credit_notes":{"default":false,"type":"boolean"}},"required":["name","prefix","suffix","yearly_reset","default_for_invoices","default_for_credit_notes"],"additionalProperties":false},"UpdateNumberingSeriesRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Name of the series, e.g. \"Estero\""},"prefix":{"type":"string","pattern":"^([A-Za-z0-9/_.-]{0,9}[A-Za-z/_.-])?$","description":"Text before the number (e.g. \"E\"); empty for none"},"suffix":{"type":"string","pattern":"^([A-Za-z/_.-][A-Za-z0-9/_.-]{0,9})?$","description":"Text after the number (e.g. \"/A\"); empty for none"},"yearly_reset":{"type":"boolean"},"default_for_invoices":{"type":"boolean"},"default_for_credit_notes":{"type":"boolean"},"archived":{"type":"boolean"}},"additionalProperties":false},"SdiReceiving":{"type":"object","properties":{"object":{"type":"string","const":"sdi_receiving"},"status":{"type":"string","enum":["not_enabled","awaiting_approval","pending","active","error"],"description":"not_enabled; awaiting_approval (the P.IVA could not be verified in VIES: a getbeel operator checks it, then receiving turns on by itself; see approval); pending (asked the SDI provider); active (supplier invoices arrive in GET /received-invoices with source sdi); error (last_error says why)"},"provider":{"type":"string","const":"openapi"},"fiscal_id":{"description":"P.IVA (or codice fiscale) invoices are received for","type":["string","null"]},"codice_destinatario":{"description":"Give it to suppliers and register it as indirizzo telematico in the AdE area (Fatture e Corrispettivi). Null until receiving is enabled.","examples":["PIC7CPS"],"type":["string","null"]},"enabled_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"last_error":{"type":["string","null"]},"approval":{"anyOf":[{"type":"object","properties":{"reason":{"type":"string","enum":["name_mismatch","vies_invalid","vies_unavailable","no_vat_number"],"description":"Why the P.IVA waits for a person: the VIES name does not match the company name, VIES says the number is invalid, VIES did not answer (or returned no name), or the company has only a codice fiscale"},"requested_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["reason","requested_at"],"additionalProperties":false},{"type":"null"}],"description":"Set while status is awaiting_approval (security: proof that the company owns the P.IVA)"},"last_received_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"received_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"indirizzo_telematico":{"type":"object","properties":{"confirmed":{"type":"boolean","description":"A member confirmed in the app that the code is registered in the AdE area (getbeel cannot check it)"},"confirmed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["confirmed","confirmed_at"],"additionalProperties":false},"conservazione":{"type":"object","properties":{"status":{"type":"string","enum":["not_activated","active","expired"],"description":"The AdE free conservazione service (activated by the company in its own AdE area; three-year agreement), as recorded in the app"},"activated_on":{"anyOf":[{"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"]},{"type":"null"}]},"expires_on":{"anyOf":[{"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"]},{"type":"null"}]}},"required":["status","activated_on","expires_on"],"additionalProperties":false},"readiness":{"type":"object","properties":{"ready":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["company_data","sdi_addon","receiving_enabled","indirizzo_telematico","conservazione"]},"done":{"type":"boolean"},"required":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string","enum":["name","country","vat_number","regime_fiscale","address","postal_code","city","province"]}}},"required":["id","done","required"],"additionalProperties":false}}},"required":["ready","steps"],"additionalProperties":false},"links":{"type":"object","properties":{"ade_portal":{"type":"string"},"ade_info":{"type":"string"}},"required":["ade_portal","ade_info"],"additionalProperties":false}},"required":["object","status","provider","fiscal_id","codice_destinatario","enabled_at","last_error","approval","last_received_at","received_count","indirizzo_telematico","conservazione","readiness","links"],"additionalProperties":false},"SandboxInboundInvoiceRequest":{"type":"object","properties":{"xml":{"description":"A FatturaPA XML (or base64 .p7m) to receive. Omit it to receive a sample invoice addressed to your company.","type":"string","minLength":1,"maxLength":5242880}},"additionalProperties":false},"TaxSettings":{"type":"object","properties":{"object":{"type":"string","const":"tax_settings"},"vat_periodicity":{"anyOf":[{"type":"string","enum":["monthly","quarterly"],"description":"How the company settles VAT (liquidazione mensile or trimestrale). It decides the VAT deadlines and periods."},{"type":"null"}]},"withholding_agent":{"anyOf":[{"type":"boolean","description":"Whether the company is a sostituto d’imposta (pays professionals and withholds ritenute): adds the 1040 F24 deadlines."},{"type":"null"}]},"oss_from":{"anyOf":[{"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"]},{"type":"null"}],"description":"The day the OSS union scheme applies from (Portale OSS registration; Reg. 282/2011 art. 57d). null: not registered (also clears oss_until). Adds the quarterly OSS return and payment deadlines."},"oss_until":{"anyOf":[{"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"]},{"type":"null"}],"description":"The day the OSS scheme stops applying (exit or exclusion). null: still registered."},"auto_prepare":{"type":"boolean","description":"Automatic preparation (default true): getbeel prepares the F24 of bollo, ritenute and periodic VAT auto_prepare_days days before the due date, once the period is over and the amount is known, and sends filing.ready. false: only reminders."},"auto_prepare_days":{"type":"integer","minimum":1,"maximum":30,"description":"Days before the due date for the automatic preparation (1-30, default 5)."},"require_accountant_approval":{"type":"boolean","description":"Read-only here (an owner sets it in the app): when true, only the commercialista approves a filing, and a receipt or protocol number waits for that approval."}},"required":["object","vat_periodicity","withholding_agent","oss_from","oss_until","auto_prepare","auto_prepare_days","require_accountant_approval"],"additionalProperties":false,"description":"null means not set yet (see missing_settings of the tax calendar)"},"UpdateTaxSettingsRequest":{"type":"object","properties":{"vat_periodicity":{"type":"string","enum":["monthly","quarterly"],"description":"How the company settles VAT (liquidazione mensile or trimestrale). It decides the VAT deadlines and periods."},"withholding_agent":{"type":"boolean","description":"Whether the company is a sostituto d’imposta (pays professionals and withholds ritenute): adds the 1040 F24 deadlines."},"oss_from":{"anyOf":[{"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"]},{"type":"null"}],"description":"The day the OSS union scheme applies from (Portale OSS registration; Reg. 282/2011 art. 57d). null: not registered (also clears oss_until). Adds the quarterly OSS return and payment deadlines."},"oss_until":{"anyOf":[{"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"]},{"type":"null"}],"description":"The day the OSS scheme stops applying (exit or exclusion). null: still registered."},"auto_prepare":{"type":"boolean","description":"Automatic preparation (default true): getbeel prepares the F24 of bollo, ritenute and periodic VAT auto_prepare_days days before the due date, once the period is over and the amount is known, and sends filing.ready. false: only reminders."},"auto_prepare_days":{"type":"integer","minimum":1,"maximum":30,"description":"Days before the due date for the automatic preparation (1-30, default 5)."}},"additionalProperties":false},"ReminderSettings":{"type":"object","properties":{"object":{"type":"string","const":"reminder_settings"},"enabled":{"type":"boolean"},"days":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"enabled_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}],"description":"When reminders were switched on: only invoices due on or after this day get them"}},"required":["object","enabled","days","enabled_at"],"additionalProperties":false},"UpdateReminderSettingsRequest":{"type":"object","properties":{"enabled":{"description":"Automatic payment reminders (solleciti) by email to customers of live overdue invoices","type":"boolean"},"days":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"integer","minimum":1,"maximum":365},"description":"Days after the due date when a reminder goes out (up to 5, e.g. [3, 10, 30])","examples":[[3,10,30]]}},"additionalProperties":false},"TaxProfile":{"type":"object","properties":{"object":{"type":"string","const":"tax_profile"},"legal_form":{"anyOf":[{"type":"string","enum":["srl","srls","spa","sapa","snc","sas","ditta_individuale","professionista","ente_non_commerciale","other"],"description":"srl, srls, spa, sapa (società di capitali: IRES), snc, sas, ditta_individuale, professionista (persone fisiche: IRPEF), ente_non_commerciale, other"},{"type":"null"}]},"regime_fiscale":{"description":"From the company profile (RF01 ordinario, RF19 forfettario…): changed there, confirmed here","type":["string","null"]},"vat_periodicity":{"anyOf":[{"type":"string","enum":["monthly","quarterly"]},{"type":"null"}]},"withholding_agent":{"type":["boolean","null"]},"has_employees":{"type":["boolean","null"]},"reverse_charge_suppliers":{"type":["boolean","null"]},"intrastat":{"type":["boolean","null"]},"oss_suggested":{"type":"boolean","description":"B2C sales to other EU countries above the €10,000 EU threshold (evidence only: the OSS registration is a separate setting)"},"oss_registered":{"description":"Registered in the OSS union scheme: read-only, from the tax settings (oss_from set: true; \"not registered\" answered on the profile: false; null: not answered). Set it with PATCH /companies/me/tax-settings (oss_from, oss_until), which also adds the quarterly OSS returns","type":["boolean","null"]},"in_liquidation":{"type":["boolean","null"]},"liquidation_from":{"anyOf":[{"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"]},{"type":"null"}]},"first_fiscal_year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"social_security":{"anyOf":[{"type":"string","enum":["gestione_separata","artigiani","commercianti","cassa_professionale","none"],"description":"Social security of a person: INPS gestione separata, artigiani, commercianti, a cassa professionale, or none"},{"type":"null"}]},"social_security_fund":{"type":["string","null"]},"is_person":{"type":"boolean","description":"A natural person (ditta individuale, professionista)"},"regimes":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["irpef_ordinario","forfettario","minimi","impatriati_2024","impatriati_legacy","rientro_docenti","neo_residenti"],"description":"irpef_ordinario, forfettario, minimi, impatriati_2024 (art. 5 D.Lgs. 209/2023), impatriati_legacy (art. 16 D.Lgs. 147/2015), rientro_docenti (art. 44 DL 78/2010), neo_residenti (art. 24-bis TUIR)"},"valid_from":{"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"],"description":"First day the regime applies"},"valid_until":{"anyOf":[{"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"]},{"type":"null"}]},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]}},"id":{"type":"string"},"source":{"type":"string","enum":["detected","user","api","mcp","ai"]},"effect":{"type":"object","properties":{"kind":{"type":"string","enum":["irpef_ordinario","forfettario","minimi","impatriati_2024","impatriati_legacy","rientro_docenti","neo_residenti"]},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The tax year it is computed for (the current one)"},"applies":{"type":"boolean"},"rate":{"anyOf":[{"type":"object","properties":{"value":{"type":"number"},"source":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","description":"Official source (normattiva, AdE, INPS)"},"article":{"type":"string"}},"required":["title","url","article"],"additionalProperties":false}},"required":["value","source"],"additionalProperties":false},{"type":"null"}],"description":"Substitute-tax rate, % (forfettario 15 or 5, minimi 5)"},"taxable_share":{"anyOf":[{"type":"object","properties":{"value":{"type":"number"},"source":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","description":"Official source (normattiva, AdE, INPS)"},"article":{"type":"string"}},"required":["title","url","article"],"additionalProperties":false}},"required":["value","source"],"additionalProperties":false},{"type":"null"}],"description":"Share of the eligible income that is taxed, % (impatriati; rientro docenti 10)"},"income_cap":{"anyOf":[{"type":"object","properties":{"value":{"type":"number"},"source":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","description":"Official source (normattiva, AdE, INPS)"},"article":{"type":"string"}},"required":["title","url","article"],"additionalProperties":false}},"required":["value","source"],"additionalProperties":false},{"type":"null"}],"description":"Yearly cap of the eligible income, € (impatriati from 2024)"},"ends_year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Last tax year of the regime (or of its current step, e.g. the 5% start-up rate)"},"tax_codes":{"anyOf":[{"type":"object","properties":{"first":{"type":"string"},"second":{"type":"string"},"balance":{"type":"string"}},"required":["first","second","balance"],"additionalProperties":false},{"type":"null"}],"description":"F24 codes of the substitute tax: acconti and saldo (neo-residenti: NRPP at the saldo, F24 ELIDE)"},"flat_tax":{"description":"Neo-residenti: the yearly flat tax on foreign income, € (by the transfer date, plus each family member)","anyOf":[{"type":"object","properties":{"value":{"type":"number"},"source":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","description":"Official source (normattiva, AdE, INPS)"},"article":{"type":"string"}},"required":["title","url","article"],"additionalProperties":false}},"required":["value","source"],"additionalProperties":false},{"type":"null"}]},"notes":{"type":"array","items":{"type":"string"},"description":"Stable keys: params_invalid, forfettario_startup_unknown, startup_years_from_regime_start, impatriati_legacy_before_2020, forfettario_startup_until, forfettario_startup_ended, step_ends, minimi_birth_year_missing, home_extension_only_2024, impatriati_professional_income_only, impatriati_legacy_extension, docenti_research_income_only, docenti_before_2020, neo_residenti_foreign_income_only, neo_residenti_transfer_assumed, not_computed"},"missing_rules":{"type":"array","items":{"type":"string"},"description":"Rule values getbeel does not have for this year (never guessed)"}},"required":["kind","year","applies","rate","taxable_share","income_cap","ends_year","tax_codes","notes","missing_rules"],"additionalProperties":false,"description":"Computed by getbeel from the regime and its params; read-only"}},"required":["kind","valid_from","valid_until","params","id","source","effect"],"additionalProperties":false}},"regime_warnings":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["key","params"],"additionalProperties":false},"description":"Mismatches between the RegimeFiscale of the company and the regimes in force: regime_code_mismatch (e.g. forfettario with RF01), regime_missing_for_code (RF19 without a forfettario regime), two_substitute_regimes, impatriati_with_forfettario (forfettario income cannot use the impatriati reduction), docenti_with_neo_residenti (not cumulable, L. 232/2016 c. 154), docenti_with_substitute_regime (forfettario or minimi income cannot use the docenti reduction)"},"sources":{"type":"object","propertyNames":{"type":"string","enum":["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"]},"additionalProperties":{"type":"string","enum":["user","detected","unknown","not_applicable"]},"required":["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"],"description":"Per field: user (set by you: wins), detected (high-confidence detection, applied), unknown (asked in questions or left out), not_applicable"},"confirmed":{"type":"object","propertyNames":{"type":"string","enum":["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"]},"additionalProperties":{"type":"object","properties":{"via":{"type":"string","enum":["user","api","mcp"]},"at":{"type":"string"}},"required":["via","at"],"additionalProperties":false},"required":["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"],"description":"Who confirmed each field, through what, when"},"detection":{"type":"object","properties":{"detected_at":{"type":["string","null"]},"fields":{"type":"object","propertyNames":{"type":"string","enum":["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"]},"additionalProperties":{"type":"object","properties":{"value":{"type":["string","number","boolean","null"]},"confidence":{"type":"string","enum":["high","low"],"description":"high: applied as detected until you confirm or change it; low: never applied, asked as a question"},"evidence":{"type":"object","properties":{"key":{"type":"string","description":"What the detection saw, as a stable key (e.g. legal_form_from_name, withholdings_found, oss_over_threshold)"},"params":{"description":"Values for the sentence (counts, amounts, names)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}}},"required":["key"],"additionalProperties":false},"held":{"description":"To check: the monthly re-detection found different data for a field you did not answer (e.g. no withholdings in the last 12 months). The value above stays applied until you answer it (PATCH the field, or confirm); this is what the new data say. getbeel never removes a deadline on its own.","type":"object","properties":{"value":{"type":["string","number","boolean","null"]},"confidence":{"type":"string","enum":["high","low"]},"evidence":{"type":"object","properties":{"key":{"type":"string","description":"What the detection saw, as a stable key (e.g. legal_form_from_name, withholdings_found, oss_over_threshold)"},"params":{"description":"Values for the sentence (counts, amounts, names)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}}},"required":["key"],"additionalProperties":false},"since":{"type":"string"}},"required":["value","confidence","evidence","since"],"additionalProperties":false}},"required":["value","confidence","evidence"],"additionalProperties":false},"required":["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"]}},"required":["detected_at","fields"],"additionalProperties":false},"questions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["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"]},"question":{"type":"string"}},"required":["field","question"],"additionalProperties":false},"description":"What to ask the user, once, in plain language. Never guess the answer: ask and PATCH it."}},"required":["object","legal_form","regime_fiscale","vat_periodicity","withholding_agent","has_employees","reverse_charge_suppliers","intrastat","oss_suggested","oss_registered","in_liquidation","liquidation_from","first_fiscal_year","social_security","social_security_fund","is_person","regimes","regime_warnings","sources","confirmed","detection","questions"],"additionalProperties":false,"description":"Values are the effective profile: yours, else a high-confidence detection, else null"},"UpdateTaxProfileRequest":{"type":"object","properties":{"legal_form":{"anyOf":[{"type":"string","enum":["srl","srls","spa","sapa","snc","sas","ditta_individuale","professionista","ente_non_commerciale","other"],"description":"srl, srls, spa, sapa (società di capitali: IRES), snc, sas, ditta_individuale, professionista (persone fisiche: IRPEF), ente_non_commerciale, other"},{"type":"null"}]},"vat_periodicity":{"anyOf":[{"type":"string","enum":["monthly","quarterly"]},{"type":"null"}]},"withholding_agent":{"description":"Pays professionals' fees with a ritenuta d'acconto (adds the monthly 1040 F24)","type":["boolean","null"]},"has_employees":{"description":"Has employees on payroll (adds the 1001 code to the monthly withholdings)","type":["boolean","null"]},"reverse_charge_suppliers":{"description":"Buys from suppliers outside Italy (reverse charge, autofatture TD17–TD19)","type":["boolean","null"]},"oss_registered":{"description":"Only false: \"not registered for the OSS\" (answers the question and clears oss_from / oss_until). To register, set oss_from with PATCH /companies/me/tax-settings","type":"boolean","const":false},"intrastat":{"description":"Files Intrastat lists (sales or purchases with other EU businesses)","type":["boolean","null"]},"in_liquidation":{"description":"The company is in liquidation (its deadlines from liquidation_from are flagged for review)","type":["boolean","null"]},"liquidation_from":{"description":"Only with in_liquidation: true","anyOf":[{"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"]},{"type":"null"}]},"first_fiscal_year":{"description":"First tax year of the business (no deadline of an earlier year is listed)","anyOf":[{"type":"integer","minimum":1900,"maximum":2100},{"type":"null"}]},"social_security":{"anyOf":[{"type":"string","enum":["gestione_separata","artigiani","commercianti","cassa_professionale","none"],"description":"Social security of a person: INPS gestione separata, artigiani, commercianti, a cassa professionale, or none"},{"type":"null"}]},"social_security_fund":{"description":"Name of the cassa (Cassa Forense, Inarcassa…), only with social_security: cassa_professionale","anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"regimes":{"description":"Replaces the special income tax regimes; [] or null: none (answers the special_regimes question)","anyOf":[{"maxItems":10,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["irpef_ordinario","forfettario","minimi","impatriati_2024","impatriati_legacy","rientro_docenti","neo_residenti"],"description":"irpef_ordinario, forfettario, minimi, impatriati_2024 (art. 5 D.Lgs. 209/2023), impatriati_legacy (art. 16 D.Lgs. 147/2015), rientro_docenti (art. 44 DL 78/2010), neo_residenti (art. 24-bis TUIR)"},"valid_from":{"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"],"description":"First day the regime applies"},"valid_until":{"description":"Last day it applies; null or missing: no end known","anyOf":[{"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"]},{"type":"null"}]},"params":{"type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"number"},{"type":"boolean"}]},"description":"Facts about the regime, typed per kind (unknown keys are refused); getbeel computes the numbers from them. forfettario: { \"startup\": true, \"activity_start_year\": 2024 } (start-up conditions of art. 1 c. 65 L. 190/2014: 5% for the start year and the four following; startup missing = not answered, no rate computed). minimi: { \"birth_year\": 1992 } (the regime lasts until the year you turn 35). impatriati_2024: { \"minor_child\": true, \"home_extension\": true }. impatriati_legacy: { \"south\": true, \"extension\": \"none\" | \"child_or_home\" (50%) | \"three_children\" (10%) }. rientro_docenti: { \"children\": 0, \"home\": false } (minor or dependent children and a home bought in Italy extend the regime, DL 78/2010 art. 44 c. 3-ter). neo_residenti: { \"transfer_date\": \"2025-10-01\", \"family_members\": 0 } (the transfer date sets the amount; default valid_from; each family member adds its flat tax, TUIR art. 24-bis c. 2). Other kinds: {}."}},"required":["kind","valid_from"],"additionalProperties":false}},{"type":"null"}]},"confirm":{"description":"Fields whose detected value you confirm as it is (e.g. [\"legal_form\"]); special_regimes confirms \"none\"","maxItems":13,"type":"array","items":{"type":"string","enum":["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"]}}},"additionalProperties":false,"description":"Changes only what it sends; null clears a value (back to the detection). Ask the user, never guess."},"TaxProfileDetection":{"type":"object","properties":{"object":{"type":"string","const":"tax_profile_detection"},"detected_at":{"type":"string"},"obligations":{"type":"array","items":{"type":"string","enum":["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"]},"description":"New obligations found by this run (a notice was added in the app)"},"changed":{"type":"array","items":{"type":"string","enum":["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"]},"description":"Fields whose detected value or confidence changed"},"held":{"type":"array","items":{"type":"string","enum":["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"]},"description":"Fields the new data would change in a way that removes or changes deadlines: kept as they were and marked held until you answer them"},"profile":{"$ref":"#/components/schemas/TaxProfile"}},"required":["object","detected_at","obligations","changed","held","profile"],"additionalProperties":false},"TaxRuleValue":{"type":"object","properties":{"object":{"type":"string","const":"tax_rule_value"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"key":{"type":"string","examples":["inps.maternity_yearly"]},"value":{"type":"number"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"valid_to":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"source_url":{"type":"string"},"source_title":{"type":"string"},"source_article":{"type":["string","null"]},"source_quote":{"description":"The sentence of the source that gives the value","type":["string","null"]},"quote_verified":{"type":"boolean","description":"The quote was found word for word in the source getbeel read (false for a PDF or a value typed by hand)"},"status":{"type":"string","enum":["pending","active","rejected"]},"proposed_via":{"type":"string","enum":["admin","api","mcp","ai"],"description":"Who added it: admin page, API, MCP, or the weekly rules watch (ai)"},"decided_at":{"type":["string","null"]},"decision_note":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["object","id","key","value","valid_from","valid_to","source_url","source_title","source_article","source_quote","quote_verified","status","proposed_via","decided_at","decision_note","created_at"],"additionalProperties":false},"TaxCalendarOverride":{"type":"object","properties":{"object":{"type":"string","const":"tax_calendar_override"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"deadline_kind":{"type":"string","enum":["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":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"nominal_to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"new_due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source_url":{"type":"string"},"source_title":{"type":"string"},"source_quote":{"type":["string","null"]},"quote_verified":{"type":"boolean"},"note":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","rejected"]},"proposed_via":{"type":"string","enum":["admin","api","mcp","ai"],"description":"Who added it: admin page, API, MCP, or the weekly rules watch (ai)"},"decided_at":{"type":["string","null"]},"notified_at":{"description":"When the teams whose deadlines it moves were told","type":["string","null"]},"created_at":{"type":"string"},"filings_updated":{"description":"Prepared, unpaid filings whose due date changed (on create and approve)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","id","deadline_kind","nominal_from","nominal_to","new_due_date","valid_from","source_url","source_title","source_quote","quote_verified","note","status","proposed_via","decided_at","notified_at","created_at"],"additionalProperties":false},"TaxRules":{"type":"object","properties":{"object":{"type":"string","const":"tax_rules"},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"rule_values":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"values":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The tax_rule_values id of a value added without a deploy (withdraw it with POST /v1/tax-rules/decisions); null for code values"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"valid_to":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"value":{"type":"number"},"origin":{"type":"string","enum":["code","db"],"description":"code: shipped with getbeel; db: added without a deploy"},"confirmed":{"type":"boolean","description":"false: not confirmed on a primary source for these dates (\"da verificare\", e.g. its law is repealed and the replacement was not read); results based on it are marked uncertain. Add the confirmed value with its source to replace it."},"source":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"},"article":{"type":"string"}},"required":["title","url","article"],"additionalProperties":false}},"required":["id","valid_from","valid_to","value","origin","confirmed","source"],"additionalProperties":false}}},"required":["key","values"],"additionalProperties":false},"description":"Every rule value, versioned by date"},"coverage":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"missing_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"publication":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"source":{"type":"string"},"expected_by":{"type":"string"}},"required":["prefix","source","expected_by"],"additionalProperties":false},{"type":"null"}]},"overdue":{"type":"boolean"}},"required":["key","missing_from","publication","overdue"],"additionalProperties":false},"description":"Values missing in the next 13 months"},"overrides":{"type":"array","items":{"$ref":"#/components/schemas/TaxCalendarOverride"},"description":"Proroghe in force"},"pending":{"anyOf":[{"type":"object","properties":{"rule_values":{"type":"array","items":{"$ref":"#/components/schemas/TaxRuleValue"}},"overrides":{"type":"array","items":{"$ref":"#/components/schemas/TaxCalendarOverride"}}},"required":["rule_values","overrides"],"additionalProperties":false},{"type":"null"}],"description":"Proposals waiting for approval: only for a live key of a getbeel administrator, null otherwise"},"watch_runs":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"week":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string"},"items_read":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"proposals":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error":{"type":["string","null"]},"started_at":{"type":"string"},"finished_at":{"type":["string","null"]}},"required":["week","status","items_read","proposals","error","started_at","finished_at"],"additionalProperties":false}},{"type":"null"}]}},"required":["object","today","rule_values","coverage","overrides","pending","watch_runs"],"additionalProperties":false},"TaxRuleDecision":{"type":"object","properties":{"object":{"type":"string","const":"tax_rule_decision"},"kind":{"type":"string","enum":["rule_value","override"]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["active","rejected"]},"decided_at":{"type":"string"},"filings_updated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rule_value":{"anyOf":[{"$ref":"#/components/schemas/TaxRuleValue"},{"type":"null"}]},"override":{"anyOf":[{"$ref":"#/components/schemas/TaxCalendarOverride"},{"type":"null"}]}},"required":["object","kind","id","status","decided_at","filings_updated","rule_value","override"],"additionalProperties":false},"CreateTaxRuleValueRequest":{"type":"object","properties":{"key":{"type":"string","description":"A rule key getbeel knows (GET /v1/tax-rules lists them), e.g. inps.maternity_yearly"},"value":{"type":"number","description":"In the unit of the key: a % as 26.07, euros as 4604.2"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day it applies (YYYY-MM-DD)"},"valid_to":{"description":"Last day it applies; null: until changed","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"source_url":{"type":"string","maxLength":500,"pattern":"^https:\\/\\/","description":"https link of the official source"},"source_title":{"type":"string","minLength":1,"maxLength":300,"description":"The act, e.g. INPS circolare n. 9 del 2 febbraio 2027"},"source_article":{"description":"Article, paragraph or section of the source","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"quote":{"description":"The sentence of the source that gives the value","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"status":{"default":"pending","type":"string","enum":["active","pending"]}},"required":["key","value","valid_from","source_url","source_title","status"],"additionalProperties":false},"CreateTaxCalendarOverrideRequest":{"type":"object","properties":{"deadline_kind":{"type":"string","enum":["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":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First legal (nominal) due date it moves (YYYY-MM-DD)"},"nominal_to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last legal due date it moves (the same day for one)"},"new_due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The new due date (YYYY-MM-DD); never earlier than nominal_to"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The day the act is in force (YYYY-MM-DD)"},"source_url":{"type":"string","maxLength":500,"pattern":"^https:\\/\\/","description":"https link of the official act"},"source_title":{"type":"string","minLength":1,"maxLength":300,"description":"The act, e.g. DPCM 12 giugno 2027, art. 1"},"quote":{"description":"The sentence of the act that moves the deadline","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"note":{"description":"Internal note","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"status":{"default":"pending","type":"string","enum":["active","pending"]}},"required":["deadline_kind","nominal_from","nominal_to","new_due_date","valid_from","source_url","source_title","status"],"additionalProperties":false},"DecideTaxRuleRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["rule_value","override"]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The proposal id (GET /v1/tax-rules → pending)"},"decision":{"type":"string","enum":["approve","reject","withdraw"]},"note":{"description":"Why (kept with the decision)","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]}},"required":["kind","id","decision"],"additionalProperties":false},"CreateFixedAssetRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"What the asset is, as it appears in the libro cespiti (fixed-asset register)","examples":["MacBook Pro 14\""]},"category_code":{"description":"A category of the DM 31/12/1988 table (GET /fixed-asset-categories); sets label, coefficient and kind. Omit it to give category_label and coefficient yourself","anyOf":[{"type":"string","enum":["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"]},{"type":"null"}]},"category_label":{"description":"Name of the asset category, when it is not in the DM 31/12/1988 table (give coefficient too). Overrides the label of category_code","examples":["Macchine d’ufficio elettroniche"],"type":"string","minLength":1,"maxLength":200},"coefficient":{"description":"Percent per year (ministerial coefficient), e.g. 20","type":"number","exclusiveMinimum":0,"maximum":100},"kind":{"type":"string","enum":["tangible","intangible"]},"cost":{"type":"string","pattern":"^\\d{1,11}\\.\\d{2}$","description":"Cost net of deductible VAT (costo fiscale)","examples":["1220.00"]},"purchase_date":{"description":"Date of the purchase; from the received invoice if omitted","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"]},"in_service_date":{"description":"Date it entered into function: depreciation starts that year (art. 102 c. 1). null = not in use yet","anyOf":[{"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"]},{"type":"null"}]},"first_year_half":{"description":"Halve the first year (default true; art. 102 c. 2). Intangibles are never halved","type":"boolean"},"expense_in_full":{"description":"Deduct a tangible asset of unit cost up to 516.46 in full in the year (art. 102 c. 5)","type":"boolean"},"depreciation_overrides":{"type":"object","propertyNames":{"type":"string","pattern":"^\\d{4}$"},"additionalProperties":{"anyOf":[{"type":"string","pattern":"^\\d{1,11}\\.\\d{2}$","description":"Decimal amount as a string","examples":["1220.00"]},{"type":"null"}]},"description":"Amount actually deducted in a year when less than the maximum (the coefficient is a ceiling, art. 102 c. 2 TUIR), e.g. {\"2027\": \"100.00\"}. Use it for assets depreciated before getbeel too. Merged per year with the saved ones; null removes a year."},"received_invoice_id":{"description":"The received invoice it was bought with (GET /received-invoices)","anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"supplier_name":{"description":"Name of the supplier the asset was bought from","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"document_number":{"description":"Number of the purchase invoice","anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"notes":{"description":"Free-text note, up to 1000 characters","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"disposal_date":{"description":"Sold or eliminated on this date (with disposal_amount)","anyOf":[{"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"]},{"type":"null"}]},"disposal_amount":{"description":"Sale price, \"0.00\" when eliminated","anyOf":[{"anyOf":[{"type":"string","pattern":"^\\d{1,11}\\.\\d{2}$","description":"Decimal amount as a string","examples":["1220.00"]},{"type":"string","const":"0.00"}]},{"type":"null"}]}},"required":["name","cost"],"additionalProperties":false},"UpdateFixedAssetRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"What the asset is, as it appears in the libro cespiti (fixed-asset register)","examples":["MacBook Pro 14\""]},"category_code":{"description":"A category of the DM 31/12/1988 table (GET /fixed-asset-categories); sets label, coefficient and kind. Omit it to give category_label and coefficient yourself","anyOf":[{"type":"string","enum":["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"]},{"type":"null"}]},"category_label":{"description":"Name of the asset category, when it is not in the DM 31/12/1988 table (give coefficient too). Overrides the label of category_code","examples":["Macchine d’ufficio elettroniche"],"type":"string","minLength":1,"maxLength":200},"coefficient":{"description":"Percent per year (ministerial coefficient), e.g. 20","type":"number","exclusiveMinimum":0,"maximum":100},"kind":{"type":"string","enum":["tangible","intangible"]},"cost":{"type":"string","pattern":"^\\d{1,11}\\.\\d{2}$","description":"Cost net of deductible VAT (costo fiscale)","examples":["1220.00"]},"purchase_date":{"description":"Date of the purchase; from the received invoice if omitted","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"]},"in_service_date":{"description":"Date it entered into function: depreciation starts that year (art. 102 c. 1). null = not in use yet","anyOf":[{"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"]},{"type":"null"}]},"first_year_half":{"description":"Halve the first year (default true; art. 102 c. 2). Intangibles are never halved","type":"boolean"},"expense_in_full":{"description":"Deduct a tangible asset of unit cost up to 516.46 in full in the year (art. 102 c. 5)","type":"boolean"},"depreciation_overrides":{"type":"object","propertyNames":{"type":"string","pattern":"^\\d{4}$"},"additionalProperties":{"anyOf":[{"type":"string","pattern":"^\\d{1,11}\\.\\d{2}$","description":"Decimal amount as a string","examples":["1220.00"]},{"type":"null"}]},"description":"Amount actually deducted in a year when less than the maximum (the coefficient is a ceiling, art. 102 c. 2 TUIR), e.g. {\"2027\": \"100.00\"}. Use it for assets depreciated before getbeel too. Merged per year with the saved ones; null removes a year."},"received_invoice_id":{"description":"The received invoice it was bought with (GET /received-invoices)","anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"supplier_name":{"description":"Name of the supplier the asset was bought from","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"document_number":{"description":"Number of the purchase invoice","anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"notes":{"description":"Free-text note, up to 1000 characters","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"disposal_date":{"description":"Sold or eliminated on this date (with disposal_amount)","anyOf":[{"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"]},{"type":"null"}]},"disposal_amount":{"description":"Sale price, \"0.00\" when eliminated","anyOf":[{"anyOf":[{"type":"string","pattern":"^\\d{1,11}\\.\\d{2}$","description":"Decimal amount as a string","examples":["1220.00"]},{"type":"string","const":"0.00"}]},{"type":"null"}]}},"additionalProperties":false},"FixedAsset":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"fixed_asset"},"name":{"type":"string"},"kind":{"type":"string","enum":["tangible","intangible"]},"category_code":{"type":["string","null"]},"category_label":{"type":"string"},"category_note":{"type":["string","null"]},"coefficient":{"type":"number"},"cost":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"purchase_date":{"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"]},"in_service_date":{"anyOf":[{"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"]},{"type":"null"}]},"first_year_half":{"type":"boolean"},"expense_in_full":{"type":"boolean"},"small_asset":{"type":"boolean","description":"Tangible with cost up to 516.46: may be deducted in full"},"depreciation_overrides":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"received_invoice_id":{"type":["string","null"]},"supplier_name":{"type":["string","null"]},"document_number":{"type":["string","null"]},"notes":{"type":["string","null"]},"status":{"type":"string","enum":["not_in_service","depreciating","fully_depreciated","disposed"]},"as_of_year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"accumulated_depreciation":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"residual_value":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"schedule":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"accumulated":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Fondo ammortamento after the year","examples":["122.00"]},"residual":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"kind":{"type":"string","enum":["depreciation","full_deduction"]},"overridden":{"type":"boolean"}},"required":["year","max_amount","amount","accumulated","residual","kind","overridden"],"additionalProperties":false}},"disposal":{"anyOf":[{"type":"object","properties":{"date":{"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"]},"price":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"residual":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Cost not depreciated when sold","examples":["122.00"]},"gain":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Positive: plusvalenza (art. 86); negative: minusvalenza (art. 101)","examples":["122.00"]}},"required":["date","price","residual","gain"],"additionalProperties":false},{"type":"null"}]},"warnings":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","object","name","kind","category_code","category_label","category_note","coefficient","cost","purchase_date","in_service_date","first_year_half","expense_in_full","small_asset","depreciation_overrides","received_invoice_id","supplier_name","document_number","notes","status","as_of_year","accumulated_depreciation","residual_value","schedule","disposal","warnings","created_at","updated_at"],"additionalProperties":false},"FixedAssetList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/FixedAsset"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"DeletedFixedAsset":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"fixed_asset"},"deleted":{"type":"boolean","const":true}},"required":["id","object","deleted"],"additionalProperties":false},"FixedAssetCategories":{"type":"object","properties":{"object":{"type":"string","const":"list"},"source":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"group":{"type":"string"},"label":{"type":"string"},"coefficient":{"type":"number"},"kind":{"type":"string","enum":["tangible","intangible"]},"note":{"type":["string","null"]}},"required":["code","group","label","coefficient","kind","note"],"additionalProperties":false}}},"required":["object","source","data"],"additionalProperties":false},"FixedAssetsRegister":{"type":"object","properties":{"object":{"type":"string","const":"fixed_assets_register"},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lines":{"type":"array","items":{"type":"object","properties":{"asset_id":{"type":"string"},"name":{"type":"string"},"category_label":{"type":"string"},"coefficient":{"type":"number"},"purchase_date":{"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"]},"in_service_date":{"anyOf":[{"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"]},{"type":"null"}]},"cost":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"opening_accumulated":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"kind":{"anyOf":[{"type":"string","enum":["depreciation","full_deduction"]},{"type":"null"}]},"closing_accumulated":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"residual":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"disposal":{"anyOf":[{"type":"object","properties":{"date":{"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"]},"price":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"residual":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Cost not depreciated when sold","examples":["122.00"]},"gain":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Positive: plusvalenza (art. 86); negative: minusvalenza (art. 101)","examples":["122.00"]}},"required":["date","price","residual","gain"],"additionalProperties":false},{"type":"null"}]}},"required":["asset_id","name","category_label","coefficient","purchase_date","in_service_date","cost","opening_accumulated","amount","kind","closing_accumulated","residual","disposal"],"additionalProperties":false}},"totals":{"type":"object","properties":{"cost":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"depreciation":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"full_deduction":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"gains":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"losses":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["cost","depreciation","full_deduction","gains","losses"],"additionalProperties":false},"by_category":{"type":"array","items":{"type":"object","properties":{"category_label":{"type":"string"},"kind":{"type":"string","enum":["tangible","intangible"]},"depreciation":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"full_deduction":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["category_label","kind","depreciation","full_deduction"],"additionalProperties":false}},"closing_entries":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"debit":{"type":"string"},"credit":{"type":"string"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["description","debit","credit","amount"],"additionalProperties":false},"description":"Summary of the year’s closing entries for the accountant (no general ledger in getbeel)"},"reliable":{"type":"boolean","const":false},"note":{"type":"string"}},"required":["object","year","lines","totals","by_category","closing_entries","reliable","note"],"additionalProperties":false},"SaveTaxEstimateRequest":{"type":"object","properties":{"year":{"type":"integer","minimum":2000,"maximum":2100,"description":"Tax year these inputs are for, e.g. 2026"},"entity":{"description":"company: società di capitali (IRES + IRAP); forfettario: regime forfettario (imposta sostitutiva + INPS); irpef: persona fisica in regime ordinario (IRPEF by bracket, detrazione lavoro autonomo, addizionali, INPS; the impatriati reduction from the tax profile); minimi: regime di vantaggio (5% substitute tax on income collected minus costs and INPS, codes 1793/1794/1795); other: not estimated","type":"string","enum":["company","forfettario","irpef","minimi","other"]},"other_revenue":{"description":"Revenue of the year not in getbeel’s issued invoices (e.g. corrispettivi), in euros as a number or a decimal string. Default 0","type":"number","minimum":0,"maximum":10000000000},"other_costs":{"description":"Costs of the year without an invoice in getbeel (rent, insurance, bank fees…), in euros as a number or a decimal string. Default 0","type":"number","minimum":0,"maximum":10000000000},"personnel_costs":{"description":"Company: all personnel costs of the year, in euros as a number or a decimal string (deducted for IRES). Default 0","type":"number","minimum":0,"maximum":10000000000},"permanent_staff_costs":{"description":"Permanent staff costs, deductible from the IRAP base","type":"number","minimum":0,"maximum":10000000000},"ires_adjustments":{"description":"Variazioni fiscali: + non-deductible costs, − exempt income","type":"number","minimum":-10000000000,"maximum":10000000000},"irap_rate":{"description":"IRAP rate of the region (default 3.9)","type":"number","minimum":0,"maximum":10},"isa_subject":{"type":"boolean"},"prior_year_ires":{"description":"Company: IRES (corporate income tax) of the previous year in euros. When given, the acconti are computed on it (historical method); null: on this year’s estimate","anyOf":[{"type":"number","minimum":0,"maximum":10000000000},{"type":"null"}]},"prior_year_irap":{"description":"Company: IRAP (regional production tax) of the previous year in euros. When given, the acconti are computed on it (historical method); null: on this year’s estimate","anyOf":[{"type":"number","minimum":0,"maximum":10000000000},{"type":"null"}]},"ateco_code":{"description":"Forfettario: ATECO code of the activity (Italian classification of economic activities), used to find the forfettario group when forfettario_group is not given","examples":["62.01","69.20.11"],"anyOf":[{"type":"string","pattern":"^\\d{2}(\\.\\d{1,2}(\\.\\d{1,2})?)?$"},{"type":"null"}]},"forfettario_group":{"description":"Forfettario: activity group 1–9 of the coefficients of profitability table (L. 190/2014, allegato 4). Takes precedence over ateco_code","anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}]},"startup_rate":{"description":"5% substitute tax for the first five years (c. 65)","type":"boolean"},"revenue_basis":{"type":"string","enum":["collected","invoiced"]},"inps_scheme":{"type":"string","enum":["gestione_separata","artigiani","commercianti","cassa_professionale","none"]},"inps_reduction_35":{"type":"boolean"},"insured_before_1996":{"type":"boolean"},"inps_amount_override":{"description":"Forfettario: the yearly social-security contributions in euros, when getbeel should not compute them (e.g. a cassa professionale). null: computed from inps_scheme","anyOf":[{"type":"number","minimum":0,"maximum":10000000000},{"type":"null"}]},"contributions_paid":{"description":"Forfettario: social-security contributions actually paid in the year, in euros, deducted from the income (cash basis). null: the estimated contributions are assumed","anyOf":[{"type":"number","minimum":0,"maximum":10000000000},{"type":"null"}]},"prior_year_substitute_tax":{"description":"Forfettario and minimi: imposta sostitutiva (the flat tax replacing income tax) of the previous year in euros (minimi: Redditi PF rigo LM42). When given, the acconti are computed on it (historical method); null: on this year’s estimate","anyOf":[{"type":"number","minimum":0,"maximum":10000000000},{"type":"null"}]},"irpef_activity":{"description":"IRPEF (persona fisica, regime ordinario): professional = lavoro autonomo (quadro RE), business = impresa individuale (RF/RG, contabilità semplificata assumed). The impatriati regime from 2024 only reduces professional income","type":"string","enum":["professional","business"]},"regional_surcharge_rate":{"description":"IRPEF: addizionale regionale of the region of residence, % (base 1.23; regions add up to 2.1 points; MEF Dipartimento Finanze tables). null: the base rate of the year, with a warning","anyOf":[{"type":"number","minimum":0,"maximum":5},{"type":"null"}]},"municipal_surcharge_rate":{"description":"IRPEF: addizionale comunale of the comune of residence, % (0 to 0.9). null: unknown, counted as 0 with a warning","anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]},"prior_year_irpef":{"description":"IRPEF: last year’s “Differenza” (Redditi PF rigo RN34: imposta netta minus ritenute) in euros. When given, the acconti (4033/4034) are computed on it (historical method); null: on this year’s estimate","anyOf":[{"type":"number","minimum":0,"maximum":10000000000},{"type":"null"}]},"withholdings_suffered":{"description":"IRPEF: ritenute d’acconto suffered in the year in euros (the clients’ 20% withholding), subtracted from the net IRPEF. null: the RT01 ritenute of the invoice payments recorded in getbeel","anyOf":[{"type":"number","minimum":0,"maximum":10000000000},{"type":"null"}]},"minimi_prior_losses":{"description":"Minimi: losses of earlier years still usable (Redditi PF rigo LM9 col. 3: the regime’s losses of the last five years, the first three years’ without time limit), in euros. Default 0","type":"number","minimum":0,"maximum":10000000000}},"required":["year"],"additionalProperties":false},"TaxEstimate":{"type":"object","properties":{"object":{"type":"string","const":"tax_estimate"},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"entity":{"type":"string","enum":["company","forfettario","irpef","minimi","other"]},"label":{"type":"string","examples":["Stima, da verificare con il commercialista"]},"reliable":{"type":"boolean","const":false},"inputs":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"inputs_saved":{"type":"boolean"},"figures":{"type":"object","properties":{"revenue_invoiced":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"revenue_collected":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"withholdings_collected":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Ritenute d’acconto IRPEF (RT01) on the payments of the year: the IRPEF default for withholdings_suffered","examples":["122.00"]},"costs_invoiced":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"asset_purchases":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Part of the year’s received invoices bought as fixed assets (not in costs_invoiced): the minimi deduct it in full","examples":["122.00"]},"depreciation":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"full_deduction":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"gains":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"losses":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"invoices_issued":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"invoices_received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unreviewed_received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped_foreign_currency":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["revenue_invoiced","revenue_collected","withholdings_collected","costs_invoiced","asset_purchases","depreciation","full_deduction","gains","losses","invoices_issued","invoices_received","unreviewed_received","skipped_foreign_currency"],"additionalProperties":false},"profit_before_tax":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"ires":{"anyOf":[{"type":"object","properties":{"base":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"rate":{"type":"number"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["base","rate","amount"],"additionalProperties":false},{"type":"null"}]},"irap":{"anyOf":[{"type":"object","properties":{"base":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"rate":{"type":"number"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["base","rate","amount"],"additionalProperties":false},{"type":"null"}]},"forfettario":{"anyOf":[{"type":"object","properties":{"revenue":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"group":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"coefficient":{"type":["number","null"]},"gross_income":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"contributions_deducted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"taxable_income":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"rate":{"type":"number"},"rate_source":{"type":"string","enum":["profile","inputs"]},"substitute_tax":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["revenue","group","coefficient","gross_income","contributions_deducted","taxable_income","rate","substitute_tax"],"additionalProperties":false},{"type":"null"}]},"flat_tax":{"description":"Neo-residenti (TUIR art. 24-bis, from the tax profile): paid in one go on F24 ELIDE, code NRPP, by the saldo date. It does not change the partita IVA income tax","anyOf":[{"type":"object","properties":{"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Neo-residenti flat tax on foreign income for the year (person + family members), by the transfer date","examples":["122.00"]},"family_members":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"}},"required":["amount","family_members","source"],"additionalProperties":false},{"type":"null"}]},"minimi":{"anyOf":[{"type":"object","properties":{"revenue":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"LM2: collected in the year","examples":["122.00"]},"costs":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"LM5: expenses, fixed assets in full in the year bought","examples":["122.00"]},"gross_income":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"LM6 (negative: a loss)","examples":["122.00"]},"contributions_deducted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"LM7 col. 2: INPS deducted, up to LM6","examples":["122.00"]},"contributions_excess":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"LM49: INPS above LM6, deductible in quadro RP","examples":["122.00"]},"losses_used":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"LM9 col. 3","examples":["122.00"]},"taxable_income":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"LM10","examples":["122.00"]},"rate":{"type":"number"},"rate_source":{"type":"string","enum":["profile","rule"]},"substitute_tax":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"LM11 (= LM42)","examples":["122.00"]}},"required":["revenue","costs","gross_income","contributions_deducted","contributions_excess","losses_used","taxable_income","rate","rate_source","substitute_tax"],"additionalProperties":false},{"type":"null"}]},"irpef":{"anyOf":[{"type":"object","properties":{"income":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Revenue minus costs of the year","examples":["122.00"]},"impatriati_share":{"description":"Impatriati (tax profile): the share of the eligible income that is taxed, %; null: none","type":["number","null"]},"reduction_kind":{"description":"Which tax-profile regime reduced the income: impatriati (2024 or legacy) or rientro docenti (10% taxed, DL 78/2010 art. 44)","anyOf":[{"type":"string","enum":["impatriati_2024","impatriati_legacy","rientro_docenti"]},{"type":"null"}]},"reddito_complessivo":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Reddito complessivo (RN1): the income after the impatriati reduction, before the deductible contributions; the base of the detrazione","examples":["122.00"]},"contributions_deducted":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"taxable_income":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Reddito imponibile (RN4): complessivo minus INPS; the base of the brackets and the addizionali","examples":["122.00"]},"gross_tax":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"IRPEF by bracket (TUIR art. 11)","examples":["122.00"]},"deduction":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Detrazione lavoro autonomo (TUIR art. 13 c. 5)","examples":["122.00"]},"net_tax":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"withholdings":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Ritenute d’acconto suffered (RN33)","examples":["122.00"]},"tax_due":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Differenza (RN34): net tax minus ritenute; negative is a credit","examples":["122.00"]},"regional_surcharge":{"type":"object","properties":{"rate":{"type":"number"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["rate","amount"],"additionalProperties":false,"description":"Addizionale regionale (F24 3801): 0 when no net IRPEF is due (D.Lgs. 446/1997 art. 50 c. 2)"},"municipal_surcharge":{"type":"object","properties":{"rate":{"type":["number","null"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["rate","amount"],"additionalProperties":false},"second_rate":{"type":"number","description":"35 in 2025, 33 from 2026"}},"required":["income","impatriati_share","reddito_complessivo","contributions_deducted","taxable_income","gross_tax","deduction","net_tax","withholdings","tax_due","regional_surcharge","municipal_surcharge","second_rate"],"additionalProperties":false},{"type":"null"}]},"inps":{"anyOf":[{"type":"object","properties":{"scheme":{"type":"string","enum":["gestione_separata","artigiani","commercianti","cassa_professionale","none"]},"base":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"fixed_part":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"reduction_applied":{"type":"boolean"}},"required":["scheme","base","amount","fixed_part","reduction_applied"],"additionalProperties":false},{"type":"null"}]},"total_taxes":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"installments":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["first_advance","second_advance","balance","next_first_advance"]},"tax_year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tax":{"type":"string","enum":["ires","irap","substitute_tax","irpef","regional_surcharge","municipal_surcharge","minimi_substitute_tax","neo_residenti_flat_tax"]},"tax_code":{"type":"string","description":"F24 codice tributo"},"due_date":{"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"]},"late_due_date":{"anyOf":[{"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"]},{"type":"null"}],"description":"With the 0.40% increase (saldo and first acconto)"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Negative balance: a credit","examples":["122.00"]},"confirmed":{"type":"boolean","description":"False when the date is not confirmed in a source in force yet"},"note":{"description":"In Italian","type":["string","null"]},"note_code":{"anyOf":[{"type":"string","enum":["estimated_advances","credit","municipal_advance_estimated","neo_residenti_elide"]},{"type":"null"}],"description":"The note as a code: estimated_advances (on this year’s estimate), credit (negative saldo), municipal_advance_estimated"}},"required":["key","tax_year","tax","tax_code","due_date","late_due_date","amount","confirmed","note","note_code"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["object","year","entity","label","reliable","inputs","inputs_saved","figures","profit_before_tax","ires","irap","forfettario","inps","total_taxes","installments","warnings","sources"],"additionalProperties":false},"CreatePosRtLinkRequest":{"type":"object","properties":{"label":{"description":"Your own name for the till, e.g. \"Cassa 1\"","anyOf":[{"type":"string","minLength":1,"maxLength":100,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$"},{"type":"null"}]},"rt_serial":{"type":"string","pattern":"^[A-Za-z0-9]{1,30}$","description":"Matricola of the RT or Server RT (CSV Matricola)","examples":["99IEY928374"]},"acquirer_country":{"default":"IT","description":"TipoAcquirer: IT italiano, ES estero","type":"string","enum":["IT","ES"]},"acquirer_id":{"type":"string","pattern":"^[A-Za-z0-9]{1,30}$","description":"IdentificativoAcquirer: the acquirer’s Italian codice fiscale (11 digits, leading zeros kept)","examples":["04107060966"]},"acquirer_name":{"type":"string","minLength":1,"maxLength":200,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$","description":"DenominazioneAcquirer","examples":["NEXI PAYMENTS S.P.A."]},"pos_type":{"type":"string","enum":["00","01"],"description":"TipoPos: 00 physical (incl. SoftPOS), 01 virtual"},"terminal_id":{"description":"TerminalId of the POS terminal: required when pos_type is 00 (physical), ignored when it is 01 (virtual)","anyOf":[{"type":"string","pattern":"^[A-Za-z0-9._/-]{1,50}$"},{"type":"null"}]},"contract_number":{"type":"string","pattern":"^[A-Za-z0-9._/-]{1,50}$","description":"Convenzione: number of the contract with the acquirer"},"itinerant":{"default":false,"description":"Ambulante: the RT is always used itinerant (no address)","type":"boolean"},"province":{"description":"Two-letter province code (sigla) of the place where the RT is used (CSV UbicazioneProv). Required unless itinerant","examples":["MI"],"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}]},"municipality":{"description":"Municipality (comune) where the RT is used (CSV UbicazioneComune). Required unless itinerant","examples":["Milano"],"anyOf":[{"type":"string","minLength":1,"maxLength":100,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$"},{"type":"null"}]},"street":{"description":"Street of the unità locale where the RT is used (CSV UbicazioneIndirizzo). Required unless itinerant","examples":["Via Roma"],"anyOf":[{"type":"string","minLength":1,"maxLength":100,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$"},{"type":"null"}]},"street_number":{"description":"Street number (CSV UbicazioneCivico). Required unless itinerant","examples":["1"],"anyOf":[{"type":"string","minLength":1,"maxLength":10,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$"},{"type":"null"}]},"postal_code":{"description":"Five-digit CAP (CSV UbicazioneCap). Required unless itinerant","examples":["20121"],"anyOf":[{"type":"string","pattern":"^\\d{5}$"},{"type":"null"}]},"active_from":{"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"],"description":"First day the POS was used with this RT (sets the deadline)"},"ended_on":{"description":"Last day of use: the link is ended (CSV operation C, DataFine)","anyOf":[{"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"]},{"type":"null"}]}},"required":["rt_serial","acquirer_country","acquirer_id","acquirer_name","pos_type","contract_number","itinerant","active_from"],"additionalProperties":false},"UpdatePosRtLinkRequest":{"type":"object","properties":{"label":{"description":"Your own name for the till, e.g. \"Cassa 1\"","anyOf":[{"type":"string","minLength":1,"maxLength":100,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$"},{"type":"null"}]},"rt_serial":{"type":"string","pattern":"^[A-Za-z0-9]{1,30}$","description":"Matricola of the RT or Server RT (CSV Matricola)","examples":["99IEY928374"]},"acquirer_country":{"type":"string","enum":["IT","ES"]},"acquirer_id":{"type":"string","pattern":"^[A-Za-z0-9]{1,30}$","description":"IdentificativoAcquirer: the acquirer’s Italian codice fiscale (11 digits, leading zeros kept)","examples":["04107060966"]},"acquirer_name":{"type":"string","minLength":1,"maxLength":200,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$","description":"DenominazioneAcquirer","examples":["NEXI PAYMENTS S.P.A."]},"pos_type":{"type":"string","enum":["00","01"],"description":"TipoPos: 00 physical (incl. SoftPOS), 01 virtual"},"terminal_id":{"description":"TerminalId of the POS terminal: required when pos_type is 00 (physical), ignored when it is 01 (virtual)","anyOf":[{"type":"string","pattern":"^[A-Za-z0-9._/-]{1,50}$"},{"type":"null"}]},"contract_number":{"type":"string","pattern":"^[A-Za-z0-9._/-]{1,50}$","description":"Convenzione: number of the contract with the acquirer"},"itinerant":{"type":"boolean"},"province":{"description":"Two-letter province code (sigla) of the place where the RT is used (CSV UbicazioneProv). Required unless itinerant","examples":["MI"],"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}]},"municipality":{"description":"Municipality (comune) where the RT is used (CSV UbicazioneComune). Required unless itinerant","examples":["Milano"],"anyOf":[{"type":"string","minLength":1,"maxLength":100,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$"},{"type":"null"}]},"street":{"description":"Street of the unità locale where the RT is used (CSV UbicazioneIndirizzo). Required unless itinerant","examples":["Via Roma"],"anyOf":[{"type":"string","minLength":1,"maxLength":100,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$"},{"type":"null"}]},"street_number":{"description":"Street number (CSV UbicazioneCivico). Required unless itinerant","examples":["1"],"anyOf":[{"type":"string","minLength":1,"maxLength":10,"pattern":"^(?![=+\\-@])[^;\"\\r\\n\\t]*$"},{"type":"null"}]},"postal_code":{"description":"Five-digit CAP (CSV UbicazioneCap). Required unless itinerant","examples":["20121"],"anyOf":[{"type":"string","pattern":"^\\d{5}$"},{"type":"null"}]},"active_from":{"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"]},"ended_on":{"description":"Last day of use: the link is ended (CSV operation C, DataFine)","anyOf":[{"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"]},{"type":"null"}]}},"additionalProperties":false},"MarkPosRtFiledRequest":{"type":"object","properties":{"links":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^prl_[0-9a-f]{32}$","description":"POS–RT link id: prl_ followed by 32 hex characters, from the list of POS–RT links","examples":["prl_0123456789abcdef0123456789abcdef"]},"operation":{"type":"string","enum":["I","C"]}},"required":["id","operation"],"additionalProperties":false},"description":"The rows of the uploaded file (links of the export): only a link whose pending operation is still the one given is marked"}},"required":["links"],"additionalProperties":false},"PosRtLink":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"pos_rt_link"},"label":{"type":["string","null"]},"rt_serial":{"type":"string"},"acquirer_country":{"type":"string","enum":["IT","ES"]},"acquirer_id":{"type":"string"},"acquirer_name":{"type":"string"},"pos_type":{"type":"string","enum":["00","01"]},"terminal_id":{"type":["string","null"]},"contract_number":{"type":"string"},"itinerant":{"type":"boolean"},"province":{"type":["string","null"]},"municipality":{"type":["string","null"]},"street":{"type":["string","null"]},"street_number":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"active_from":{"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"]},"ended_on":{"anyOf":[{"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"]},{"type":"null"}]},"status":{"type":"string","enum":["to_file","filed","end_to_file","ended"]},"pending":{"anyOf":[{"type":"object","properties":{"operation":{"type":"string","enum":["I","C"]},"from":{"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"]},"due":{"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"],"description":"Last working day of the window"},"not_late_until":{"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"]},"reference_month":{"type":"string"},"initial_window":{"type":"boolean"}},"required":["operation","from","due","not_late_until","reference_month","initial_window"],"additionalProperties":false},{"type":"null"}],"description":"What is still to communicate to the AdE, and by when"},"linked_filed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"end_filed_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","object","label","rt_serial","acquirer_country","acquirer_id","acquirer_name","pos_type","terminal_id","contract_number","itinerant","province","municipality","street","street_number","postal_code","active_from","ended_on","status","pending","linked_filed_at","end_filed_at","created_at","updated_at"],"additionalProperties":false},"DeletedPosRtLink":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"pos_rt_link"},"deleted":{"type":"boolean","const":true}},"required":["id","object","deleted"],"additionalProperties":false},"PosRtLinkList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PosRtLink"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"PosRtExport":{"type":"object","properties":{"object":{"type":"string","const":"pos_rt_export"},"file_name":{"type":"string"},"part":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"operation":{"type":"string","enum":["I","C"]}},"required":["id","operation"],"additionalProperties":false}},"columns":{"type":"array","items":{"type":"string"}},"csv":{"type":"string"},"tsv":{"type":"string","description":"The same rows tab-separated, to paste into the AdE template"},"layout":{"type":"object","properties":{"official":{"type":"array","items":{"type":"string"}},"not_confirmed":{"type":"array","items":{"type":"string"}}},"required":["official","not_confirmed"],"additionalProperties":false},"next_steps":{"type":"object","properties":{"deep_link":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["deep_link","steps","sources"],"additionalProperties":false}},"required":["object","file_name","part","parts","rows","links","columns","csv","tsv","layout","next_steps"],"additionalProperties":false},"MarkPosRtFiledResponse":{"type":"object","properties":{"object":{"type":"string","const":"pos_rt_filed"},"updated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"data":{"type":"array","items":{"$ref":"#/components/schemas/PosRtLink"}}},"required":["object","updated","data"],"additionalProperties":false},"SetVatAdjustmentRequest":{"type":"object","properties":{"action":{"type":"string","enum":["exclude","adjust"],"description":"exclude: the row does not enter the liquidazione. adjust: vat_amount is the VAT that counts instead."},"vat_amount":{"description":"Required for adjust: the VAT of the row that counts","examples":["122.00"],"anyOf":[{"type":"string","pattern":"^-?\\d{1,9}(\\.\\d{1,2})?$"},{"type":"null"}]},"reason":{"type":"string","minLength":3,"maxLength":500,"description":"Why (kept with the row for the accountant), e.g. \"IVA indetraibile al 60% (auto aziendale)\""}},"required":["action","reason"],"additionalProperties":false},"VatAdjustment":{"type":"object","properties":{"object":{"type":"string","const":"vat_adjustment"},"key":{"type":"string"},"register":{"type":"string","enum":["sales","purchases"]},"source":{"type":"string","enum":["issued_invoice","received_invoice","autofattura"]},"document_id":{"type":"string"},"action":{"type":"string","enum":["exclude","adjust"]},"vat_amount":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}]},"reason":{"type":"string"}},"required":["object","key","register","source","document_id","action","vat_amount","reason"],"additionalProperties":false},"DeletedVatAdjustment":{"type":"object","properties":{"object":{"type":"string","const":"vat_adjustment"},"key":{"type":"string"},"deleted":{"type":"boolean","description":"false when the row had no adjustment"}},"required":["object","key","deleted"],"additionalProperties":false},"CreateWithholdingRequest":{"type":"object","properties":{"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300,"description":"Full name or company name of the recipient","examples":["Mario Rossi"]},"fiscal_code":{"description":"Codice fiscale of the percipiente: the CU needs it","type":"string","pattern":"^[A-Z0-9]{11,16}$","examples":["RSSMRA80A01F205X"]},"vat":{"description":"Partita IVA (VAT number) of the recipient","type":"string","maxLength":30}},"required":["name"],"additionalProperties":false,"description":"The percipiente: the professional or agent the fee is paid to"},"document":{"description":"The invoice, parcella or notula (receipt for occasional work) the fee is billed on","type":"object","properties":{"number":{"description":"Number of that document, as printed on it","type":"string","maxLength":50},"date":{"description":"Date of that document (YYYY-MM-DD)","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"]}},"additionalProperties":false},"invoice_id":{"description":"The received invoice (GET /received-invoices) it pays","type":"string","minLength":1,"maxLength":100},"type":{"default":"RT01","description":"RT01 natural person, RT02 company or other entity","type":"string","enum":["RT01","RT02"]},"causale":{"default":"A","type":"string","enum":["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"],"description":"CU causale (punto 1): A lavoro autonomo abituale, M occasionale, Q/R provvigioni agente mono/plurimandatario, … (CU 2026 instructions)"},"rate":{"description":"Decimal string (or number)","examples":["20"]},"gross_amount":{"description":"Ammontare lordo (CU punto 4): the fee net of VAT, without the contributo integrativo of the professional funds","examples":["1000.00"]},"not_subject_amount":{"description":"Sums not subject to the ritenuta (CU punto 7), e.g. expenses advanced for you, the 50% of provvigioni. Default 0","examples":["100.00"]},"withheld_amount":{"description":"Ritenuta withheld (CU punto 9). Omit to compute (gross − not subject) × rate","examples":["100.00"]},"paid_on":{"description":"The day the fee was paid: the ritenuta is made then (art. 25 DPR 600/1973) and paid with F24 1040 by the 16th of the next month","anyOf":[{"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"]},{"type":"null"}]},"notes":{"description":"Free-text note, up to 500 characters","type":"string","maxLength":500}},"required":["recipient","type","causale","rate","gross_amount"],"additionalProperties":false},"UpdateWithholdingRequest":{"type":"object","properties":{"recipient":{"description":"The percipiente: the professional or agent the fee is paid to; only the fields sent change","type":"object","properties":{"name":{"description":"Full name or company name of the recipient","type":"string","minLength":1,"maxLength":300},"fiscal_code":{"description":"Codice fiscale of the percipiente: 16 characters for a person, 11 digits for a company (null clears it)","anyOf":[{"type":"string","pattern":"^[A-Z0-9]{11,16}$","description":"Codice fiscale (Italian tax code) of the percipiente, the professional or agent paid: 16 characters for a person, 11 digits for a company. The CU needs it","examples":["RSSMRA80A01F205X"]},{"type":"null"}]},"vat":{"description":"Partita IVA (VAT number) of the recipient (null clears it)","anyOf":[{"type":"string","maxLength":30},{"type":"null"}]}},"additionalProperties":false},"document":{"description":"The invoice, parcella or notula (receipt for occasional work) the fee is billed on; only the fields sent change","type":"object","properties":{"number":{"description":"Number of that document, as printed on it (null clears it)","anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"date":{"description":"Date of that document (YYYY-MM-DD) (null clears it)","anyOf":[{"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"]},{"type":"null"}]}},"additionalProperties":false},"invoice_id":{"description":"The received invoice (GET /received-invoices) it pays; null unlinks it","anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"type":{"type":"string","enum":["RT01","RT02"]},"causale":{"type":"string","enum":["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"],"description":"CU causale (punto 1): A lavoro autonomo abituale, M occasionale, Q/R provvigioni agente mono/plurimandatario, … (CU 2026 instructions)"},"rate":{"description":"Decimal string (or number)","examples":["100.00"]},"gross_amount":{"description":"Decimal string (or number)","examples":["100.00"]},"not_subject_amount":{"description":"Decimal string (or number)","examples":["100.00"]},"withheld_amount":{"description":"Omit when changing the rate or the amounts to recompute it","examples":["100.00"]},"paid_on":{"description":"The day the fee was paid (null: not paid yet)","anyOf":[{"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"]},{"type":"null"}]},"notes":{"description":"Free-text note, up to 500 characters (null clears it)","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"remitted":{"description":"true: the ritenuta was paid with the month’s withholdings F24 already recorded as paid (e.g. prepared with a typed amount): links it to that F24 and locks it. 409 no_paid_filing when there is none","type":"boolean","const":true}},"additionalProperties":false},"Withholding":{"type":"object","properties":{"id":{"type":"string","examples":["wht_3f2a…"]},"object":{"type":"string","const":"withholding"},"source":{"type":"string","enum":["sdi","manual"],"description":"sdi: read from the DatiRitenuta of an invoice received from SDI; manual: typed in"},"invoice_id":{"type":["string","null"]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"fiscal_code":{"type":["string","null"]},"vat":{"type":["string","null"]}},"required":["name","fiscal_code","vat"],"additionalProperties":false},"document":{"type":"object","properties":{"number":{"type":["string","null"]},"date":{"anyOf":[{"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"]},{"type":"null"}]}},"required":["number","date"],"additionalProperties":false},"type":{"type":"string","enum":["RT01","RT02"]},"causale":{"type":"string"},"rate":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"gross_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"CU punto 4","examples":["122.00"]},"not_subject_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"CU punto 7","examples":["122.00"]},"taxable_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"CU punto 8","examples":["122.00"]},"withheld_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"CU punto 9","examples":["122.00"]},"tax_code":{"type":"string","const":"1040"},"paid_on":{"anyOf":[{"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"]},{"type":"null"}]},"period":{"description":"Month the ritenuta was made (the month of paid_on)","type":["string","null"]},"status":{"type":"string","enum":["unpaid","withheld","remitted"]},"due_date":{"anyOf":[{"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"]},{"type":"null"}],"description":"F24 deadline: the 16th of the next month, moved off holidays"},"overdue":{"type":"boolean"},"filing_id":{"description":"The withholdings F24 that paid it (status remitted)","type":["string","null"]},"needs_review":{"type":"boolean","description":"Read from an invoice whose figures need a check (notes says why)"},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","object","source","invoice_id","recipient","document","type","causale","rate","gross_amount","not_subject_amount","taxable_amount","withheld_amount","tax_code","paid_on","period","status","due_date","overdue","filing_id","needs_review","notes","created_at","updated_at"],"additionalProperties":false},"WithholdingList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Withholding"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"WithholdingSync":{"type":"object","properties":{"object":{"type":"string","const":"withholding_sync"},"checked":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"has_more":{"type":"boolean","description":"More received invoices to read: call again"}},"required":["object","checked","created","failed","has_more"],"additionalProperties":false},"WithholdingsCu":{"type":"object","properties":{"object":{"type":"string","const":"withholdings_cu"},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"recipients":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"fiscal_code":{"type":["string","null"]},"vat":{"type":["string","null"]},"lines":{"type":"array","items":{"type":"object","properties":{"causale":{"type":"string"},"gross_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Punto 4","examples":["122.00"]},"not_subject_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Punto 7","examples":["122.00"]},"taxable_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Punto 8","examples":["122.00"]},"withheld_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Punto 9","examples":["122.00"]},"remitted_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Of punto 9, paid with an F24 recorded in getbeel","examples":["122.00"]},"payments":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["causale","gross_amount","not_subject_amount","taxable_amount","withheld_amount","remitted_amount","payments"],"additionalProperties":false}},"ade_due_date":{"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"],"description":"CU to the AdE: 30 April for lavoro autonomo abituale and non-occasional provvigioni, else 16 March (CU 2026 instructions)"},"missing_fiscal_code":{"type":"boolean"}},"required":["key","name","fiscal_code","vat","lines","ade_due_date","missing_fiscal_code"],"additionalProperties":false}},"totals":{"type":"object","properties":{"recipients":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"gross_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"not_subject_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"taxable_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"withheld_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"remitted_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]}},"required":["recipients","gross_amount","not_subject_amount","taxable_amount","withheld_amount","remitted_amount"],"additionalProperties":false},"deadlines":{"type":"object","properties":{"to_recipients":{"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"]},"to_ade":{"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"]},"to_ade_professionals":{"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"]},"form_770":{"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"]}},"required":["to_recipients","to_ade","to_ade_professionals","form_770"],"additionalProperties":false},"missing_fiscal_codes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"form_770":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"period_label":{"type":"string","description":"Punto 1 (MM/AAAA)"},"withheld_amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Punto 2","examples":["122.00"]},"paid_amount":{"anyOf":[{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},{"type":"null"}],"description":"Punto 7"},"paid_on":{"anyOf":[{"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"]},{"type":"null"}],"description":"Punto 14: the day the F24 receipt was recorded; check it against the receipt"},"tax_code":{"type":"string","const":"1040","description":"Punto 11"},"filing_id":{"type":["string","null"]}},"required":["period","period_label","withheld_amount","paid_amount","paid_on","tax_code","filing_id"],"additionalProperties":false},"description":"770 quadro ST, sezione I, per month"}},"required":["object","year","recipients","totals","deadlines","missing_fiscal_codes","form_770"],"additionalProperties":false},"BankConnection":{"type":"object","properties":{"object":{"type":"string","const":"bank_connection"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"provider":{"type":"string","const":"enable_banking"},"application_id":{"type":"string","description":"Your Enable Banking application id (the key is never returned)."},"bank":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","examples":["Intesa Sanpaolo"]},"country":{"type":"string","examples":["IT"]}},"required":["name","country"],"additionalProperties":false},{"type":"null"}]},"psu_type":{"type":"string","enum":["business","personal"]},"status":{"type":"string","enum":["pending","active","requires_reconnect"],"description":"pending: the bank login was not completed yet. active: synced every 6 hours. requires_reconnect: the consent expired or was revoked; reconnect (POST /bank-connections/{id}/reconnect or the app)."},"consent_expires_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"expires_soon":{"type":"boolean","description":"The consent ends within 7 days: reconnect (POST /bank-connections/{id}/reconnect or the app)."},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"last_error":{"type":["string","null"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"iban":{"type":["string","null"]},"name":{"type":["string","null"]},"currency":{"type":["string","null"]},"active":{"type":"boolean"},"balance":{"anyOf":[{"type":"object","properties":{"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"currency":{"type":"string"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"last_booking_date":{"anyOf":[{"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"]},{"type":"null"}]},"transactions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Transactions synced from this account so far."},"pending_transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"date":{"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"]},"description":{"type":"string"},"counterparty_name":{"type":["string","null"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Signed: negative = money out.","examples":["122.00"]},"currency":{"type":"string"},"type":{"type":"string","enum":["debit","credit"]}},"required":["id","date","description","counterparty_name","amount","currency","type"],"additionalProperties":false},"description":"Movements the bank reports as pending (Enable Banking status PDNG, newest 50) as of the last sync. They are not in GET /bank-transactions, never matched, and disappear once the bank books them (the booked movement then arrives as a transaction)."}},"required":["id","iban","name","currency","active","balance","last_synced_at","last_booking_date","transactions","pending_transactions"],"additionalProperties":false}},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["object","id","provider","application_id","bank","psu_type","status","consent_expires_at","expires_soon","last_synced_at","last_error","accounts","created_at"],"additionalProperties":false},"BankConnectionList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/BankConnection"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"CreateBankConnectionRequest":{"type":"object","properties":{"application_id":{"type":"string","pattern":"^[A-Za-z0-9-]{8,100}$","description":"The Enable Banking application id."},"private_key":{"type":"string","minLength":100,"maxLength":16000,"description":"The application's RSA private key in PEM (\"-----BEGIN PRIVATE KEY-----…\"). Stored encrypted, never returned."},"bank":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The bank (ASPSP) name exactly as Enable Banking lists it."},"country":{"default":"IT","type":"string","pattern":"^[A-Z]{2}$"}},"required":["name","country"],"additionalProperties":false},"psu_type":{"default":"business","type":"string","enum":["business","personal"]},"language":{"type":"string","enum":["it","en","es","fr"]}},"required":["application_id","private_key","bank","psu_type"],"additionalProperties":false},"CreateBankConnectionResponse":{"type":"object","properties":{"object":{"type":"string","const":"bank_connection"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"provider":{"type":"string","const":"enable_banking"},"application_id":{"type":"string","description":"Your Enable Banking application id (the key is never returned)."},"bank":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","examples":["Intesa Sanpaolo"]},"country":{"type":"string","examples":["IT"]}},"required":["name","country"],"additionalProperties":false},{"type":"null"}]},"psu_type":{"type":"string","enum":["business","personal"]},"status":{"type":"string","enum":["pending","active","requires_reconnect"],"description":"pending: the bank login was not completed yet. active: synced every 6 hours. requires_reconnect: the consent expired or was revoked; reconnect (POST /bank-connections/{id}/reconnect or the app)."},"consent_expires_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"expires_soon":{"type":"boolean","description":"The consent ends within 7 days: reconnect (POST /bank-connections/{id}/reconnect or the app)."},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"last_error":{"type":["string","null"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"iban":{"type":["string","null"]},"name":{"type":["string","null"]},"currency":{"type":["string","null"]},"active":{"type":"boolean"},"balance":{"anyOf":[{"type":"object","properties":{"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"currency":{"type":"string"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"last_booking_date":{"anyOf":[{"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"]},{"type":"null"}]},"transactions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Transactions synced from this account so far."},"pending_transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"date":{"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"]},"description":{"type":"string"},"counterparty_name":{"type":["string","null"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Signed: negative = money out.","examples":["122.00"]},"currency":{"type":"string"},"type":{"type":"string","enum":["debit","credit"]}},"required":["id","date","description","counterparty_name","amount","currency","type"],"additionalProperties":false},"description":"Movements the bank reports as pending (Enable Banking status PDNG, newest 50) as of the last sync. They are not in GET /bank-transactions, never matched, and disappear once the bank books them (the booked movement then arrives as a transaction)."}},"required":["id","iban","name","currency","active","balance","last_synced_at","last_booking_date","transactions","pending_transactions"],"additionalProperties":false}},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"authorization_url":{"type":"string","format":"uri","description":"Open it in a browser: a getbeel page (/bank-login) names your team, then the user continues to the bank, logs in and lands in the getbeel app. Valid for 30 minutes."},"redirect_url_registered":{"description":"Whether getbeel's redirect URL is in your application's allowed redirect URLs (null when unknown).","type":["boolean","null"]}},"required":["object","id","provider","application_id","bank","psu_type","status","consent_expires_at","expires_soon","last_synced_at","last_error","accounts","created_at","authorization_url","redirect_url_registered"],"additionalProperties":false},"ReconnectBankConnectionRequest":{"type":"object","properties":{"language":{"description":"Language of the bank's login pages, when it offers it.","type":"string","enum":["it","en","es","fr"]}},"additionalProperties":false},"ReconnectBankConnectionResponse":{"type":"object","properties":{"object":{"type":"string","const":"bank_connection"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"provider":{"type":"string","const":"enable_banking"},"application_id":{"type":"string","description":"Your Enable Banking application id (the key is never returned)."},"bank":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","examples":["Intesa Sanpaolo"]},"country":{"type":"string","examples":["IT"]}},"required":["name","country"],"additionalProperties":false},{"type":"null"}]},"psu_type":{"type":"string","enum":["business","personal"]},"status":{"type":"string","enum":["pending","active","requires_reconnect"],"description":"pending: the bank login was not completed yet. active: synced every 6 hours. requires_reconnect: the consent expired or was revoked; reconnect (POST /bank-connections/{id}/reconnect or the app)."},"consent_expires_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"expires_soon":{"type":"boolean","description":"The consent ends within 7 days: reconnect (POST /bank-connections/{id}/reconnect or the app)."},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"last_error":{"type":["string","null"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"iban":{"type":["string","null"]},"name":{"type":["string","null"]},"currency":{"type":["string","null"]},"active":{"type":"boolean"},"balance":{"anyOf":[{"type":"object","properties":{"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount as a string","examples":["122.00"]},"currency":{"type":"string"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"last_booking_date":{"anyOf":[{"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"]},{"type":"null"}]},"transactions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Transactions synced from this account so far."},"pending_transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"date":{"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"]},"description":{"type":"string"},"counterparty_name":{"type":["string","null"]},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Signed: negative = money out.","examples":["122.00"]},"currency":{"type":"string"},"type":{"type":"string","enum":["debit","credit"]}},"required":["id","date","description","counterparty_name","amount","currency","type"],"additionalProperties":false},"description":"Movements the bank reports as pending (Enable Banking status PDNG, newest 50) as of the last sync. They are not in GET /bank-transactions, never matched, and disappear once the bank books them (the booked movement then arrives as a transaction)."}},"required":["id","iban","name","currency","active","balance","last_synced_at","last_booking_date","transactions","pending_transactions"],"additionalProperties":false}},"created_at":{"type":"string","format":"date-time","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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"authorization_url":{"type":"string","format":"uri","description":"Open it in a browser: a getbeel page (/bank-login) names your team, then the user continues to the bank, gives a new consent and lands in the getbeel app; the first sync runs right away. Valid for 30 minutes."}},"required":["object","id","provider","application_id","bank","psu_type","status","consent_expires_at","expires_soon","last_synced_at","last_error","accounts","created_at","authorization_url"],"additionalProperties":false},"BankConnectionSync":{"type":"object","properties":{"object":{"type":"string","const":"bank_connection_sync"},"connection_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","const":"synced"},"transactions_added":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"statement_ids":{"type":"array","items":{"type":"string"},"description":"Synced statements (one per bank account and month, source open_banking) that gained transactions; matching runs on them in the background."},"errors":{"type":"array","items":{"type":"string"}}},"required":["object","connection_id","status","transactions_added","statement_ids","errors"],"additionalProperties":false},"DeletedBankConnection":{"type":"object","properties":{"object":{"type":"string","const":"bank_connection"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"deleted":{"type":"boolean","const":true}},"required":["object","id","deleted"],"additionalProperties":false},"BankConnectionWebhookEvent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"event"},"type":{"type":"string","enum":["bank_connection.expiring","bank_connection.expired"]},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Unix seconds"},"livemode":{"type":"boolean","const":true},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/BankConnection"}},"required":["object"],"additionalProperties":false}},"required":["id","object","type","created","livemode","data"],"additionalProperties":false}}}}