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 oppure, se non la trova, genera la fattura elettronica;
• se chi paga è un privato che ha chiesto la fattura, SamBooks la genera a suo nome con il codice fiscale;
• se chi paga è un privato che non ha chiesto la fattura (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 nasce (o viene riconciliato) sempre dentro SamBooks.

Cosa ti serve

• Un account Stripe attivo (lo stesso con cui incassi i tuoi clienti).
• L'accesso a SamBooks con il ruolo Gestore o Amministrativo e il permesso di lettura e scrittura.
• Due credenziali che creerai su Stripe in pochi minuti e incollerai in SamBooks:
  1. una restricted key (inizia con rk_) con permessi di sola lettura, con cui SamBooks legge abbonamenti, fatture e incassi;
  2. il webhook signing secret (inizia con whsec_), con cui SamBooks verifica che gli eventi d'incasso arrivino davvero dal tuo account Stripe.

Le due credenziali 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 Collega Stripe: tienila aperta, ti servirà per incollare le credenziali e copiare l'URL del webhook.

2. Crea la restricted key su Stripe

Apri il Dashboard di Stripe alla pagina Chiavi API (API keys): 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 None e metti Read solo su queste quattro risorse (con il Dashboard in italiano i due livelli si chiamano Nessuno e Lettura):

   Risorsa	Gruppo	Permesso
   Customers	Core	Read
   Invoices	Billing	Read
   Subscriptions	Billing	Read
   Prices	Billing	Read

   Se incassi anche pagamenti una tantum, puoi aggiungere Checkout Sessions → Read: 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 restricted key che inizia con rk_: Stripe te la mostra una volta sola.

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

3. Collega la restricted key in SamBooks

Nella finestra Collega Stripe incolla la restricted key nel campo Restricted key (sola lettura) e clicca Collega. Lascia vuoto, per ora, il campo Webhook signing secret: lo compilerai al passo 5.

Se la chiave è corretta lo stato diventa Connesso, la finestra mostra la modalità (test o live) e compare la sezione Webhook per la ricezione dei pagamenti con l'URL del webhook, unico per la tua azienda.

4. Crea il webhook su Stripe

Il webhook è il canale con cui Stripe avvisa SamBooks a ogni incasso.

1. In SamBooks, nella sezione Webhook per la ricezione dei pagamenti, copia l'URL del webhook con il pulsante Copia.

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 Endpoint URL incolla l'URL copiato da SamBooks.

4. Tra gli eventi da inviare seleziona questi.

   Per gli incassi (registrazione automatica dei pagamenti):

   • invoice.paid
   • invoice.payment_succeeded
   • checkout.session.completed
   • payment_intent.succeeded

   Per gli abbonamenti (se colleghi una fattura ricorrente di SamBooks a un abbonamento Stripe, vedi le domande frequenti):

   • customer.subscription.deleted
   • customer.subscription.updated

5. Salva l'endpoint, poi aprilo e copia il Signing secret, che inizia con whsec_.

5. Incolla il webhook signing secret in SamBooks

Torna nella finestra Collega Stripe e clicca Aggiorna credenziali. Nel modulo che si apre incolla di nuovo la restricted key (il campo è obbligatorio) e, nel campo Webhook signing secret, il valore whsec_ appena copiato; poi clicca Collega.

Nel riquadro dello stato la voce Webhook passa a Configurato: da questo momento ogni nuovo incasso viene contabilizzato in automatico. Con Verifica connessione puoi ricontrollare in qualsiasi momento che la restricted key sia ancora valida.

6. Scegli se inviare a SDI in automatico

Sotto la sezione del webhook trovi l'interruttore Invia le fatture a SDI automaticamente:

• attivo: le fatture generate all'incasso partono verso SDI da sole;
• disattivo: restano bozze, e le controlli e invii tu.

Cosa fa SamBooks a ogni incasso

• Incasso da azienda (B2B, con partita IVA): SamBooks cerca la tua fattura corrispondente a quell'incasso (stessa partita IVA, stesso importo, periodo vicino) e, se ne trova esattamente una, la riconcilia (la segna come pagata). Se non ne trova, genera la fattura elettronica dalle righe del pagamento Stripe. Se la partita IVA non è valida o il trattamento IVA non si può ricavare con certezza, registra l'incasso come sospeso e ti avvisa, perché lo sistemi tu.
• Incasso da privato che ha chiesto la fattura: SamBooks genera la fattura a suo nome con il codice fiscale. Il codice fiscale deve arrivare a Stripe come spiegato nella sezione qui sotto.
• Incasso da privato senza richiesta di fattura (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.
• Incasso da privato estero: SamBooks lo registra come sospeso e ti avvisa, perché va gestito a parte.
• Abbonamenti e una tantum: il meccanismo è identico per i pagamenti ricorrenti e per quelli singoli.

Fattura a un privato: come far arrivare il codice fiscale

Con la Tax ID collection attiva, il Checkout di Stripe mostra al cliente il campo per il codice fiscale d'impresa. Stripe però la limita ai clienti business: in Italia raccoglie solo la partita IVA (Tax ID di tipo eu_vat) e non chiede il codice fiscale di un privato.

Stripe sa invece conservare il codice fiscale sul cliente, come Tax ID di tipo it_cf. Per emettere la fattura a un privato che la chiede:

1. nel tuo sito, prima di mandarlo al pagamento, chiedigli se vuole la fattura e raccogli nome, indirizzo e codice fiscale;
2. salva il codice fiscale sul suo Customer Stripe come Tax ID di tipo it_cf (API POST /v1/customers/{id}/tax_ids con type=it_cf) e fai partire il pagamento con quel Customer.

A ogni incasso SamBooks legge i Tax ID del cliente: se trova un it_cf di un privato e nessuna partita IVA, genera la fattura a suo nome. Se il Tax ID non è un codice fiscale valido di persona fisica, registra l'incasso come sospeso e ti avvisa.

Non usare i custom field del Checkout per il codice fiscale. Stripe stesso sconsiglia di raccogliere con i custom field dati personali o protetti dalla legge. SamBooks legge ancora un eventuale campo "codice fiscale" già configurato, ma la strada giusta è il Tax ID it_cf.

Per sapere se il tuo Checkout raccoglie già i dati fiscali, chiedilo a Sam (vedi sotto).

Chiedilo a Sam

Il collegamento con le credenziali resta un passaggio da fare qui sopra: una volta attivo, puoi chiedere a Sam di controllarlo e di usarlo al posto tuo per gli incassi che arrivano.

• Cercare — «Il mio account Stripe risulta collegato a SamBooks? In che modalità?». Sam ti dice se l'integrazione è attiva, in modalità test o live.
• Cercare — «Il mio checkout Stripe raccoglie partita IVA e indirizzo? Mi servono per fatturare agli abbonati». Sam controlla la configurazione del tuo checkout Stripe e te lo conferma.
• Registrare — «Sul mio Stripe è stata pagata la fattura in_1QabcdEFGH2345: registramela in contabilità». Sam la registra subito in contabilità e te lo dice: resta tracciata e puoi annullarla.

Creare la restricted key e il webhook su Stripe resta comunque un passaggio manuale, fuori dalla chat: nessun prompt lo sostituisce.

Domande frequenti

Incasso dai clienti con Stripe. Si può collegare a SamBooks così non ricopio gli incassi a mano? Sì, è proprio questa guida: colleghi Stripe una volta con le due credenziali, e da quel momento SamBooks contabilizza da solo ogni incasso, che diventi una fattura (riconciliata o generata) o un corrispettivo.

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 restricted key e non la secret key? SamBooks deve solo leggere i tuoi incassi, non modificarli. Una restricted key con permessi Read è la scelta più sicura: la secret key (sk_) darebbe accesso completo al tuo account.

Posso provare prima senza rischi? Sì: usa la modalità test di Stripe (i link /test/...). La restricted key di test inizia con rk_test_, il webhook signing secret con whsec_; non muovono denaro reale.

Ho rigenerato la restricted key su Stripe: cosa faccio? Riapri Impostazioni → Azienda → Integrazioni → Stripe, clicca Aggiorna credenziali, incolla la nuova restricted key (e il webhook signing secret) e clicca Collega.

Come scollego Stripe? Dalla stessa finestra, pulsante Disconnetti, poi conferma. Le credenziali salvate vengono rimosse; gli incassi già contabilizzati restano.

Cosa succede se il cliente disdice l'abbonamento su Stripe? Se hai collegato una fattura ricorrente di SamBooks a quell'abbonamento Stripe, alla disdetta SamBooks disattiva automaticamente la fattura ricorrente collegata, così non continui a emettere documenti per un servizio ormai cessato, e ti avvisa con una notifica. Se la disdetta era solo programmata a fine periodo e poi viene annullata, la fattura ricorrente viene riattivata in automatico. Lo scheduler delle fatture ricorrenti resta comunque tuo: puoi sempre riattivarla o disattivarla a mano. Perché tutto questo funzioni, ricordati di selezionare anche gli eventi customer.subscription.deleted e customer.subscription.updated al passo 4.

Come collego una fattura ricorrente a un abbonamento Stripe? Apri Fatture di vendita, premi Fatture ricorrenti in alto, apri il modello e compila il campo Abbonamento Stripe collegato con l'id della subscription del cliente (inizia con sub_, lo trovi nel Dashboard di Stripe). In alternativa chiedilo a Sam, indicandogli il modello e l'id. Per scollegarlo, svuota il campo.

SamBooks può creare pagamenti o modificare qualcosa su Stripe? No. Con la restricted key in sola lettura SamBooks legge abbonamenti, fatture e incassi e riceve gli eventi dal webhook, ma non crea pagamenti, non emette rimborsi e non disdice abbonamenti: tutto questo resta nel tuo Dashboard di Stripe.

Funzioni correlate

• Registrare incassi e pagamenti
• Riconciliare i movimenti bancari
• Registrare i corrispettivi
• Fatture ricorrenti automatiche
• Collegare il negozio Shopify