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://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts?phone=%2B393471234567" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contatto trovato​

{
  "content": [{
    "id": "cnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "phone": "+393471234567",
    "firstName": "Marco",
    "lastName": "Bianchi",
    "lists": [
      { "id": "lst_001", "name": "Clienti attivi" },
      { "id": "lst_002", "name": "Newsletter marketing" },
      { "id": "lst_003", "name": "Promo stagionali" }
    ]
  }],
  "totalElements": 1
}

:::tip Nota il contactId e le liste Il campo id del contatto e gli id delle liste ti serviranno per gli step successivi. Se il contatto e presente in più liste, dovrai rimuoverlo da ciascuna. :::

Step 2 — Rimuovi il contatto da tutte le liste​

Per ogni lista in cui il contatto e presente, rimuovilo:

# Rimuovi da "Clienti attivi"
curl -X DELETE "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list/lst_001/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["cnt_f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }'

Response — Rimosso dalla lista​

{
  "removed": 1,
  "listId": "lst_001",
  "listName": "Clienti attivi"
}

Ripeti per tutte le liste (lst_002, lst_003, ecc.) con lo stesso pattern.

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://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/cnt_f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contatto cancellato​

{
  "deleted": true,
  "contactId": "cnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "deletedAt": "2026-04-09T16:45:00+02:00"
}

:::danger 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. :::

Step 4 — Verifica la cancellazione​

Conferma che il contatto non esista più nel sistema:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts?phone=%2B393471234567" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Nessun risultato​

{
  "content": [],
  "totalElements": 0,
  "page": 0,
  "size": 20
}

Risultato atteso​

StepAzioneRisultato
1GET /contacts?phone=...Contatto trovato con lista associazioni
2DELETE /contacts/list/{id}/contactsContatto rimosso da tutte le liste
3DELETE /contacts/{id}Contatto cancellato definitivamente
4GET /contacts?phone=...totalElements: 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://lora-api.agiletelecom.com/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?phone=${PHONE_ENCODED}" \
  -H "X-Api-Key: ${API_KEY}")

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

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

echo "Contatto trovato: ${CONTACT_ID}"

# 2. Recupera le liste associate
LISTS=$(echo "$CONTACT" | jq -r '.content[0].lists[].id')

for LIST_ID in $LISTS; do
  echo "Rimozione da lista: ${LIST_ID}"
  curl -s -X DELETE "${BASE_URL}/contacts/list/${LIST_ID}/contacts" \
    -H "X-Api-Key: ${API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"contactIds": ["'"${CONTACT_ID}"'"]}' > /dev/null
done

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

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

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 a DELETE /contacts/list/{listId}/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​