# Email, pagamenti e solleciti (https://docs.getbeel.com/it/api/invoice-collection)

Invia la fattura al cliente, registra i pagamenti, crea un link di pagamento Stripe e manda i solleciti.

Dopo l'invio allo SDI la fattura va incassata. L'API fa le stesse cose della scheda **Incasso** di una fattura emessa nell'app: email al cliente, pagamenti, link di pagamento e solleciti. Tutti gli endpoint usano lo scope `invoices:write` (le letture `invoices:read`).

Si possono inviare via email, segnare come pagate e sollecitare le fatture accettate dallo SDI (`sent`, `delivered`, `not_delivered`) e le proforma. Le bozze e le fatture scartate rispondono `409 invoice_not_issued`. Le note di credito (TD04) si possono inviare via email ma non si incassano: niente pagamenti, link o solleciti.

<Callout title="Chiavi di test">
  Con una chiave `gb_test_` lavori sulle fatture sandbox e **le email non
  arrivano mai al cliente**: vanno solo all'indirizzo del titolare del team, con
  un avviso in testa e `[TEST]` nell'oggetto. Nella risposta `sandbox` è `true`
  e `sent_to` mostra dove è andata davvero.
</Callout>

## Invia la fattura al cliente [#invia-la-fattura-al-cliente]

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/email \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "to": ["amministrazione@cliente.it"], "language": "it", "message": "Grazie per la collaborazione!", "attach_xml": false }'
```

Tutti i campi sono facoltativi: senza `to` usa l'email del cliente sulla fattura (`422 customer_email_missing` se manca). Il cliente riceve il PDF come **copia di cortesia**: la fattura valida ai fini fiscali resta quella consegnata dallo SDI, e l'email lo dice. Con `attach_xml: true` alleghi anche il file FatturaPA. Se la fattura ha un link di pagamento, l'email ha il pulsante **Paga ora**.

La risposta (`201`) è il record dell'email con `status: sent` e `provider_message_id`. Se il provider rifiuta l'invio rispondiamo `502 email_failed`: il tentativo resta registrato e puoi riprovare con la stessa `Idempotency-Key`.

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

`GET /deliveries` elenca le email della fattura (copie e solleciti), le più recenti prima.

## Registra un pagamento [#registra-un-pagamento]

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payments \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Senza corpo registra tutto quello che resta da incassare, con la data di oggi e il metodo `bank_transfer`: la fattura diventa `paid`. Per un acconto passa l'importo:

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payments \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "50.00", "date": "2026-10-30", "method": "card" }'
```

Metodi: `bank_transfer`, `card`, `cash`, `stripe`, `other`. Un importo superiore al residuo risponde `422 amount_exceeds_balance`, una fattura già pagata `409 invoice_already_paid`. La risposta contiene `payment` e la fattura aggiornata.

Ogni fattura ha ora questi campi:

| Campo              | Significato                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `payment_status`   | `unpaid`, `partially_paid` o `paid`                                 |
| `amount_due`       | Quanto paga il cliente: il totale meno la ritenuta d'acconto        |
| `amount_paid`      | Somma dei pagamenti registrati                                      |
| `paid_at`          | Data del pagamento che ha saldato la fattura                        |
| `overdue`          | `true` se è emessa, non pagata e la scadenza (`due_date`) è passata |
| `payment_link_url` | Il link di pagamento Stripe, finché non è pagata                    |

Per le fatture da incassare o scadute: `GET /invoices?payment_status=unpaid` oppure `GET /invoices?overdue=true`. Le fatture importate da Stripe sono già pagate.

## Link di pagamento Stripe [#link-di-pagamento-stripe]

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payment-link \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Crea un [Payment Link](https://docs.stripe.com/payment-links) per il residuo sull'account Stripe collegato al team (`201`), oppure restituisce quello esistente (`200`). Senza Stripe collegato risponde `409 stripe_not_connected`: collegalo dalla pagina fatture emesse dell'app o con [`POST /connections/stripe`](/it/api/connections). La modalità di Stripe deve corrispondere alla fattura: le fatture sandbox richiedono una connessione in modalità test, quelle reali una connessione live (altrimenti `409 stripe_mode_mismatch`). Quando registri un pagamento il link viene disattivato, perché chiederebbe il vecchio residuo: creane uno nuovo per quanto resta.

Quando il cliente paga, Getbeel registra il pagamento (metodo `stripe`) entro un'ora e la fattura diventa pagata.

## Solleciti [#solleciti]

Un sollecito manuale:

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/reminders \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "it" }'
```

Accetta gli stessi campi dell'email (`to`, `cc`, `language`, `message`) e allega il PDF con il link di pagamento. Una fattura già pagata risponde `409`.

I **solleciti automatici** si attivano per azienda nell'app (**Fatture emesse → Solleciti**): spenti di default, partono il numero di giorni dopo la scadenza che scegli (ad esempio 3, 10, 30), una volta per passaggio, solo per le fatture live con l'email del cliente e con scadenza dal giorno in cui li hai attivati.

La stessa impostazione dall'API (`invoices:write`, chiavi live; la lettura richiede `invoices:read` e va con entrambe):

```bash
curl -X PATCH https://www.getbeel.com/api/v1/companies/me/reminder-settings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "days": [3, 10, 30] }'
```

Un `PATCH` cambia solo quello che invia. La risposta, come `GET /companies/me/reminder-settings`, ha `enabled`, `days` (fino a 5 passaggi) e `enabled_at`, il giorno da cui partono i solleciti. Strumenti MCP: `get_reminder_settings`, `update_reminder_settings`.

## Webhook [#webhook]

| Evento                 | Quando                                               | `data.object`   |
| ---------------------- | ---------------------------------------------------- | --------------- |
| `invoice.emailed`      | Email o sollecito inviato                            | `invoice_email` |
| `invoice.email_failed` | Invio non riuscito                                   | `invoice_email` |
| `invoice.paid`         | I pagamenti coprono il dovuto                        | `invoice`       |
| `invoice.overdue`      | Il giorno dopo la scadenza, una volta, se non pagata | `invoice`       |

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

Il [server MCP](/it/api/mcp) ha `email_invoice_to_customer`, `mark_invoice_paid`, `list_overdue_invoices`, `create_payment_link` e `send_payment_reminder`. Prima di inviare un'email l'assistente ti chiede conferma dei destinatari.
