Passa al contenuto principale

UC-029 — Report Campagna Completo

CampoValore
IDUC-029
ObiettivoCreare una campagna, monitorarne le statistiche e scaricare il report completo in CSV
CanaleSMS (applicabile a tutti i canali)
Complessità⭐⭐⭐ Avanzato
Tempo stimato25 minuti
API coinvoltePOST /api/partner-gateway/v1/campaigns, PUT /api/partner-gateway/v1/campaigns/{id}/confirm, GET /api/partner-gateway/v1/campaigns/{id}/stats, POST /api/partner-gateway/v1/exports/delivery-reports, GET /api/partner-gateway/v1/exports/{exportId}

Scenari reali​

  • FashionOutlet — Analisi ROI Black Friday: Dopo la campagna Black Friday, il team marketing vuole un report dettagliato con tassi di consegna per operatore, costi totali e confronto con l'anno precedente.
  • TelcoMobile — Report settimanale per il management: Ogni lunedi, il responsabile comunicazione genera un report aggregato delle campagne della settimana per la direzione.
  • BancaAdriatica — Audit consegne cliente enterprise: Il team compliance deve documentare il tasso di consegna delle notifiche transazionali per un audit interno trimestrale.

:::info Use case composito Questo UC combina i flussi di UC-006 — Campagna Bulk SMS e UC-011 — Export Delivery Reports in un workflow end-to-end completo. :::

Flusso completo​

Il diagramma illustra il workflow completo: dalla creazione della campagna al download del report CSV per l'analisi.

Step 1 — Crea la campagna​

Crea una nuova campagna SMS indirizzata a una lista di contatti:

curl -X POST "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday 2026 - SMS Promo",
    "channel": "SMS",
    "sender": "FashionOut",
    "contactListId": "lst_bf2026_clienti_vip",
    "message": {
      "body": "Ciao {firstName}! Black Friday FashionOutlet: -50% su tutto solo oggi! Usa il codice BF2026 su https://fashionoutlet.it/bf Rispondi STOP per opt-out."
    },
    "scheduledDate": "2026-11-27T09:00:00+01:00"
  }'

Response — Campagna creata​

{ "id": "cmp_d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", "status": "DRAFT", "totalContacts": 15420, "scheduledDate": "2026-11-27T09:00:00+01:00" }

:::tip Salva l'ID campagna Il campo id della campagna e necessario per tutti gli step successivi: conferma, monitoraggio e collegamento al report. :::

Step 2 — Conferma l'invio della campagna​

La campagna resta in stato DRAFT fino alla conferma esplicita:

curl -X PUT "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/cmp_d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90/confirm" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Campagna confermata​

{ "id": "cmp_d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", "status": "CONFIRMED", "estimatedCompletionTime": "2026-11-27T09:45:00+01:00" }
Dietro le quinte — Cosa succede dopo la conferma
  1. Validazione: Il sistema verifica lista contatti, mittente e credito.
  2. Scheduling: Se la scheduledDate e futura, la campagna resta in coda.
  3. Throttling: L'invio avviene in batch (15.000 SMS in ~30-45 minuti).
  4. Credito: Addebitato all'invio effettivo, non alla conferma.

Step 3 — Monitora le statistiche della campagna​

Durante e dopo l'invio, controlla le statistiche aggregate:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/cmp_d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90/stats" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Statistiche campagna completata​

{
  "campaignId": "cmp_d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
  "status": "COMPLETED",
  "stats": {
    "totalMessages": 15420, "delivered": 14650, "failed": 458,
    "deliveryRate": 95.01, "totalCost": 539.70
  },
  "completedAt": "2026-11-27T09:38:22+01:00"
}

:::info Polling delle statistiche Le statistiche si aggiornano in tempo reale durante l'invio. Puoi interrogare l'endpoint ogni 30-60 secondi per monitorare il progresso. Lo status passa da SENDING a COMPLETED quando tutti i messaggi sono stati processati. :::

Step 4 — Esporta il delivery report​

Richiedi l'export CSV con il dettaglio di ogni singolo messaggio:

curl -X POST "https://lora-api.agiletelecom.com/api/partner-gateway/v1/exports/delivery-reports" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2026-11-27",
    "dateTo": "2026-11-28",
    "channel": "SMS",
    "campaignId": "cmp_d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"
  }'

Response — Export in coda​

