GetbeelDocs

Regole fiscali

I valori e le proroghe dietro lo scadenzario e le stime, con le fonti ufficiali; per gli amministratori di getbeel, le proposte del controllo settimanale delle fonti.

Lo scadenzario e le stime seguono regole che cambiano ogni anno o per legge. getbeel le tiene versionate per data, ognuna con la sua fonte ufficiale:

  • valori: numeri come il minimale e le aliquote INPS dell'anno, le soglie del forfettario o le quote degli impatriati (chiave, valore, valid_from, valid_to);
  • proroghe: un decreto o un comunicato dell'Agenzia delle Entrate che sposta una scadenza (deadline_kind, le date di legge che sposta, new_due_date).

Un valore mancante non viene mai sostituito da quello dell'anno prima: la stima dice che manca.

Ogni settimana un controllo delle fonti legge le fonti ufficiali (news e prassi dell'Agenzia delle Entrate, MEF Dipartimento delle Finanze, Gazzetta Ufficiale, circolari e messaggi INPS) e propone le modifiche, ognuna con il link e la frase che la stabilisce. Nulla cambia finché un amministratore di getbeel non la approva. Quando si approva una proroga, i team di cui sposta le scadenze ricevono un avviso nell'app e gli F24 preparati e non ancora pagati prendono la nuova data.

Scope: taxes:read per leggere. Solo gli amministratori di getbeel modificano le regole, con una chiave live che ha lo scope riservato tax_rules:admin. Questa chiave si crea nella pagina di amministrazione di getbeel e non viene mai proposta in Impostazioni → Chiavi API né all'accesso MCP (403 insufficient_scope senza, 403 live_key_required con una chiave di test, 403 super_admin_required se chi l'ha creata non è più amministratore). Ogni modifica è nel registro di audit.

Leggere le regole in vigore

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

GET /v1/tax-rules restituisce ogni valore per data (origin: "code" incluso in getbeel, "db" aggiunto dopo), coverage (i valori che mancano nei prossimi 13 mesi e se sono in ritardo) e overrides (le proroghe in vigore). pending e watch_runs sono null se la chiave non è di un amministratore di getbeel.

Aggiungere un valore

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

POST /v1/tax-rules/values risponde 201. Con status: "active" il valore è subito in vigore, solo con una fonte ufficiale (agenziaentrate.gov.it, mef.gov.it, finanze.gov.it, gazzettaufficiale.it, inps.it, normattiva.it, fatturapa.gov.it; altrimenti 400 official_source_required). Due valori attivi della stessa chiave non si sovrappongono mai (409 rule_value_overlap). Una chiave nuova richiede un rilascio di getbeel.

Aggiungere una proroga

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

POST /v1/tax-rules/overrides risponde 201. Con deadline_kind: "all" sposta ogni scadenza fiscale di quelle date (mai la dichiarazione OSS né il deposito del bilancio, che una proroga deve nominare). Una proroga non anticipa mai una scadenza.

Approvare, rifiutare o ritirare

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

POST /v1/tax-rules/decisions mette in vigore una proposta (approve) o la scarta (reject); withdraw ritira una regola in vigore (un valore inserito male: ritiralo, poi aggiungi quello corretto; l'id di un valore aggiunto senza rilascio è in GET /v1/tax-rules). Ritirare una proroga riporta gli F24 preparati alla data di legge. Via API si approvano solo proposte con una fonte ufficiale e, per quelle del controllo delle fonti, solo se la citazione è stata trovata parola per parola nella fonte (400 quote_not_verified per un PDF: leggilo e approvalo dalla pagina di amministrazione). 404 proposal_not_found se è già stata decisa.

Gli stessi strumenti sono in MCP: get_tax_rules, add_tax_rule_value, add_tax_calendar_override, decide_tax_rule.

In questa pagina