Passa al contenuto principale

UC-028 — Compliance e Opt-out (GDPR)

CampoValore
IDUC-028
ObiettivoGestire richieste di opt-out e cancellazione contatti in conformita GDPR
CanaleTutti (SMS, RCS, WhatsApp)
Complessità⭐⭐ Intermedio
Tempo stimato15 minuti
API coinvolteGET /api/partner-gateway/v1/contacts, DELETE /api/partner-gateway/v1/contacts, DELETE /api/partner-gateway/v1/contacts/list/contacts

Scenari reali​

  • FashionOutlet — Richiesta GDPR art. 17: Un cliente invia un'email richiedendo la cancellazione completa dei propri dati. L'operatore deve rimuoverlo da tutte le liste e cancellare il contatto entro 30 giorni.
  • TelcoMobile — Gestione opt-out: Un utente risponde "STOP" a un SMS promozionale. Il sistema automaticamente lo rimuove dalle liste marketing e lo aggiunge alla lista di esclusione.
  • ClinicaSalute — Pulizia contatti non raggiungibili: Dopo una campagna, il team marketing rimuove tutti i contatti con stato ERROR permanente per mantenere le liste pulite e ridurre i costi.

Flusso di opt-out e cancellazione​

Il diagramma illustra il flusso completo di gestione di una richiesta di opt-out: ricerca del contatto, rimozione dalle liste, cancellazione definitiva e conferma.

Step 1 — Cerca il contatto per numero di telefono​

Quando ricevi una richiesta di opt-out, cerca il contatto nel sistema:

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts?phoneNumber=%2B393471234567" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contatto trovato​

{
  "data": [
    {
      "id": 20481,
      "fullName": "Marco Bianchi",
      "firstName": "Marco",
      "lastName": "Bianchi",
      "phoneNumbers": ["+393471234567"],
      "mobilePhoneNumber": "+393471234567",
      "listIds": [1201, 1202, 1203]
    }
  ],
  "page": 0,
  "limit": 10,
  "totalCount": 1,
  "totalPages": 1
}
Nota l'id e i listIds

Il campo id del contatto e i suoi listIds ti serviranno per gli step successivi. Una sola chiamata nello Step 2 rimuove il contatto da tutte queste liste; per vederne i nomi, chiama GET /contacts/list?contactIds=20481.

Step 2 — Rimuovi il contatto da tutte le liste​

Rimuovi il contatto da tutte le sue liste con una sola chiamata, passando i listIds dello Step 1:

# Rimuovi da "Clienti attivi", "Newsletter marketing" e "Promo stagionali"
curl -X DELETE "https://api.qlara.ai/api/partner-gateway/v1/contacts/list/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "listIds": [1201, 1202, 1203],
    "contactIds": [20481]
  }'

Response — Rimosso dalle liste​

true

Non serve ripetere la chiamata per ogni lista: tutte le liste in listIds vengono gestite insieme.

Dietro le quinte — Perche rimuovere dalle liste prima di cancellare
  1. Integrita referenziale: Rimuovere il contatto dalle liste prima della cancellazione assicura che non restino riferimenti orfani. Alcune campagne programmate potrebbero ancora referenziare le liste.
  2. Audit trail: La rimozione esplicita da ogni lista genera eventi tracciabili nel log, utili per dimostrare la conformita GDPR.
  3. Campagne in corso: Se una campagna e in fase di invio e usa una di queste liste, la rimozione preventiva impedisce che il contatto riceva ulteriori messaggi prima della cancellazione completa.
  4. Tempistiche GDPR: Il Regolamento europeo (art. 17) concede 30 giorni per completare la cancellazione. Tuttavia, e buona pratica bloccare immediatamente l'invio (rimozione dalle liste) e procedere alla cancellazione il prima possibile.

Step 3 — Cancella il contatto​

Dopo aver rimosso il contatto da tutte le liste, procedi con la cancellazione definitiva:

curl -X DELETE "https://api.qlara.ai/api/partner-gateway/v1/contacts?ids=20481" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contatto cancellato​

true
Cancellazione permanente

La cancellazione del contatto e irreversibile. Tutti i dati associati (nome, email, telefono, storico liste) verranno rimossi definitivamente. Assicurati di aver completato le operazioni di audit e backup necessarie prima di procedere. Passa sempre il contatto in ids: il parametro notIds funziona al contrario e cancella tutti i contatti dell'account tranne quelli elencati.

