# Fatture ricorrenti (https://docs.getbeel.com/it/api/recurring-invoices)

Ripeti una fattura ogni mese, trimestre o anno, con l'invio allo SDI facoltativo.

Una fattura ricorrente parte da una fattura che hai già (il **modello**): ogni mese, trimestre o anno Getbeel ne crea una copia in bozza con la data del giorno, il numero successivo e lo stesso termine di pagamento (la scadenza si sposta degli stessi giorni). Con `auto_send` la nuova fattura va anche allo SDI. Scope `invoices:write` (letture `invoices:read`).

Nell'app: apri una fattura emessa e scegli **Rendi ricorrente**; l'elenco è in **Fatture emesse → Fatture ricorrenti**, con pausa e ripresa.

## Crea [#crea]

```bash
curl -X POST https://www.getbeel.com/api/v1/recurring-invoices \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "invoice_id": "fe_…", "interval": "monthly", "auto_send": false }'
```

- `interval`: `monthly`, `quarterly` o `yearly`.
- `start_date` (facoltativo, da oggi in poi): la data della prima nuova fattura. Di default è la prima data dopo oggi nella serie `invoice_date` + n × intervallo. Una ricorrenza il 31 passa al 28 dopo febbraio (si tiene il giorno della prossima data salvata).
- `auto_send`: invia allo SDI ogni nuova fattura. Con una chiave live è una trasmissione reale; con una chiave di test va alla sandbox. Le proforma non vengono mai inviate.

Una sola ricorrenza per fattura (`409 recurring_invoice_exists`). Una fattura che non si può copiare (dati non validi) risponde `422 invoice_not_copyable`.

## Come gira [#come-gira]

Ogni mattina Getbeel crea le fatture delle ricorrenze arrivate a `next_date` e sposta `next_date` al periodo successivo. Le fatture live seguono le stesse regole dell'app: servono l'add-on SDI e la quota. Se la creazione non riesce (ad esempio quota esaurita) `last_error` lo spiega e Getbeel riprova il giorno dopo; `last_invoice_id` è l'ultima fattura creata.

Le chiavi di test vedono e creano solo ricorrenze sandbox, quelle live solo ricorrenze reali.

## Gestisci [#gestisci]

```bash
# elenco
curl https://www.getbeel.com/api/v1/recurring-invoices \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# pausa e ripresa
curl -X POST https://www.getbeel.com/api/v1/recurring-invoices/$ID/pause \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
curl -X POST https://www.getbeel.com/api/v1/recurring-invoices/$ID/resume \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# modifica
curl -X PATCH https://www.getbeel.com/api/v1/recurring-invoices/$ID \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "interval": "quarterly", "next_date": "2027-01-01", "auto_send": true }'

# elimina (le fatture già create restano)
curl -X DELETE https://www.getbeel.com/api/v1/recurring-invoices/$ID \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Alla ripresa, una `next_date` già passata salta al periodo successivo: niente fatture arretrate.

## Con un assistente AI [#con-un-assistente-ai]

Lo strumento MCP `create_recurring_invoice` crea la ricorrenza dopo averti chiesto conferma di intervallo e data; imposta `auto_send` solo se lo chiedi tu.