{
  "exportId": "exp_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "status": "PENDING",
  "type": "DELIVERY_REPORTS",
  "createdAt": "2026-11-28T10:00:00+01:00"
}

Step 5 — Scarica il CSV​

Interroga lo stato dell'export con GET /exports/{exportId}. Quando status e COMPLETED, usa il downloadUrl per scaricare il file:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/exports/exp_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
  -H "X-Api-Key: YOUR_API_KEY"
{
  "exportId": "exp_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "status": "COMPLETED",
  "isAvailableForDownload": true,
  "downloadUrl": "https://cdn.agiletelecom.com/exports/exp_1a2b3c4d.csv?token=eyJhbG...",
  "fileSize": 2458900,
  "totalRows": 15420
}
curl -o "report_blackfriday_2026.csv" \
  "https://cdn.agiletelecom.com/exports/exp_1a2b3c4d.csv?token=eyJhbG..."
Dietro le quinte — Struttura del CSV

Il CSV contiene una riga per messaggio con colonne: messageId, destination, channel, status, statusCode, sendDate, deliveryDate, cost, parts, campaignId. L'export asincrono e necessario per dataset di grandi dimensioni.

Risultato atteso​

StepAzioneRisultato
1POST /campaignsCampagna creata, status: "DRAFT"
2PUT /campaigns/{id}/confirmstatus: "CONFIRMED", invio schedulato
3GET /campaigns/{id}/statsStatistiche aggregate, deliveryRate: 95.01%
4POST /exports/delivery-reportsExport in coda, status: "PENDING"
5GET /exports/{id}CSV scaricabile con dettaglio 15.420 messaggi

Esempio completo end-to-end​

#!/bin/bash
API_KEY="YOUR_API_KEY"
BASE_URL="https://lora-api.agiletelecom.com/api/partner-gateway/v1"

# 1. Crea e conferma campagna
CMP_ID=$(curl -s -X POST "${BASE_URL}/campaigns" \
  -H "X-Api-Key: ${API_KEY}" -H "Content-Type: application/json" \
  -d '{"name":"Black Friday 2026","channel":"SMS","sender":"FashionOut","contactListId":"lst_bf2026_clienti_vip","message":{"body":"Ciao {firstName}! -50% su tutto! Codice BF2026"}}' | jq -r '.id')

curl -s -X PUT "${BASE_URL}/campaigns/${CMP_ID}/confirm" -H "X-Api-Key: ${API_KEY}" > /dev/null

# 2. Monitora fino al completamento
while true; do
  CMP_STATUS=$(curl -s -X GET "${BASE_URL}/campaigns/${CMP_ID}/stats" \
    -H "X-Api-Key: ${API_KEY}" | jq -r '.status')
  echo "Stato: ${CMP_STATUS}"
  [[ "$CMP_STATUS" == "COMPLETED" ]] && break
  sleep 60
done

# 3. Esporta e scarica
EXP_ID=$(curl -s -X POST "${BASE_URL}/exports/delivery-reports" \
  -H "X-Api-Key: ${API_KEY}" -H "Content-Type: application/json" \
  -d '{"dateFrom":"2026-11-27","dateTo":"2026-11-28","channel":"SMS","campaignId":"'"${CMP_ID}"'"}' | jq -r '.exportId')

sleep 30
DL_URL=$(curl -s -X GET "${BASE_URL}/exports/${EXP_ID}" -H "X-Api-Key: ${API_KEY}" | jq -r '.downloadUrl')
curl -o "report_blackfriday_2026.csv" "$DL_URL"

Varianti​

Report multi-canale​

Per campagne multi-canale, ometti il filtro channel nella richiesta di export per includere SMS, RCS e WhatsApp nello stesso CSV.

Report aggregato per periodo​

Per un report settimanale che include tutte le campagne, ometti campaignId e specifica solo dateFrom/dateTo.

Errori comuni​

404 Not Found — Campagna non esistente​

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

Soluzione: Verifica l'ID campagna. Usa GET /campaigns per elencare le campagne disponibili.

Export FAILED — Intervallo date troppo ampio​

{ "exportId": "exp_1a2b3c4d", "status": "FAILED", "error": "Date range too large. Maximum 90 days." }

Soluzione: Riduci l'intervallo a massimo 90 giorni. Per periodi più lunghi, suddividi in più export.

Prossimi passi​

Riferimenti​