Tutorial Fiduciario: come usare Accountex nel tuo studio

Cosa impari da questo tutorial

Primo accesso, onboarding e dashboard

Prima di poter invitare clienti devi creare correttamente la tua organizzazione fiduciaria. Il processo richiede pochi minuti ma determina il codice associazione FID-… che userai per associare i mandati.

Registrazione e sicurezza dello studio

Come fiduciario sei responsabile dei dati dei tuoi clienti: la sicurezza deve essere massima fin dal primo accesso.

• Apri /auth/register e inserisci nome, cognome, email professionale dello studio e password di almeno 8 caratteri.
• Conferma l'email ricevuta da Brevo. Il login è automatico e vieni reindirizzato a /onboard.
• Attiva immediatamente la 2FA in /settings/security e salva i codici di backup nella cassaforte dello studio.
• Per il login successivo puoi usare email/password o Google OAuth da /auth.
• In caso di smarrimento usa /auth/forgot-password per ricevere un link di reset via email.

Creare l'organizzazione fiduciaria

In /onboard, alla domanda "Che tipo di organizzazione vuoi creare?" seleziona Fiduciaria. Compila ragione sociale, forma giuridica, indirizzo, NPA (≥4 cifre), cantone, IBAN e banca. Al termine il sistema genera un codice associazione FID-… univoco visibile in /settings o nella sezione mandati.

Dashboard e orientamento

L'interfaccia è identica a quella di un'azienda, con alcune voci aggiuntive pensate per lo studio:

• Sidebar Fiduciaria con Mandati (/fiduciary/mandates) e Richieste documenti (/fiduciary/document-requests).
• Selettore "Acting as" con banner in header che ricorda quale cliente stai gestendo.
• Chat FAB che mostra le conversazioni con tutti i clienti attivi e un badge per i messaggi non letti.
• Badge notifiche che include eventi dei clienti (documenti caricati, richieste completate, inviti ricevuti).
• Fiscal Year Switcher in contesto actAs per passare rapidamente tra esercizi del cliente durante la review.

Mandati: invitare, associare e creare clienti gestiti

Ogni relazione con un cliente in Accountex è rappresentata da un mandato (record FiduciaryAssociation). La lista completa è in /fiduciary/mandates con filtri per stato (in attesa, attivo, rifiutato, terminato) e ricerca per nome azienda.

Panoramica dei mandati

Apri /fiduciary/mandates per la lista o /fiduciary/mandates/[id] per il dettaglio di un singolo mandato. Hai tre modalità per instaurare una relazione con un cliente, da scegliere in base al grado di autonomia del cliente stesso.

Invitare un'azienda cliente

Dal menu /fiduciary/mandates clicca Invita cliente (o Nuovo mandato) per inviare via email un link di adesione.

• Clicca Invita cliente o Nuovo mandato nella pagina dei mandati.
• Inserisci l'email del referente dell'azienda cliente.
• Aggiungi un messaggio personalizzato (opzionale ma consigliato).
• Clicca Invia invito: viene creato un record FiduciaryInvitation e inviata un'email al cliente.
• L'invito compare in lista come In attesa; quando il cliente lo accetta, il mandato diventa Attivo.

Associazione con codice fiduciario

Se il cliente ha già un account Accountex può auto-richiedere l'associazione inserendo il tuo codice FID-… nella propria area. La richiesta compare in /fiduciary/mandates sezione Richieste in attesa: valuta le informazioni dell'azienda e clicca Approva o Rifiuta.

Creare un cliente gestito direttamente

Quando il cliente non ha (ancora) un account Accountex e preferisci gestirgli interamente la contabilità, usa il pulsante Crea cliente gestito. In un'unica transazione il sistema crea organizzazione azienda con flag managed:true, abbonamento free, piano dei conti svizzero, primo esercizio fiscale, FiduciaryAssociation già approved e chat pronta.

