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 (il pulsante si adatta alla tariffazione della commessa; per le commesse importate da ClickUp, tipicamente a tempo e materiali, indichi periodo e aliquota): 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 (a tempo e materiali o a forfait/SAL).