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/invoicesconwithholding(bloccoDatiRitenuta) e, se serve,cassa_previdenziale. Il cliente pagaamount_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/withholdingstiene un compenso per riga; a fine anno/v1/withholdings/cudà 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.amountsi può omettere: Getbeel calcolarate× (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 indichisubject_to_withholding: true. Sulle righe soggette scrive<Ritenuta>SI</Ritenuta>.- Per le provvigioni (
reasonda Q a V) l'aliquota si applica solo a una parte dell'importo (art. 25-bis DPR 600/1973):amountè obbligatorio. withholding.contributions: altri blocchiDatiRitenutaper i contributi trattenuti dal cliente (RT03 INPS, RT04 ENASARCO, RT05 ENPAM, RT06 altro). Anche questi riduconoamount_dueeImportoPagamento.cassa_previdenziale.amountsi può omettere:rate× compensi (righe tranne N1); Getbeel scrive ancheImponibileCassa.subject_to_withholdingvale 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:
| Campo | CU | Come |
|---|---|---|
gross_amount | punto 4 | Righe senza IVA + contributo cassa soggetto a ritenuta. Il contributo integrativo (cassa senza Ritenuta SI) è escluso |
not_subject_amount | punto 7 | Il resto: spese anticipate, quota non soggetta delle provvigioni (50% o 80%) |
taxable_amount | punto 8 | La base a cui l'emittente ha applicato l'aliquota: le righe con Ritenuta SI, o la parte che corrisponde a ImportoRitenuta |
withheld_amount | punto 9 | Somma di ImportoRitenuta dei blocchi RT01/RT02 |
Quando i numeri non tornano, manca il codice fiscale del professionista (serve per la CU) o la fattura ha uno sconto sul totale, la ritenuta ha needs_review: true e notes spiega perché.
status:
unpaid: non hai ancora pagato il compenso, quindi non hai ancora trattenuto nulla. Quando paghi:PATCH /v1/withholdings/{id}conpaid_on.withheld: compenso pagato, ritenuta da versare entrodue_date(16 del mese dopo, spostato al primo giorno lavorativo).overduedopo.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,PATCHcon{ "remitted": true }la collega e la blocca (409 no_paid_filingse 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
- Specifiche tecniche FatturaPA, Allegato A, versione 1.9.1 e schema XSD 1.2.3:
DatiRitenuta(0..N),TipoRitenutaRT01–RT06,CausalePagamento,Ritenutasu righe e cassa, controlli 00411 e 00415. - Art. 25 e 25-bis DPR 600/1973 (ritenuta del 20% all'atto del pagamento; provvigioni) e art. 18 D.Lgs. 241/1997 (versamento entro il 16).
- Codice tributo 1040 e Risoluzione 13/E del 17 marzo 2016 (dal 2017 il codice 1038 delle provvigioni confluisce nel 1040).
- Istruzioni Certificazione Unica 2026, "Certificazione lavoro autonomo, provvigioni e redditi diversi"; istruzioni del Modello 770/2026, quadro ST.