• In /fiduciary/mandates clicca Crea cliente gestito.
• Sezione Dati aziendali: ragione sociale, forma giuridica, settore, UID e P.IVA (opzionali).
• Sezione Sede: via, NPA 4 cifre, città, cantone.
• Sezione Impostazioni contabili: inizio/fine esercizio, anno contabile, IBAN e banca.
• Clicca Crea cliente gestito: il mandato è attivo immediatamente.

Contesto actAs: operare come il cliente

Una volta approvato un mandato, accedi alla contabilità del cliente via parametro ?actAs=<orgId>. Tutte le chiamate tRPC/API includono automaticamente l'header x-acting-as-org e ogni azione viene tracciata nell'audit log del cliente con il tuo userId come autore.

Avviare ed uscire dal contesto actAs

• Apri /fiduciary/mandates e sulla riga del mandato clicca Accedi, oppure apri il dettaglio e clicca Apri contabilità.
• L'URL assume il formato /?actAs=<orgId> e in header compare il banner "Stai operando come <Nome Azienda Cliente>".
• Navighi dashboard, fatture, spese, report e IVA del cliente con i permessi di owner dell'azienda.
• Per uscire clicca Esci dal cliente nel banner, oppure torna su /fiduciary/mandates senza parametro.

Operare sulla contabilità

Esegui tutte le operazioni contabili come farebbe l'azienda. Ogni mutazione viene loggata con il tuo user come autore. Non cambiare impostazioni sensibili (IBAN, dati fiscali) senza concordarle con il cliente: potresti rompere flussi di pagamento esistenti.

Gestire l'accesso del cliente alla propria contabilità

Sui mandati attivi puoi decidere se il cliente può vedere/modificare la propria contabilità oppure se la gestione è esclusiva dello studio (mutation toggleClientAccountingAccess, campo allowClientAccountingAccess). L'interruttore è nella scheda mandato in /fiduciary/mandates/[id].

• Durante le chiusure di fine anno: disabilita l'accesso per evitare registrazioni del cliente mentre esegui rettifiche.
• Per clienti creati come managed: evita accessi accidentali quando il cliente non ha interesse a operare.
• Per periodi di consolidamento: mantieni fermi i saldi mentre lavori il cluster di più mandati.

Comunicazione: chat, richieste documenti e upload pubblico

Accountex offre tre canali complementari per raccogliere informazioni e documenti dai clienti. Usa quello giusto in base al livello di formalità richiesto.

Chat fiduciario-cliente

Apri il FAB chat in basso a destra per vedere le conversazioni con tutti i clienti attivi, oppure clicca Chat dal dettaglio mandato. La consegna è real-time via Socket.IO (stanza org:[id]).

• Allegati file diretti tramite icona graffetta (ChatMessage supporta allegati).
• Badge FAB con totale messaggi non letti (getTotalUnread); marcatura lettura automatica all'apertura.
• Notifica push/email al cliente se configurata dalla sua organizzazione.
• Ideale per chiarimenti rapidi; per richieste formali con tracking e scadenze usa invece le Richieste documenti.

Richieste documenti ai clienti

Dal menu /fiduciary/document-requests crea richieste formali con link pubblico che il cliente apre senza login. Ogni documento caricato viene automaticamente sigillato (SHA-256 + RSA-PSS + TSA) per revisione.

• Clicca Nuova richiesta e seleziona il cliente destinatario dai mandati attivi.
• Compila titolo (es. "Documenti IVA Q2 2026"), descrizione e lista documenti richiesti.
• Imposta una scadenza opzionale per attivare i solleciti automatici.
• Il sistema crea un token univoco, invia email al cliente con link /r/[token] e genera notifica document_request_pending.
• Monitora lo stato di caricamento in /fiduciary/document-requests/[id] con timeline e download integrità.
• Invia sollecito manuale dal dettaglio oppure lascia che /api/cron/document-reminders invii reminder automatici fino al completamento.

Upload pubblico del cliente /r/[token]

