GetbeelDocs

Email, pagamenti e solleciti

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.

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.

Invia la fattura al cliente

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.

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

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:

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:

CampoSignificato
payment_statusunpaid, partially_paid o paid
amount_dueQuanto paga il cliente: il totale meno la ritenuta d'acconto
amount_paidSomma dei pagamenti registrati
paid_atData del pagamento che ha saldato la fattura
overduetrue se è emessa, non pagata e la scadenza (due_date) è passata
payment_link_urlIl 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.

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

Crea un Payment Link 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. 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

Un sollecito manuale:

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):

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

EventoQuandodata.object
invoice.emailedEmail o sollecito inviatoinvoice_email
invoice.email_failedInvio non riuscitoinvoice_email
invoice.paidI pagamenti coprono il dovutoinvoice
invoice.overdueIl giorno dopo la scadenza, una volta, se non pagatainvoice

Con un assistente AI

Il server 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.

In questa pagina