Integrazione ClickUp: importare ore e progetti in SamBooks

Colleghi ClickUp una volta, scegli il periodo e SamBooks porta dentro le ore tracciate dal tuo team. I rapportini importati diventano timesheet pronti da fatturare, senza doppio inserimento. Tariffe e valore della commessa restano dati amministrativi che imposti in SamBooks.

A cosa serve

Se il tuo team traccia il tempo su ClickUp, l'integrazione chiude il passaggio che ClickUp non copre: dalle ore tracciate alla fattura elettronica. SamBooks importa la parte fatturabile del lavoro (ore, progetti, attività, collaboratori, flag fatturabile) e la fa confluire nei rapportini, dove segue lo stesso flusso di fatturazione delle ore inserite a mano.

La direzione è una sola, da ClickUp verso SamBooks. ClickUp resta lo strumento dove organizzi il lavoro del team; SamBooks diventa lo strumento dove quel lavoro si trasforma in fatture. SamBooks non scrive nulla su ClickUp e non sostituisce ClickUp nella gestione dei progetti.

Prerequisiti

• Un account ClickUp con accesso al workspace di cui vuoi importare le ore.
• Il ruolo Gestore o Amministrativo in SamBooks: solo questi ruoli possono collegare un tool, importare e riconciliare. Il collaboratore non vede questi controlli.
• Per la connessione tramite token: un personal token ClickUp, che inizia con pk_. Lo trovi nelle impostazioni del tuo profilo ClickUp.

Procedura passo-passo

1. Apri la tab Integrazioni PM

Vai su Progetti e apri la tab Integrazioni PM. Trovi due schede di collegamento (ClickUp e File CSV/Excel) e, più sotto, la sezione Riconciliazione.

2. Collega ClickUp

Hai due modi, equivalenti nel risultato.

• Collega con ClickUp (consigliato): apre la pagina di consenso ClickUp dove autorizzi SamBooks ad accedere al tuo workspace. Al termine torni in automatico su SamBooks e la scheda ClickUp risulta collegata.
• Collega con il token: incolli il tuo personal token ClickUp (pk_…) nel campo dedicato e premi Collega con il token. SamBooks verifica subito il token con ClickUp e sceglie il workspace. Se il token non è valido o non dà accesso a nessun workspace, ricevi un messaggio e nulla viene salvato.

In entrambi i casi il token viene conservato cifrato lato SamBooks. La scheda ClickUp mostra l'etichetta Collegato, il workspace e la data dell'ultima sincronizzazione.

3. Importa le ore per un periodo

Con ClickUp collegato, imposti facoltativamente Dal e Al con i selettori data e premi Importa ora. Se non indichi un periodo, SamBooks importa gli ultimi 30 giorni. Al termine compare il riepilogo: quanti rapportini sono stati creati e quanti elementi restano da riconciliare.

In alternativa, dalla scheda File CSV/Excel puoi caricare un foglio ore esportato da qualunque tool. Le colonne previste sono Data, Ore, Collaboratore, Commessa, Attività, Fatturabile, Tariffa, Descrizione; le righe non interpretabili vengono scartate con il motivo, senza far fallire l'intero import.

4. Riconcilia cliente e risorsa

Subito dopo l'import, nella sezione Riconciliazione trovi gli elementi da abbinare, con i pending_review in cima. Per ciascuno SamBooks mostra l'etichetta esterna (ad esempio «ClickUp: Acme S.r.l.») e una select per scegliere il cliente o la risorsa SamBooks corrispondente, poi premi Conferma.

• L'abbinamento automatico avviene solo quando il nome corrisponde in modo esatto e univoco, così non si creano abbinamenti sbagliati. Tutto il resto è scelta manuale.
• Il legame progetto → cliente è il principale da confermare a mano, perché ClickUp non ha il concetto di cliente.
• Scegliere una risorsa non si limita a etichettare: SamBooks sposta davvero i rapportini importati sulla risorsa SamBooks che indichi, così costi e consuntivi della commessa restano corretti.
• Progetti e attività già abbinati uno-a-uno compaiono in Già collegati in sola lettura.