Il cliente riceve l'email con link /r/[token], apre una pagina pubblica senza login con nome del fiduciario, titolo della richiesta e lista documenti. Carica ciascun file (max 10 MB via presigned URL S3); al termine ricevi email + notifica document_uploaded.

Chiusure d'esercizio, IVA e report

Per ogni cliente gestito esegui tipicamente un ciclo di chiusura pre-verificato, la dichiarazione IVA AFC e la produzione dei report fondamentali per la revisione annuale.

Flusso di chiusura d'esercizio

• In /fiscal-years seleziona l'esercizio e clicca Anteprima chiusura; nello step Report pre-chiusura scarica il PDF (/api/reports/pre-closing/pdf) con registrazioni in bozza, conti non riconciliati e documenti mancanti.
• Completa le riconciliazioni bancarie in /tools/bank-statement-import e gli ammortamenti cespiti in /assets.
• Registra ratei e risconti e altre rettifiche di fine anno in /journal.
• Compila le note di bilancio in /reports/financial-notes: fai rivedere al cliente in Bozza, poi passa a Definitiva.
• In /fiscal-years usa closingPreviewWithAdjustments per l'anteprima con rettifiche e invia al cliente per conferma.
• Clicca Chiudi: lo stato diventa closed, vengono generati i saldi di apertura; esporta il giornale da /tools/accounting-export per archivio dello studio.

Dichiarazione IVA AFC

In contesto actAs apri /vat/afc-declaration per gestire le dichiarazioni periodiche per ciascun cliente.

• Clicca Nuova dichiarazione e seleziona periodo e metodo (effettivo/concordato).
• Clicca Genera e rivedi i totali per aliquota.
• Esporta XML da /api/vat/declaration/xml per upload al portale AFC.
• Esporta PDF per archivio cliente e allegalo alla chat come prova dell'invio.
• Dopo l'invio al portale, clicca Segna come inviata per chiudere lo stato.

Report periodici per revisione

Per ciascun cliente e a intervalli regolari produci il set standard di report, allegabili alla chat per review con il cliente:

• Bilancio (/reports/balance-sheet) e Conto economico (/reports/income-statement) in PDF.
• Bilancio di verifica (/reports/trial-balance) e libro mastro / partitari (/reports/subsidiary-ledger) indispensabili per revisione e controlli AFC.
• Libro conto per singolo conto da /chart-of-accounts/[code] → Esporta PDF libro conto (/api/reports/account-ledger/pdf).
• Aging crediti/debiti (/reports/aging) per monitorare incassi e pagamenti.
• Analisi centri di costo (/reports/cost-center-analytics) e report valute per clienti multivaluta.
• Report budget dal dettaglio /budget/[id] → Esporta PDF (/api/reports/budget/pdf) per confronto previsioni/consuntivo.

Consolidamento multi-mandato

Se gestisci più società legate (gruppo di aziende dello stesso cliente) puoi creare gruppi di consolidamento in /consolidation con mappatura conti, riconciliazione intercompany e rettifiche.

Creare e gestire un gruppo di consolidamento

• Vai su /consolidation/new e inserisci nome gruppo, valuta di presentazione, capogruppo.
• In /consolidation/[groupId]/members aggiungi i membri (getAvailableClients) con quota, metodo (integrale/proporzionale/patrimonio netto) e valuta funzionale.
• In /consolidation/[groupId]/account-mapping clicca Auto-mappa (autoMapAccounts) e correggi manualmente dove serve.
• In /consolidation/[groupId]/intercompany crea regole per identificare poste reciproche e clicca Riconcilia.
• In /consolidation/[groupId]/adjustments inserisci rettifiche di consolidamento (eliminazioni, riclassifiche) e genera report consolidati in PDF.

Gestione dello studio: impostazioni, collaboratori, abbonamento

Tutte le funzioni di amministrazione dello studio sono sotto /settings. Qui gestisci dati anagrafici, collaboratori, abbonamento Stripe e notifiche.

Terminare un mandato

