Skip to main content

​
Importazione CSV dei contatti

Importa contatti in blocco in un’area di lavoro da un file CSV. L’importazione viene eseguita in background: il file viene caricato nello storage a oggetti, un worker lo analizza e lo ingerisce a blocchi, e l’interfaccia mostra l’avanzamento in tempo reale.

​
Panoramica

  1. Dalla pagina Contatti, fai clic su Importa CSV.
  2. Scegli uno o più file .csv dal disco (seleziona più file per accodarli in sequenza).
  3. Ogni file viene caricato, accodato per l’elaborazione, e vedrai Caricamento → In coda → Elaborazione → Completato ✓ con una barra di avanzamento per file e contatori aggiornati.
  4. Le righe non andate a buon fine vengono riepilogate con un pulsante Visualizza errori — controllale, correggile nel tuo foglio di calcolo e ricarica il file corretto.

​
Colonne obbligatorie

​
Colonne opzionali

Le intestazioni delle colonne vengono confrontate senza distinzione tra maiuscole e minuscole. Le colonne non fornite vengono ignorate — le colonne extra vengono saltate in sicurezza.

​
Formato del numero di telefono

Tutti i numeri di telefono devono essere normalizzati in formato E.164 — un formato internazionale che inizia con +, il prefisso internazionale, e solo cifre (senza spazi, trattini o parentesi). Suggerimento: se il tuo foglio di calcolo rimuove il + iniziale o introduce la notazione scientifica, formatta la colonna del telefono come Testo prima di esportare.

​
Esempio di CSV

Scarica questo esempio come punto di partenza e sostituisci le righe con i tuoi contatti.

​
Limiti

  • Dimensione file: 10 MB per file.
  • Numero di righe: massimo consigliato 50.000 righe per file. Suddividi elenchi più grandi in più file e caricali in un’unica operazione — verranno elaborati in sequenza.
  • Codifica: UTF-8. Esporta da Excel come “CSV UTF-8 (delimitato da virgole)” su macOS, oppure “CSV (delimitato da virgole) (*.csv)” con codifica UTF-8 su Windows.
  • Terminatori di riga: sono supportati sia \n che \r\n.
  • Escape: citazione CSV standard — racchiudi un campo tra "…" per includere virgole o a capo, esegui l’escape di una virgoletta interna come "".

​
Risoluzione dei problemi

“missing name” / “missing phone” Alla riga manca un valore obbligatorio. Assicurati che la riga di intestazione usi name e phone (o uno degli alias elencati) e che ogni riga di dati abbia entrambi i campi compilati. “invalid phone format” Il numero di telefono non è stato normalizzabile in formato E.164. Aggiungi un prefisso internazionale con un + iniziale (es. +39…, +1…) oppure rimuovi i caratteri non numerici che interrompono l’analisi. “duplicate phone number (contact already exists)” Un altro contatto nell’area di lavoro ha già questo numero di telefono. Le importazioni non sovrascrivono i contatti esistenti — elimina o aggiorna prima il record esistente se devi sostituirlo. Importazione bloccata su “In coda” Il worker in background è temporaneamente in ritardo sui job. L’interfaccia si aggiornerà automaticamente quando il worker prenderà in carico il job — lascia la pagina aperta, oppure controlla più tardi; lo stato del job viene mantenuto lato server. “upload failed: 413” Il tuo file supera il limite di 10 MB. Suddividilo in file più piccoli e caricali insieme.

​
Come funziona

Sotto il cofano:
  1. POST /api/contacts/import accetta dati multipart form, valida il file e lo carica nel bucket di storage a oggetti contact-imports al percorso {workspaceId}/{importId}/{filename}.
  2. Viene inserita una riga in public.contact_import_jobs con stato pending, e viene accodato un job outbox contacts.import.process.
  3. Il worker prende in carico il job, scarica il file, analizza le righe, normalizza i numeri di telefono e inserisce i contatti a blocchi di 100 — aggiornando processed_rows, successful_rows, failed_rows e error_report dopo ogni blocco.
  4. GET /api/contacts/import/:id restituisce lo stato corrente affinché l’interfaccia possa effettuare il polling.
I numeri di telefono duplicati vengono segnalati come righe non riuscite (il contatto esistente non viene modificato) — questo rende i ricaricamenti sicuri e idempotenti.