UC-020 — Import Contatti da VCard

Campo	Valore
ID	UC-020
Obiettivo	Importare contatti da file VCard e verificare l'importazione
Canale	Tutti
Complessità	Intermedia
Tempo stimato	10 minuti
API coinvolte	`POST /api/partner-gateway/v1/contacts/upload/vcard`, `GET /api/partner-gateway/v1/contacts`, `POST /api/partner-gateway/v1/contacts/list/contacts`, `GET /api/partner-gateway/v1/contacts/list/{listId}/contacts`

Scenari reali

Migrare da CRM: L'azienda SalesForce-Pro esporta i contatti dal vecchio CRM in formato VCard e li importa nella piattaforma Qlara per avviare campagne SMS.
Importare da telefono: Il commerciale esporta la rubrica del telefono aziendale in .vcf e la carica per creare una lista di contatti business.
Sync Outlook: Il team marketing sincronizza periodicamente i contatti Outlook esportati in VCard per mantenere aggiornate le liste di invio.

Flusso di importazione

Il diagramma mostra il flusso completo: upload del file, parsing, salvataggio, aggiunta alla lista e verifica.

Prerequisiti

API Key attiva con permessi di gestione contatti
File VCard (.vcf) in formato vCard 3.0 o 4.0
Lista di destinazione già creata (o crearne una nuova con POST /contacts/list, vedi Varianti)

Step 1 — Carica il file VCard

Invia il file .vcf tramite multipart form-data, con il nome del file in fileName.

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/contacts-export.vcf" \
  -F "fileName=contacts-export.vcf"

Response — Import completato

{
  "numContact": 250,
  "addedContact": 230,
  "updatedContact": 15,
  "listId": null,
  "listName": null,
  "numError": 5
}

Contatti già presenti

L'import avviene in modalità CREATE_UPDATE: i nuovi contatti vengono creati (addedContact), mentre quelli già presenti, riconosciuti dal numero di telefono, vengono aggiornati con i dati del VCard (updatedContact). numError conta le voci che non è stato possibile importare. listId e listName restano null perché l'upload non ha un parametro per la lista di destinazione: è lo Step 2 ad aggiungere i contatti alla lista.

Dietro le quinte — Parsing del file VCard

Validazione formato: Il parser verifica che il file sia un VCard valido (header BEGIN:VCARD, footer END:VCARD).
Estrazione campi: Vengono estratti FN (nome completo), TEL (telefono), EMAIL e ADR (indirizzo). Il campo TEL e obbligatorio.
Normalizzazione numeri: I numeri di telefono vengono normalizzati in formato E.164 (es. 347 123 4567 diventa +393471234567). Se il prefisso internazionale manca, viene applicato il default dell'account.
Deduplicazione: I contatti vengono confrontati per numero di telefono normalizzato: un contatto già presente viene aggiornato, altrimenti ne viene creato uno nuovo.
Solo rubrica: I contatti importati vengono salvati in rubrica senza essere aggiunti a nessuna lista; l'assegnazione alla lista è una chiamata separata (Step 2).

Step 2 — Aggiungi i contatti importati alla lista

Trova gli ID dei contatti importati con GET /contacts: notListIds=4821 restituisce i contatti non ancora presenti nella lista di destinazione, fino a 1.000 per pagina. Tieni quelli del tuo file (per esempio in base al numero di telefono) e aggiungili alla lista:

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts?notListIds=4821&page=0&limit=1000" \
  -H "X-Api-Key: YOUR_API_KEY"

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/list/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "listIds": [4821],
    "contactIds": [72045, 72046, 72047]
  }'

Response — Contatti aggiunti

[90311, 90312, 90313]

La risposta elenca gli ID delle associazioni create.

Intera rubrica

Se la lista deve contenere tutta la tua rubrica, come in una migrazione da CRM verso un nuovo account, invia "allContacts": true al posto di contactIds: vengono aggiunti tutti i contatti, tranne quelli elencati in excludeIdsAllContacts.

Step 3 — Verifica i contatti importati

Recupera la lista dei contatti per verificare che l'importazione sia andata a buon fine.

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts/list/4821/contacts?limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contatti nella lista

