GetbeelDocs

Tax rules

The rule values and proroghe behind the tax calendar and estimates, with their official sources; for getbeel administrators, the proposals of the weekly rules watch.

The tax calendar and the estimates follow rules that change by year or by law. getbeel keeps them versioned by date, each with its official source:

  • rule values: numbers such as the INPS minimale and rates of a year, the forfettario thresholds or the impatriati shares (key, value, valid_from, valid_to);
  • proroghe: a decree or an Agenzia delle Entrate communication that moves a deadline (deadline_kind, the legal dates it moves, new_due_date).

A missing value is never replaced by last year's: the estimate says it is missing.

Every week a rules watch reads the official sources (Agenzia delle Entrate news and prassi, MEF Dipartimento Finanze, Gazzetta Ufficiale, INPS circolari and messaggi) and proposes changes, each with its link and the sentence that states it. Nothing changes until a getbeel administrator approves it. When a proroga is approved, the teams whose deadlines it moves get a notice in the app, and prepared F24s not paid yet take the new date.

Scopes: taxes:read to read. Only getbeel administrators change the rules, with a live key that has the admin-only scope tax_rules:admin. That key is created in the getbeel admin page and is never offered in Settings → API keys or on an MCP sign-in (403 insufficient_scope without it, 403 live_key_required with a test key, 403 super_admin_required once its creator is no longer an administrator). Every change is in the audit log.

Read the rules in force

curl https://www.getbeel.com/api/v1/tax-rules \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

GET /v1/tax-rules returns every rule value by date (origin: "code" shipped with getbeel, "db" added since), coverage (values missing in the next 13 months, and whether they are overdue) and overrides (the proroghe in force). pending and watch_runs are null unless the key belongs to a getbeel administrator.

Add a rule value

curl https://www.getbeel.com/api/v1/tax-rules/values \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "inps.maternity_yearly",
    "value": 7.5,
    "valid_from": "2027-01-01",
    "valid_to": "2027-12-31",
    "source_url": "https://www.inps.it/…/circolare-2027",
    "source_title": "INPS, circolare n. 9 del 2 febbraio 2027",
    "source_article": "§ 1",
    "status": "pending"
  }'

POST /v1/tax-rules/values answers 201. status: "active" puts the value in force at once, only with an official source (agenziaentrate.gov.it, mef.gov.it, finanze.gov.it, gazzettaufficiale.it, inps.it, normattiva.it, fatturapa.gov.it; 400 official_source_required otherwise). Two active values of a key never overlap (409 rule_value_overlap). An unknown key needs a release of getbeel.

Add a proroga

curl https://www.getbeel.com/api/v1/tax-rules/overrides \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deadline_kind": "vat_payment",
    "nominal_from": "2027-06-16",
    "nominal_to": "2027-06-16",
    "new_due_date": "2027-07-21",
    "valid_from": "2027-06-01",
    "source_url": "https://www.gazzettaufficiale.it/eli/id/…",
    "source_title": "DPCM 1 giugno 2027, art. 1",
    "status": "pending"
  }'

POST /v1/tax-rules/overrides answers 201. deadline_kind: "all" moves every tax deadline of those legal dates (never the EU OSS return or the bilancio deposit, which a proroga must name). A proroga never brings a deadline earlier.

Approve, reject or withdraw

curl https://www.getbeel.com/api/v1/tax-rules/decisions \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "override", "id": "3f6c…", "decision": "approve" }'

POST /v1/tax-rules/decisions puts a pending proposal in force (approve) or sets it aside (reject); withdraw takes a rule in force out (a value entered wrong: withdraw it, then add the corrected one; the id of a value added without a deploy is in GET /v1/tax-rules). Withdrawing a proroga moves prepared F24s back to the legal date. Through the API only proposals with an official source can be approved, and a rules-watch proposal only when its quote was found word for word in the source (400 quote_not_verified for a PDF: read it and approve it in the admin page). 404 proposal_not_found when it was already decided.

The same tools exist in MCP: get_tax_rules, add_tax_rule_value, add_tax_calendar_override, decide_tax_rule.

On this page