Apri /fiduciary/mandates/[id] e clicca Termina mandato: l'associazione viene disattivata, perdi l'accesso actAs e il cliente riceve notifica. Se un tuo invito è stato rifiutato clicca Dismetti per rimuoverlo dalla lista principale (resta nello storico).

Impostazioni dello studio

In /settings trovi schede identiche alle aziende, con alcune particolarità per le fiduciarie:

• Codice associazione FID-… in sola lettura visibile in Organizzazione (copialo per comunicarlo ai clienti).
• Dati studio: ragione sociale, indirizzo, IBAN per parcelle, logo applicato ai PDF generati per i clienti se configurato.
• Prefissi fattura/sollecito: usati solo per la fatturazione emessa dallo studio (tue parcelle).
• Colori personalizzati applicati a PDF e documenti dello studio.
• Privacy e registro trattamenti (/settings/privacy/registro-trattamenti) obbligatorio ex Art. 30 GDPR / Art. 12 nLPD.

Collaboratori dello studio

In /settings/collaborators clicca Invita collaboratore (limite per piano) e inserisci l'email: viene creato CollaboratorInvitation e inviata email. Il collaboratore ha ruolo collaborator sull'organizzazione fiduciaria, vede i mandati e accede in actAs.

Abbonamento dello studio

In /settings/subscription visualizzi piano attuale e limiti (OCR/mese, storage, collaboratori). Clicca Cambia piano per upgrade via Stripe o accedi al Portale clienti Stripe per metodi di pagamento e fatture. Storico in /settings/billing.

Notifiche per il fiduciario

In /settings/notifications configura in-app (Socket.IO real-time), push browser ed email digest (giornaliera o settimanale). Eventi rilevanti: document_uploaded, messaggi chat, inviti/richieste associazione, fatture scadute dei clienti. Attiva push per eventi urgenti ed email digest per panoramica.

Compliance: audit log, sigillatura, privacy, API

Le fiduciarie sono responsabili della tracciabilità e della conformità normativa (nLPD, LIP, archiviazione 10 anni). Accountex offre strumenti integrati per coprire questi obblighi.

Audit log

Lo strumento chiave per revisione e controlli fiscali è disponibile sia a livello studio (/audit-log) sia in contesto actAs (dove mostra le azioni sull'organizzazione cliente, incluse quelle svolte da te).

• A livello studio: azioni dei membri sull'account dello studio.
• In contesto actAs: azioni sull'organizzazione cliente tracciate con il tuo userId.
• Filtri per utente, azione, data, entità; le chiavi sensibili (password, token) sono sanitizzate.
• Indispensabile per revisioni periodiche (consigliate mensili se ci sono più collaboratori).

Sigillatura documenti

Ogni documento in /documents del cliente è sigillato con hash SHA-256, firma RSA-PSS e marca temporale TSA. Per revisioni apri /documents, clicca Verifica integrità sul documento: se autentico e non manomesso il check passa.

Privacy, GDPR e nLPD

In /settings/privacy gestisci i consensi dello studio e le richieste di export/cancellazione dei dati personali. In /settings/privacy/registro-trattamenti compili il registro obbligatorio (finalità, base giuridica, categorie di dati, destinatari, retention, misure di sicurezza) per ciascuna attività di trattamento svolta per i clienti.

API Keys e webhook

In /settings/api crei API key (nome + scopes, valore mostrato una sola volta) e webhook (URL + eventi invoice.*, expense.* + secret HMAC). Monitora lo Storico consegne e usa Invia test per verificare l'endpoint. Per operazioni sui clienti usa sempre l'header x-acting-as-org.

Supporto integrato

Clicca Supporto in sidebar/header per aprire un ticket SupportTicket: se non esiste viene creato automaticamente. Scrivi la richiesta, allega screenshot; gli admin Accountex rispondono in-app. I messaggi admin non letti sono contati nel badge notifiche; gli allegati sono disponibili via presigned URL.

Best practice operative

FAQ e troubleshooting