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/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 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 l'import)
• Quota contatti sufficiente (verifica con UC-016)

Step 1 — Carica il file VCard

Invia il file .vcf tramite multipart form-data specificando la lista di destinazione.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/contacts-export.vcf" \
  -F "listId=list_crm_migration" \
  -F "duplicateStrategy=SKIP" \
  -F "tags=crm-import,q2-2026"

Response — Import completato

{
  "importId": "imp_v1c2a3r4d5",
  "listId": "list_crm_migration",
  "status": "COMPLETED",
  "summary": {
    "total": 250,
    "imported": 230,
    "duplicates": 15,
    "errors": 5,
    "skipped": 20
  },
  "errors": [
    {
      "line": 45,
      "name": "Luca Verdi",
      "reason": "Invalid phone number format"
    },
    {
      "line": 89,
      "name": "Anna Neri",
      "reason": "Missing phone number"
    }
  ],
  "completedAt": "2026-04-09T11:00:15+02:00"
}

:::tip Strategia duplicati Il parametro duplicateStrategy controlla il comportamento in caso di contatti già presenti:

• SKIP: Ignora i duplicati (default)
• UPDATE: Aggiorna i campi del contatto esistente
• DUPLICATE: Crea una copia (non consigliato) :::

Dietro le quinte — Parsing del file VCard

1. Validazione formato: Il parser verifica che il file sia un VCard valido (header BEGIN:VCARD, footer END:VCARD).
2. Estrazione campi: Vengono estratti FN (nome completo), TEL (telefono), EMAIL e ADR (indirizzo). Il campo TEL e obbligatorio.
3. 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.
4. Deduplicazione: I contatti vengono confrontati per numero di telefono normalizzato. La strategia scelta (SKIP, UPDATE) determina il comportamento.
5. Tagging: I tag specificati vengono associati a tutti i contatti importati per facilitare la segmentazione futura.

Step 2 — Verifica i contatti importati

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

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list/list_crm_migration/contacts?limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contatti nella lista

{
  "listId": "list_crm_migration",
  "contacts": [
    {
      "contactId": "cnt_001",
      "name": "Marco Rossi",
      "phoneNumber": "+393471234567",
      "email": "marco.rossi@email.com",
      "tags": ["crm-import", "q2-2026"],
      "createdAt": "2026-04-09T11:00:10+02:00"
    },
    {
      "contactId": "cnt_002",
      "name": "Giulia Bianchi",
      "phoneNumber": "+393489876543",
      "email": "g.bianchi@company.it",
      "tags": ["crm-import", "q2-2026"],
      "createdAt": "2026-04-09T11:00:10+02:00"
    }
  ],
  "total": 230,
  "page": 1,
  "totalPages": 23,
  "hasMore": true
}

Dietro le quinte — Indicizzazione e ricerca

1. Indicizzazione: Dopo l'import, i contatti vengono indicizzati per nome, telefono ed email per consentire ricerche rapide.
2. Segmentazione: I tag assegnati durante l'import permettono di creare segmenti dinamici per le campagne.
3. Quota: Ogni contatto importato viene conteggiato nella quota dell'abbonamento. I duplicati skippati non consumano quota aggiuntiva.

Risultato atteso

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

Esempio completo end-to-end

Scenario SalesForce-Pro: migrazione contatti dal vecchio CRM.

# 1. Verifica quota contatti disponibile
echo "=== Quota Contatti ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/subscription/contacts \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{used, total, available: (.total - .used)}'

# 2. Importa il file VCard
echo "=== Import VCard ==="
IMPORT_RESULT=$(curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@./crm-export-2026-04.vcf" \
  -F "listId=list_crm_migration" \
  -F "duplicateStrategy=SKIP" \
  -F "tags=crm-import,q2-2026")

echo "$IMPORT_RESULT" | jq '.summary'

# 3. Verifica i contatti importati
LIST_ID=$(echo "$IMPORT_RESULT" | jq -r '.listId')
echo "=== Primi 5 contatti importati ==="
curl -s -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list/${LIST_ID}/contacts?limit=5" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.contacts[] | {name, phoneNumber, tags}'

Varianti

Import con aggiornamento contatti esistenti

Se vuoi aggiornare i dati dei contatti già presenti (es. nuovo indirizzo email):

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@./contacts-updated.vcf" \
  -F "listId=list_crm_migration" \
  -F "duplicateStrategy=UPDATE"

Import in una nuova lista

Per creare automaticamente una nuova lista durante l'import:

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@./outlook-contacts.vcf" \
  -F "listName=Outlook Sync Aprile 2026" \
  -F "duplicateStrategy=SKIP"

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.

409 Conflict — Quota contatti esaurita

{
  "status": "fail",
  "data": {
    "contacts": "Contact quota exceeded. Current: 50000/50000. Upgrade your plan to import more contacts."
  }
}

Soluzione: Hai raggiunto il limite di contatti del tuo piano. Elimina contatti non necessari o esegui l'upgrade del piano.

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 quota e credito prima dell'invio

Riferimenti

• API Reference — Contacts