{
  "data": [
    {
      "id": 72045,
      "fullName": "Marco Rossi",
      "firstName": "Marco",
      "lastName": "Rossi",
      "phoneNumbers": ["+393471234567"],
      "emailAddresses": ["marco.rossi@email.com"],
      "mobilePhoneNumber": "+393471234567",
      "isValidMobilePhoneNumber": true,
      "createdAt": "2026-04-09 09:00:10.215+0000",
      "listIds": [4821]
    },
    {
      "id": 72046,
      "fullName": "Giulia Bianchi",
      "firstName": "Giulia",
      "lastName": "Bianchi",
      "phoneNumbers": ["+393489876543"],
      "emailAddresses": ["g.bianchi@company.it"],
      "mobilePhoneNumber": "+393489876543",
      "isValidMobilePhoneNumber": true,
      "createdAt": "2026-04-09 09:00:10.231+0000",
      "listIds": [4821]
    }
  ],
  "page": 0,
  "limit": 10,
  "totalCount": 245,
  "totalPages": 25
}

Dietro le quinte — Indicizzazione e ricerca

Indicizzazione: Dopo l'import, i contatti vengono indicizzati per nome, telefono ed email per consentire ricerche rapide.
Segmentazione: I contatti importati possono essere raggruppati ulteriormente con le smart list, i cui filters confrontano campi del contatto come city o tags (vedi UC-023).

Risultato atteso

Step	Azione	Risultato
1	`POST /contacts/upload/vcard`	File importato, summary con conteggi
2	`POST /contacts/list/contacts`	Contatti importati aggiunti alla lista
3	`GET /contacts/list/{listId}/contacts`	Contatti visibili nella lista

Esempio completo end-to-end

Scenario SalesForce-Pro: migrazione contatti dal vecchio CRM.

# 1. Importa il file VCard
echo "=== Import VCard ==="
IMPORT_RESULT=$(curl -s -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@./crm-export-2026-04.vcf" \
  -F "fileName=crm-export-2026-04.vcf")

echo "$IMPORT_RESULT" | jq '{numContact, addedContact, updatedContact, numError}'

# 2. Aggiungi i contatti importati alla lista di migrazione
#    (in un account nuovo, i contatti non ancora in lista sono quelli appena importati)
LIST_ID=4821
CONTACT_IDS=$(curl -s -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts?notListIds=${LIST_ID}&page=0&limit=1000" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -c '[.data[].id]')

curl -s -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/list/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d "{\"listIds\": [${LIST_ID}], \"contactIds\": ${CONTACT_IDS}}" | jq 'length'

# 3. Verifica i contatti importati
echo "=== Primi 5 contatti importati ==="
curl -s -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts/list/${LIST_ID}/contacts?limit=5" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.data[] | {fullName, mobilePhoneNumber, listIds}'

Varianti

Import con aggiornamento contatti esistenti

Se vuoi aggiornare i dati dei contatti già presenti (es. nuovo indirizzo email), carica il file aggiornato: l'import avviene sempre in modalità CREATE_UPDATE, quindi i contatti riconosciuti dal numero di telefono vengono aggiornati.

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@./contacts-updated.vcf" \
  -F "fileName=contacts-updated.vcf"

Import in una nuova lista

L'upload non crea liste: crea prima la nuova lista, poi importa il file e aggiungi i contatti alla lista con l'id restituito dalla prima chiamata, come nello Step 2:

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/list \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "Outlook Sync Aprile 2026"
  }'

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@./outlook-contacts.vcf" \
  -F "fileName=outlook-contacts.vcf"

Errori comuni

400 Bad Request — File VCard non valido

{
  "status": "fail",
  "data": {
    "file": "Invalid VCard format. Expected BEGIN:VCARD header."
  }
}

Soluzione: Verifica che il file sia un VCard valido (v3.0 o v4.0). Apri il file con un editor di testo e controlla che inizi con BEGIN:VCARD.

413 Payload Too Large — File troppo grande

{
  "status": "fail",
  "data": {
    "file": "File size exceeds maximum allowed (10 MB)"
  }
}

Soluzione: Suddividi il file VCard in più file più piccoli (max 10 MB ciascuno) e importali separatamente.

Prossimi passi

UC-007 — Gestione Contatti e Liste: Gestisci e segmenta i contatti importati
UC-006 — Campagna Bulk SMS: Invia una campagna alla lista appena importata
UC-016 — Monitorare Credito e Abbonamento: Verifica il credito prima dell'invio

Riferimenti

API Reference — Contacts

Scenari reali​

Flusso di importazione​

Prerequisiti​

Step 1 — Carica il file VCard​

Response — Import completato​

Step 2 — Aggiungi i contatti importati alla lista​

Response — Contatti aggiunti​

Step 3 — Verifica i contatti importati​

Response — Contatti nella lista​

Risultato atteso​

Esempio completo end-to-end​

Varianti​

Import con aggiornamento contatti esistenti​

Import in una nuova lista​

Errori comuni​

400 Bad Request — File VCard non valido​

413 Payload Too Large — File troppo grande​

Prossimi passi​

Riferimenti​