Step 4 — Verifica la cancellazione​

Conferma che il contatto non esista più nel sistema:

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts?phoneNumber=%2B393471234567" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Nessun risultato​

{
  "data": [],
  "page": 0,
  "limit": 10,
  "totalCount": 0,
  "totalPages": 0
}

Risultato atteso​

StepAzioneRisultato
1GET /contacts?phoneNumber=...Contatto trovato con i suoi listIds
2DELETE /contacts/list/contactsContatto rimosso da tutte le liste
3DELETE /contacts?ids={id}Contatto cancellato definitivamente
4GET /contacts?phoneNumber=...totalCount: 0, conferma cancellazione

Esempio completo end-to-end​

Ecco lo scenario FashionOutlet completo per una richiesta GDPR art. 17:

#!/bin/bash
# Script GDPR opt-out completo per FashionOutlet

API_KEY="YOUR_API_KEY"
BASE_URL="https://api.qlara.ai/api/partner-gateway/v1"
PHONE="+393471234567"
PHONE_ENCODED="%2B393471234567"

echo "=== GDPR Opt-out Request ==="
echo "Data richiesta: $(date -Iseconds)"
echo "Numero: ${PHONE}"

# 1. Cerca il contatto
CONTACT=$(curl -s -X GET "${BASE_URL}/contacts?phoneNumber=${PHONE_ENCODED}" \
  -H "X-Api-Key: ${API_KEY}")

CONTACT_ID=$(echo "$CONTACT" | jq -r '.data[0].id')
TOTAL=$(echo "$CONTACT" | jq -r '.totalCount')

if [[ "$TOTAL" == "0" || "$CONTACT_ID" == "null" ]]; then
  echo "Contatto non trovato. Nessuna azione necessaria."
  exit 0
fi

echo "Contatto trovato: ${CONTACT_ID}"

# 2. Rimuovi il contatto da tutte le sue liste con una sola chiamata
LIST_IDS=$(echo "$CONTACT" | jq -c '.data[0].listIds // []')

if [[ "$LIST_IDS" != "[]" ]]; then
  echo "Rimozione dalle liste: ${LIST_IDS}"
  curl -s -X DELETE "${BASE_URL}/contacts/list/contacts" \
    -H "X-Api-Key: ${API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"listIds": '"${LIST_IDS}"', "contactIds": ['"${CONTACT_ID}"']}' > /dev/null
fi

# 3. Cancella il contatto
echo "Cancellazione contatto: ${CONTACT_ID}"
curl -s -X DELETE "${BASE_URL}/contacts?ids=${CONTACT_ID}" \
  -H "X-Api-Key: ${API_KEY}" > /dev/null

# 4. Verifica
VERIFY=$(curl -s -X GET "${BASE_URL}/contacts?phoneNumber=${PHONE_ENCODED}" \
  -H "X-Api-Key: ${API_KEY}" | jq -r '.totalCount')

if [[ "$VERIFY" == "0" ]]; then
  echo "Cancellazione confermata. GDPR request completata."
else
  echo "ATTENZIONE: contatto ancora presente. Verifica manuale necessaria."
fi

Varianti​

Opt-out solo marketing (conserva contatto)​

Se l'utente vuole solo smettere di ricevere messaggi promozionali, rimuovilo solo dalle liste marketing mantenendo il contatto nel sistema per le comunicazioni transazionali.

Pulizia massiva contatti non raggiungibili​

Dopo una campagna, rimuovi in batch i contatti con errori permanenti passando un array di contactIds, insieme ai listIds da ripulire, a DELETE /contacts/list/contacts.

Errori comuni​

404 Not Found — Contatto non esistente​

{ "status": "fail", "data": { "error": "Contact not found" } }

Soluzione: Il contatto potrebbe essere già stato cancellato. Verifica con GET /contacts prima di tentare la cancellazione.

409 Conflict — Contatto in uso da campagna attiva​

{ "status": "fail", "data": { "error": "Contact is referenced by an active campaign" } }

Soluzione: Attendi il completamento della campagna oppure rimuovi prima il contatto dalle liste coinvolte.

Prossimi passi​

Riferimenti​