Aggiungere e invitare un cliente

Aggiungere un cliente alla tua rubrica è il primo passo per associarlo alle commesse e attivare le notifiche operative di ritiro e consegna. Quando vuoi che il cliente acceda direttamente a Truckscanner per vedere le sue spedizioni in tempo reale, lo inviti a registrarsi: l'invito viene inviato per email ed è il canale di collaborazione vero e proprio.

Prima di iniziare la lettura: la guida Panoramica Clienti ti dà la mappa completa della sezione (tabella, filtri, drawer di dettaglio, azioni di riga). Qui invece ci concentriamo sul flusso «aggiungo + invito».

Prima di iniziare

Per aggiungere e invitare un cliente serve:

• Account spedizioniere con ruolo ADMIN oppure OPERATOR (gli utenti con ruolo VIEWER non vedono i bottoni di creazione e invito).
• Partita IVA o codice fiscale del cliente. È obbligatoria perché serve da identificatore univoco e perché abilita la verifica automatica su VIES e nei registri istituzionali. Se non hai una P.IVA — caso raro per un committente reale — non puoi creare il record.
• Indirizzo email del cliente, ma solo nel momento in cui decidi di invitarlo a collaborare su Truckscanner. In rubrica puoi tenere il cliente anche senza email.

1. Apri il dialog «Nuovo cliente»

Dalla pagina Clienti (URL /company/{idAzienda}/trading-partners), clicca il bottone lime «+ NUOVO» in alto a destra dell'header.

Il bottone apre il dialog modale «Nuovo cliente». Il dialog è organizzato in due colonne: a sinistra tutto quello che riguarda l'azienda cliente (identificazione fiscale, ragione sociale, indirizzo sede legale), a destra il referente operativo opzionale e i toggle delle notifiche automatiche che scatteranno quando associerai il cliente alle commesse.

2. Inserisci paese e P.IVA / codice fiscale

I campi Paese e P.IVA / Codice fiscale sono obbligatori (asterisco rosso accanto alle label). Il paese di default è l'Italia, ma puoi cambiarlo: nel menu trovi tutti i paesi UE più i principali extra-UE (Svizzera, Regno Unito, Norvegia, Stati Uniti, ecc.).

Appena scrivi una P.IVA di almeno 8 caratteri Truckscanner avvia in automatico due verifiche in parallelo:

• VIES — il sistema ufficiale dell'Unione Europea che valida la P.IVA per i paesi UE. Restituisce la ragione sociale ufficiale e in alcuni casi un indirizzo grezzo.
• Registri istituzionali — il registro delle imprese del paese (per IT è il Registro Imprese italiano, per gli altri paesi UE le rispettive Camere di Commercio nazionali). Restituisce ragione sociale, indirizzo della sede legale, dati commerciali quando disponibili.

Sotto i campi compare un piccolo drawer verde che ti dice in tempo reale cosa è stato trovato. Cliccandoci sopra, i dati trovati vengono pre-compilati automaticamente nei campi Ragione sociale e Indirizzo sede legale qui sotto. La label cambia da «USA QUESTI DATI» a «DATI USATI» e il bordo della card diventa più scuro per confermarti che la pre-compilazione è avvenuta.

3. Compila il referente e le notifiche, poi salva

Nella colonna destra hai due blocchi, entrambi opzionali in fase di creazione:

• Referente (opzionale) — nome, telefono e email della persona di contatto in azienda. Sono dati di anagrafica utili per le commesse, non vengono usati per l'invito su Truckscanner. Puoi aggiungerli dopo dal drawer di dettaglio se preferisci.
• Notifiche automatiche — i due toggle «Notifiche Email» e «Notifiche SMS / WhatsApp» decidono se il cliente riceverà comunicazioni operative (conferma ritiro, in transito, consegnato, problema) quando lo associ come mittente o destinatario di una commessa. Sono accesi di default. Spegnerli qui o spegnerli più tardi nel drawer Commerciale ha lo stesso effetto: le notifiche operative non partono per quel cliente. I toggle del dialog e del drawer modificano lo stesso campo del cliente, quindi sono sempre allineati.

Quando hai finito clicca il bottone lime «SALVA» in fondo a destra. Truckscanner crea il cliente, chiude il dialog e mostra un toast di conferma «Cliente "{nome}" creato». La nuova riga compare immediatamente in tabella e i contatori delle tab in alto («Tutti», «Registrato», «Invitato», «Non invitato») si aggiornano live: il nuovo cliente entra come «Non invitato» finché non gli mandi l'invito.

4. Invita il cliente a collaborare su Truckscanner

Sulla riga del cliente appena creato, nella colonna Truckscanner, vedi il bottone lime «COLLABORA SU TRUCKSCANNER». È la scorciatoia per inviare l'invito.

Cliccandolo si apre il dialog «Invita su Truckscanner». La descrizione lo dice subito: «L'invito viene inviato per email all'indirizzo qui sotto. Il cliente potrà collaborare su Truckscanner per il monitoraggio e il tracking delle spedizioni».

I campi che vedi:

• Card riepilogo in alto con la ragione sociale e la P.IVA con prefisso paese — solo conferma, non sono editabili.
• Email destinatario invito — obbligatoria. È l'indirizzo a cui parte la mail di invito; viene anche salvata sul cliente come email di contatto se non era già presente.
• Telefono — opzionale e con un piccolo helper sotto: «Anagrafica per le commesse — non viene usato per l'invito». Lo lasci vuoto se vuoi: l'invito scatta comunque solo via email.
• Messaggio opzionale — testo libero che verrà incluso nel corpo dell'email di invito (es. «Marco, abbiamo deciso di passare a Truckscanner: trovi qui il link per accedere alle tue spedizioni»).