Quando non resta nulla da riconciliare vedi il messaggio «Tutto riconciliato: i rapportini importati sono pronti per la fattura».

5. Genera la fattura

Una volta che la commessa ha un cliente confermato, dal dettaglio della commessa usi Genera fattura T&M: SamBooks raccoglie le ore fatturabili non ancora fatturate, le aggrega per cliente e periodo e produce una bozza di fattura elettronica TD01. È lo stesso flusso delle ore inserite a mano. Finché il cliente di una commessa non è confermato, la commessa non è fatturabile: è una protezione per non far nascere bozze di fattura con dati errati.

Cosa importa SamBooks da ClickUp (e cosa no)

SamBooks importa:

• Progetti, dalle List di ClickUp.
• Attività, dai Task di ClickUp.
• Risorse, dai membri del workspace.
• Ore (rapportini), dalle time entry di ClickUp, con la data e il flag fatturabile di ciascuna voce. I timer ancora in corso non vengono importati.

SamBooks non importa da ClickUp:

• Il cliente: ClickUp non ha un'entità cliente nativa. Il cliente si abbina in SamBooks con la riconciliazione.
• La tariffa e il valore della commessa: sono dati amministrativi che imposti solo in SamBooks, nel prezziario della commessa. Come dice anche la tab: «per ClickUp la tariffa la imposti in SamBooks (dal prezziario della commessa); ClickUp non espone tariffe né clienti».

C'è un'eccezione opzionale, spenta di default: se nel tuo ClickUp usi dei custom field per cliente o tariffa, SamBooks può leggerli e proporli durante l'import. È una configurazione avanzata e non sostituisce il prezziario.

Suggerimenti

• Importa per periodi gestibili (un mese alla volta) per tenere ordinata la riconciliazione.
• Riconcilia subito i clienti dopo il primo import: finché manca il cliente, la commessa resta non fatturabile.
• Un nuovo import dello stesso periodo non duplica le ore già importate: SamBooks riconosce ogni voce e salta quelle già presenti.
• Se preferisci, puoi chiedere a Sam in chat «com'è andato l'ultimo import da ClickUp» o «quante riconciliazioni ho in sospeso».

Errori frequenti

• «Token ClickUp non valido o senza workspace.» Il personal token è errato o non dà accesso ad alcun workspace. Ricontrolla di aver copiato l'intero token pk_… dalle impostazioni ClickUp.
• Righe scartate dopo un import CSV. Alcune righe del foglio non erano interpretabili (data o ore mancanti o non valide, collaboratore o commessa vuoti). Il riepilogo indica quante righe sono state scartate; correggi il foglio e reimporta.
• La commessa non si fattura. Manca il cliente confermato: aprila nella sezione Riconciliazione, abbina il cliente e premi Conferma.
• Ore mancanti dopo l'import. ClickUp restituisce di default solo le ore dell'utente collegato; SamBooks le recupera per ogni membro del workspace. Se mancano ancora, verifica il periodo selezionato e che le voci non siano timer ancora in corso.

FAQ

SamBooks scrive qualcosa su ClickUp? No. L'integrazione è solo in entrata: ClickUp resta intatto.

Devo reinserire le tariffe ogni volta? No. Le tariffe vivono nel prezziario della commessa in SamBooks e si applicano automaticamente alle ore importate al momento della fatturazione.

Cosa succede se importo due volte lo stesso periodo? Niente di problematico: le ore già presenti non vengono duplicate e ciò che è già stato fatturato non viene rifatturato.

Posso usare ClickUp e i fogli Excel insieme? Sì. Puoi avere collegato ClickUp e in più caricare fogli CSV/Excel; la riconciliazione gestisce entrambe le fonti.

Chi può collegare e importare? Solo i ruoli Gestore e Amministrativo. Il collaboratore vede le proprie ore ma non i controlli di integrazione.

Funzioni correlate

• Gestire progetti e commesse: come strutturare le commesse, le attività e il prezziario in SamBooks.
• Rapportini e fatturazione delle commesse: come si revisionano le ore e si genera la fattura T&M.