Passa al contenuto principale

Stripe Revenue Sync

Disponibile

Questa integrazione è attiva e pronta all'uso su tutti i piani Pro.

Importa automaticamente i tuoi incassi da Stripe come fatture registrate in Frihet. Ideale per le attività SaaS che incassano con Stripe e hanno bisogno di tenere in ordine la propria fatturazione.

A cosa serve?​

Se incassi con Stripe e vuoi che tali incassi appaiano come fatture in Frihet senza doverle creare manualmente:

  • Importazione automatica — Ogni fattura pagata in Stripe si converte in una fattura in Frihet
  • Sincronizzazione incrementale — Importa solo nuovi incassi dall'ultima sincronizzazione
  • Deduplicazione — Una fattura non viene mai duplicata anche se esegui l'importazione più volte
  • Compatibile con VeriFactu — Le fatture importate passano attraverso la catena di hash e la numerazione gap-free

Differenza con l'integrazione di Stripe​

Stripe (OAuth)Stripe Revenue Sync
ConnessioneOAuth (reindirizza a Stripe)API Key limitata
DirezioneBidirezionaleSolo Stripe → Frihet
TipoPagamenti + abbonamenti + ConnectSolo fatture pagate
FattureAutomatica tramite webhookImportazione su richiesta + auto-sync
Caso d'usoIncassare da FrihetRegistrare incassi da Stripe in Frihet

Usa Revenue Sync se: incassi direttamente da Stripe (Dashboard, Billing, ecc.) e vuoi che tali incassi appaiano in Frihet per la tua contabilità e le tue dichiarazioni.

Requisiti​

  • Account Stripe attivo — Creane uno su stripe.com
  • API Key limitata — Con permessi di sola lettura su invoices e customers
  • Frihet Pro o superiore — Non disponibile nel piano Free

Configurare Stripe Revenue Sync​

Passaggio 1: Crea un'API Key limitata in Stripe​

  1. Vai su Stripe Dashboard → Developers → API Keys
  2. Clicca su Create restricted key
  3. Nome: Frihet Revenue Sync
  4. Permessi necessari:
    • Invoices → Read
    • Customers → Read
  5. Copia la chiave (rk_live_...)

Passaggio 2: Connettiti a Frihet​

  1. Vai su Impostazioni → Integrazioni
  2. Cerca Stripe Revenue Sync
  3. Clicca su Connetti
  4. Incolla la tua API Key limitata
  5. Seleziona la data da cui vuoi importare
  6. Clicca su Salva e connetti

Passaggio 3: Importa fatture​

  1. Clicca su Importa ora
  2. Frihet consulterà le fatture pagate in Stripe a partire dalla data selezionata
  3. Ogni fattura viene creata come bozza e contrassegnata come pagata
  4. La numerazione gap-free e l'hash VeriFactu vengono applicati automaticamente

Passaggio 4: Attiva l'auto-sync (opzionale)​

  1. Nella scheda di configurazione, attiva Auto-sync
  2. Frihet importerà nuovi incassi automaticamente ogni 6 ore
  3. Vengono importate solo le nuove fatture (sincronizzazione incrementale)

Come funziona​

Importazione manuale​

  1. Clicchi su Importa ora
  2. Frihet consulta GET /v1/invoices?status=paid in Stripe
  3. Per ogni fattura che non esista già in Frihet (tramite stripeInvoiceId):
    • Crea una fattura bozza con i dati del cliente
    • La contrassegna come pagata
    • Vengono eseguiti i trigger di Firestore: numerazione e hash VeriFactu
  4. Risultato: fatture pronte per il tuo registro e le tue dichiarazioni

Auto-sync (ogni 6 ore)​

  1. Ogni 6 ore viene eseguita una funzione programmata
  2. Consulta solo le fatture da lastSync (incrementale)
  3. Importa le nuove automaticamente
  4. Aggiorna lastSync con la data attuale
  5. Se rileva che la tua API Key è scaduta, contrassegna l'integrazione come requiresReconnect

Deduplicazione​

Ogni fattura importata salva l'ID della fattura Stripe (stripeInvoiceId) nei suoi metadati. Se tenti di importare la stessa fattura due volte, Frihet la ignora automaticamente.

Mappatura dei dati​

StripeFrihet
invoice.customer_name o customer_emailNome del cliente
invoice.numberRiferimento (nel concetto)
line_items[].descriptionLinee della fattura
line_items[].amountImporto per linea
invoice.taxImposte (se applicabile)
invoice.createdData della fattura
invoice.idstripeInvoiceId (metadato)

Sicurezza​

  • API Key limitata — Sola lettura di invoices e customers. Nessun accesso al denaro.
  • Crittografia AES-256-GCM — La tua API Key viene archiviata crittografata sul server
  • Disconnessione istantanea — Revoca l'accesso in Impostazioni quando vuoi
  • Nessun dato in transito — La comunicazione con Stripe è HTTPS, la chiave non viene mai esposta al frontend

Disconnetti​

  1. Vai su Impostazioni → Integrazioni
  2. Cerca Stripe Revenue Sync
  3. Clicca su Disconnetti
  4. Conferma l'azione

Le fatture già importate rimangono in Frihet. Non vengono eliminate alla disconnessione.

Risoluzione dei problemi​

"Nessuna fattura importata"​

  • Verifica che la tua API Key abbia i permessi di lettura su Invoices e Customers
  • Assicurati che la data di importazione sia precedente ai tuoi incassi
  • Vengono importate solo fatture con stato paid in Stripe
  • Verifica di non essere in modalità test di Stripe (usa chiavi live)

"Riconnetti il tuo account"​

  • La tua API Key è scaduta o è stata revocata
  • Vai su Stripe Dashboard → API Keys e creane una nuova
  • Disconnettiti e riconnettiti in Frihet con la nuova chiave

"Fattura duplicata"​

  • Non dovrebbe succedere. La deduplicazione tramite stripeInvoiceId lo previene
  • Se vedi duplicati, contatta il supporto

"Gli importi non corrispondono"​

  • Frihet importa l'importo così come viene riportato da Stripe
  • Le commissioni di Stripe non vengono dedotte dalla fattura (sono una spesa separata)
  • Verifica la valuta: Stripe riporta in centesimi, Frihet converte automaticamente

Prossimi passi​

Successivo: Stripe Connect - Link di pagamento nelle tue fatture