Quando clicchi «INVIA INVITO» parte la mail e il dialog cambia: scompaiono i campi del form e compare un banner verde di conferma con l'email destinataria, un suggerimento per la condivisione manuale del link e l'input con il link di registrazione pre-compilato dalla tua P.IVA invitante. C'è anche un'iconcina di copia per portarlo negli appunti.

5. Cosa cambia in tabella dopo l'invito

Chiudendo il dialog con «OK», la riga del cliente cambia colonna Truckscanner in tempo reale:

• Il bottone «COLLABORA SU TRUCKSCANNER» sparisce, sostituito dal badge arancione «Invitato».
• Accanto al badge compaiono tre iconcine che ti permettono di gestire l'invito mentre è ancora pendente.

Le tre iconcine fanno questo:

1. Copia link invito (icona quadrato/clipboard) — copia negli appunti lo stesso link che hai visto nel banner di conferma. Toast «Link copiato».
2. Reinvia invito (icona aeroplano di carta) — rimanda la stessa email NC-A04 allo stesso indirizzo, utile se il cliente non ha ricevuto la prima o se è finita in spam. Toast «Invito reinviato con successo».
3. Annulla invito (icona X) — rimuove l'invito pendente. Il record cliente resta in rubrica come «Non invitato», potrai inviare un nuovo invito quando vuoi. Toast «Invito rimosso».

Il contatore della tab «Invitato» si aggiorna in tempo reale appena clicchi una di queste azioni — è lo stesso fix che abbiamo applicato per la creazione del cliente.

Quando il cliente accetta l'invito e completa la registrazione, lo stato passa automaticamente a «Registrato» (badge verde) e il record viene linkato al suo account Truckscanner: da quel momento condivide con te le spedizioni che lo coinvolgono come mittente o destinatario.

Cosa succede dopo, lato Truckscanner

L'invio dell'invito attiva diverse cose dietro le quinte:

• Viene creata una riga in client_relationships con stato INVITED, un token unico per il link di registrazione e timestamp invited_at.
• Parte la notifica NC-A04 — Invito committente verso l'email destinataria via SMTP. È una notifica diretta (non passa dal dispatcher generale), quindi è immediata.
• Sul cliente vengono aggiornati i campi contact_email e contact_phone se erano vuoti, in modo che diventino disponibili per le future commesse.

Quando in futuro userai questo cliente come mittente o destinatario di una commessa e gli eventi della commessa progrediscono (ritiro confermato, consegnato, problema), partiranno notifiche operative via email all'indirizzo del cliente — sempre che il toggle «Notifiche Email» del cliente sia acceso. Le notifiche su WhatsApp e SMS sono cablate ma in fase di rollout: arrivano in una release successiva e non rompono nulla quando saranno attive perché il toggle è già lì pronto.

Impatto cross-target — cosa riceve il committente

Lato cliente l'invito arriva come email transazionale. Apre Mailpit (in dev) o la posta del destinatario in produzione e trova questo:

Cosa vede l'altro lato

Committente

Il committente riceve un'email con oggetto «Sei stato invitato su Truckscanner da {nome spedizioniere}». Nel corpo trova un saluto personalizzato con la sua ragione sociale, la frase «{spedizioniere} ti ha invitato a unirti alla piattaforma Truckscanner come committente», una lista dei tre vantaggi principali (monitorare spedizioni in tempo reale, gestire contratti e documenti, vedere lo stato di magazzini e sedi) e il bottone lime «REGISTRATI COME COMMITTENTE».

Il bottone della mail apre il flusso di registrazione cliente con il tuo nome di spedizioniere e la tua P.IVA già pre-compilati nel form: il committente non deve cercarti, ti trova già agganciato. Quando completa la registrazione, lo stato della tua riga in tabella diventa «Registrato» e il cliente vede la sua dashboard committente con le spedizioni che lo coinvolgono.

Per il dettaglio completo del lato cliente — schermate del form di registrazione, gestione password, accettazione termini — vedi la pagina speculare: Accettare l'invito di uno spedizioniere.

Cliente «in rubrica» vs cliente «collaboratore»

Una distinzione importante che spesso confonde all'inizio: un cliente in rubrica non è automaticamente un collaboratore attivo su Truckscanner.

• In rubrica — il record cliente vive solo nella tua azienda spedizioniere. Lo associ alle commesse, ricevi notifiche operative al posto suo (o per lui), archivi contratti e listini. Il cliente non sa nulla di Truckscanner: riceve solo le tue comunicazioni email/SMS/WhatsApp dirette quando i suoi mandati si muovono. È perfetto per i clienti piccoli o per quelli che non vogliono uno strumento dedicato.
• Collaboratore attivo — quando il cliente accetta l'invito, ottiene accesso diretto alla piattaforma con la sua dashboard, le sue spedizioni in tempo reale, la gestione dei suoi documenti. Dal tuo lato vedi ancora la sua riga in rubrica, ma con badge «Registrato» e relazione a doppio senso.

Le due cose convivono: ogni cliente è prima «in rubrica» e poi diventa opzionalmente «collaboratore». Il bottone «Collabora su Truckscanner» è la transizione fra i due stati. Puoi sospendere o rimuovere la relazione piattaforma in qualsiasi momento dal drawer di dettaglio senza perdere il cliente in rubrica.

Problemi comuni

Vedi anche

• Panoramica Clienti — la mappa di lettura completa della sezione: tabella, filtri, drawer di dettaglio.
• Accettare l'invito di uno spedizioniere — la pagina speculare lato cliente, con il flusso di registrazione completo.
• Importare clienti da un file CSV — guida in arrivo (per aggiungere molti clienti in un colpo solo invece che uno alla volta).
• Modificare i dati di un cliente esistente — guida in arrivo.