> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Importazione CSV dei contatti

> Importa contatti in blocco da un file CSV — formato, limiti e risoluzione dei problemi.

# 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

| Colonna | Obbligatoria | Note                                                               |
| ------- | ------------ | ------------------------------------------------------------------ |
| `name`  | Sì           | Nome visualizzato. Alias: `display_name`, `full_name`.             |
| `phone` | Sì           | Numero di telefono. Alias: `phone_e164`, `phone_number`, `mobile`. |

## Colonne opzionali

| Colonna | Note                                                                  |
| ------- | --------------------------------------------------------------------- |
| `tags`  | Elenco separato da punto e virgola, es. `vip;newsletter;2026-winter`. |
| `email` | Email del contatto (memorizzata sulla scheda contatto).               |

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).

| Input originale     | Normalizzato                                   |
| ------------------- | ---------------------------------------------- |
| `+393289214993`     | `+393289214993`                                |
| `+1 (555) 123-4567` | `+15551234567`                                 |
| `393289214993`      | `+393289214993`                                |
| `555-123-4567`      | ❌ prefisso internazionale mancante — rifiutato |

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

```csv theme={null}
name,phone,tags,email
Alice Rossi,+393289214993,vip;newsletter,alice@example.com
Bob Meyer,+4915112345678,partners,bob@example.com
Carla Díaz,+34911234567,vip,
Derek Okafor,+2348011234567,,
```

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.