Collegare Stripe a SamBooks per incassi, fatture e corrispettivi automatici: guida passo-passo

A cosa serve

Stripe è uno dei sistemi più usati per incassare pagamenti online: abbonamenti ricorrenti, pagamenti una tantum, checkout di SaaS e servizi digitali. Stripe però incassa soltanto: non emette i documenti fiscali italiani al posto tuo.

Collegando Stripe a SamBooks, ogni incasso che entra sul tuo account Stripe viene contabilizzato automaticamente con il documento giusto:

• se chi paga è un'azienda con partita IVA (B2B), SamBooks riconcilia l'incasso alla fattura che hai già emesso;
• se chi paga è un privato consumatore (B2C), SamBooks registra il corrispettivo, scorporando l'IVA dall'importo incassato;
• funziona sia per gli abbonamenti sia per i pagamenti una tantum.

Non devi più esportare i pagamenti da Stripe e reinserirli a mano: li trovi già registrati in SamBooks, pronti per la liquidazione IVA.

Importante: le fatture e i corrispettivi restano documenti di SamBooks. Stripe è il canale d'incasso; il documento fiscale lo emetti (o lo riconcili) sempre dentro SamBooks.

Cosa ti serve

• Un account Stripe attivo (lo stesso con cui incassi i tuoi clienti).
• L'accesso a SamBooks come Gestore dell'azienda.
• Due "chiavi" che creerai su Stripe in pochi minuti e incollerai in SamBooks:
  1. una chiave a sola lettura (restricted key), con cui SamBooks legge abbonamenti, fatture e incassi;
  2. un segreto del webhook, con cui SamBooks riconosce che gli eventi d'incasso arrivano davvero dal tuo Stripe.

Le due chiavi si incollano dentro SamBooks: non vanno comunicate a nessun altro e vengono conservate cifrate.

Procedura passo-passo (~5 minuti)

1. Apri il pannello di collegamento in SamBooks

In SamBooks vai in Impostazioni → Azienda → Integrazioni e, sulla card Stripe, clicca Collega. Si apre la finestra di collegamento: tienila aperta, ti servirà per copiare l'indirizzo del webhook e per incollare le due chiavi.

2. Crea la chiave a sola lettura su Stripe

Apri il pannello di Stripe alla pagina Chiavi API: dashboard.stripe.com/apikeys. Per fare prima una prova senza muovere denaro reale, usa la modalità test: dashboard.stripe.com/test/apikeys.

1. Clicca "Crea chiave con limitazioni" (Create restricted key).

2. Stripe chiede "Come utilizzerai questa chiave?" mostrando tre riquadri: scegli il primo, "Attivare un'integrazione che hai creato". (Gli altri due — "Fornire la chiave a una terza parte" e "Autorizzazione di un agente di IA" — non servono.)

3. Alla voce "Scegli un modello di autorizzazione" seleziona "Scegli il tuo" (Create your own): così imposti i permessi esatti.

4. Nella tabella dei permessi lascia tutto su Nessuno (None) e metti Lettura (Read) solo su queste quattro risorse:

   Risorsa	Gruppo	Permesso
   Customers (Clienti)	Core	Lettura
   Invoices (Fatture)	Billing	Lettura
   Subscriptions (Abbonamenti)	Billing	Lettura
   Prices (Prezzi)	Billing	Lettura

   Se incassi anche pagamenti una tantum, puoi aggiungere Checkout Sessions → Lettura: migliora il riconoscimento dei pagamenti diretti. È opzionale.

5. Dai un nome alla chiave, ad esempio "SamBooks (sola lettura)", e clicca Crea chiave (Create key).

6. Copia la chiave che inizia con rk_ — Stripe te la mostra una volta sola — e incollala in SamBooks, nel campo Chiave a sola lettura della finestra di collegamento.

Serve la verifica in due passaggi (2FA)? In modalità test no: Stripe ti fa creare la chiave senza alcuna verifica. In modalità reale (live) Stripe chiede la verifica 2FA al momento della creazione — tienilo presente quando passi ai pagamenti veri.

3. Configura il webhook su Stripe

Il webhook è il "filo diretto" con cui Stripe avvisa SamBooks a ogni incasso.

1. In SamBooks, nella finestra di collegamento, copia l'indirizzo del webhook con il pulsante Copia: è un indirizzo unico per la tua azienda.
2. Apri Stripe alla pagina Webhook: dashboard.stripe.com/webhooks (in test: dashboard.stripe.com/test/webhooks) e clicca "Aggiungi endpoint" (Add endpoint).
3. Nel campo URL dell'endpoint incolla l'indirizzo copiato da SamBooks.
4. Alla voce eventi da inviare seleziona questi quattro:
   • invoice.paid
   • invoice.payment_succeeded
   • checkout.session.completed
   • payment_intent.succeeded
5. Salva l'endpoint, poi aprilo e copia il segreto di firma (Signing secret) che inizia con whsec_.
6. Incolla il whsec_ in SamBooks, nel campo Segreto del webhook della finestra di collegamento.

4. Verifica il collegamento

In SamBooks clicca Collega (o Verifica). Se le chiavi sono corrette lo stato diventa Connessa e nella finestra compaiono, in sola lettura, i tuoi abbonamenti e le tue fatture Stripe. Da questo momento ogni nuovo incasso viene contabilizzato in automatico.

Cosa fa SamBooks a ogni incasso

• Incasso da azienda (B2B, con partita IVA): SamBooks cerca la tua fattura corrispondente a quell'incasso e la riconcilia (la segna come pagata). Se non trova una fattura corrispondente, registra l'incasso come sospeso e ti avvisa di abbinarlo o di emettere la fattura.
• Incasso da privato (B2C): SamBooks registra il corrispettivo, scorporando l'IVA dall'importo incassato. Per le vendite online il corrispettivo è esonerato dall'invio telematico all'Agenzia delle Entrate: entra comunque nel registro dei corrispettivi e nella liquidazione IVA. La fattura al privato si emette solo se la richiede.
• Abbonamenti e una tantum: il meccanismo è identico per i pagamenti ricorrenti e per i pagamenti singoli.

Codice fiscale dei privati: Stripe non trasmette il codice fiscale del consumatore italiano (porta solo la partita IVA, quando c'è). Se per un privato ti serve la fattura, il codice fiscale va raccolto a parte.

Domande frequenti

Devo creare le fatture su Stripe? No. Stripe serve solo a incassare. Le fatture e i corrispettivi li emette SamBooks: è quello che ti tiene in regola con il fisco italiano.

Perché una chiave a sola lettura e non quella completa? SamBooks deve solo leggere i tuoi incassi, non modificarli. La chiave a sola lettura è la scelta più sicura, ed è quella consigliata da Stripe per condividere l'accesso.

Posso provare prima senza rischi? Sì: usa la modalità test di Stripe (link /test/...). Le chiavi di test iniziano con rk_test_ e il segreto webhook con whsec_; non muovono denaro reale.

Ho cambiato chiave su Stripe: cosa faccio? Riapri Impostazioni → Azienda → Integrazioni → Stripe, clicca Aggiorna credenziali e incolla la nuova chiave.

Come scollego Stripe? Dalla stessa finestra, pulsante Scollega. Gli incassi già contabilizzati restano; smette solo la sincronizzazione con Stripe.