GetbeelDocs

Ritenute d'acconto

Fatture con ritenuta e cassa previdenziale, ritenute dovute come sostituto d'imposta, F24 codice 1040 e dati per la Certificazione Unica e il 770.

Due lati della stessa ritenuta:

  • Emetti una fattura da professionista: POST /v1/invoices con withholding (blocco DatiRitenuta) e, se serve, cassa_previdenziale. Il cliente paga amount_due, cioè il totale meno le ritenute.
  • Paghi un professionista o un agente: sei sostituto d'imposta, trattieni la ritenuta e la versi tu con l'F24 (codice tributo 1040) entro il 16 del mese dopo il pagamento. /v1/withholdings tiene un compenso per riga; a fine anno /v1/withholdings/cu dà i dati per la CU e il 770.

Scope: taxes:read per leggere, taxes:write per scrivere (chiave live, come gli adempimenti). Registrare le ritenute è gratis.

Emettere una fattura con ritenuta

curl -X POST https://www.getbeel.com/api/v1/invoices \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "denominazione": "Cliente S.r.l.", "partita_iva": "01234567890" },
    "lines": [
      { "description": "Consulenza ottobre", "unit_price": "1000.00", "vat_rate": "22" },
      { "description": "Spese anticipate", "unit_price": "50.00", "natura": "N1" }
    ],
    "cassa_previdenziale": { "type": "TC22", "rate": "4", "vat_rate": "22", "subject_to_withholding": true },
    "withholding": { "type": "RT01", "rate": "20", "reason": "A" }
  }'
  • withholding.amount si può omettere: Getbeel calcola rate × (righe soggette + contributo cassa se soggetto). Le righe con natura N1 (spese anticipate in nome e per conto, art. 15 DPR 633/72) non sono soggette se non indichi subject_to_withholding: true. Sulle righe soggette scrive <Ritenuta>SI</Ritenuta>.
  • Per le provvigioni (reason da Q a V) l'aliquota si applica solo a una parte dell'importo (art. 25-bis DPR 600/1973): amount è obbligatorio.
  • withholding.contributions: altri blocchi DatiRitenuta per i contributi trattenuti dal cliente (RT03 INPS, RT04 ENASARCO, RT05 ENPAM, RT06 altro). Anche questi riducono amount_due e ImportoPagamento.
  • cassa_previdenziale.amount si può omettere: rate × compensi (righe tranne N1); Getbeel scrive anche ImponibileCassa. subject_to_withholding vale per la rivalsa che fa parte del compenso; il contributo integrativo delle casse professionali non ne fa parte (istruzioni CU 2026, punto 4).
  • reason è la causale della CU: i codici accettati sono quelli dello schema FatturaPA che sono anche causali della CU 2026 (A, B, C, D, E, G, H, I, L, L1, M, M1, M2, N, O, O1, P, Q, R, S, T, U, V, V1, W, ZO).

La fattura restituita ha withholdings (tipo, aliquota, importo e causale di ogni blocco) e amount_due al netto di tutti.

Ritenute che devi versare

curl https://www.getbeel.com/api/v1/withholdings?paid_in=2026-10 \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

Le fatture ricevute dallo SDI con DatiRitenuta RT01 o RT02 diventano una ritenuta da sole all'arrivo (source: sdi). POST /v1/withholdings/sync rilegge quelle arrivate prima (100 per chiamata, has_more). Getbeel ricava gli importi come li vuole la CU:

CampoCUCome
gross_amountpunto 4Righe senza IVA + contributo cassa soggetto a ritenuta. Il contributo integrativo (cassa senza Ritenuta SI) è escluso
not_subject_amountpunto 7Il resto: spese anticipate, quota non soggetta delle provvigioni (50% o 80%)
taxable_amountpunto 8La base a cui l'emittente ha applicato l'aliquota: le righe con Ritenuta SI, o la parte che corrisponde a ImportoRitenuta
withheld_amountpunto 9Somma di ImportoRitenuta dei blocchi RT01/RT02

Quando i numeri non tornano, manca il codice fiscale del professionista (serve per la CU) o la fattura ha uno sconto sul totale, la ritenuta ha needs_review: true e notes spiega perché.

status:

  • unpaid: non hai ancora pagato il compenso, quindi non hai ancora trattenuto nulla. Quando paghi: PATCH /v1/withholdings/{id} con paid_on.
  • withheld: compenso pagato, ritenuta da versare entro due_date (16 del mese dopo, spostato al primo giorno lavorativo). overdue dopo.
  • remitted: versata con un F24 registrato in Getbeel. Non si modifica più (409 withholding_remitted).
  • Se il compenso cambia dopo aver preparato l'F24, l'F24 va ricalcolato: pagato così com'è, versa solo i compensi rimasti uguali; gli altri restano da versare.
  • Un compenso registrato dopo l'F24 del mese già pagato, o un F24 preparato con amount: se quella ritenuta era compresa nell'F24 pagato, PATCH con { "remitted": true } la collega e la blocca (409 no_paid_filing se per il mese non c'è un F24 pagato).
  • Le chiavi di test non vedono le ritenute (sono dati reali dei professionisti, come le fatture ricevute).

Un compenso non arrivato dallo SDI (fattura cartacea, ricevuta per prestazione occasionale):

curl -X POST https://www.getbeel.com/api/v1/withholdings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "name": "Luca Bianchi", "fiscal_code": "BNCLCU85M01H501Z" },
    "causale": "M",
    "rate": "20",
    "gross_amount": "500.00",
    "paid_on": "2026-10-20"
  }'

withheld_amount si calcola se lo ometti: (gross_amount − not_subject_amount) × rate.

L'F24 del mese

POST /v1/filings con { "type": "withholdings", "period": "2026-10" } somma le ritenute con paid_on nel mese e prepara l'F24 (sezione Erario, codice 1040, mese 10, anno 2026). Vedi Adempimenti. Caricata la quietanza, quelle ritenute diventano remitted.

Certificazione Unica e 770

curl "https://www.getbeel.com/api/v1/withholdings/cu?year=2026" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

Per percipiente e causale, i compensi pagati nell'anno (conta la data di pagamento): lordo (punto 4), somme non soggette (7), imponibile (8), ritenute (9), e quanto è stato versato con F24 registrati in Getbeel. form_770 elenca per mese le ritenute operate, l'importo versato e la data (quadro ST, sezione I: punti 1, 2, 7, 11, 14). format=csv restituisce un foglio (punto e virgola, decimali con la virgola).

Scadenze (istruzioni CU 2026, periodo d'imposta 2025; per i compensi del 2026 valgono le istruzioni CU 2027 di gennaio 2027): CU al percipiente entro il 16 marzo; all'Agenzia entro il 16 marzo, o entro il 30 aprile per lavoro autonomo abituale (causale A) e provvigioni non occasionali; 770 entro il 31 ottobre.

Non è il file telematico

Getbeel non prepara il file da inviare all'Agenzia né firma la CU: questi sono i dati da controllare e dare a chi la presenta (spesso il commercialista), o da riportare nel software dell'Agenzia.

Fonti

In questa pagina