# Ritenute d'acconto (https://docs.getbeel.com/it/api/withholdings)

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](/it/api/filings)). Registrare le ritenute è gratis.

## Emettere una fattura con ritenuta [#emettere-una-fattura-con-ritenuta]

```bash
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 [#ritenute-che-devi-versare]

```bash
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}` 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):

```bash
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 [#lf24-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](/it/api/filings). Caricata la quietanza, quelle ritenute diventano `remitted`.

## Certificazione Unica e 770 [#certificazione-unica-e-770]

```bash
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.

<Callout title="Non è il file telematico" type="warn">
  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.
</Callout>

## Fonti [#fonti]

- [Specifiche tecniche FatturaPA, Allegato A, versione 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) e [schema XSD 1.2.3](https://www.fatturapa.gov.it/it/norme-e-regole/documentazione-fattura-elettronica/formato-fatturapa/): `DatiRitenuta` (0..N), `TipoRitenuta` RT01–RT06, `CausalePagamento`, `Ritenuta` su 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](https://www1.agenziaentrate.gov.it/servizi/codici/ricerca/SezioneErario.php?CT=1040) e [Risoluzione 13/E del 17 marzo 2016](https://www.agenziaentrate.gov.it/portale/documents/20143/303158/Risoluzione+n.+13+del+17+marzo+2016_RIs+13e+del+17.03.16.pdf/21945510-c111-1c5d-bc36-ea35db076953) (dal 2017 il codice 1038 delle provvigioni confluisce nel 1040).
- [Istruzioni Certificazione Unica 2026](https://www.agenziaentrate.gov.it/portale/documents/20143/9602395/CU_istruzioni_2026.pdf/4184818b-05a3-acce-5956-70811c7d2233), "Certificazione lavoro autonomo, provvigioni e redditi diversi"; istruzioni del Modello 770/2026, quadro ST.
